Skip to content

Commit 43f1bff

Browse files
naman-contentstacknaman-contentstack
authored
Merge pull request #167 from contentstack/feat/DX-5393
feat: add skills in type-gen package
2 parents 9e26792 + 9cf6674 commit 43f1bff

12 files changed

Lines changed: 335 additions & 0 deletions

File tree

‎.cursor/rules/README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Cursor rules for `@contentstack/types-generator`
2+
3+
This folder contains project-specific rules for AI assistants and developers. Each file lists its scope in YAML frontmatter (`description`, `globs`, `alwaysApply`).
4+
5+
6+
| Rule file | `alwaysApply` | Globs | When it applies | Related skill |
7+
| -------------------------------------------------------------- | ------------- | ------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------ |
8+
| [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) |
9+
| [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) |
10+
| [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) |
11+
| [testing.mdc](testing.mdc) | No | `tests/**`, `jest.config.js` | Writing or running Jest tests, env for live tests | [testing](../../skills/testing/SKILL.md) |
12+
| [code-review.mdc](code-review.mdc) | **Yes** | — | Every change: API docs, compatibility, errors, security, tests | [code-review](../../skills/code-review/SKILL.md) |
13+
14+
15+
## Referencing rules in Cursor
16+
17+
- 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.
18+
- Rules with `alwaysApply: true` are included automatically; others apply when matching files are in context or when @-mentioned.
19+

‎.cursor/rules/code-review.mdc‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
description: PR and change review checklist for types-generator
3+
alwaysApply: true
4+
---
5+
6+
# Code review checklist
7+
8+
Use this for every change. Severity labels are optional (**Blocker** / **Major** / **Minor**).
9+
10+
## API and documentation
11+
12+
- **Public API:** New or changed exports need **JSDoc** (or equivalent) where the package documents behavior; keep examples accurate.
13+
- **Terminology:** Use **CDA / Delivery** and **GraphQL** as in this codebase. **Do not** describe this library as CMA or Management-API–centric.
14+
15+
## Compatibility
16+
17+
- **Backward compatibility:** Avoid breaking changes to function signatures, error shapes, and generated output format unless versioned or documented.
18+
- **Errors:** Align with existing patterns: **`type: "validation"`** and related helpers in `generateTS` / `graphqlTS`; do not silently swallow SDK or network errors.
19+
20+
## Correctness and safety
21+
22+
- **Null safety:** Respect **`strictNullChecks`**; guard optional stack config (`host`, `branch`, etc.).
23+
- **Dependencies:** New dependencies need justification; watch license and footprint. **SCA:** `.github/workflows/sca-scan.yml` runs Snyk and `contentstack/sca-policy` on PRs.
24+
25+
## Tests
26+
27+
- **Unit:** Add or update tests under **`tests/unit/`** for logic changes.
28+
- **Integration / sanity:** Touch **`tests/integration/`** when behavior depends on live APIs; document required env vars.
29+
- **Coverage:** CI uses **`test:unit:report:json`**; keep meaningful coverage for new code paths.

‎.cursor/rules/contentstack-delivery-cda.mdc‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
description: Contentstack Delivery (CDA) SDK and GraphQL usage in types-generator
3+
globs:
4+
- src/sdk/**
5+
- src/generateTS/**
6+
- src/graphqlTS/**
7+
---
8+
9+
# Contentstack Delivery and GraphQL (this repo)
10+
11+
Scope: **SDK-facing library code only** (no separate `samples/` tree). This package is **not** a CMA (Management) client.
12+
13+
## Delivery / CDA
14+
15+
- **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.
16+
- **SDK entry:** [`initializeContentstackSdk`](src/sdk/utils.ts) wraps **`@contentstack/delivery-sdk`** (`Contentstack.stack` with `deliveryToken`, `environment`, `region` or `host`, optional `branch`).
17+
- **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)).
18+
- **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.
19+
20+
## GraphQL
21+
22+
- **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)).
23+
- **Schema:** Introspection query + **`@gql2ts/from-schema`** (`schemaToInterfaces`, `generateNamespace`). Align URL and headers (`access_token`, `branch`) with Contentstack GraphQL documentation for the target region.
24+
25+
When unsure, prefer official **Content Delivery API** / **GraphQL** docs—not Management API patterns.

‎.cursor/rules/dev-workflow.mdc‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
description: Branches, build/test commands, PR and release workflow for types-generator
3+
alwaysApply: false
4+
globs:
5+
- package.json
6+
- package-lock.json
7+
- .github/workflows/**/*
8+
- jest.config.js
9+
- tsup.config.ts
10+
- AGENTS.md
11+
---
12+
13+
# Development workflow
14+
15+
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.
16+
17+
## Branches
18+
19+
- **CI (Node.js workflow)** runs on **push** and **pull_request** for branches **`master`** and **`development`** (see `.github/workflows/node.js.yml`).
20+
- **Release / publish** runs on **push** to **`main`** (see `.github/workflows/release.yml`), using Node **22.x**, autotag, npm publish, and GitHub release.
21+
22+
**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.
23+
24+
## Local commands
25+
26+
- **Build:** `npm run build` (tsup; `prepare` also runs build).
27+
- **Test (all under `tests/`):** `npm test` (sets `NODE_OPTIONS=--experimental-vm-modules`).
28+
- **Unit tests + coverage (CI):** `npm run test:unit:report:json` (targets `tests/unit`, coverage and JSON artifacts).
29+
30+
## Pull requests
31+
32+
- Ensure **`npm run build`** and **`npm test`** pass before requesting review.
33+
- 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.
34+
35+
## Releases
36+
37+
- Version in **`package.json`** is the source of truth for the published package.
38+
- 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.

‎.cursor/rules/testing.mdc‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
description: Jest tests, layout, and env for types-generator
3+
globs:
4+
- tests/**
5+
- jest.config.js
6+
---
7+
8+
# Testing (`@contentstack/types-generator`)
9+
10+
- **Runner:** **Jest** with **ts-jest** ([jest.config.js](jest.config.js)). **`setupFiles: ["dotenv/config"]`** loads environment variables for tests.
11+
- **Match:** `**/?(*.)+(spec|test).+(ts|tsx)` and `test/**/*.test.ts`.
12+
- **Layout:**
13+
- **`tests/unit/`** — fast, isolated tests (including `tests/unit/tsgen/` with **`.ct.js`** content-type fixtures paired with **`.test.ts`** files).
14+
- **`tests/integration/`** — live stack / API tests (e.g. `generateTS`, `graphqlTS`); require real credentials.
15+
- **Commands:**
16+
- `npm test` — all tests under `tests` (via `--testPathPattern=tests`).
17+
- `npm run test:unit:report:json` — unit coverage + reports for CI.
18+
- **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.

‎.cursor/rules/typescript.mdc‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
description: TypeScript layout, strict mode, and logging for types-generator
3+
globs:
4+
- src/**/*.ts
5+
- tests/**/*.ts
6+
---
7+
8+
# TypeScript conventions (`@contentstack/types-generator`)
9+
10+
- **Compiler:** TypeScript **5.9** with **`strict`**, **`noImplicitAny`**, **`strictNullChecks`** ([tsconfig.json](tsconfig.json)). Prefer explicit types at public boundaries.
11+
- **Layout:** Source lives under **`src/`** — `generateTS/`, `graphqlTS/`, `sdk/`, `types/`, `format/`, `logger/`, `constants/`. Tests mirror under **`tests/unit/`** and **`tests/integration/`**.
12+
- **Logging:** Use **`createLogger`** from [`src/logger`](src/logger/index.ts); pass optional logger instances into `generateTS` / `graphqlTS` where supported.
13+
- **Formatting output:** **`prettier`** is a **runtime** dependency used to format generated TypeScript strings—not only dev formatting.
14+
- **Linting:** This package does **not** ship an ESLint config or `lint` script; do not assume ESLint fixes are available in CI.

‎.talismanrc‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,14 @@ fileignoreconfig:
44
- filecontent
55
- filename: package-lock.json
66
checksum: d392a5bf70cad2cb90afaf284410f580e359afe4f1a0a970a6f6061aee7c821c
7+
- filename: .cursor/rules/testing.mdc
8+
checksum: a3768ed70d1fa61e73d1838efbc3066859dd5dfce3fbefe40fb6c23800679a43
9+
- filename: skills/README.md
10+
checksum: ae09bf77a43f81f76a06f23ae2b2cbb1e81c490a66cf1b4e7df4e7142e22b5f5
11+
- filename: AGENTS.md
12+
checksum: 6ff4b2c6957f75f85f6afd188cc09af21ac9c90f05f87e4198674302b74bb021
13+
- filename: skills/testing/SKILL.md
14+
checksum: 858b4a830e74a0e90fe2f1097b4480a5eed513cdd88ba2646087399423ddee00
15+
- filename: skills/typescript-types-generator/SKILL.md
16+
checksum: aaa97f6eb31a66221ceedc7e5e965a9b13d33358a350dbfb3034014ece0c3e6c
717
version: "1.0"

‎AGENTS.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# `@contentstack/types-generator`
2+
3+
**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).
4+
5+
- **Repository:** [github.com/contentstack/types-generator](https://github.com/contentstack/types-generator)
6+
- **Homepage:** [https://github.com/contentstack/types-generator](https://github.com/contentstack/types-generator)
7+
8+
## Tech stack
9+
10+
| Area | Details |
11+
| --- | --- |
12+
| Language | TypeScript **5.9** (`strict` in [tsconfig.json](tsconfig.json)) |
13+
| Runtime | Node (CI on **18.x** and **20.x**; release workflow uses **22.x**) |
14+
| Build | **tsup** → `dist/` ([tsup.config.ts](tsup.config.ts)): entries `index` ([src/index.ts](src/index.ts)), `web` ([src/web.ts](src/web.ts)) |
15+
| Tests | **Jest** + **ts-jest** ([jest.config.js](jest.config.js)); `dotenv/config` in setup |
16+
| Main dependencies | `@contentstack/delivery-sdk`, `axios`, `@gql2ts/from-schema`, `lodash`, `async`, `prettier` |
17+
18+
This package targets **Content Delivery (CDA)** and **GraphQL** only—not the Management API (CMA).
19+
20+
## Public API and source layout
21+
22+
- **Package entry:** `main` / `module` / `types` point to `./dist/*` (see [package.json](package.json)).
23+
- **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/)).
24+
- **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/).
25+
26+
## Common commands
27+
28+
| Command | Purpose |
29+
| --- | --- |
30+
| `npm run build` | Run `tsup` (also runs on `npm run prepare`) |
31+
| `npm test` | Jest with `--testPathPattern=tests` and `NODE_OPTIONS=--experimental-vm-modules` |
32+
| `npm run test:unit:report:json` | Unit tests under `tests/unit` with coverage and JSON reports (used in CI) |
33+
34+
There is **no ESLint** script in this package; rely on TypeScript strictness and project conventions.
35+
36+
## Credentials and integration tests
37+
38+
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:
39+
40+
`TOKEN`, `APIKEY`, `ENVIRONMENT`, `REGION`, `TOKENTYPE`, `BRANCH`
41+
42+
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.
43+
44+
---
45+
46+
## AI guidance index
47+
48+
- [Cursor rules (overview)](.cursor/rules/README.md) — when each rule applies and how to reference it.
49+
- [Skills index](skills/README.md) — deeper checklists and package mental model.

‎skills/README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Skills for `@contentstack/types-generator`
2+
3+
Short index of deeper guidance (use alongside [AGENTS.md](../AGENTS.md) and [`.cursor/rules/`](../.cursor/rules/README.md)).
4+
5+
| Skill | When to use |
6+
| --- | --- |
7+
| [code-review](code-review/SKILL.md) | Preparing or reviewing a PR: API docs, compatibility, errors, security, tests, Delivery vs Management terminology. |
8+
| [testing](testing/SKILL.md) | Running Jest, unit vs integration layout, `.env` and CI secrets, content-type fixtures. |
9+
| [typescript-types-generator](typescript-types-generator/SKILL.md) | Understanding `generateTS` vs `graphqlTS`, main modules, and where to change behavior. |
10+
11+
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.

‎skills/code-review/SKILL.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
name: code-review
3+
description: PR review checklist for @contentstack/types-generator (API docs, compatibility, errors, tests, CDA/GraphQL terminology).
4+
---
5+
6+
# Code review skill (`@contentstack/types-generator`)
7+
8+
Expanded checklist aligned with [`.cursor/rules/code-review.mdc`](../../.cursor/rules/code-review.mdc).
9+
10+
## Documentation and API surface
11+
12+
- Public exports from [`src/index.ts`](../../src/index.ts) should stay coherent and documented (JSDoc on exported functions where the package documents behavior).
13+
- **`generateTS`** / **`graphqlTS`** options and error behavior should match README and real usage.
14+
15+
## Product terminology
16+
17+
- 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.
18+
19+
## Backward compatibility
20+
21+
- Generated TypeScript shape changes can break consumers; treat output as a semver-sensitive API.
22+
- Error objects with **`type`** and **`error_message`** should remain predictable; document intentional changes.
23+
24+
## Error handling
25+
26+
- Prefer existing helpers (**`createValidationError`**, **`createErrorDetails`**) and patterns in [`src/generateTS`](../../src/generateTS) / [`src/graphqlTS`](../../src/graphqlTS).
27+
- SDK initialization errors in [`src/sdk/utils.ts`](../../src/sdk/utils.ts) use **`type: "validation"`**; keep consistency.
28+
29+
## Null and config safety
30+
31+
- Optional **`host`**, **`branch`**, logger instances, and stack parameters must be guarded per **`strictNullChecks`**.
32+
33+
## Dependencies and security
34+
35+
- Justify new runtime dependencies (bundle size, maintenance).
36+
- CI runs SCA (Snyk + policy) on pull requests—consider supply-chain impact of new packages.
37+
38+
## Tests
39+
40+
- **Unit:** [`tests/unit/`](../../tests/unit/) for deterministic logic; use **`.ct.js`** fixtures with matching **`.test.ts`** where applicable.
41+
- **Integration:** [`tests/integration/`](../../tests/integration/) for live stack tests; require documented env vars.
42+
43+
## Optional severity tags
44+
45+
- **Blocker:** breaks consumers, security issue, or wrong API family (e.g. CMA-only assumption).
46+
- **Major:** missing tests for new behavior, unclear errors, semver risk.
47+
- **Minor:** style, small doc gaps, non-user-facing refactors.

0 commit comments

Comments
 (0)