diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md new file mode 100644 index 0000000..634bc5a --- /dev/null +++ b/.cursor/rules/README.md @@ -0,0 +1,19 @@ +# Cursor rules for `@contentstack/types-generator` + +This folder contains project-specific rules for AI assistants and developers. Each file lists its scope in YAML frontmatter (`description`, `globs`, `alwaysApply`). + + +| Rule file | `alwaysApply` | Globs | When it applies | Related skill | +| -------------------------------------------------------------- | ------------- | ------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | +| [dev-workflow.mdc](dev-workflow.mdc) | No | `package.json`, `package-lock.json`, `.github/workflows/**/*`, `jest.config.js`, `tsup.config.ts`, `AGENTS.md` | Branch strategy, build/test commands, PR and release expectations | [testing](../../skills/testing/SKILL.md), [code-review](../../skills/code-review/SKILL.md) | +| [typescript.mdc](typescript.mdc) | No | `src/**/*.ts`, `tests/**/*.ts` | Editing or adding TypeScript in this package | [typescript-types-generator](../../skills/typescript-types-generator/SKILL.md) | +| [contentstack-delivery-cda.mdc](contentstack-delivery-cda.mdc) | No | `src/sdk/**`, `src/generateTS/**`, `src/graphqlTS/**` | Delivery SDK, regions, stack config, GraphQL introspection/axios | [typescript-types-generator](../../skills/typescript-types-generator/SKILL.md) | +| [testing.mdc](testing.mdc) | No | `tests/**`, `jest.config.js` | Writing or running Jest tests, env for live tests | [testing](../../skills/testing/SKILL.md) | +| [code-review.mdc](code-review.mdc) | **Yes** | — | Every change: API docs, compatibility, errors, security, tests | [code-review](../../skills/code-review/SKILL.md) | + + +## Referencing rules in Cursor + +- Use **@** in chat and pick a rule file (e.g. `@contentstack-delivery-cda`, `@dev-workflow`) to focus the model on Delivery/GraphQL or workflow context. +- Rules with `alwaysApply: true` are included automatically; others apply when matching files are in context or when @-mentioned. + diff --git a/.cursor/rules/code-review.mdc b/.cursor/rules/code-review.mdc new file mode 100644 index 0000000..5170e2a --- /dev/null +++ b/.cursor/rules/code-review.mdc @@ -0,0 +1,29 @@ +--- +description: PR and change review checklist for types-generator +alwaysApply: true +--- + +# Code review checklist + +Use this for every change. Severity labels are optional (**Blocker** / **Major** / **Minor**). + +## API and documentation + +- **Public API:** New or changed exports need **JSDoc** (or equivalent) where the package documents behavior; keep examples accurate. +- **Terminology:** Use **CDA / Delivery** and **GraphQL** as in this codebase. **Do not** describe this library as CMA or Management-API–centric. + +## Compatibility + +- **Backward compatibility:** Avoid breaking changes to function signatures, error shapes, and generated output format unless versioned or documented. +- **Errors:** Align with existing patterns: **`type: "validation"`** and related helpers in `generateTS` / `graphqlTS`; do not silently swallow SDK or network errors. + +## Correctness and safety + +- **Null safety:** Respect **`strictNullChecks`**; guard optional stack config (`host`, `branch`, etc.). +- **Dependencies:** New dependencies need justification; watch license and footprint. **SCA:** `.github/workflows/sca-scan.yml` runs Snyk and `contentstack/sca-policy` on PRs. + +## Tests + +- **Unit:** Add or update tests under **`tests/unit/`** for logic changes. +- **Integration / sanity:** Touch **`tests/integration/`** when behavior depends on live APIs; document required env vars. +- **Coverage:** CI uses **`test:unit:report:json`**; keep meaningful coverage for new code paths. diff --git a/.cursor/rules/contentstack-delivery-cda.mdc b/.cursor/rules/contentstack-delivery-cda.mdc new file mode 100644 index 0000000..11b889f --- /dev/null +++ b/.cursor/rules/contentstack-delivery-cda.mdc @@ -0,0 +1,25 @@ +--- +description: Contentstack Delivery (CDA) SDK and GraphQL usage in types-generator +globs: + - src/sdk/** + - src/generateTS/** + - src/graphqlTS/** +--- + +# Contentstack Delivery and GraphQL (this repo) + +Scope: **SDK-facing library code only** (no separate `samples/` tree). This package is **not** a CMA (Management) client. + +## Delivery / CDA + +- **Token type:** Only **`TOKEN_TYPE.DELIVERY`** is defined ([`src/constants/index.ts`](src/constants/index.ts)). `generateTS` validates `tokenType` and uses the **Delivery SDK** for content types and global fields. +- **SDK entry:** [`initializeContentstackSdk`](src/sdk/utils.ts) wraps **`@contentstack/delivery-sdk`** (`Contentstack.stack` with `deliveryToken`, `environment`, `region` or `host`, optional `branch`). +- **Regions:** Map string constants in **`REGIONS`** to **`Region`** enum; **custom** regions require **`host`** (see `isCustomRegion` branch in [`src/sdk/utils.ts`](src/sdk/utils.ts)). +- **Errors:** Validation failures often use **`{ type: "validation", error_message: string }`** or helpers from [`generateTS/shared/utils`](src/generateTS/shared/utils.ts). Preserve stable `type` / message shapes for callers. + +## GraphQL + +- **Transport:** **`graphqlTS`** uses **`axios`** POST to region-specific GraphQL URLs or to **`https://${host}/...`** when `host` is set ([`src/graphqlTS/index.ts`](src/graphqlTS/index.ts)). +- **Schema:** Introspection query + **`@gql2ts/from-schema`** (`schemaToInterfaces`, `generateNamespace`). Align URL and headers (`access_token`, `branch`) with Contentstack GraphQL documentation for the target region. + +When unsure, prefer official **Content Delivery API** / **GraphQL** docs—not Management API patterns. diff --git a/.cursor/rules/dev-workflow.mdc b/.cursor/rules/dev-workflow.mdc new file mode 100644 index 0000000..1ead756 --- /dev/null +++ b/.cursor/rules/dev-workflow.mdc @@ -0,0 +1,38 @@ +--- +description: Branches, build/test commands, PR and release workflow for types-generator +alwaysApply: false +globs: + - package.json + - package-lock.json + - .github/workflows/**/* + - jest.config.js + - tsup.config.ts + - AGENTS.md +--- + +# Development workflow + +For deeper detail, see **[skills/testing](../../skills/testing/SKILL.md)** (commands, env, fixtures) and **[skills/code-review](../../skills/code-review/SKILL.md)** (PR expectations). In chat you can also @-mention those skill folders if your workspace exposes them. + +## Branches + +- **CI (Node.js workflow)** runs on **push** and **pull_request** for branches **`master`** and **`development`** (see `.github/workflows/node.js.yml`). +- **Release / publish** runs on **push** to **`main`** (see `.github/workflows/release.yml`), using Node **22.x**, autotag, npm publish, and GitHub release. + +**Maintainer note:** Default branch naming differs between CI (`master`/`development`) and release (`main`). Align branch protection and contributor docs when convenient—no change required for local development if your fork uses the upstream defaults. + +## Local commands + +- **Build:** `npm run build` (tsup; `prepare` also runs build). +- **Test (all under `tests/`):** `npm test` (sets `NODE_OPTIONS=--experimental-vm-modules`). +- **Unit tests + coverage (CI):** `npm run test:unit:report:json` (targets `tests/unit`, coverage and JSON artifacts). + +## Pull requests + +- Ensure **`npm run build`** and **`npm test`** pass before requesting review. +- CI runs **`test:unit:report:json`** with secrets for integration-related env vars; PRs from forks may not have secrets—coordinate with maintainers if integration jobs fail only on secrets. + +## Releases + +- Version in **`package.json`** is the source of truth for the published package. +- Publishing is automated from **`main`** via the release workflow (tag prefix `v`, npm publish, GitHub release). Bump version on the branch that merges to `main` per team process. diff --git a/.cursor/rules/testing.mdc b/.cursor/rules/testing.mdc new file mode 100644 index 0000000..dd30bc3 --- /dev/null +++ b/.cursor/rules/testing.mdc @@ -0,0 +1,18 @@ +--- +description: Jest tests, layout, and env for types-generator +globs: + - tests/** + - jest.config.js +--- + +# Testing (`@contentstack/types-generator`) + +- **Runner:** **Jest** with **ts-jest** ([jest.config.js](jest.config.js)). **`setupFiles: ["dotenv/config"]`** loads environment variables for tests. +- **Match:** `**/?(*.)+(spec|test).+(ts|tsx)` and `test/**/*.test.ts`. +- **Layout:** + - **`tests/unit/`** — fast, isolated tests (including `tests/unit/tsgen/` with **`.ct.js`** content-type fixtures paired with **`.test.ts`** files). + - **`tests/integration/`** — live stack / API tests (e.g. `generateTS`, `graphqlTS`); require real credentials. +- **Commands:** + - `npm test` — all tests under `tests` (via `--testPathPattern=tests`). + - `npm run test:unit:report:json` — unit coverage + reports for CI. +- **Integration env:** Typically **`TOKEN`**, **`APIKEY`**, **`ENVIRONMENT`**, **`REGION`**, **`TOKENTYPE`**, **`BRANCH`**. Integration tests may load **`.env`** from the package root path (see test files). CI sets additional secrets such as **`TOKEN_WITH_NO_CT`** / **`APIKEY_WITH_NO_CT`** where needed. diff --git a/.cursor/rules/typescript.mdc b/.cursor/rules/typescript.mdc new file mode 100644 index 0000000..c080b0b --- /dev/null +++ b/.cursor/rules/typescript.mdc @@ -0,0 +1,14 @@ +--- +description: TypeScript layout, strict mode, and logging for types-generator +globs: + - src/**/*.ts + - tests/**/*.ts +--- + +# TypeScript conventions (`@contentstack/types-generator`) + +- **Compiler:** TypeScript **5.9** with **`strict`**, **`noImplicitAny`**, **`strictNullChecks`** ([tsconfig.json](tsconfig.json)). Prefer explicit types at public boundaries. +- **Layout:** Source lives under **`src/`** — `generateTS/`, `graphqlTS/`, `sdk/`, `types/`, `format/`, `logger/`, `constants/`. Tests mirror under **`tests/unit/`** and **`tests/integration/`**. +- **Logging:** Use **`createLogger`** from [`src/logger`](src/logger/index.ts); pass optional logger instances into `generateTS` / `graphqlTS` where supported. +- **Formatting output:** **`prettier`** is a **runtime** dependency used to format generated TypeScript strings—not only dev formatting. +- **Linting:** This package does **not** ship an ESLint config or `lint` script; do not assume ESLint fixes are available in CI. diff --git a/.talismanrc b/.talismanrc index e7fc3f6..f973e15 100644 --- a/.talismanrc +++ b/.talismanrc @@ -4,4 +4,14 @@ fileignoreconfig: - filecontent - filename: package-lock.json checksum: d392a5bf70cad2cb90afaf284410f580e359afe4f1a0a970a6f6061aee7c821c + - filename: .cursor/rules/testing.mdc + checksum: a3768ed70d1fa61e73d1838efbc3066859dd5dfce3fbefe40fb6c23800679a43 + - filename: skills/README.md + checksum: ae09bf77a43f81f76a06f23ae2b2cbb1e81c490a66cf1b4e7df4e7142e22b5f5 + - filename: AGENTS.md + checksum: 6ff4b2c6957f75f85f6afd188cc09af21ac9c90f05f87e4198674302b74bb021 + - filename: skills/testing/SKILL.md + checksum: 858b4a830e74a0e90fe2f1097b4480a5eed513cdd88ba2646087399423ddee00 + - filename: skills/typescript-types-generator/SKILL.md + checksum: aaa97f6eb31a66221ceedc7e5e965a9b13d33358a350dbfb3034014ece0c3e6c version: "1.0" diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..74b2d25 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,49 @@ +# `@contentstack/types-generator` + +**Purpose:** Library for generating TypeScript type definitions from Contentstack stack content types (via the Delivery SDK) and from GraphQL schema (introspection over the Contentstack GraphQL endpoint). + +- **Repository:** [github.com/contentstack/types-generator](https://github.com/contentstack/types-generator) +- **Homepage:** [https://github.com/contentstack/types-generator](https://github.com/contentstack/types-generator) + +## Tech stack + +| Area | Details | +| --- | --- | +| Language | TypeScript **5.9** (`strict` in [tsconfig.json](tsconfig.json)) | +| Runtime | Node (CI on **18.x** and **20.x**; release workflow uses **22.x**) | +| Build | **tsup** → `dist/` ([tsup.config.ts](tsup.config.ts)): entries `index` ([src/index.ts](src/index.ts)), `web` ([src/web.ts](src/web.ts)) | +| Tests | **Jest** + **ts-jest** ([jest.config.js](jest.config.js)); `dotenv/config` in setup | +| Main dependencies | `@contentstack/delivery-sdk`, `axios`, `@gql2ts/from-schema`, `lodash`, `async`, `prettier` | + +This package targets **Content Delivery (CDA)** and **GraphQL** only—not the Management API (CMA). + +## Public API and source layout + +- **Package entry:** `main` / `module` / `types` point to `./dist/*` (see [package.json](package.json)). +- **Exports:** `generateTS`, `graphqlTS`, and related symbols from [src/index.ts](src/index.ts) (re-exports from [src/generateTS/](src/generateTS/) and [src/graphqlTS/](src/graphqlTS/)). +- **Key paths:** [src/sdk/](src/sdk/) (Delivery SDK wiring), [src/types/](src/types/), [src/format/](src/format/), [src/logger/](src/logger/), [src/constants/](src/constants/). + +## Common commands + +| Command | Purpose | +| --- | --- | +| `npm run build` | Run `tsup` (also runs on `npm run prepare`) | +| `npm test` | Jest with `--testPathPattern=tests` and `NODE_OPTIONS=--experimental-vm-modules` | +| `npm run test:unit:report:json` | Unit tests under `tests/unit` with coverage and JSON reports (used in CI) | + +There is **no ESLint** script in this package; rely on TypeScript strictness and project conventions. + +## Credentials and integration tests + +Integration tests need a live stack. Set a **`.env`** at the repo root (see integration tests under `tests/integration/`) or export variables in your shell. Typical names: + +`TOKEN`, `APIKEY`, `ENVIRONMENT`, `REGION`, `TOKENTYPE`, `BRANCH` + +CI injects these from GitHub Actions secrets (see [.github/workflows/node.js.yml](.github/workflows/node.js.yml)), including `TOKEN_WITH_NO_CT` and `APIKEY_WITH_NO_CT` where tests require them. + +--- + +## AI guidance index + +- [Cursor rules (overview)](.cursor/rules/README.md) — when each rule applies and how to reference it. +- [Skills index](skills/README.md) — deeper checklists and package mental model. diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000..7480ed8 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,11 @@ +# Skills for `@contentstack/types-generator` + +Short index of deeper guidance (use alongside [AGENTS.md](../AGENTS.md) and [`.cursor/rules/`](../.cursor/rules/README.md)). + +| Skill | When to use | +| --- | --- | +| [code-review](code-review/SKILL.md) | Preparing or reviewing a PR: API docs, compatibility, errors, security, tests, Delivery vs Management terminology. | +| [testing](testing/SKILL.md) | Running Jest, unit vs integration layout, `.env` and CI secrets, content-type fixtures. | +| [typescript-types-generator](typescript-types-generator/SKILL.md) | Understanding `generateTS` vs `graphqlTS`, main modules, and where to change behavior. | + +There is no separate **framework** skill: HTTP/GraphQL details are covered in [contentstack-delivery-cda.mdc](../.cursor/rules/contentstack-delivery-cda.mdc) and the typescript skill. diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md new file mode 100644 index 0000000..065ca66 --- /dev/null +++ b/skills/code-review/SKILL.md @@ -0,0 +1,47 @@ +--- +name: code-review +description: PR review checklist for @contentstack/types-generator (API docs, compatibility, errors, tests, CDA/GraphQL terminology). +--- + +# Code review skill (`@contentstack/types-generator`) + +Expanded checklist aligned with [`.cursor/rules/code-review.mdc`](../../.cursor/rules/code-review.mdc). + +## Documentation and API surface + +- Public exports from [`src/index.ts`](../../src/index.ts) should stay coherent and documented (JSDoc on exported functions where the package documents behavior). +- **`generateTS`** / **`graphqlTS`** options and error behavior should match README and real usage. + +## Product terminology + +- This library is **Delivery (CDA)** + **GraphQL** only. Do not label features or errors as **CMA** or Management API unless you are explicitly comparing upstream docs—and even then, keep user-facing text accurate to this package. + +## Backward compatibility + +- Generated TypeScript shape changes can break consumers; treat output as a semver-sensitive API. +- Error objects with **`type`** and **`error_message`** should remain predictable; document intentional changes. + +## Error handling + +- Prefer existing helpers (**`createValidationError`**, **`createErrorDetails`**) and patterns in [`src/generateTS`](../../src/generateTS) / [`src/graphqlTS`](../../src/graphqlTS). +- SDK initialization errors in [`src/sdk/utils.ts`](../../src/sdk/utils.ts) use **`type: "validation"`**; keep consistency. + +## Null and config safety + +- Optional **`host`**, **`branch`**, logger instances, and stack parameters must be guarded per **`strictNullChecks`**. + +## Dependencies and security + +- Justify new runtime dependencies (bundle size, maintenance). +- CI runs SCA (Snyk + policy) on pull requests—consider supply-chain impact of new packages. + +## Tests + +- **Unit:** [`tests/unit/`](../../tests/unit/) for deterministic logic; use **`.ct.js`** fixtures with matching **`.test.ts`** where applicable. +- **Integration:** [`tests/integration/`](../../tests/integration/) for live stack tests; require documented env vars. + +## Optional severity tags + +- **Blocker:** breaks consumers, security issue, or wrong API family (e.g. CMA-only assumption). +- **Major:** missing tests for new behavior, unclear errors, semver risk. +- **Minor:** style, small doc gaps, non-user-facing refactors. diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md new file mode 100644 index 0000000..675ce5e --- /dev/null +++ b/skills/testing/SKILL.md @@ -0,0 +1,38 @@ +--- +name: testing +description: How to run and write tests for @contentstack/types-generator (Jest, unit vs integration, env, fixtures). +--- + +# Testing skill (`@contentstack/types-generator`) + +## Commands + +| Command | What it runs | +| --- | --- | +| `npm test` | Jest with `--testPathPattern=tests` and `NODE_OPTIONS=--experimental-vm-modules` ([`package.json`](../../package.json)). | +| `npm run test:unit:report:json` | Unit tests only (`tests/unit`), coverage (clover + json), `test-results.json` — mirrors CI. | +| `npm run build` | Build first if imports from `dist/` matter (normally tests import `src/`). | + +[`jest.config.js`](../../jest.config.js) sets **`setupFiles: ["dotenv/config"]`** so `.env` keys load when present. + +## Layout + +- **`tests/unit/`** — Fast tests; **`tests/unit/tsgen/`** pairs **`.ct.js`** content-type fixtures with **`.test.ts`** files. +- **`tests/integration/`** — Live API tests (e.g. `generateTS`, `graphqlTS`); need credentials. + +## Environment variables (integration) + +Common variables read in integration tests: + +- **`TOKEN`**, **`APIKEY`**, **`ENVIRONMENT`**, **`REGION`**, **`TOKENTYPE`**, **`BRANCH`** + +Some tests use **`TOKEN_WITH_NO_CT`** / **`APIKEY_WITH_NO_CT`** (see CI env in [`.github/workflows/node.js.yml`](../../.github/workflows/node.js.yml)). Integration specs may load **`.env`** from the package root via `dotenv` paths—check the specific test file. + +## Mocks + +- **`axios-mock-adapter`** and **`nock`** are devDependencies for HTTP mocking when adding unit tests around network code. + +## Timeouts and coverage + +- Use reasonable async timeouts for integration tests hitting real endpoints. +- CI publishes coverage from **`test:unit:report:json`**; keep new unit code covered when practical. diff --git a/skills/typescript-types-generator/SKILL.md b/skills/typescript-types-generator/SKILL.md new file mode 100644 index 0000000..da9df6e --- /dev/null +++ b/skills/typescript-types-generator/SKILL.md @@ -0,0 +1,37 @@ +--- + +## name: typescript-types-generator +description: Mental model for @contentstack/types-generator — generateTS pipeline, graphqlTS, and where to change code. + +# TypeScript types generator skill + +Package: `**@contentstack/types-generator**`. Entry: `[src/index.ts](../../src/index.ts)` re-exports `**generateTS**` and `**graphqlTS**`. + +## `generateTS` (Delivery / content types) + +1. **Validation** — Required params include `**token`**, `**tokenType**`, `**apiKey**`, `**environment**`, `**region**` (`[src/generateTS/index.ts](../../src/generateTS/index.ts)`). Only `**TOKEN_TYPE.DELIVERY**` is supported in constants. +2. **SDK** — `[initializeContentstackSdk](../../src/sdk/utils.ts)` builds a Delivery stack client; fetches content types and global fields. +3. **Generation** — `**tsgenFactory`** / `[factory.ts](../../src/generateTS/factory.ts)` drives type emission; **docgen** picks JSDoc vs null doc via `[docgen/](../../src/generateTS/docgen/)`; **builtins** in `[stack/builtins.ts](../../src/generateTS/stack/builtins.ts)`. +4. **Formatting** — `[src/format/index.ts](../../src/format/index.ts)` + **Prettier** produce the final string. +5. **Errors** — Shared helpers in `[generateTS/shared/utils.ts](../../src/generateTS/shared/utils.ts)`; validation uses `**createValidationError`** where applicable. + +**Where to change:** New field types or schema handling → `**factory.ts`**, `**types/schema**`, docgen modules. Connection issues → `**sdk/utils.ts**`. + +## `graphqlTS` (GraphQL introspection) + +1. **Validation** — Requires `**token`**, `**apiKey**`, `**environment**`, `**region**` (optional `**host**`, `**branch**`, `**namespace**`). +2. **HTTP** — `**axios`** POST to region GraphQL base URLs or custom `**host**` (`[src/graphqlTS/index.ts](../../src/graphqlTS/index.ts)`). +3. **Types** — Introspection query in `[queries.ts](../../src/graphqlTS/queries.ts)`; `**@gql2ts/from-schema`** builds interfaces. + +**Where to change:** Endpoint or headers → `**graphqlTS/index.ts`**; introspection shape → **queries** + gql2ts usage. + +## Shared pieces + +- **Constants / messages:** `[src/constants/](../../src/constants/)` +- **Logger:** `[src/logger/](../../src/logger/)` +- **Types:** `[src/types/](../../src/types/)` + +## Secondary entry + +- `**src/web.ts`** re-exports from `**generateTS**` only (`[web` bundle in tsup](../../tsup.config.ts))—keep exports minimal and consistent with the main package story. +