From 3cc38d7ba381e181095139d1a57da25b2edd568a Mon Sep 17 00:00:00 2001 From: reeshika-h Date: Thu, 2 Apr 2026 16:12:06 +0530 Subject: [PATCH 1/4] Added cursor rules and skills --- .cursor/rules/README.md | 13 ++++ .cursor/rules/code-review.mdc | 14 ++++ .cursor/rules/contentstack-utils-sdk.mdc | 14 ++++ .cursor/rules/dev-workflow.md | 48 ++++++++++++++ .cursor/rules/swift-style.mdc | 14 ++++ .cursor/rules/tests.mdc | 14 ++++ .vscode/settings.json | 4 ++ AGENTS.md | 66 +++++++++++++++++++ skills/README.md | 10 +++ skills/contentstack-utils-api/SKILL.md | 32 +++++++++ .../contentstack-utils-code-review/SKILL.md | 32 +++++++++ skills/contentstack-utils-platform/SKILL.md | 27 ++++++++ skills/contentstack-utils-testing/SKILL.md | 29 ++++++++ 13 files changed, 317 insertions(+) create mode 100644 .cursor/rules/README.md create mode 100644 .cursor/rules/code-review.mdc create mode 100644 .cursor/rules/contentstack-utils-sdk.mdc create mode 100644 .cursor/rules/dev-workflow.md create mode 100644 .cursor/rules/swift-style.mdc create mode 100644 .cursor/rules/tests.mdc create mode 100644 .vscode/settings.json create mode 100644 AGENTS.md create mode 100644 skills/README.md create mode 100644 skills/contentstack-utils-api/SKILL.md create mode 100644 skills/contentstack-utils-code-review/SKILL.md create mode 100644 skills/contentstack-utils-platform/SKILL.md create mode 100644 skills/contentstack-utils-testing/SKILL.md diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md new file mode 100644 index 0000000..9e90d47 --- /dev/null +++ b/.cursor/rules/README.md @@ -0,0 +1,13 @@ +# Cursor rules index + +Rules in this folder guide contributors and AI agents toward this repository’s conventions. Cursor applies them by glob match or as always-on rules. + +| File | Scope | Purpose | +|------|--------|---------| +| `swift-style.mdc` | `**/*.swift` | Swift language and repo-wide style (SwiftLint, targets, naming). | +| `contentstack-utils-sdk.mdc` | `Sources/ContentstackUtils/**/*.swift` | Public SDK surface: `ContentstackUtils`, `Option`, RTE/JSON models, HTML rendering, variants. | +| `tests.mdc` | `Tests/**/*.swift` | XCTest layout, mocks, fixtures, and coverage exclusions. | +| `code-review.mdc` | Always | PR checklist: API stability, docs, errors, compatibility, dependencies/SCA, tests. | +| `dev-workflow.md` | (documentation) | Branches, build/test commands, lint/format, PR expectations—not a Cursor rule file. | + +See also [AGENTS.md](../../AGENTS.md) for project overview and command references. diff --git a/.cursor/rules/code-review.mdc b/.cursor/rules/code-review.mdc new file mode 100644 index 0000000..947a88a --- /dev/null +++ b/.cursor/rules/code-review.mdc @@ -0,0 +1,14 @@ +--- +description: PR review checklist for Contentstack Utils Swift—API, docs, errors, compatibility, security, tests. +alwaysApply: true +--- + +# Code review checklist (this repo) + +- **Public API stability:** Any change to `public`/`open` types in `Sources/ContentstackUtils/` (e.g. `ContentstackUtils`, `Option`, `Node`, GQL helpers, variant APIs) must be semver-conscious; call out breaking renames or signature changes. +- **Documentation:** User-visible behavior belongs in `README.md` and `CHANGELOG.md`; podspec summary/version when releasing. Examples should match actual method names (`jsonToHtml` overloads, `GQL.jsonToHtml`). +- **Error handling:** New `throws` paths should use clear error types; avoid silent failures on bad RTE JSON or variant input when callers need to debug. +- **Backward compatibility:** Support existing Contentstack JSON RTE and GraphQL result shapes; prefer additive fields and default `Option()` behavior. +- **Dependencies and security:** `Package.swift` / `ContentstackUtils.podspec` dependency changes need justification; CI may run SCA/policy scans—address reported issues per org process. +- **Tests:** Add or update tests under `Tests/ContentstackUtilsTests/` for bug fixes and features; run `swift test` and/or `xcodebuild` as in CI. +- **Vendored code:** Changes under `Sources/Kanna/` or `Modules/` need extra scrutiny (upstream parity, licensing, platform builds). diff --git a/.cursor/rules/contentstack-utils-sdk.mdc b/.cursor/rules/contentstack-utils-sdk.mdc new file mode 100644 index 0000000..e6a5c2c --- /dev/null +++ b/.cursor/rules/contentstack-utils-sdk.mdc @@ -0,0 +1,14 @@ +--- +description: ContentstackUtils public SDK patterns—RTE rendering, Option/Renderable, GQL JSON, variants. +globs: "Sources/ContentstackUtils/**/*.swift" +--- + +# ContentstackUtils SDK patterns + +- **Main entry:** Consumers `import ContentstackUtils` and use `ContentstackUtils` (e.g. `render(content:_:)`, `render(contents:_:)`, `jsonToHtml(node:_:)`, `getVariantAliases`, `GQL.jsonToHtml(rte:_:)`). Keep static surface small and documented; breaking changes require semver and changelog notes. +- **Customization:** Subclass or replace behavior via `Option` (open class) implementing `Renderable`—`renderItem(embeddedObject:metadata:)`, `renderMark(markType:text:)`, `renderNode(nodeType:node:next:)`. Do not remove or rename open hooks without a major version. +- **Data model:** RTE JSON uses types such as `Node`, `JSONNode`/`JSONNodes`, `MarkType`, `StyleType`, `Metadata`, and embedded entry/asset types (`EmbeddedObject`, `EmbeddedEntry`, etc.). Preserve `Codable`/decoding compatibility with Contentstack Delivery/GraphQL payloads. +- **Errors:** Expose domain errors as nested types where appropriate (e.g. `ContentstackUtils.VariantUtilityError.invalidArgument`). Use `throws` for recoverable failures; avoid force-unwraps in public paths. +- **HTML:** Rendering uses Kanna/HTML under the hood; output should remain safe and predictable for documented inputs. Document any new node types or GQL JSON shapes in README/CHANGELOG. +- **No network layer:** This package does not ship HTTP clients or tokens. README examples that show `Stack`, `fetch`, or Apollo are integration sketches—do not add hard dependencies on Contentstack’s main iOS SDK or Apollo inside this library unless the product owner requests it and `Package.swift` is updated. +- **Typos in legacy API:** Some property names (e.g. `embdeddedItems`) are entrenched; changing them is a breaking API change—coordinate with maintainers. diff --git a/.cursor/rules/dev-workflow.md b/.cursor/rules/dev-workflow.md new file mode 100644 index 0000000..80e6edd --- /dev/null +++ b/.cursor/rules/dev-workflow.md @@ -0,0 +1,48 @@ +# Development workflow (ContentstackUtils Swift) + +## Branches and pull requests + +- **CI** runs on push to `master` and on pull requests targeting `master` or `next` (see `.github/workflows/ci.yml`). +- **Merges into `master`** from the wider org are gated: pull requests whose base is `master` are expected to come from the `staging` branch; other head branches may be blocked by the check-branch workflow (`.github/workflows/check-branch.yml`). Confirm with your team’s release process before opening PRs to `master`. + +## Build and test + +**Swift Package Manager (library development):** + +```bash +swift build +swift test +``` + +**Xcode (matches CI):** CI uses the Xcode project and iOS Simulator: + +```bash +xcodebuild -project "ContentstackUtils.xcodeproj" -scheme "ContentstackUtils-Package" -destination "OS=13.4.1,name=iPhone 11 Pro" test +``` + +Adjust `-destination` for your local Xcode/Simulator names. CI pins `DEVELOPER_DIR` to a specific Xcode; local runs use your default toolchain. + +## Lint and format + +- **SwiftLint:** configuration is `.swiftlint.yml` (excludes `Carthage`, `Pods`, `Sources/Kanna`, and some test constants). Run from repo root: + +```bash +swiftlint +``` + +- **Formatting:** there is no separate formatter config in-repo; match existing file style and SwiftLint output. + +## Coverage + +- **Slather** is configured in `.slather.yml` (Cobertura, scheme `ContentstackUtils-Package`, ignores tests, Kanna, and `Decodable.*` under ContentstackUtils). Use Slather/Xcode coverage as your team prefers after a test run. + +## Pull request expectations + +- Describe behavior changes and any public API or semver impact. +- Update `CHANGELOG.md` and version metadata (`ContentstackUtils.podspec`, tags) when releasing—per team process. +- Ensure tests pass locally (`swift test` and/or `xcodebuild` as above). +- Security/policy scans may run in CI (`.github/workflows/sca-scan.yml`, `policy-scan.yml`); fix findings per org policy. + +## Test-driven development + +TDD is optional; there is no enforced workflow. New behavior should include or update tests under `Tests/ContentstackUtilsTests/` when feasible. diff --git a/.cursor/rules/swift-style.mdc b/.cursor/rules/swift-style.mdc new file mode 100644 index 0000000..0f20cea --- /dev/null +++ b/.cursor/rules/swift-style.mdc @@ -0,0 +1,14 @@ +--- +description: Swift style and project conventions for all Swift sources (SwiftLint, layout, vendored Kanna). +globs: "**/*.swift" +--- + +# Swift style (this repo) + +- **Tooling:** Run SwiftLint using `.swiftlint.yml`. Do not weaken rules for new code without team agreement; `Sources/Kanna` is excluded upstream—avoid copying patterns that would fail lint in `Sources/ContentstackUtils/`. +- **Package layout:** Library code lives under `Sources/ContentstackUtils/`. Vendored **Kanna** lives under `Sources/Kanna/`; treat it as third-party unless explicitly updating the fork—prefer fixes in `ContentstackUtils` or documented Kanna upgrades. +- **Platforms:** The package supports macOS 10.13+, iOS/tvOS 11+, watchOS 4+ (`Package.swift`). Avoid APIs that break the declared deployment targets without bumping them deliberately. +- **libxml2:** Non-Linux Apple platforms use system libxml; Linux uses the `libxml2` system target and `pkg-config`. Keep `Modules/` and conditional compilation in sync with `Package.swift` when changing platform support. +- **Naming:** Follow existing Swift naming (types `UpperCamelCase`, members `lowerCamelCase`). Preserve established public names even if imperfect (e.g. historical typos in protocol/API) unless doing a semver-major cleanup. +- **Imports:** `import Foundation` where needed; HTML parsing goes through Kanna types re-exported/used from this package’s structure—follow existing files. +- **Access control:** Mark public API `public`/`open` intentionally; keep implementation details `internal` or `private` unless cross-target tests require `@testable` patterns already in use. diff --git a/.cursor/rules/tests.mdc b/.cursor/rules/tests.mdc new file mode 100644 index 0000000..4f2800b --- /dev/null +++ b/.cursor/rules/tests.mdc @@ -0,0 +1,14 @@ +--- +description: XCTest conventions for ContentstackUtilsTests—naming, mocks, fixtures, coverage ignores. +globs: "Tests/**/*.swift" +--- + +# Tests (ContentstackUtilsTests) + +- **Runner:** XCTest via SPM (`swift test`) and Xcode scheme `ContentstackUtils-Package`. Test target folder: `Tests/ContentstackUtilsTests/`. +- **Naming:** Files follow `*Tests.swift`, `*Test.swift`, or descriptive names (`GQLJsonToHtml.swift`, `JsonNodes.swift`). Mirror the feature under test (e.g. `VariantUtilityTests.swift` for variant helpers). +- **Fixtures:** JSON/HTML fixtures and helpers live alongside tests (`JsonNodes.swift`, `JsonNodesHtmlResults.swift`, `EmbededModelMock.swift`, `CustomRenderOptionMock.swift`, etc.). Prefer extending existing fixtures over one-off huge literals when possible. +- **SwiftLint:** `Tests/ContentstackUtilsTests/Constants.swift` is excluded in `.swiftlint.yml`; other test files are linted—keep them compliant. +- **Coverage:** Slather ignores `Tests/*` and parts of sources per `.slather.yml`; new code under `Sources/ContentstackUtils/` should be covered unless explicitly excluded. +- **Integration vs unit:** This repo does not use separate integration directories; tests are colocated in `ContentstackUtilsTests` with mocks (`TestClient`, model mocks) simulating API payloads—no live network calls required for CI. +- **Manifests:** `XCTestManifests.swift` exists for Linux/test discovery where applicable—update when adding tests if your workflow requires it. diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..64557a7 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,4 @@ +{ + "snyk.advanced.organization": "18cb8ddb-8261-46fc-85fd-8b7025684b29", + "snyk.advanced.autoSelectOrganization": true +} \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..f2db7ae --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,66 @@ +# AGENTS.md — Contentstack Utils (Swift) + +Single entry point for humans and AI agents working on **contentstack-utils-swift**: a small Swift library for rendering Contentstack RTE (rich text) and related JSON to HTML, plus variant alias helpers. + +## Project name and purpose + +**ContentstackUtils** helps iOS/macOS/tvOS/watchOS apps turn **stack RTE content** (HTML fragments, JSON RTE / “supercharged” RTE, and GraphQL-shaped JSON) into HTML strings, with hooks for embedded entries and assets. It does **not** implement Contentstack REST/GraphQL networking; apps use the [Contentstack Swift SDK](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/swift) or other clients to fetch data, then pass strings or dictionaries into this package. + +## Tech stack + +| Area | Choice | +|------|--------| +| Language | Swift 5 (`Package.swift` `swiftLanguageVersions: [.v5]`, podspec Swift 5.0) | +| Build | Swift Package Manager; CocoaPods via `ContentstackUtils.podspec`; optional Xcode `ContentstackUtils.xcodeproj` | +| HTML/XML | Vendored **Kanna** under `Sources/Kanna/`, **libxml2** (`Modules/`, system on Apple platforms) | +| Tests | **XCTest**, target `ContentstackUtilsTests`, path `Tests/ContentstackUtilsTests/` | +| Lint | **SwiftLint** (`.swiftlint.yml`) | +| Coverage | **Slather** (`.slather.yml`, Cobertura, scheme `ContentstackUtils-Package`) | + +## Main entry points (paths and symbols) + +| What | Where | +|------|--------| +| Public API surface | `Sources/ContentstackUtils/ContentstackUtils.swift` — `struct ContentstackUtils` (`render`, `jsonToHtml`, `getVariantAliases`, nested `GQL`, `VariantUtilityError`) | +| Rendering options | `Sources/ContentstackUtils/Option.swift` — `open class Option`, `Renderable` | +| RTE JSON model | `Sources/ContentstackUtils/Node.swift`, `JSONNode.swift`, `JSONNodes.swift`, `MarkType.swift`, `Metadata.swift`, … | +| Tests | `Tests/ContentstackUtilsTests/*.swift` (e.g. `ContentstackUtilsTests.swift`, `VariantUtilityTests.swift`, `GQLJsonToHtml.swift`) | +| Package manifest | `Package.swift` — product `ContentstackUtils`, targets `ContentstackUtils`, `ContentstackUtilsTests`, system `libxml2` | + +Consumers typically: `import ContentstackUtils`, create an `Option` (or subclass), call `ContentstackUtils.render(content:_:)` or `ContentstackUtils.jsonToHtml(node:_:)` / `ContentstackUtils.GQL.jsonToHtml(rte:_:)`. + +## Commands (build / test / lint) + +```bash +swift build +swift test +swiftlint +``` + +CI-style Xcode test (see `.github/workflows/ci.yml`): + +```bash +xcodebuild -project "ContentstackUtils.xcodeproj" -scheme "ContentstackUtils-Package" -destination "OS=13.4.1,name=iPhone 11 Pro" test +``` + +CocoaPods consumption: `pod 'ContentstackUtils', '~> …'` (see `README.md` and `ContentstackUtils.podspec` for current version). + +## Cursor rules (`.cursor/rules/`) + +| Resource | Role | +|----------|------| +| `.cursor/rules/README.md` | Index of rule files and globs | +| `.cursor/rules/dev-workflow.md` | Branches (`master` / `next` / `staging` expectations), CI parity, PR notes | +| `swift-style.mdc` | Swift + repo style | +| `contentstack-utils-sdk.mdc` | SDK-specific patterns under `Sources/ContentstackUtils/` | +| `tests.mdc` | Test layout and conventions | +| `code-review.mdc` | Always-on PR checklist | + +## Skills (`skills/`) + +Reusable guidance for agents lives under `skills//SKILL.md`. See `skills/README.md` for a table of when to use each skill. Typical uses: public API and integration boundaries (`contentstack-utils-api`), XCTest and fixtures (`contentstack-utils-testing`), review criteria (`contentstack-utils-code-review`), libxml/Kanna/SPM platforms (`contentstack-utils-platform`). + +## Official docs (external) + +- Product: [Contentstack](https://www.contentstack.com/) +- Swift usage examples in this repo: `README.md` diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000..0c6cfe3 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,10 @@ +# Agent skills (Contentstack Utils Swift) + +Skills are reusable instruction sets for AI agents. Each skill is a folder containing `SKILL.md` with YAML frontmatter (`name`, `description`). + +| Skill folder | When to use it | +|--------------|----------------| +| `contentstack-utils-api` | Changing or documenting public API, `ContentstackUtils` / `Option` / RTE JSON types, GQL JSON entry points, errors, semver impact. | +| `contentstack-utils-testing` | Adding or fixing XCTest tests, mocks, JSON fixtures, `swift test` / Xcode test workflow. | +| `contentstack-utils-code-review` | Structured PR review with severity (blocker/major/minor) aligned with this SDK. | +| `contentstack-utils-platform` | libxml2, Kanna vendoring, SPM targets, deployment platforms, `Modules/`, Linux vs Apple differences. | diff --git a/skills/contentstack-utils-api/SKILL.md b/skills/contentstack-utils-api/SKILL.md new file mode 100644 index 0000000..3e75bbf --- /dev/null +++ b/skills/contentstack-utils-api/SKILL.md @@ -0,0 +1,32 @@ +--- +name: contentstack-utils-api +description: Public API for ContentstackUtils Swift—rendering, Option/Renderable, GQL JSON, variants, errors; no bundled HTTP client. +--- + +# Contentstack Utils — public API skill + +## Scope + +This package exposes **HTML/RTE rendering** and **variant alias** helpers. It does **not** ship Stack configuration, API keys, or network clients. + +## Core types + +- **`ContentstackUtils`** (`Sources/ContentstackUtils/ContentstackUtils.swift`): static methods `render(content:_:)`, `render(contents:_:)`, `jsonToHtml` overloads, `getVariantAliases`, nested **`GQL`** with `jsonToHtml(rte:_:)` for GraphQL-shaped dictionaries. +- **`Option`** (`Option.swift`): open class; override `renderItem`, `renderMark`, `renderNode` for custom HTML. Implements **`Renderable`**. +- **RTE JSON:** `Node`, `JSONNode`, `JSONNodes`, `MarkType`, `StyleType`, `Metadata`, embedded models — keep decoding tolerant and documented when stack payloads evolve. + +## Errors + +- Use **`ContentstackUtils.VariantUtilityError`** (and similar nested types) for domain failures; prefer `throws` over optional soup for invalid variant input. + +## Integration boundary + +- README shows **`Contentstack.stack`**, **`fetch`**, and **Apollo** as **examples only**. Do not add hard dependencies on the main Contentstack iOS SDK or Apollo in `Package.swift` unless product explicitly requires it. + +## Docs and versioning + +- Update **`README.md`** and **`CHANGELOG.md`** for behavior users see. Align **`ContentstackUtils.podspec`** version with releases. Follow semver for `public`/`open` changes. + +## Reference + +- [Contentstack](https://www.contentstack.com/) — product home; Delivery API docs apply to how apps fetch data before calling this library. diff --git a/skills/contentstack-utils-code-review/SKILL.md b/skills/contentstack-utils-code-review/SKILL.md new file mode 100644 index 0000000..5dcd133 --- /dev/null +++ b/skills/contentstack-utils-code-review/SKILL.md @@ -0,0 +1,32 @@ +--- +name: contentstack-utils-code-review +description: PR review for contentstack-utils-swift—severity-rated checks for API, docs, errors, compatibility, deps, tests. +--- + +# Contentstack Utils — code review skill + +Use this skill to review changes consistently with `.cursor/rules/code-review.mdc`, with explicit **severity**. + +## Blocker + +- Breaks **`public`/`open`** API without semver/CHANGELOG/podspec alignment. +- Removes or weakens handling of RTE JSON shapes that existing apps rely on (without migration notes). +- New dependencies in **`Package.swift`** / **podspec** without security/license review when org requires it. +- **No tests** for clear behavioral fixes or new features in `Sources/ContentstackUtils/` when tests are practical. + +## Major + +- **`throws` / error** changes that confuse callers (wrong type, message, or non-throwing to throwing without version bump). +- **Kanna** or **`Modules/libxml2`** edits that diverge from upstream without documentation or break Linux/Apple builds. +- **README** examples that no longer compile against the actual API. + +## Minor + +- Style-only issues fixable by SwiftLint; internal naming; comment clarity. +- Test naming or fixture organization improvements without functional gaps. + +## Always verify + +- `swift build` / `swift test` (and Xcode scheme if touching iOS-specific paths). +- SwiftLint clean for edited files (respect exclusions). +- Backward compatibility for default **`Option()`** rendering paths. diff --git a/skills/contentstack-utils-platform/SKILL.md b/skills/contentstack-utils-platform/SKILL.md new file mode 100644 index 0000000..3197b68 --- /dev/null +++ b/skills/contentstack-utils-platform/SKILL.md @@ -0,0 +1,27 @@ +--- +name: contentstack-utils-platform +description: Build/runtime stack for ContentstackUtils—SPM targets, libxml2, vendored Kanna, Apple vs Linux, deployment targets. +--- + +# Contentstack Utils — platform and runtime skill + +## Swift Package Manager + +- **`Package.swift`:** Product **`ContentstackUtils`**; targets **`ContentstackUtils`** (sources `Sources/`), **`ContentstackUtilsTests`**, system library **`libxml2`** pointing at **`Modules/`**. +- **Conditional dependencies:** On Swift ≥5.3 and non-Linux Apple platforms, `ContentstackUtils` may omit the explicit `libxml2` target dependency; Linux uses `pkg-config` / `libxml-2.0` and apt providers as declared. + +## Vendored Kanna + +- HTML parsing lives under **`Sources/Kanna/`**. SwiftLint excludes this path globally—changes here are infrequent and should stay aligned with intentional vendoring updates. + +## Platforms + +- **Declared:** macOS 10.13+, iOS/tvOS 11+, watchOS 4+ (`Package.swift` / podspec). Do not use newer SDK APIs without availability checks or raising deployment targets deliberately. + +## CocoaPods + +- **`ContentstackUtils.podspec`:** `source_files` `Sources/**/*.{swift}`, `HEADER_SEARCH_PATHS` / `-lxml2` for libxml. Pod releases must match tagged source layout. + +## CI note + +- GitHub Actions uses **Xcode** and **xcodebuild** for iOS Simulator tests; local SPM `swift test` may differ slightly—run both when changing low-level parsing or linking. diff --git a/skills/contentstack-utils-testing/SKILL.md b/skills/contentstack-utils-testing/SKILL.md new file mode 100644 index 0000000..55a3187 --- /dev/null +++ b/skills/contentstack-utils-testing/SKILL.md @@ -0,0 +1,29 @@ +--- +name: contentstack-utils-testing +description: XCTest setup for ContentstackUtilsTests—swift test, Xcode scheme, mocks, fixtures, Slather/SwiftLint notes. +--- + +# Contentstack Utils — testing skill + +## Runner + +- **SPM:** `swift test` from repository root (target `ContentstackUtilsTests`). +- **Xcode:** Scheme **`ContentstackUtils-Package`**, project **`ContentstackUtils.xcodeproj`** — matches `.github/workflows/ci.yml` (`xcodebuild` + iOS Simulator destination). + +## Layout + +- Tests live under **`Tests/ContentstackUtilsTests/`** with names like `*Tests.swift`, `*Test.swift`, or feature files (`GQLJsonToHtml.swift`, `DefaultRenderTests.swift`). +- Reuse mocks: `CustomRenderOptionMock.swift`, `EmbededModelMock.swift`, `TestClient.swift`, JSON helpers in `JsonNodes.swift` / `JsonNodesHtmlResults.swift`. + +## Lint and coverage + +- **SwiftLint:** `.swiftlint.yml` excludes `Tests/ContentstackUtilsTests/Constants.swift` only; other test files are linted. +- **Slather:** `.slather.yml` ignores all of `Tests/*` from coverage reporting; source ignores include Kanna and specific files—see config when interpreting coverage. + +## Credentials + +- Tests are **offline** (no live API keys). Do not commit secrets; keep fixtures static JSON/Swift literals. + +## Linux + +- If extending Linux CI, maintain **`XCTestManifests.swift`** as needed for test discovery on Linux. From 7b26d02cd1d13021eb28e8cca26dbb98de823a91 Mon Sep 17 00:00:00 2001 From: reeshika-h Date: Mon, 6 Apr 2026 10:57:52 +0530 Subject: [PATCH 2/4] Refactor AGENTS.md and update cursor rules documentation --- .cursor/rules/README.md | 30 +++-- .cursor/rules/code-review.mdc | 44 ++++++-- .cursor/rules/dev-workflow.md | 57 ++++------ .cursor/rules/testing.mdc | 28 +++++ .cursor/rules/tests.mdc | 14 --- AGENTS.md | 104 ++++++++---------- skills/README.md | 27 +++-- skills/code-review/SKILL.md | 56 ++++++++++ skills/contentstack-utils-api/SKILL.md | 32 ------ .../contentstack-utils-code-review/SKILL.md | 32 ------ skills/contentstack-utils-platform/SKILL.md | 27 ----- skills/contentstack-utils-testing/SKILL.md | 29 ----- skills/contentstack-utils/SKILL.md | 39 +++++++ skills/framework/SKILL.md | 36 ++++++ skills/testing/SKILL.md | 24 ++++ 15 files changed, 325 insertions(+), 254 deletions(-) create mode 100644 .cursor/rules/testing.mdc delete mode 100644 .cursor/rules/tests.mdc create mode 100644 skills/code-review/SKILL.md delete mode 100644 skills/contentstack-utils-api/SKILL.md delete mode 100644 skills/contentstack-utils-code-review/SKILL.md delete mode 100644 skills/contentstack-utils-platform/SKILL.md delete mode 100644 skills/contentstack-utils-testing/SKILL.md create mode 100644 skills/contentstack-utils/SKILL.md create mode 100644 skills/framework/SKILL.md create mode 100644 skills/testing/SKILL.md diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md index 9e90d47..ff835d2 100644 --- a/.cursor/rules/README.md +++ b/.cursor/rules/README.md @@ -1,13 +1,23 @@ -# Cursor rules index +# Cursor Rules – Contentstack Utils Swift -Rules in this folder guide contributors and AI agents toward this repository’s conventions. Cursor applies them by glob match or as always-on rules. +This directory contains Cursor AI rules that apply when working in this repository. Rules provide persistent context so the AI follows project conventions and Contentstack Utils (RTE rendering) patterns. -| File | Scope | Purpose | -|------|--------|---------| -| `swift-style.mdc` | `**/*.swift` | Swift language and repo-wide style (SwiftLint, targets, naming). | -| `contentstack-utils-sdk.mdc` | `Sources/ContentstackUtils/**/*.swift` | Public SDK surface: `ContentstackUtils`, `Option`, RTE/JSON models, HTML rendering, variants. | -| `tests.mdc` | `Tests/**/*.swift` | XCTest layout, mocks, fixtures, and coverage exclusions. | -| `code-review.mdc` | Always | PR checklist: API stability, docs, errors, compatibility, dependencies/SCA, tests. | -| `dev-workflow.md` | (documentation) | Branches, build/test commands, lint/format, PR expectations—not a Cursor rule file. | +## How rules are applied -See also [AGENTS.md](../../AGENTS.md) for project overview and command references. +- **File-specific rules** use the `globs` frontmatter: they apply when you open or edit files matching that pattern. +- **Always-on rules** use `alwaysApply: true`: they are included in every conversation in this project. + +## Rule index + +| File | Applies when | Purpose | +|------|----------------|---------| +| **dev-workflow.md** | (Reference only; no glob) | Core development workflow: branches, running tests, lint, PR expectations. Read for process guidance. | +| **swift-style.mdc** | Editing any `**/*.swift` file | Swift standards: SwiftLint, package layout, Kanna/libxml2, platforms, access control. | +| **contentstack-utils-sdk.mdc** | Editing `Sources/ContentstackUtils/**/*.swift` | Utils SDK patterns: `ContentstackUtils`, `Option` / `Renderable`, RTE/JSON models, GQL helpers, variants, errors. | +| **testing.mdc** | Editing `Tests/**/*.swift` | XCTest layout, mocks, fixtures, SwiftLint/Slather, offline tests. | +| **code-review.mdc** | Always | PR/review checklist: API stability, documentation, error handling, backward compatibility, dependencies and security (e.g. SCA), tests. | + +## Related + +- **AGENTS.md** (repo root) – Main entry point for AI agents: project overview, entry points, and pointers to rules and skills. +- **skills/** – Reusable skill docs (`contentstack-utils`, `testing`, `code-review`, `framework`) for deeper guidance on specific tasks. diff --git a/.cursor/rules/code-review.mdc b/.cursor/rules/code-review.mdc index 947a88a..f595b75 100644 --- a/.cursor/rules/code-review.mdc +++ b/.cursor/rules/code-review.mdc @@ -1,14 +1,40 @@ --- -description: PR review checklist for Contentstack Utils Swift—API, docs, errors, compatibility, security, tests. +description: PR and code review checklist – API stability, docs, errors, compatibility, security, tests alwaysApply: true --- -# Code review checklist (this repo) +# Code Review Checklist – Contentstack Utils Swift -- **Public API stability:** Any change to `public`/`open` types in `Sources/ContentstackUtils/` (e.g. `ContentstackUtils`, `Option`, `Node`, GQL helpers, variant APIs) must be semver-conscious; call out breaking renames or signature changes. -- **Documentation:** User-visible behavior belongs in `README.md` and `CHANGELOG.md`; podspec summary/version when releasing. Examples should match actual method names (`jsonToHtml` overloads, `GQL.jsonToHtml`). -- **Error handling:** New `throws` paths should use clear error types; avoid silent failures on bad RTE JSON or variant input when callers need to debug. -- **Backward compatibility:** Support existing Contentstack JSON RTE and GraphQL result shapes; prefer additive fields and default `Option()` behavior. -- **Dependencies and security:** `Package.swift` / `ContentstackUtils.podspec` dependency changes need justification; CI may run SCA/policy scans—address reported issues per org process. -- **Tests:** Add or update tests under `Tests/ContentstackUtilsTests/` for bug fixes and features; run `swift test` and/or `xcodebuild` as in CI. -- **Vendored code:** Changes under `Sources/Kanna/` or `Modules/` need extra scrutiny (upstream parity, licensing, platform builds). +Use this checklist when reviewing pull requests or before opening a PR. + +## API design and stability + +- [ ] **Public API:** New or changed `public` / `open` types in `Sources/ContentstackUtils/` are necessary, semver-conscious, and documented (`README.md` / `CHANGELOG.md` when user-visible). +- [ ] **Backward compatibility:** No breaking changes to public API unless explicitly called out and justified (e.g. major version). Prefer additive behavior and default `Option()` paths. +- [ ] **Naming:** Method and type names match existing Utils style and Contentstack RTE terminology (`ContentstackUtils`, `Option`, `Node`, `GQL`, etc.). + +## Error handling and robustness + +- [ ] **Errors:** New `throws` paths use clear domain types (e.g. `VariantUtilityError`); callers can distinguish invalid input from parsing failures where relevant. +- [ ] **Optionals:** Avoid force-unwraps on public code paths; document preconditions for non-optional parameters. +- [ ] **RTE JSON:** Decoding and HTML traversal stay tolerant of documented stack payload shapes; regressions in embedded-item handling are called out. + +## Dependencies and security + +- [ ] **Dependencies:** Changes to `Package.swift` or `ContentstackUtils.podspec` are justified; version bumps do not introduce known vulnerabilities. +- [ ] **SCA:** Address any security findings (e.g. from Snyk or org scanners) in the PR scope or via an agreed follow-up. + +## Testing + +- [ ] **Coverage:** New or modified behavior in `Sources/ContentstackUtils/` is covered by tests under `Tests/ContentstackUtilsTests/` when feasible. +- [ ] **Test quality:** Tests are readable, deterministic, and follow project naming (`*Tests.swift`, mocks, fixtures). + +## Vendored and native code + +- [ ] **Kanna / libxml2 / `Modules/`:** Changes are reviewed for upstream parity, licensing, and cross-platform builds (Apple vs Linux). + +## Severity (optional) + +- **Blocker:** Must fix before merge (e.g. breaking public API without approval, security issue, no tests for new code where tests are practical). +- **Major:** Should fix (e.g. inconsistent error handling, README examples that do not compile). +- **Minor:** Nice to fix (e.g. style, minor docs). diff --git a/.cursor/rules/dev-workflow.md b/.cursor/rules/dev-workflow.md index 80e6edd..f19779f 100644 --- a/.cursor/rules/dev-workflow.md +++ b/.cursor/rules/dev-workflow.md @@ -1,48 +1,39 @@ -# Development workflow (ContentstackUtils Swift) +# Development Workflow – Contentstack Utils Swift -## Branches and pull requests +Use this as the standard workflow when contributing to Contentstack Utils Swift. -- **CI** runs on push to `master` and on pull requests targeting `master` or `next` (see `.github/workflows/ci.yml`). -- **Merges into `master`** from the wider org are gated: pull requests whose base is `master` are expected to come from the `staging` branch; other head branches may be blocked by the check-branch workflow (`.github/workflows/check-branch.yml`). Confirm with your team’s release process before opening PRs to `master`. +## Branches -## Build and test +- Use feature branches for changes (e.g. `feat/...`, `fix/...`, ticket branches like `DX-5372-cursor`). +- **CI** runs on push to `master` and on pull requests targeting `master` or `next` (see `.github/workflows/ci.yml`). +- **Merges into `master`** may be gated: PRs whose base is `master` are expected to come from the `staging` branch; other head branches may be blocked (see `.github/workflows/check-branch.yml`). Confirm with your team’s release process before opening PRs to `master`. -**Swift Package Manager (library development):** +## Running tests -```bash -swift build -swift test -``` +- **All tests (SPM):** `swift test` +- **Build:** `swift build` +- **CI-style Xcode (iOS Simulator):** + `xcodebuild -project "ContentstackUtils.xcodeproj" -scheme "ContentstackUtils-Package" -destination "OS=13.4.1,name=iPhone 11 Pro" test` + Adjust `-destination` for your local Xcode/Simulator. -**Xcode (matches CI):** CI uses the Xcode project and iOS Simulator: +Run tests before opening a PR. Integration-style behavior is covered with **offline** mocks and fixtures—no `.env` or live stack credentials required for the default test suite. -```bash -xcodebuild -project "ContentstackUtils.xcodeproj" -scheme "ContentstackUtils-Package" -destination "OS=13.4.1,name=iPhone 11 Pro" test -``` +## Lint -Adjust `-destination` for your local Xcode/Simulator names. CI pins `DEVELOPER_DIR` to a specific Xcode; local runs use your default toolchain. +- **SwiftLint:** `swiftlint` (config `.swiftlint.yml`) -## Lint and format +## Pull requests -- **SwiftLint:** configuration is `.swiftlint.yml` (excludes `Carthage`, `Pods`, `Sources/Kanna`, and some test constants). Run from repo root: +- Ensure the build passes: `swift build` and `swift test` (and/or `xcodebuild` if you touch Xcode-specific paths). +- Follow the **code-review** rule (see `.cursor/rules/code-review.mdc`) for the PR checklist. +- Keep changes backward-compatible for public API; call out any breaking changes clearly. +- Describe behavior changes and semver impact; update `CHANGELOG.md` and version metadata (`ContentstackUtils.podspec`, tags) when releasing—per team process. +- Security/policy scans may run in CI (`.github/workflows/sca-scan.yml`, `policy-scan.yml`); fix findings per org policy. -```bash -swiftlint -``` +## Optional: TDD -- **Formatting:** there is no separate formatter config in-repo; match existing file style and SwiftLint output. +If the team uses TDD, follow RED–GREEN–REFACTOR when adding behavior: write a failing test first, implement to pass, then refactor. The **testing** rule and **skills/testing** skill describe test structure and naming. ## Coverage -- **Slather** is configured in `.slather.yml` (Cobertura, scheme `ContentstackUtils-Package`, ignores tests, Kanna, and `Decodable.*` under ContentstackUtils). Use Slather/Xcode coverage as your team prefers after a test run. - -## Pull request expectations - -- Describe behavior changes and any public API or semver impact. -- Update `CHANGELOG.md` and version metadata (`ContentstackUtils.podspec`, tags) when releasing—per team process. -- Ensure tests pass locally (`swift test` and/or `xcodebuild` as above). -- Security/policy scans may run in CI (`.github/workflows/sca-scan.yml`, `policy-scan.yml`); fix findings per org policy. - -## Test-driven development - -TDD is optional; there is no enforced workflow. New behavior should include or update tests under `Tests/ContentstackUtilsTests/` when feasible. +- **Slather** is configured in `.slather.yml` (scheme `ContentstackUtils-Package`). Use after tests to inspect coverage of `Sources/ContentstackUtils/`. diff --git a/.cursor/rules/testing.mdc b/.cursor/rules/testing.mdc new file mode 100644 index 0000000..8c6582a --- /dev/null +++ b/.cursor/rules/testing.mdc @@ -0,0 +1,28 @@ +--- +description: XCTest patterns for ContentstackUtilsTests—naming, mocks, fixtures, Slather, SwiftLint exclusions. +globs: "Tests/**/*.swift" +--- + +# Testing Rules – Contentstack Utils Swift + +Apply when writing or editing tests. The project uses **XCTest** and **SwiftLint** (see `.swiftlint.yml`); coverage is reported with **Slather** (see `.slather.yml`). + +## Test naming and layout + +- **Target:** `ContentstackUtilsTests`; path **`Tests/ContentstackUtilsTests/`**. +- **File names:** `*Tests.swift`, `*Test.swift`, or feature-oriented names (`GQLJsonToHtml.swift`, `JsonNodes.swift`, `VariantUtilityTests.swift`). +- **Fixtures and mocks:** Reuse `JsonNodes.swift`, `JsonNodesHtmlResults.swift`, `EmbededModelMock.swift`, `CustomRenderOptionMock.swift`, `TestClient.swift`, etc., before adding parallel helpers. + +## XCTest usage + +- Run tests via **`swift test`** (SPM) and/or Xcode scheme **`ContentstackUtils-Package`** (`ContentstackUtils.xcodeproj`), matching CI (`.github/workflows/ci.yml`). +- This repo does **not** split integration tests into a separate tree; use mocks for API-shaped payloads—**no live network** or credentials in CI. + +## SwiftLint and coverage + +- **`Tests/ContentstackUtilsTests/Constants.swift`** is excluded from SwiftLint; other test files are linted. +- **Slather** ignores `Tests/*` in reports; new production code under `Sources/ContentstackUtils/` should still gain tests when practical. + +## Linux / discovery + +- Maintain **`XCTestManifests.swift`** if your workflow requires explicit Linux test discovery. diff --git a/.cursor/rules/tests.mdc b/.cursor/rules/tests.mdc deleted file mode 100644 index 4f2800b..0000000 --- a/.cursor/rules/tests.mdc +++ /dev/null @@ -1,14 +0,0 @@ ---- -description: XCTest conventions for ContentstackUtilsTests—naming, mocks, fixtures, coverage ignores. -globs: "Tests/**/*.swift" ---- - -# Tests (ContentstackUtilsTests) - -- **Runner:** XCTest via SPM (`swift test`) and Xcode scheme `ContentstackUtils-Package`. Test target folder: `Tests/ContentstackUtilsTests/`. -- **Naming:** Files follow `*Tests.swift`, `*Test.swift`, or descriptive names (`GQLJsonToHtml.swift`, `JsonNodes.swift`). Mirror the feature under test (e.g. `VariantUtilityTests.swift` for variant helpers). -- **Fixtures:** JSON/HTML fixtures and helpers live alongside tests (`JsonNodes.swift`, `JsonNodesHtmlResults.swift`, `EmbededModelMock.swift`, `CustomRenderOptionMock.swift`, etc.). Prefer extending existing fixtures over one-off huge literals when possible. -- **SwiftLint:** `Tests/ContentstackUtilsTests/Constants.swift` is excluded in `.swiftlint.yml`; other test files are linted—keep them compliant. -- **Coverage:** Slather ignores `Tests/*` and parts of sources per `.slather.yml`; new code under `Sources/ContentstackUtils/` should be covered unless explicitly excluded. -- **Integration vs unit:** This repo does not use separate integration directories; tests are colocated in `ContentstackUtilsTests` with mocks (`TestClient`, model mocks) simulating API payloads—no live network calls required for CI. -- **Manifests:** `XCTestManifests.swift` exists for Linux/test discovery where applicable—update when adding tests if your workflow requires it. diff --git a/AGENTS.md b/AGENTS.md index f2db7ae..8bec49f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,66 +1,50 @@ -# AGENTS.md — Contentstack Utils (Swift) +# Contentstack Utils Swift – Agent Guide -Single entry point for humans and AI agents working on **contentstack-utils-swift**: a small Swift library for rendering Contentstack RTE (rich text) and related JSON to HTML, plus variant alias helpers. +This document is the main entry point for AI agents working in this repository. -## Project name and purpose +## Project -**ContentstackUtils** helps iOS/macOS/tvOS/watchOS apps turn **stack RTE content** (HTML fragments, JSON RTE / “supercharged” RTE, and GraphQL-shaped JSON) into HTML strings, with hooks for embedded entries and assets. It does **not** implement Contentstack REST/GraphQL networking; apps use the [Contentstack Swift SDK](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/swift) or other clients to fetch data, then pass strings or dictionaries into this package. +- **Name:** Contentstack Utils Swift ([contentstack-utils-swift](https://github.com/contentstack/contentstack-utils-swift)) +- **Purpose:** Swift library for rendering Contentstack **RTE** (rich text) and related JSON to HTML, with hooks for embedded entries/assets and helpers for **variant** metadata. It does **not** implement Contentstack HTTP clients; apps fetch content with the [Content Delivery / Swift SDK](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/swift) or other clients, then pass strings or dictionaries into this package. ## Tech stack -| Area | Choice | -|------|--------| -| Language | Swift 5 (`Package.swift` `swiftLanguageVersions: [.v5]`, podspec Swift 5.0) | -| Build | Swift Package Manager; CocoaPods via `ContentstackUtils.podspec`; optional Xcode `ContentstackUtils.xcodeproj` | -| HTML/XML | Vendored **Kanna** under `Sources/Kanna/`, **libxml2** (`Modules/`, system on Apple platforms) | -| Tests | **XCTest**, target `ContentstackUtilsTests`, path `Tests/ContentstackUtilsTests/` | -| Lint | **SwiftLint** (`.swiftlint.yml`) | -| Coverage | **Slather** (`.slather.yml`, Cobertura, scheme `ContentstackUtils-Package`) | - -## Main entry points (paths and symbols) - -| What | Where | -|------|--------| -| Public API surface | `Sources/ContentstackUtils/ContentstackUtils.swift` — `struct ContentstackUtils` (`render`, `jsonToHtml`, `getVariantAliases`, nested `GQL`, `VariantUtilityError`) | -| Rendering options | `Sources/ContentstackUtils/Option.swift` — `open class Option`, `Renderable` | -| RTE JSON model | `Sources/ContentstackUtils/Node.swift`, `JSONNode.swift`, `JSONNodes.swift`, `MarkType.swift`, `Metadata.swift`, … | -| Tests | `Tests/ContentstackUtilsTests/*.swift` (e.g. `ContentstackUtilsTests.swift`, `VariantUtilityTests.swift`, `GQLJsonToHtml.swift`) | -| Package manifest | `Package.swift` — product `ContentstackUtils`, targets `ContentstackUtils`, `ContentstackUtilsTests`, system `libxml2` | - -Consumers typically: `import ContentstackUtils`, create an `Option` (or subclass), call `ContentstackUtils.render(content:_:)` or `ContentstackUtils.jsonToHtml(node:_:)` / `ContentstackUtils.GQL.jsonToHtml(rte:_:)`. - -## Commands (build / test / lint) - -```bash -swift build -swift test -swiftlint -``` - -CI-style Xcode test (see `.github/workflows/ci.yml`): - -```bash -xcodebuild -project "ContentstackUtils.xcodeproj" -scheme "ContentstackUtils-Package" -destination "OS=13.4.1,name=iPhone 11 Pro" test -``` - -CocoaPods consumption: `pod 'ContentstackUtils', '~> …'` (see `README.md` and `ContentstackUtils.podspec` for current version). - -## Cursor rules (`.cursor/rules/`) - -| Resource | Role | -|----------|------| -| `.cursor/rules/README.md` | Index of rule files and globs | -| `.cursor/rules/dev-workflow.md` | Branches (`master` / `next` / `staging` expectations), CI parity, PR notes | -| `swift-style.mdc` | Swift + repo style | -| `contentstack-utils-sdk.mdc` | SDK-specific patterns under `Sources/ContentstackUtils/` | -| `tests.mdc` | Test layout and conventions | -| `code-review.mdc` | Always-on PR checklist | - -## Skills (`skills/`) - -Reusable guidance for agents lives under `skills//SKILL.md`. See `skills/README.md` for a table of when to use each skill. Typical uses: public API and integration boundaries (`contentstack-utils-api`), XCTest and fixtures (`contentstack-utils-testing`), review criteria (`contentstack-utils-code-review`), libxml/Kanna/SPM platforms (`contentstack-utils-platform`). - -## Official docs (external) - -- Product: [Contentstack](https://www.contentstack.com/) -- Swift usage examples in this repo: `README.md` +- **Language:** Swift 5 (`Package.swift` `swiftLanguageVersions: [.v5]`, podspec Swift 5.0) +- **Build:** Swift Package Manager; CocoaPods (`ContentstackUtils.podspec`); Xcode `ContentstackUtils.xcodeproj` +- **Testing:** XCTest, target `ContentstackUtilsTests`, path `Tests/ContentstackUtilsTests/` +- **Lint / coverage:** SwiftLint (`.swiftlint.yml`), Slather (`.slather.yml`, scheme `ContentstackUtils-Package`) +- **HTML/XML:** Vendored **Kanna** (`Sources/Kanna/`), **libxml2** via `Modules/` (system on Apple platforms) + +## Main entry points + +- **`ContentstackUtils`** – `Sources/ContentstackUtils/ContentstackUtils.swift`: `render`, `jsonToHtml`, `getVariantAliases`, nested **`GQL`**, **`VariantUtilityError`** +- **`Option` / `Renderable`** – `Sources/ContentstackUtils/Option.swift`: customize HTML for marks, nodes, embedded items +- **RTE model types** – `Node.swift`, `JSONNode.swift`, `JSONNodes.swift`, `MarkType.swift`, `Metadata.swift`, and related files under `Sources/ContentstackUtils/` +- **Tests** – `Tests/ContentstackUtilsTests/*.swift` +- **Package** – `Package.swift`: product `ContentstackUtils`, targets `ContentstackUtils`, `ContentstackUtilsTests`, system `libxml2` + +## Commands + +- **Build and test:** `swift build` && `swift test` +- **Lint:** `swiftlint` +- **CI-style Xcode test:** + `xcodebuild -project "ContentstackUtils.xcodeproj" -scheme "ContentstackUtils-Package" -destination "OS=13.4.1,name=iPhone 11 Pro" test` + +CocoaPods: `pod 'ContentstackUtils', '~> …'` (see `README.md` and `ContentstackUtils.podspec` for the current version). + +## Rules and skills + +- **`.cursor/rules/`** – Cursor rules for this repo: + - **README.md** – Index of all rules and how globs apply. + - **dev-workflow.md** – Development workflow (branches, tests, lint, PRs). + - **swift-style.mdc** – Applies to `**/*.swift`: SwiftLint, layout, Kanna/libxml2, platforms. + - **contentstack-utils-sdk.mdc** – Applies to `Sources/ContentstackUtils/**/*.swift`: Utils SDK patterns, `Option`, RTE/GQL, variants. + - **testing.mdc** – Applies to `Tests/**/*.swift`: XCTest, mocks, fixtures, coverage. + - **code-review.mdc** – Always applied: PR/review checklist. +- **`skills/`** – Reusable skill docs: + - Use **contentstack-utils** when implementing or changing public API, RTE rendering, or GQL JSON entry points. + - Use **testing** when adding or refactoring tests. + - Use **code-review** when reviewing PRs or before opening one. + - Use **framework** when changing SPM/libxml2, Kanna vendoring, deployment targets, or CocoaPods packaging. + +Refer to `.cursor/rules/README.md` for when each rule applies and to `skills/README.md` for skill details. diff --git a/skills/README.md b/skills/README.md index 0c6cfe3..d113569 100644 --- a/skills/README.md +++ b/skills/README.md @@ -1,10 +1,21 @@ -# Agent skills (Contentstack Utils Swift) +# Skills – Contentstack Utils Swift -Skills are reusable instruction sets for AI agents. Each skill is a folder containing `SKILL.md` with YAML frontmatter (`name`, `description`). +This directory contains **skills**: reusable guidance for AI agents (and developers) on specific tasks. Each skill is a folder with a `SKILL.md` file (YAML frontmatter: `name`, `description`). -| Skill folder | When to use it | -|--------------|----------------| -| `contentstack-utils-api` | Changing or documenting public API, `ContentstackUtils` / `Option` / RTE JSON types, GQL JSON entry points, errors, semver impact. | -| `contentstack-utils-testing` | Adding or fixing XCTest tests, mocks, JSON fixtures, `swift test` / Xcode test workflow. | -| `contentstack-utils-code-review` | Structured PR review with severity (blocker/major/minor) aligned with this SDK. | -| `contentstack-utils-platform` | libxml2, Kanna vendoring, SPM targets, deployment platforms, `Modules/`, Linux vs Apple differences. | +## When to use which skill + +| Skill | Use when | +|-------|----------| +| **contentstack-utils** | Implementing or changing Utils features: `ContentstackUtils`, `Option` / `Renderable`, RTE/JSON models, GQL helpers, variant APIs, errors, documentation and semver. | +| **testing** | Writing or refactoring tests: XCTest, `swift test`, Xcode scheme, mocks, fixtures, SwiftLint/Slather, offline fixtures. | +| **code-review** | Reviewing a PR or preparing your own: API design, errors, backward compatibility, dependencies/security, test coverage, severity (blocker/major/minor). | +| **framework** | Touching SPM layout, `libxml2` / `Modules/`, vendored Kanna, deployment targets, or `ContentstackUtils.podspec` / CI `xcodebuild` assumptions. | + +## How agents should use skills + +- **contentstack-utils:** Apply when editing `Sources/ContentstackUtils/` or documenting public behavior. Do not add hard dependencies on the main Contentstack iOS SDK or Apollo unless product requires it and `Package.swift` is updated deliberately. +- **testing:** Apply when creating or modifying files under `Tests/ContentstackUtilsTests/`. Follow existing mocks and fixtures; keep tests credential-free. +- **code-review:** Apply when performing or simulating a PR review. Work through `.cursor/rules/code-review.mdc` and optionally tag findings by severity. +- **framework:** Apply when changing `Package.swift`, `Modules/`, `Sources/Kanna/`, or podspec—keep Apple vs Linux libxml behavior and CI destinations in mind. + +Each skill’s `SKILL.md` contains more detailed instructions and references. diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md new file mode 100644 index 0000000..4a54ba8 --- /dev/null +++ b/skills/code-review/SKILL.md @@ -0,0 +1,56 @@ +--- +name: code-review +description: Use when reviewing PRs or before opening a PR—API design, errors, backward compatibility, dependencies, security, and test quality. +--- + +# Code Review – Contentstack Utils Swift + +## When to use + +- Reviewing someone else’s PR. +- Self-reviewing before submission. +- Checking that changes meet project standards (API, errors, compatibility, tests, security). + +## Instructions + +Work through the checklist in `.cursor/rules/code-review.mdc`. Optionally tag items with severity: **Blocker**, **Major**, **Minor**. + +### 1. API design and stability + +- [ ] **Public API:** New or changed `public` / `open` surface is necessary and documented (`README` / `CHANGELOG` as appropriate). +- [ ] **Backward compatibility:** No breaking changes unless agreed (e.g. major version). Call out deprecations and alternatives. +- [ ] **Naming:** Consistent with existing Utils and RTE terminology (`ContentstackUtils`, `Option`, `Node`, `GQL`). + +**Severity:** Breaking public API without approval = Blocker. Missing docs on new public API = Major. + +### 2. Error handling and robustness + +- [ ] **Errors:** Domain failures use clear types; `throws` is used where callers need to recover or log. +- [ ] **Optionals:** No unintended force-unwraps on public paths. + +**Severity:** Wrong or missing error handling in new code = Major. + +### 3. Dependencies and security + +- [ ] **Dependencies:** `Package.swift` / podspec changes are justified; versions do not introduce known vulnerabilities. +- [ ] **SCA:** Security findings (e.g. Snyk) in scope are addressed or deferred with a ticket. + +**Severity:** New critical/high vulnerability = Blocker. + +### 4. Testing + +- [ ] **Coverage:** New or modified behavior has corresponding tests under `Tests/ContentstackUtilsTests/` when feasible. +- [ ] **Quality:** Tests are readable and deterministic. + +**Severity:** No tests for new behavior where tests are practical = Blocker. Flaky tests = Major. + +### 5. Optional severity summary + +- **Blocker:** Must fix before merge (e.g. breaking API without approval, security issue, missing tests). +- **Major:** Should fix (e.g. inconsistent errors, broken README examples). +- **Minor:** Nice to fix (e.g. style, minor docs). + +## References + +- Project rule: `.cursor/rules/code-review.mdc` +- Testing skill: `skills/testing/SKILL.md` diff --git a/skills/contentstack-utils-api/SKILL.md b/skills/contentstack-utils-api/SKILL.md deleted file mode 100644 index 3e75bbf..0000000 --- a/skills/contentstack-utils-api/SKILL.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -name: contentstack-utils-api -description: Public API for ContentstackUtils Swift—rendering, Option/Renderable, GQL JSON, variants, errors; no bundled HTTP client. ---- - -# Contentstack Utils — public API skill - -## Scope - -This package exposes **HTML/RTE rendering** and **variant alias** helpers. It does **not** ship Stack configuration, API keys, or network clients. - -## Core types - -- **`ContentstackUtils`** (`Sources/ContentstackUtils/ContentstackUtils.swift`): static methods `render(content:_:)`, `render(contents:_:)`, `jsonToHtml` overloads, `getVariantAliases`, nested **`GQL`** with `jsonToHtml(rte:_:)` for GraphQL-shaped dictionaries. -- **`Option`** (`Option.swift`): open class; override `renderItem`, `renderMark`, `renderNode` for custom HTML. Implements **`Renderable`**. -- **RTE JSON:** `Node`, `JSONNode`, `JSONNodes`, `MarkType`, `StyleType`, `Metadata`, embedded models — keep decoding tolerant and documented when stack payloads evolve. - -## Errors - -- Use **`ContentstackUtils.VariantUtilityError`** (and similar nested types) for domain failures; prefer `throws` over optional soup for invalid variant input. - -## Integration boundary - -- README shows **`Contentstack.stack`**, **`fetch`**, and **Apollo** as **examples only**. Do not add hard dependencies on the main Contentstack iOS SDK or Apollo in `Package.swift` unless product explicitly requires it. - -## Docs and versioning - -- Update **`README.md`** and **`CHANGELOG.md`** for behavior users see. Align **`ContentstackUtils.podspec`** version with releases. Follow semver for `public`/`open` changes. - -## Reference - -- [Contentstack](https://www.contentstack.com/) — product home; Delivery API docs apply to how apps fetch data before calling this library. diff --git a/skills/contentstack-utils-code-review/SKILL.md b/skills/contentstack-utils-code-review/SKILL.md deleted file mode 100644 index 5dcd133..0000000 --- a/skills/contentstack-utils-code-review/SKILL.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -name: contentstack-utils-code-review -description: PR review for contentstack-utils-swift—severity-rated checks for API, docs, errors, compatibility, deps, tests. ---- - -# Contentstack Utils — code review skill - -Use this skill to review changes consistently with `.cursor/rules/code-review.mdc`, with explicit **severity**. - -## Blocker - -- Breaks **`public`/`open`** API without semver/CHANGELOG/podspec alignment. -- Removes or weakens handling of RTE JSON shapes that existing apps rely on (without migration notes). -- New dependencies in **`Package.swift`** / **podspec** without security/license review when org requires it. -- **No tests** for clear behavioral fixes or new features in `Sources/ContentstackUtils/` when tests are practical. - -## Major - -- **`throws` / error** changes that confuse callers (wrong type, message, or non-throwing to throwing without version bump). -- **Kanna** or **`Modules/libxml2`** edits that diverge from upstream without documentation or break Linux/Apple builds. -- **README** examples that no longer compile against the actual API. - -## Minor - -- Style-only issues fixable by SwiftLint; internal naming; comment clarity. -- Test naming or fixture organization improvements without functional gaps. - -## Always verify - -- `swift build` / `swift test` (and Xcode scheme if touching iOS-specific paths). -- SwiftLint clean for edited files (respect exclusions). -- Backward compatibility for default **`Option()`** rendering paths. diff --git a/skills/contentstack-utils-platform/SKILL.md b/skills/contentstack-utils-platform/SKILL.md deleted file mode 100644 index 3197b68..0000000 --- a/skills/contentstack-utils-platform/SKILL.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -name: contentstack-utils-platform -description: Build/runtime stack for ContentstackUtils—SPM targets, libxml2, vendored Kanna, Apple vs Linux, deployment targets. ---- - -# Contentstack Utils — platform and runtime skill - -## Swift Package Manager - -- **`Package.swift`:** Product **`ContentstackUtils`**; targets **`ContentstackUtils`** (sources `Sources/`), **`ContentstackUtilsTests`**, system library **`libxml2`** pointing at **`Modules/`**. -- **Conditional dependencies:** On Swift ≥5.3 and non-Linux Apple platforms, `ContentstackUtils` may omit the explicit `libxml2` target dependency; Linux uses `pkg-config` / `libxml-2.0` and apt providers as declared. - -## Vendored Kanna - -- HTML parsing lives under **`Sources/Kanna/`**. SwiftLint excludes this path globally—changes here are infrequent and should stay aligned with intentional vendoring updates. - -## Platforms - -- **Declared:** macOS 10.13+, iOS/tvOS 11+, watchOS 4+ (`Package.swift` / podspec). Do not use newer SDK APIs without availability checks or raising deployment targets deliberately. - -## CocoaPods - -- **`ContentstackUtils.podspec`:** `source_files` `Sources/**/*.{swift}`, `HEADER_SEARCH_PATHS` / `-lxml2` for libxml. Pod releases must match tagged source layout. - -## CI note - -- GitHub Actions uses **Xcode** and **xcodebuild** for iOS Simulator tests; local SPM `swift test` may differ slightly—run both when changing low-level parsing or linking. diff --git a/skills/contentstack-utils-testing/SKILL.md b/skills/contentstack-utils-testing/SKILL.md deleted file mode 100644 index 55a3187..0000000 --- a/skills/contentstack-utils-testing/SKILL.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -name: contentstack-utils-testing -description: XCTest setup for ContentstackUtilsTests—swift test, Xcode scheme, mocks, fixtures, Slather/SwiftLint notes. ---- - -# Contentstack Utils — testing skill - -## Runner - -- **SPM:** `swift test` from repository root (target `ContentstackUtilsTests`). -- **Xcode:** Scheme **`ContentstackUtils-Package`**, project **`ContentstackUtils.xcodeproj`** — matches `.github/workflows/ci.yml` (`xcodebuild` + iOS Simulator destination). - -## Layout - -- Tests live under **`Tests/ContentstackUtilsTests/`** with names like `*Tests.swift`, `*Test.swift`, or feature files (`GQLJsonToHtml.swift`, `DefaultRenderTests.swift`). -- Reuse mocks: `CustomRenderOptionMock.swift`, `EmbededModelMock.swift`, `TestClient.swift`, JSON helpers in `JsonNodes.swift` / `JsonNodesHtmlResults.swift`. - -## Lint and coverage - -- **SwiftLint:** `.swiftlint.yml` excludes `Tests/ContentstackUtilsTests/Constants.swift` only; other test files are linted. -- **Slather:** `.slather.yml` ignores all of `Tests/*` from coverage reporting; source ignores include Kanna and specific files—see config when interpreting coverage. - -## Credentials - -- Tests are **offline** (no live API keys). Do not commit secrets; keep fixtures static JSON/Swift literals. - -## Linux - -- If extending Linux CI, maintain **`XCTestManifests.swift`** as needed for test discovery on Linux. diff --git a/skills/contentstack-utils/SKILL.md b/skills/contentstack-utils/SKILL.md new file mode 100644 index 0000000..8a327f8 --- /dev/null +++ b/skills/contentstack-utils/SKILL.md @@ -0,0 +1,39 @@ +--- +name: contentstack-utils +description: Use when changing ContentstackUtils Swift public API—rendering, Option/Renderable, GQL JSON, variants, errors; no bundled HTTP client. +--- + +# Contentstack Utils – SDK skill + +## When to use + +- Implementing or changing RTE/HTML rendering, JSON RTE parsing, or variant helpers. +- Updating `README.md` / `CHANGELOG.md` / podspec for user-visible behavior. +- Assessing semver impact of `public` / `open` changes. + +## Instructions + +This package exposes **HTML/RTE rendering** and **variant alias** helpers. It does **not** ship Stack configuration, API keys, or network clients. + +### Core types + +- **`ContentstackUtils`** (`Sources/ContentstackUtils/ContentstackUtils.swift`): `render(content:_:)`, `render(contents:_:)`, `jsonToHtml` overloads, `getVariantAliases`, nested **`GQL`** with `jsonToHtml(rte:_:)` for GraphQL-shaped dictionaries. +- **`Option`** (`Option.swift`): open class; override `renderItem`, `renderMark`, `renderNode`. Implements **`Renderable`**. +- **RTE JSON:** `Node`, `JSONNode`, `JSONNodes`, `MarkType`, `StyleType`, `Metadata`, embedded models—keep decoding aligned with stack payloads. + +### Errors + +- Use **`ContentstackUtils.VariantUtilityError`** (and similar nested types) for domain failures; prefer `throws` over opaque optionals for invalid variant input. + +### Integration boundary + +- README examples using **`Contentstack.stack`**, **`fetch`**, or **Apollo** are illustrative only—do not add those as package dependencies without an explicit product decision. + +### Docs and versioning + +- Align **`ContentstackUtils.podspec`** and tags with releases. Follow semver for `public` / `open` changes. + +## References + +- Project rule: `.cursor/rules/contentstack-utils-sdk.mdc` +- Product: [Contentstack](https://www.contentstack.com/) diff --git a/skills/framework/SKILL.md b/skills/framework/SKILL.md new file mode 100644 index 0000000..42304ea --- /dev/null +++ b/skills/framework/SKILL.md @@ -0,0 +1,36 @@ +--- +name: framework +description: Use when changing SPM, libxml2 Modules, vendored Kanna, deployment targets, CocoaPods, or CI xcodebuild setup. +--- + +# Framework – Contentstack Utils Swift + +## When to use + +- Editing `Package.swift`, `Modules/`, or `Sources/Kanna/`. +- Changing iOS/macOS/tvOS/watchOS deployment targets or conditional libxml linking. +- Updating `ContentstackUtils.podspec` or CI Xcode destination/scheme assumptions. + +## Instructions + +### Swift Package Manager + +- **Product:** `ContentstackUtils`; **targets:** `ContentstackUtils`, `ContentstackUtilsTests`, system **`libxml2`** → **`Modules/`**. +- **Platforms:** Apple vs Linux: conditional `libxml2` dependency and `pkg-config` as in `Package.swift`—preserve behavior when refactoring. + +### Vendored Kanna + +- **`Sources/Kanna/`** is excluded from SwiftLint; treat updates as intentional vendoring work (licensing, diffs, cross-platform build). + +### CocoaPods + +- **`ContentstackUtils.podspec`:** `source_files` `Sources/**/*.{swift}`, header search and `-lxml2` for libxml—keep in sync with SPM layout. + +### CI + +- GitHub Actions uses **xcodebuild** with `ContentstackUtils-Package`; validate low-level changes with both `swift test` and Xcode builds when touching parsing or linking. + +## References + +- Project rule: `.cursor/rules/swift-style.mdc` +- Workflow: `.cursor/rules/dev-workflow.md` diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md new file mode 100644 index 0000000..794c79b --- /dev/null +++ b/skills/testing/SKILL.md @@ -0,0 +1,24 @@ +--- +name: testing +description: Use when writing or refactoring tests—XCTest, swift test, Xcode scheme, mocks, fixtures, Slather/SwiftLint. +--- + +# Testing – Contentstack Utils Swift + +## When to use + +- Adding or changing tests under `Tests/ContentstackUtilsTests/`. +- Debugging flaky or slow tests; improving fixtures or mocks. + +## Instructions + +- **Run:** `swift test` from repo root; use Xcode scheme **`ContentstackUtils-Package`** and `ContentstackUtils.xcodeproj` to mirror `.github/workflows/ci.yml`. +- **Layout:** Files such as `*Tests.swift`, `*Test.swift`, or feature files (`GQLJsonToHtml.swift`, `DefaultRenderTests.swift`). Reuse `CustomRenderOptionMock.swift`, `EmbededModelMock.swift`, `TestClient.swift`, `JsonNodes.swift`, `JsonNodesHtmlResults.swift`. +- **Lint:** `.swiftlint.yml` excludes only `Tests/ContentstackUtilsTests/Constants.swift` from SwiftLint. +- **Coverage:** Slather ignores `Tests/*` in reports; still add tests for new production behavior in `Sources/ContentstackUtils/` when practical. +- **Secrets:** Tests stay **offline**—no API keys or `.env` in CI. + +## References + +- Project rule: `.cursor/rules/testing.mdc` +- Workflow: `.cursor/rules/dev-workflow.md` From 23052d10db37c7a9529cb10454c9534db1f26cb8 Mon Sep 17 00:00:00 2001 From: reeshika-h Date: Mon, 6 Apr 2026 11:47:59 +0530 Subject: [PATCH 3/4] Refactoring skills and agents.md --- .cursor/rules/README.md | 24 +------- .cursor/rules/code-review.mdc | 40 ------------ .cursor/rules/contentstack-utils-sdk.mdc | 14 ----- .cursor/rules/dev-workflow.md | 39 ------------ .cursor/rules/swift-style.mdc | 14 ----- .cursor/rules/testing.mdc | 28 --------- AGENTS.md | 77 ++++++++++++------------ skills/README.md | 26 ++++---- skills/code-review/SKILL.md | 62 ++++++++++--------- skills/contentstack-utils/SKILL.md | 46 +++++++++----- skills/dev-workflow/SKILL.md | 51 ++++++++++++++++ skills/framework/SKILL.md | 35 ++++++----- skills/swift-style/SKILL.md | 41 +++++++++++++ skills/testing/SKILL.md | 36 ++++++++--- 14 files changed, 256 insertions(+), 277 deletions(-) delete mode 100644 .cursor/rules/code-review.mdc delete mode 100644 .cursor/rules/contentstack-utils-sdk.mdc delete mode 100644 .cursor/rules/dev-workflow.md delete mode 100644 .cursor/rules/swift-style.mdc delete mode 100644 .cursor/rules/testing.mdc create mode 100644 skills/dev-workflow/SKILL.md create mode 100644 skills/swift-style/SKILL.md diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md index ff835d2..0c75565 100644 --- a/.cursor/rules/README.md +++ b/.cursor/rules/README.md @@ -1,23 +1,5 @@ -# Cursor Rules – Contentstack Utils Swift +# Cursor (optional) -This directory contains Cursor AI rules that apply when working in this repository. Rules provide persistent context so the AI follows project conventions and Contentstack Utils (RTE rendering) patterns. +**Cursor** users: start at the repo root **[`AGENTS.md`](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`** (universal for any editor or tool). -## How rules are applied - -- **File-specific rules** use the `globs` frontmatter: they apply when you open or edit files matching that pattern. -- **Always-on rules** use `alwaysApply: true`: they are included in every conversation in this project. - -## Rule index - -| File | Applies when | Purpose | -|------|----------------|---------| -| **dev-workflow.md** | (Reference only; no glob) | Core development workflow: branches, running tests, lint, PR expectations. Read for process guidance. | -| **swift-style.mdc** | Editing any `**/*.swift` file | Swift standards: SwiftLint, package layout, Kanna/libxml2, platforms, access control. | -| **contentstack-utils-sdk.mdc** | Editing `Sources/ContentstackUtils/**/*.swift` | Utils SDK patterns: `ContentstackUtils`, `Option` / `Renderable`, RTE/JSON models, GQL helpers, variants, errors. | -| **testing.mdc** | Editing `Tests/**/*.swift` | XCTest layout, mocks, fixtures, SwiftLint/Slather, offline tests. | -| **code-review.mdc** | Always | PR/review checklist: API stability, documentation, error handling, backward compatibility, dependencies and security (e.g. SCA), tests. | - -## Related - -- **AGENTS.md** (repo root) – Main entry point for AI agents: project overview, entry points, and pointers to rules and skills. -- **skills/** – Reusable skill docs (`contentstack-utils`, `testing`, `code-review`, `framework`) for deeper guidance on specific tasks. +This folder only points contributors here so nothing editor-specific duplicates the canonical docs. diff --git a/.cursor/rules/code-review.mdc b/.cursor/rules/code-review.mdc deleted file mode 100644 index f595b75..0000000 --- a/.cursor/rules/code-review.mdc +++ /dev/null @@ -1,40 +0,0 @@ ---- -description: PR and code review checklist – API stability, docs, errors, compatibility, security, tests -alwaysApply: true ---- - -# Code Review Checklist – Contentstack Utils Swift - -Use this checklist when reviewing pull requests or before opening a PR. - -## API design and stability - -- [ ] **Public API:** New or changed `public` / `open` types in `Sources/ContentstackUtils/` are necessary, semver-conscious, and documented (`README.md` / `CHANGELOG.md` when user-visible). -- [ ] **Backward compatibility:** No breaking changes to public API unless explicitly called out and justified (e.g. major version). Prefer additive behavior and default `Option()` paths. -- [ ] **Naming:** Method and type names match existing Utils style and Contentstack RTE terminology (`ContentstackUtils`, `Option`, `Node`, `GQL`, etc.). - -## Error handling and robustness - -- [ ] **Errors:** New `throws` paths use clear domain types (e.g. `VariantUtilityError`); callers can distinguish invalid input from parsing failures where relevant. -- [ ] **Optionals:** Avoid force-unwraps on public code paths; document preconditions for non-optional parameters. -- [ ] **RTE JSON:** Decoding and HTML traversal stay tolerant of documented stack payload shapes; regressions in embedded-item handling are called out. - -## Dependencies and security - -- [ ] **Dependencies:** Changes to `Package.swift` or `ContentstackUtils.podspec` are justified; version bumps do not introduce known vulnerabilities. -- [ ] **SCA:** Address any security findings (e.g. from Snyk or org scanners) in the PR scope or via an agreed follow-up. - -## Testing - -- [ ] **Coverage:** New or modified behavior in `Sources/ContentstackUtils/` is covered by tests under `Tests/ContentstackUtilsTests/` when feasible. -- [ ] **Test quality:** Tests are readable, deterministic, and follow project naming (`*Tests.swift`, mocks, fixtures). - -## Vendored and native code - -- [ ] **Kanna / libxml2 / `Modules/`:** Changes are reviewed for upstream parity, licensing, and cross-platform builds (Apple vs Linux). - -## Severity (optional) - -- **Blocker:** Must fix before merge (e.g. breaking public API without approval, security issue, no tests for new code where tests are practical). -- **Major:** Should fix (e.g. inconsistent error handling, README examples that do not compile). -- **Minor:** Nice to fix (e.g. style, minor docs). diff --git a/.cursor/rules/contentstack-utils-sdk.mdc b/.cursor/rules/contentstack-utils-sdk.mdc deleted file mode 100644 index e6a5c2c..0000000 --- a/.cursor/rules/contentstack-utils-sdk.mdc +++ /dev/null @@ -1,14 +0,0 @@ ---- -description: ContentstackUtils public SDK patterns—RTE rendering, Option/Renderable, GQL JSON, variants. -globs: "Sources/ContentstackUtils/**/*.swift" ---- - -# ContentstackUtils SDK patterns - -- **Main entry:** Consumers `import ContentstackUtils` and use `ContentstackUtils` (e.g. `render(content:_:)`, `render(contents:_:)`, `jsonToHtml(node:_:)`, `getVariantAliases`, `GQL.jsonToHtml(rte:_:)`). Keep static surface small and documented; breaking changes require semver and changelog notes. -- **Customization:** Subclass or replace behavior via `Option` (open class) implementing `Renderable`—`renderItem(embeddedObject:metadata:)`, `renderMark(markType:text:)`, `renderNode(nodeType:node:next:)`. Do not remove or rename open hooks without a major version. -- **Data model:** RTE JSON uses types such as `Node`, `JSONNode`/`JSONNodes`, `MarkType`, `StyleType`, `Metadata`, and embedded entry/asset types (`EmbeddedObject`, `EmbeddedEntry`, etc.). Preserve `Codable`/decoding compatibility with Contentstack Delivery/GraphQL payloads. -- **Errors:** Expose domain errors as nested types where appropriate (e.g. `ContentstackUtils.VariantUtilityError.invalidArgument`). Use `throws` for recoverable failures; avoid force-unwraps in public paths. -- **HTML:** Rendering uses Kanna/HTML under the hood; output should remain safe and predictable for documented inputs. Document any new node types or GQL JSON shapes in README/CHANGELOG. -- **No network layer:** This package does not ship HTTP clients or tokens. README examples that show `Stack`, `fetch`, or Apollo are integration sketches—do not add hard dependencies on Contentstack’s main iOS SDK or Apollo inside this library unless the product owner requests it and `Package.swift` is updated. -- **Typos in legacy API:** Some property names (e.g. `embdeddedItems`) are entrenched; changing them is a breaking API change—coordinate with maintainers. diff --git a/.cursor/rules/dev-workflow.md b/.cursor/rules/dev-workflow.md deleted file mode 100644 index f19779f..0000000 --- a/.cursor/rules/dev-workflow.md +++ /dev/null @@ -1,39 +0,0 @@ -# Development Workflow – Contentstack Utils Swift - -Use this as the standard workflow when contributing to Contentstack Utils Swift. - -## Branches - -- Use feature branches for changes (e.g. `feat/...`, `fix/...`, ticket branches like `DX-5372-cursor`). -- **CI** runs on push to `master` and on pull requests targeting `master` or `next` (see `.github/workflows/ci.yml`). -- **Merges into `master`** may be gated: PRs whose base is `master` are expected to come from the `staging` branch; other head branches may be blocked (see `.github/workflows/check-branch.yml`). Confirm with your team’s release process before opening PRs to `master`. - -## Running tests - -- **All tests (SPM):** `swift test` -- **Build:** `swift build` -- **CI-style Xcode (iOS Simulator):** - `xcodebuild -project "ContentstackUtils.xcodeproj" -scheme "ContentstackUtils-Package" -destination "OS=13.4.1,name=iPhone 11 Pro" test` - Adjust `-destination` for your local Xcode/Simulator. - -Run tests before opening a PR. Integration-style behavior is covered with **offline** mocks and fixtures—no `.env` or live stack credentials required for the default test suite. - -## Lint - -- **SwiftLint:** `swiftlint` (config `.swiftlint.yml`) - -## Pull requests - -- Ensure the build passes: `swift build` and `swift test` (and/or `xcodebuild` if you touch Xcode-specific paths). -- Follow the **code-review** rule (see `.cursor/rules/code-review.mdc`) for the PR checklist. -- Keep changes backward-compatible for public API; call out any breaking changes clearly. -- Describe behavior changes and semver impact; update `CHANGELOG.md` and version metadata (`ContentstackUtils.podspec`, tags) when releasing—per team process. -- Security/policy scans may run in CI (`.github/workflows/sca-scan.yml`, `policy-scan.yml`); fix findings per org policy. - -## Optional: TDD - -If the team uses TDD, follow RED–GREEN–REFACTOR when adding behavior: write a failing test first, implement to pass, then refactor. The **testing** rule and **skills/testing** skill describe test structure and naming. - -## Coverage - -- **Slather** is configured in `.slather.yml` (scheme `ContentstackUtils-Package`). Use after tests to inspect coverage of `Sources/ContentstackUtils/`. diff --git a/.cursor/rules/swift-style.mdc b/.cursor/rules/swift-style.mdc deleted file mode 100644 index 0f20cea..0000000 --- a/.cursor/rules/swift-style.mdc +++ /dev/null @@ -1,14 +0,0 @@ ---- -description: Swift style and project conventions for all Swift sources (SwiftLint, layout, vendored Kanna). -globs: "**/*.swift" ---- - -# Swift style (this repo) - -- **Tooling:** Run SwiftLint using `.swiftlint.yml`. Do not weaken rules for new code without team agreement; `Sources/Kanna` is excluded upstream—avoid copying patterns that would fail lint in `Sources/ContentstackUtils/`. -- **Package layout:** Library code lives under `Sources/ContentstackUtils/`. Vendored **Kanna** lives under `Sources/Kanna/`; treat it as third-party unless explicitly updating the fork—prefer fixes in `ContentstackUtils` or documented Kanna upgrades. -- **Platforms:** The package supports macOS 10.13+, iOS/tvOS 11+, watchOS 4+ (`Package.swift`). Avoid APIs that break the declared deployment targets without bumping them deliberately. -- **libxml2:** Non-Linux Apple platforms use system libxml; Linux uses the `libxml2` system target and `pkg-config`. Keep `Modules/` and conditional compilation in sync with `Package.swift` when changing platform support. -- **Naming:** Follow existing Swift naming (types `UpperCamelCase`, members `lowerCamelCase`). Preserve established public names even if imperfect (e.g. historical typos in protocol/API) unless doing a semver-major cleanup. -- **Imports:** `import Foundation` where needed; HTML parsing goes through Kanna types re-exported/used from this package’s structure—follow existing files. -- **Access control:** Mark public API `public`/`open` intentionally; keep implementation details `internal` or `private` unless cross-target tests require `@testable` patterns already in use. diff --git a/.cursor/rules/testing.mdc b/.cursor/rules/testing.mdc deleted file mode 100644 index 8c6582a..0000000 --- a/.cursor/rules/testing.mdc +++ /dev/null @@ -1,28 +0,0 @@ ---- -description: XCTest patterns for ContentstackUtilsTests—naming, mocks, fixtures, Slather, SwiftLint exclusions. -globs: "Tests/**/*.swift" ---- - -# Testing Rules – Contentstack Utils Swift - -Apply when writing or editing tests. The project uses **XCTest** and **SwiftLint** (see `.swiftlint.yml`); coverage is reported with **Slather** (see `.slather.yml`). - -## Test naming and layout - -- **Target:** `ContentstackUtilsTests`; path **`Tests/ContentstackUtilsTests/`**. -- **File names:** `*Tests.swift`, `*Test.swift`, or feature-oriented names (`GQLJsonToHtml.swift`, `JsonNodes.swift`, `VariantUtilityTests.swift`). -- **Fixtures and mocks:** Reuse `JsonNodes.swift`, `JsonNodesHtmlResults.swift`, `EmbededModelMock.swift`, `CustomRenderOptionMock.swift`, `TestClient.swift`, etc., before adding parallel helpers. - -## XCTest usage - -- Run tests via **`swift test`** (SPM) and/or Xcode scheme **`ContentstackUtils-Package`** (`ContentstackUtils.xcodeproj`), matching CI (`.github/workflows/ci.yml`). -- This repo does **not** split integration tests into a separate tree; use mocks for API-shaped payloads—**no live network** or credentials in CI. - -## SwiftLint and coverage - -- **`Tests/ContentstackUtilsTests/Constants.swift`** is excluded from SwiftLint; other test files are linted. -- **Slather** ignores `Tests/*` in reports; new production code under `Sources/ContentstackUtils/` should still gain tests when practical. - -## Linux / discovery - -- Maintain **`XCTestManifests.swift`** if your workflow requires explicit Linux test discovery. diff --git a/AGENTS.md b/AGENTS.md index 8bec49f..e172364 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,50 +1,53 @@ -# Contentstack Utils Swift – Agent Guide +# Contentstack Utils Swift – Agent guide -This document is the main entry point for AI agents working in this repository. +**Universal entry point** for anyone automating or assisting work in this repo—AI agents (Cursor, Copilot, CLI tools), reviewers, and contributors. Conventions and detailed guidance live in **`skills/*/SKILL.md`**, not in editor-specific config, so the same instructions apply whether or not you use Cursor. -## Project +## What this repo is -- **Name:** Contentstack Utils Swift ([contentstack-utils-swift](https://github.com/contentstack/contentstack-utils-swift)) -- **Purpose:** Swift library for rendering Contentstack **RTE** (rich text) and related JSON to HTML, with hooks for embedded entries/assets and helpers for **variant** metadata. It does **not** implement Contentstack HTTP clients; apps fetch content with the [Content Delivery / Swift SDK](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/swift) or other clients, then pass strings or dictionaries into this package. +- **Name:** [contentstack-utils-swift](https://github.com/contentstack/contentstack-utils-swift) +- **Purpose:** Swift library that renders Contentstack **RTE** (rich text) and related JSON to HTML, with hooks for embedded entries/assets and helpers for **variant** metadata. +- **Out of scope:** This package does **not** ship HTTP clients or stack credentials. Apps fetch content with the [Content Delivery / Swift SDK](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/swift) (or other clients), then pass strings or dictionaries into ContentstackUtils. -## Tech stack +## Tech stack (at a glance) -- **Language:** Swift 5 (`Package.swift` `swiftLanguageVersions: [.v5]`, podspec Swift 5.0) -- **Build:** Swift Package Manager; CocoaPods (`ContentstackUtils.podspec`); Xcode `ContentstackUtils.xcodeproj` -- **Testing:** XCTest, target `ContentstackUtilsTests`, path `Tests/ContentstackUtilsTests/` -- **Lint / coverage:** SwiftLint (`.swiftlint.yml`), Slather (`.slather.yml`, scheme `ContentstackUtils-Package`) -- **HTML/XML:** Vendored **Kanna** (`Sources/Kanna/`), **libxml2** via `Modules/` (system on Apple platforms) +| Area | Details | +|------|---------| +| Language | Swift 5 (`Package.swift`, podspec) | +| Build | SwiftPM; CocoaPods `ContentstackUtils.podspec`; Xcode `ContentstackUtils.xcodeproj` | +| Tests | XCTest → `Tests/ContentstackUtilsTests/` | +| Lint / coverage | SwiftLint `.swiftlint.yml`; Slather `.slather.yml` (scheme `ContentstackUtils-Package`) | +| HTML/XML | Vendored Kanna `Sources/Kanna/`; libxml2 via `Modules/` | -## Main entry points +## Commands (quick reference) -- **`ContentstackUtils`** – `Sources/ContentstackUtils/ContentstackUtils.swift`: `render`, `jsonToHtml`, `getVariantAliases`, nested **`GQL`**, **`VariantUtilityError`** -- **`Option` / `Renderable`** – `Sources/ContentstackUtils/Option.swift`: customize HTML for marks, nodes, embedded items -- **RTE model types** – `Node.swift`, `JSONNode.swift`, `JSONNodes.swift`, `MarkType.swift`, `Metadata.swift`, and related files under `Sources/ContentstackUtils/` -- **Tests** – `Tests/ContentstackUtilsTests/*.swift` -- **Package** – `Package.swift`: product `ContentstackUtils`, targets `ContentstackUtils`, `ContentstackUtilsTests`, system `libxml2` +```bash +swift build && swift test +swiftlint +``` -## Commands +CI-style Xcode (see `.github/workflows/ci.yml`): -- **Build and test:** `swift build` && `swift test` -- **Lint:** `swiftlint` -- **CI-style Xcode test:** - `xcodebuild -project "ContentstackUtils.xcodeproj" -scheme "ContentstackUtils-Package" -destination "OS=13.4.1,name=iPhone 11 Pro" test` +```bash +xcodebuild -project "ContentstackUtils.xcodeproj" -scheme "ContentstackUtils-Package" -destination "OS=13.4.1,name=iPhone 11 Pro" test +``` -CocoaPods: `pod 'ContentstackUtils', '~> …'` (see `README.md` and `ContentstackUtils.podspec` for the current version). +CocoaPods: `pod 'ContentstackUtils', '~> …'` — see `README.md` and `ContentstackUtils.podspec` for the current version. -## Rules and skills +## Where the real documentation lives: skills -- **`.cursor/rules/`** – Cursor rules for this repo: - - **README.md** – Index of all rules and how globs apply. - - **dev-workflow.md** – Development workflow (branches, tests, lint, PRs). - - **swift-style.mdc** – Applies to `**/*.swift`: SwiftLint, layout, Kanna/libxml2, platforms. - - **contentstack-utils-sdk.mdc** – Applies to `Sources/ContentstackUtils/**/*.swift`: Utils SDK patterns, `Option`, RTE/GQL, variants. - - **testing.mdc** – Applies to `Tests/**/*.swift`: XCTest, mocks, fixtures, coverage. - - **code-review.mdc** – Always applied: PR/review checklist. -- **`skills/`** – Reusable skill docs: - - Use **contentstack-utils** when implementing or changing public API, RTE rendering, or GQL JSON entry points. - - Use **testing** when adding or refactoring tests. - - Use **code-review** when reviewing PRs or before opening one. - - Use **framework** when changing SPM/libxml2, Kanna vendoring, deployment targets, or CocoaPods packaging. +Read these **`SKILL.md` files** for full conventions—**this is the source of truth** for implementation and review: -Refer to `.cursor/rules/README.md` for when each rule applies and to `skills/README.md` for skill details. +| Skill | Path | What it covers | +|-------|------|----------------| +| **Development workflow** | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Branches, CI, build/test/lint commands, PR expectations, TDD note, Slather | +| **Contentstack Utils (SDK)** | [`skills/contentstack-utils/SKILL.md`](skills/contentstack-utils/SKILL.md) | Public API: `ContentstackUtils`, `Option` / `Renderable`, RTE/JSON, GQL, variants, errors, semver, no network layer | +| **Swift style & repo layout** | [`skills/swift-style/SKILL.md`](skills/swift-style/SKILL.md) | SwiftLint, `Sources/` layout, Kanna/libxml2, platforms, naming, access control | +| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | XCTest layout, mocks, fixtures, SwiftLint/Slather, offline tests, `XCTestManifests` | +| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist (API, errors, deps/SCA, tests, vendored code), Blocker/Major/Minor | +| **Framework / build** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | SPM targets, `Modules/` libxml2, Kanna vendoring, deployment targets, podspec, CI `xcodebuild` | + +An index with short “when to use” hints is in [`skills/README.md`](skills/README.md). + +## Using Cursor + +If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same source of truth as everyone else; no separate `.mdc` rule files. diff --git a/skills/README.md b/skills/README.md index d113569..fc46249 100644 --- a/skills/README.md +++ b/skills/README.md @@ -1,21 +1,19 @@ # Skills – Contentstack Utils Swift -This directory contains **skills**: reusable guidance for AI agents (and developers) on specific tasks. Each skill is a folder with a `SKILL.md` file (YAML frontmatter: `name`, `description`). +**This directory is the source of truth** for conventions (workflow, SDK API, style, tests, review, build). Read **`AGENTS.md`** at the repo root for the index and quick commands; each skill is a folder with **`SKILL.md`** (YAML frontmatter: `name`, `description`). ## When to use which skill -| Skill | Use when | -|-------|----------| -| **contentstack-utils** | Implementing or changing Utils features: `ContentstackUtils`, `Option` / `Renderable`, RTE/JSON models, GQL helpers, variant APIs, errors, documentation and semver. | -| **testing** | Writing or refactoring tests: XCTest, `swift test`, Xcode scheme, mocks, fixtures, SwiftLint/Slather, offline fixtures. | -| **code-review** | Reviewing a PR or preparing your own: API design, errors, backward compatibility, dependencies/security, test coverage, severity (blocker/major/minor). | -| **framework** | Touching SPM layout, `libxml2` / `Modules/`, vendored Kanna, deployment targets, or `ContentstackUtils.podspec` / CI `xcodebuild` assumptions. | +| Skill folder | Use when | +|--------------|----------| +| **dev-workflow** | Branches, CI, `swift build` / `swift test` / `swiftlint`, `xcodebuild`, PRs, Slather, optional TDD | +| **contentstack-utils** | `ContentstackUtils`, `Option` / `Renderable`, RTE/JSON, GQL, variants, errors, semver, docs | +| **swift-style** | SwiftLint, `Sources/` vs Kanna, libxml2/platforms, naming, access control | +| **testing** | XCTest layout, mocks, fixtures, offline tests, `XCTestManifests` | +| **code-review** | PR checklist, Blocker/Major/Minor, API and security gates | +| **framework** | `Package.swift`, `Modules/`, Kanna vendoring, podspec, CI scheme | -## How agents should use skills +## How to use these docs -- **contentstack-utils:** Apply when editing `Sources/ContentstackUtils/` or documenting public behavior. Do not add hard dependencies on the main Contentstack iOS SDK or Apollo unless product requires it and `Package.swift` is updated deliberately. -- **testing:** Apply when creating or modifying files under `Tests/ContentstackUtilsTests/`. Follow existing mocks and fixtures; keep tests credential-free. -- **code-review:** Apply when performing or simulating a PR review. Work through `.cursor/rules/code-review.mdc` and optionally tag findings by severity. -- **framework:** Apply when changing `Package.swift`, `Modules/`, `Sources/Kanna/`, or podspec—keep Apple vs Linux libxml behavior and CI destinations in mind. - -Each skill’s `SKILL.md` contains more detailed instructions and references. +- **Humans / any AI tool:** Start at **`AGENTS.md`**, then open the relevant **`skills//SKILL.md`**. +- **Cursor users:** **`.cursor/rules/README.md`** only points to **`AGENTS.md`** so guidance stays universal—no duplicate `.mdc` rule sets. diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index 4a54ba8..81b1619 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -1,56 +1,60 @@ --- name: code-review -description: Use when reviewing PRs or before opening a PR—API design, errors, backward compatibility, dependencies, security, and test quality. +description: PR checklist—API stability, docs, errors, compatibility, dependencies/SCA, tests, vendored code; Blocker/Major/Minor. --- -# Code Review – Contentstack Utils Swift +# Code review – Contentstack Utils Swift ## When to use -- Reviewing someone else’s PR. -- Self-reviewing before submission. -- Checking that changes meet project standards (API, errors, compatibility, tests, security). +- Reviewing a PR, self-review before submit, or automated review prompts. ## Instructions -Work through the checklist in `.cursor/rules/code-review.mdc`. Optionally tag items with severity: **Blocker**, **Major**, **Minor**. +Work through the checklist below. Optionally tag findings: **Blocker**, **Major**, **Minor**. -### 1. API design and stability +### API design and stability -- [ ] **Public API:** New or changed `public` / `open` surface is necessary and documented (`README` / `CHANGELOG` as appropriate). -- [ ] **Backward compatibility:** No breaking changes unless agreed (e.g. major version). Call out deprecations and alternatives. -- [ ] **Naming:** Consistent with existing Utils and RTE terminology (`ContentstackUtils`, `Option`, `Node`, `GQL`). +- [ ] **Public API:** New or changed `public` / `open` types in `Sources/ContentstackUtils/` are necessary, semver-conscious, and documented (`README.md` / `CHANGELOG.md` when user-visible). +- [ ] **Backward compatibility:** No breaking changes unless explicitly justified (e.g. major version). Prefer additive behavior and default `Option()` paths. +- [ ] **Naming:** Matches existing Utils and RTE terminology (`ContentstackUtils`, `Option`, `Node`, `GQL`, etc.). -**Severity:** Breaking public API without approval = Blocker. Missing docs on new public API = Major. +### Error handling and robustness -### 2. Error handling and robustness +- [ ] **Errors:** New `throws` paths use clear domain types (e.g. `VariantUtilityError`); callers can distinguish invalid input from parsing failures where relevant. +- [ ] **Optionals:** No force-unwraps on public code paths; document preconditions for non-optional parameters. +- [ ] **RTE JSON:** Decoding and HTML traversal stay tolerant of documented stack payload shapes; embedded-item regressions are called out. -- [ ] **Errors:** Domain failures use clear types; `throws` is used where callers need to recover or log. -- [ ] **Optionals:** No unintended force-unwraps on public paths. +### Dependencies and security -**Severity:** Wrong or missing error handling in new code = Major. +- [ ] **Dependencies:** `Package.swift` / `ContentstackUtils.podspec` changes are justified; versions do not introduce known vulnerabilities. +- [ ] **SCA:** Address security findings (e.g. Snyk, org scanners) in the PR or via an agreed follow-up. -### 3. Dependencies and security +### Testing -- [ ] **Dependencies:** `Package.swift` / podspec changes are justified; versions do not introduce known vulnerabilities. -- [ ] **SCA:** Security findings (e.g. Snyk) in scope are addressed or deferred with a ticket. +- [ ] **Coverage:** New or modified behavior in `Sources/ContentstackUtils/` has tests under `Tests/ContentstackUtilsTests/` when feasible. +- [ ] **Quality:** Tests are readable, deterministic, and follow naming/mocks conventions. -**Severity:** New critical/high vulnerability = Blocker. +### Vendored and native code -### 4. Testing +- [ ] **Kanna / libxml2 / `Modules/`:** Reviewed for upstream parity, licensing, and Apple vs Linux builds. -- [ ] **Coverage:** New or modified behavior has corresponding tests under `Tests/ContentstackUtilsTests/` when feasible. -- [ ] **Quality:** Tests are readable and deterministic. +### Severity (optional) -**Severity:** No tests for new behavior where tests are practical = Blocker. Flaky tests = Major. +| Level | Examples | +|-------|----------| +| **Blocker** | Breaking public API without approval; security issue; no tests for new code where tests are practical | +| **Major** | Inconsistent errors; README examples that do not compile | +| **Minor** | Style; minor docs | -### 5. Optional severity summary +### Detailed review themes (from checklist sections) -- **Blocker:** Must fix before merge (e.g. breaking API without approval, security issue, missing tests). -- **Major:** Should fix (e.g. inconsistent errors, broken README examples). -- **Minor:** Nice to fix (e.g. style, minor docs). +- **API:** Breaking `public`/`open` without semver/CHANGELOG/podspec alignment. +- **Errors:** `throws` changes that confuse callers without a version strategy. +- **README:** Examples must match real APIs (`jsonToHtml` overloads, `GQL.jsonToHtml`). +- **Dependencies:** New packages in `Package.swift` / podspec need justification. ## References -- Project rule: `.cursor/rules/code-review.mdc` -- Testing skill: `skills/testing/SKILL.md` +- `skills/testing/SKILL.md` +- `skills/contentstack-utils/SKILL.md` diff --git a/skills/contentstack-utils/SKILL.md b/skills/contentstack-utils/SKILL.md index 8a327f8..5626327 100644 --- a/skills/contentstack-utils/SKILL.md +++ b/skills/contentstack-utils/SKILL.md @@ -1,6 +1,6 @@ --- name: contentstack-utils -description: Use when changing ContentstackUtils Swift public API—rendering, Option/Renderable, GQL JSON, variants, errors; no bundled HTTP client. +description: Public API—ContentstackUtils, Option/Renderable, RTE/JSON, GQL, variants, errors; no bundled HTTP client. --- # Contentstack Utils – SDK skill @@ -11,29 +11,45 @@ description: Use when changing ContentstackUtils Swift public API—rendering, O - Updating `README.md` / `CHANGELOG.md` / podspec for user-visible behavior. - Assessing semver impact of `public` / `open` changes. -## Instructions +## Main entry (consumer API) -This package exposes **HTML/RTE rendering** and **variant alias** helpers. It does **not** ship Stack configuration, API keys, or network clients. +- Consumers `import ContentstackUtils` and use **`ContentstackUtils`**: e.g. `render(content:_:)`, `render(contents:_:)`, `jsonToHtml(node:_:)`, `getVariantAliases`, nested **`GQL.jsonToHtml(rte:_:)`**. +- Keep the static surface small and documented; breaking changes need semver and changelog notes. -### Core types +## Customization -- **`ContentstackUtils`** (`Sources/ContentstackUtils/ContentstackUtils.swift`): `render(content:_:)`, `render(contents:_:)`, `jsonToHtml` overloads, `getVariantAliases`, nested **`GQL`** with `jsonToHtml(rte:_:)` for GraphQL-shaped dictionaries. -- **`Option`** (`Option.swift`): open class; override `renderItem`, `renderMark`, `renderNode`. Implements **`Renderable`**. -- **RTE JSON:** `Node`, `JSONNode`, `JSONNodes`, `MarkType`, `StyleType`, `Metadata`, embedded models—keep decoding aligned with stack payloads. +- Subclass or extend via **`Option`** (open class) conforming to **`Renderable`**: `renderItem(embeddedObject:metadata:)`, `renderMark(markType:text:)`, `renderNode(nodeType:node:next:)`. +- Do not remove or rename open hooks without a **major** version. -### Errors +## Data model -- Use **`ContentstackUtils.VariantUtilityError`** (and similar nested types) for domain failures; prefer `throws` over opaque optionals for invalid variant input. +- RTE JSON uses **`Node`**, **`JSONNode`** / **`JSONNodes`**, **`MarkType`**, **`StyleType`**, **`Metadata`**, embedded entry/asset types (`EmbeddedObject`, `EmbeddedEntry`, etc.). +- Preserve **`Codable`** / decoding compatibility with Contentstack Delivery and GraphQL payloads. -### Integration boundary +## Errors -- README examples using **`Contentstack.stack`**, **`fetch`**, or **Apollo** are illustrative only—do not add those as package dependencies without an explicit product decision. +- Expose domain failures with nested types where appropriate (e.g. **`ContentstackUtils.VariantUtilityError.invalidArgument`**). +- Use **`throws`** for recoverable failures; avoid force-unwraps on public paths. -### Docs and versioning +## HTML and documentation -- Align **`ContentstackUtils.podspec`** and tags with releases. Follow semver for `public` / `open` changes. +- Rendering uses Kanna/HTML internally; keep output predictable for documented inputs. +- Document new node types or GQL JSON shapes in **`README.md`** / **`CHANGELOG.md`**. + +## No network layer + +- This package does **not** ship HTTP clients or tokens. +- README examples showing **`Stack`**, **`fetch`**, or **Apollo** are integration sketches only—do **not** add hard dependencies on the main Contentstack iOS SDK or Apollo in **`Package.swift`** unless product explicitly requires it. + +## Legacy naming + +- Some names (e.g. **`embdeddedItems`**) are entrenched; changing them is a **breaking** API change—coordinate with maintainers. + +## Docs and versioning + +- Align **`ContentstackUtils.podspec`** and git tags with releases. Follow **semver** for `public` / `open` changes. ## References -- Project rule: `.cursor/rules/contentstack-utils-sdk.mdc` -- Product: [Contentstack](https://www.contentstack.com/) +- [Contentstack](https://www.contentstack.com/) +- `skills/swift-style/SKILL.md`, `skills/framework/SKILL.md` diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md new file mode 100644 index 0000000..fe75550 --- /dev/null +++ b/skills/dev-workflow/SKILL.md @@ -0,0 +1,51 @@ +--- +name: dev-workflow +description: Branches, CI, build/test/lint, PR expectations, coverage—standard workflow for Contentstack Utils Swift. +--- + +# Development workflow – Contentstack Utils Swift + +## When to use + +- Setting up locally, opening a PR, or aligning with CI. +- Answering “how do we run tests?” or “which branch targets `master`?” + +## Branches + +- Use feature branches (e.g. `feat/...`, `fix/...`, ticket branches). +- **CI** runs on push to `master` and on pull requests targeting `master` or `next` (`.github/workflows/ci.yml`). +- **Merges into `master`** may be gated: PRs whose base is `master` are often expected to come from **`staging`**; other heads may fail the check-branch workflow (`.github/workflows/check-branch.yml`). Confirm with your team before opening PRs to `master`. + +## Running tests and build + +- **SPM:** `swift build`, `swift test` +- **CI-style Xcode (iOS Simulator):** + `xcodebuild -project "ContentstackUtils.xcodeproj" -scheme "ContentstackUtils-Package" -destination "OS=13.4.1,name=iPhone 11 Pro" test` + Adjust `-destination` for your local Xcode/Simulator. + +Run tests before opening a PR. Default tests use **offline** mocks and fixtures—no `.env` or live stack credentials. + +## Lint + +- **SwiftLint:** `swiftlint` (`.swiftlint.yml`) + +## Pull requests + +- Build passes: `swift build` and `swift test` (and `xcodebuild` if you touch Xcode-specific paths). +- Follow the **code-review** skill (`skills/code-review/SKILL.md`) before merge. +- Prefer backward-compatible public API; call out breaking changes and semver. +- Describe behavior and update `CHANGELOG.md` / version metadata (`ContentstackUtils.podspec`, tags) when releasing—per team process. +- Security/policy scans may run in CI (e.g. `.github/workflows/sca-scan.yml`, `policy-scan.yml`). + +## Optional: TDD + +If the team uses TDD: RED → GREEN → REFACTOR. Test structure is in `skills/testing/SKILL.md`. + +## Coverage + +- **Slather** (`.slather.yml`, scheme `ContentstackUtils-Package`): use after tests to inspect `Sources/ContentstackUtils/` coverage. + +## References + +- `skills/testing/SKILL.md` +- `skills/code-review/SKILL.md` diff --git a/skills/framework/SKILL.md b/skills/framework/SKILL.md index 42304ea..1565408 100644 --- a/skills/framework/SKILL.md +++ b/skills/framework/SKILL.md @@ -1,36 +1,39 @@ --- name: framework -description: Use when changing SPM, libxml2 Modules, vendored Kanna, deployment targets, CocoaPods, or CI xcodebuild setup. +description: SPM targets, libxml2 Modules, vendored Kanna, deployment targets, CocoaPods podspec, CI xcodebuild. --- -# Framework – Contentstack Utils Swift +# Framework / build – Contentstack Utils Swift ## When to use - Editing `Package.swift`, `Modules/`, or `Sources/Kanna/`. -- Changing iOS/macOS/tvOS/watchOS deployment targets or conditional libxml linking. -- Updating `ContentstackUtils.podspec` or CI Xcode destination/scheme assumptions. +- Changing deployment targets or conditional libxml linking. +- Updating `ContentstackUtils.podspec` or CI assumptions (scheme, destination). -## Instructions +## Swift Package Manager -### Swift Package Manager +- **Product:** `ContentstackUtils`. +- **Targets:** `ContentstackUtils` (sources under `Sources/`), `ContentstackUtilsTests`, system library **`libxml2`** → **`Modules/`**. +- **Apple vs Linux:** Conditional `libxml2` dependency and `pkg-config` as in `Package.swift`—preserve behavior when refactoring. -- **Product:** `ContentstackUtils`; **targets:** `ContentstackUtils`, `ContentstackUtilsTests`, system **`libxml2`** → **`Modules/`**. -- **Platforms:** Apple vs Linux: conditional `libxml2` dependency and `pkg-config` as in `Package.swift`—preserve behavior when refactoring. +## Vendored Kanna -### Vendored Kanna +- **`Sources/Kanna/`** is excluded from SwiftLint. Updates = intentional vendoring (license, diff, cross-platform build). -- **`Sources/Kanna/`** is excluded from SwiftLint; treat updates as intentional vendoring work (licensing, diffs, cross-platform build). +## CocoaPods -### CocoaPods +- **`ContentstackUtils.podspec`:** e.g. `source_files` `Sources/**/*.{swift}`, `HEADER_SEARCH_PATHS` / `-lxml2` for libxml. Keep aligned with SPM layout and tagged releases. -- **`ContentstackUtils.podspec`:** `source_files` `Sources/**/*.{swift}`, header search and `-lxml2` for libxml—keep in sync with SPM layout. +## Platforms -### CI +- Declared in `Package.swift` / podspec (e.g. macOS 10.13+, iOS/tvOS 11+, watchOS 4+). See also **`skills/swift-style/SKILL.md`** for API availability and naming. -- GitHub Actions uses **xcodebuild** with `ContentstackUtils-Package`; validate low-level changes with both `swift test` and Xcode builds when touching parsing or linking. +## CI + +- **GitHub Actions** uses **xcodebuild** with scheme **`ContentstackUtils-Package`**. After changing parsing or linking, validate with both **`swift test`** and Xcode builds. ## References -- Project rule: `.cursor/rules/swift-style.mdc` -- Workflow: `.cursor/rules/dev-workflow.md` +- `skills/swift-style/SKILL.md` +- `skills/dev-workflow/SKILL.md` diff --git a/skills/swift-style/SKILL.md b/skills/swift-style/SKILL.md new file mode 100644 index 0000000..e01b5e1 --- /dev/null +++ b/skills/swift-style/SKILL.md @@ -0,0 +1,41 @@ +--- +name: swift-style +description: SwiftLint, Sources layout, Kanna/libxml2, platforms, naming, access control for all Swift in this repo. +--- + +# Swift style and repo layout – Contentstack Utils Swift + +## When to use + +- Editing any Swift under `Sources/` or `Tests/`. +- Adding files or changing platform/deployment assumptions. + +## Tooling + +- Run **SwiftLint** with `.swiftlint.yml`. Do not relax rules for new code without team agreement. +- **`Sources/Kanna/`** is excluded from SwiftLint—do not copy patterns into `Sources/ContentstackUtils/` that would fail lint there. + +## Package layout + +- **Library code:** `Sources/ContentstackUtils/`. +- **Vendored Kanna:** `Sources/Kanna/`—treat as third-party unless you are deliberately upgrading the vendored copy; prefer fixes in `ContentstackUtils` or documented Kanna upgrades. + +## Platforms and libxml2 + +- **Deployment targets:** macOS 10.13+, iOS/tvOS 11+, watchOS 4+ (`Package.swift`). Avoid newer SDK-only APIs without availability checks or a deliberate target bump. +- **libxml2:** Apple platforms use system libxml where applicable; Linux uses the `libxml2` system target and `pkg-config`. Keep `Modules/` and `Package.swift` conditionals in sync when changing platform support. + +## Naming and API surface + +- Swift conventions: types `UpperCamelCase`, members `lowerCamelCase`. +- Preserve established **public** names even when imperfect (e.g. historical typos) unless doing a **semver-major** cleanup with maintainer agreement. + +## Imports and access control + +- `import Foundation` as needed; HTML parsing follows existing Kanna usage in this package. +- Mark **`public` / `open`** intentionally; keep implementation `internal` or `private` unless tests use established `@testable` patterns. + +## References + +- `skills/framework/SKILL.md` (SPM, podspec, CI) +- `skills/testing/SKILL.md` (lint exclusions in tests) diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md index 794c79b..aed7610 100644 --- a/skills/testing/SKILL.md +++ b/skills/testing/SKILL.md @@ -1,6 +1,6 @@ --- name: testing -description: Use when writing or refactoring tests—XCTest, swift test, Xcode scheme, mocks, fixtures, Slather/SwiftLint. +description: XCTest—layout, mocks, fixtures, SwiftLint/Slather, offline tests, Linux manifests. --- # Testing – Contentstack Utils Swift @@ -8,17 +8,33 @@ description: Use when writing or refactoring tests—XCTest, swift test, Xcode s ## When to use - Adding or changing tests under `Tests/ContentstackUtilsTests/`. -- Debugging flaky or slow tests; improving fixtures or mocks. +- Debugging flaky tests; improving fixtures or mocks. -## Instructions +## Runner and tooling -- **Run:** `swift test` from repo root; use Xcode scheme **`ContentstackUtils-Package`** and `ContentstackUtils.xcodeproj` to mirror `.github/workflows/ci.yml`. -- **Layout:** Files such as `*Tests.swift`, `*Test.swift`, or feature files (`GQLJsonToHtml.swift`, `DefaultRenderTests.swift`). Reuse `CustomRenderOptionMock.swift`, `EmbededModelMock.swift`, `TestClient.swift`, `JsonNodes.swift`, `JsonNodesHtmlResults.swift`. -- **Lint:** `.swiftlint.yml` excludes only `Tests/ContentstackUtilsTests/Constants.swift` from SwiftLint. -- **Coverage:** Slather ignores `Tests/*` in reports; still add tests for new production behavior in `Sources/ContentstackUtils/` when practical. -- **Secrets:** Tests stay **offline**—no API keys or `.env` in CI. +- **XCTest** via **`swift test`** (SPM) and/or Xcode scheme **`ContentstackUtils-Package`** (`ContentstackUtils.xcodeproj`), matching `.github/workflows/ci.yml`. +- **SwiftLint:** `.swiftlint.yml`; **`Tests/ContentstackUtilsTests/Constants.swift`** is excluded—other test files are linted. +- **Slather:** `.slather.yml` ignores `Tests/*` in coverage reports; still add tests for new production code in `Sources/ContentstackUtils/` when practical. + +## Test naming and layout + +- **Target:** `ContentstackUtilsTests`; path **`Tests/ContentstackUtilsTests/`**. +- **File names:** `*Tests.swift`, `*Test.swift`, or feature-oriented names (`GQLJsonToHtml.swift`, `JsonNodes.swift`, `VariantUtilityTests.swift`). +- **Fixtures and mocks:** Prefer `JsonNodes.swift`, `JsonNodesHtmlResults.swift`, `EmbededModelMock.swift`, `CustomRenderOptionMock.swift`, `TestClient.swift`, etc., before adding parallel helpers. + +## Integration vs unit + +- No separate integration tree: tests live in **`ContentstackUtilsTests`** with mocks for API-shaped payloads—**no live network** or credentials in CI. + +## Linux / discovery + +- Maintain **`XCTestManifests.swift`** if your workflow requires explicit Linux test discovery. + +## Secrets + +- Tests are **offline**; do not commit API keys or real tokens. ## References -- Project rule: `.cursor/rules/testing.mdc` -- Workflow: `.cursor/rules/dev-workflow.md` +- `skills/dev-workflow/SKILL.md` +- `skills/code-review/SKILL.md` From f808f9b1be470b5f931fa64698d67f574cdbd08e Mon Sep 17 00:00:00 2001 From: reeshika-h Date: Mon, 6 Apr 2026 11:52:25 +0530 Subject: [PATCH 4/4] Remove .vscode/settings.json file --- .vscode/settings.json | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json deleted file mode 100644 index 64557a7..0000000 --- a/.vscode/settings.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "snyk.advanced.organization": "18cb8ddb-8261-46fc-85fd-8b7025684b29", - "snyk.advanced.autoSelectOrganization": true -} \ No newline at end of file