From 9bae8bae3b8902f06e3680658d8c7cfc0069f835 Mon Sep 17 00:00:00 2001 From: reeshika-h Date: Thu, 2 Apr 2026 12:12:04 +0530 Subject: [PATCH 1/5] Update documentation to deprecate CocoaPods for new projects in favor of Swift Package Manager; added DEPRECATION.md and updated README and overview documentation. --- CHANGELOG.md | 6 ++++++ DEPRECATION.md | 33 +++++++++++++++++++++++++++++++++ Docs/overview.md | 7 +++++++ README.md | 13 ++++++++++++- 4 files changed, 58 insertions(+), 1 deletion(-) create mode 100644 DEPRECATION.md create mode 100644 Docs/overview.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 613fe71..6554c17 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,12 @@ All notable changes to this project will be documented in this file. +## [Unreleased] + +### Documentation + +- 2026-04-02: Added CocoaPods deprecation guidance for **new** projects—**SPM** is recommended for ContentstackUtils; clarified companion role vs the core Swift CDA SDK. Updated README (Important section), added root **DEPRECATION.md** (customer-facing only), added **Docs/overview.md** banner with link to `DEPRECATION.md`. + ## [1.4.0] - 2026-03-30 ### Enhancement diff --git a/DEPRECATION.md b/DEPRECATION.md new file mode 100644 index 0000000..8e8d2a2 --- /dev/null +++ b/DEPRECATION.md @@ -0,0 +1,33 @@ +# CocoaPods distribution for ContentstackUtils + +This notice applies to developers who integrate **ContentstackUtils** using **CocoaPods** (`ContentstackUtils` pod). + +## What this package is + +**ContentstackUtils** is a **companion library** for the [Contentstack Swift SDK](https://github.com/contentstack/contentstack-swift). It provides utilities (for example JSON RTE rendering and embedded items) for use **alongside** the Swift Content Delivery API (CDA) client. It is **not** a replacement for the core CDA SDK—you still use the [Swift SDK](https://github.com/contentstack/contentstack-swift) for stack, queries, and delivery. + +## What we recommend for new work + +For **new** projects and new integrations, we recommend adding **ContentstackUtils** with **Swift Package Manager (SPM)** from this repository, and using the **Swift SDK** via SPM as well. That keeps your dependency graph aligned with current tooling and our primary distribution path. + +- **Contentstack Swift SDK (source):** [github.com/contentstack/contentstack-swift](https://github.com/contentstack/contentstack-swift) +- **Swift SDK on Swift Package Index:** [swiftpackageindex.com/contentstack/contentstack-swift](https://swiftpackageindex.com/contentstack/contentstack-swift) +- **Swift CDA reference:** [Content Delivery SDK — Swift reference](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/swift/reference) + +**Version alignment:** Use ContentstackUtils versions that match the guidance in this repository’s README (keep Utils in step with the Swift SDK version you use). + +We are **deprecating CocoaPods as the recommended way** to add ContentstackUtils for **new** work. CocoaPods remains part of the broader ecosystem, but our product direction favors **SPM** for Apple platforms. For background on how the CocoaPods ecosystem is evolving, see [CocoaPods Specs Repo](https://blog.cocoapods.org/CocoaPods-Specs-Repo/). + +## If you already use CocoaPods + +**Existing** apps that already depend on the `ContentstackUtils` pod can continue to ship as they do today. You are not required to migrate on a fixed deadline to keep using what you have. When you are ready to standardize on SPM or refresh dependencies, plan a migration at your own pace. + +## Maintenance and features + +We continue to maintain ContentstackUtils for supported integration paths. **New** feature work and documentation will emphasize **SPM** and the Swift SDK. CocoaPods-based setups may receive necessary maintenance but are not our focus for new capabilities. + +## Support + +Questions or help with your integration: [support@contentstack.io](mailto:support@contentstack.io). + +See also the **Important** section at the top of the [README](./README.md). diff --git a/Docs/overview.md b/Docs/overview.md new file mode 100644 index 0000000..5361f69 --- /dev/null +++ b/Docs/overview.md @@ -0,0 +1,7 @@ +# ContentstackUtils — overview + +## Important + +**ContentstackUtils** is a **companion** to the [Contentstack Swift SDK](https://github.com/contentstack/contentstack-swift), not the core CDA client. Prefer **Swift Package Manager** for new work; the **CocoaPods** pod is **not** recommended for new projects. Existing CocoaPods users can keep shipping until they choose to migrate. + +Full details: **[DEPRECATION.md](../DEPRECATION.md)** · [README](../README.md) · [Swift SDK reference](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/swift/reference) diff --git a/README.md b/README.md index 982f61e..4433358 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,19 @@ # ![Contentstack](https://www.contentstack.com/docs/static/images/contentstack.png) -# Contentstack Swift SDK +# ContentstackUtils + ![ContentstackUtils CI](https://github.com/contentstack/contentstack-utils-swift/workflows/ContentstackUtils%20CI/badge.svg) +## Important + +**ContentstackUtils** is a **companion** library for the [Contentstack Swift SDK](https://github.com/contentstack/contentstack-swift)—utilities for JSON RTE, embedded items, and related helpers; it is **not** the core Content Delivery API (CDA) client. Add **ContentstackUtils** with Swift Package Manager from [`contentstack/contentstack-utils-swift`](https://github.com/contentstack/contentstack-utils-swift), add the [Swift SDK](https://github.com/contentstack/contentstack-swift) the same way (see also [Swift Package Index](https://swiftpackageindex.com/contentstack/contentstack-swift)), and **align versions** between them as described in this README. + +We are **deprecating CocoaPods** (`pod 'ContentstackUtils'`) as the recommended integration path for **new** projects—prefer SPM. **Existing** CocoaPods users can keep shipping; migrate when it suits you. This applies only to the **CocoaPods delivery channel**, not to the Swift libraries themselves. + +Read the full customer-facing notice: **[DEPRECATION.md](./DEPRECATION.md)**. Swift CDA reference: [Swift SDK reference](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/swift/reference). Optional context: [CocoaPods Specs Repo](https://blog.cocoapods.org/CocoaPods-Specs-Repo/). + +--- + Contentstack is a headless CMS with an API-first approach. It is a CMS that developers can use to build powerful cross-platform applications in their favorite languages. Build your application frontend, and Contentstack will take care of the rest. [Read More](https://www.contentstack.com/). Contentstack provides iOS SDK to build application on top of iOS. Given below is the detailed guide and helpful resources to get started with our iOS SDK. From 3cc38d7ba381e181095139d1a57da25b2edd568a Mon Sep 17 00:00:00 2001 From: reeshika-h Date: Thu, 2 Apr 2026 16:12:06 +0530 Subject: [PATCH 2/5] 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 3/5] 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 4/5] 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 5/5] 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