From 2cd3ed47d955c10aa788e2fea2f43d97dcb7fd32 Mon Sep 17 00:00:00 2001 From: raj pandey Date: Wed, 8 Apr 2026 12:10:33 +0530 Subject: [PATCH] Removed the references --- skills/code-review/SKILL.md | 52 ++++++++- skills/code-review/references/checklist.md | 52 --------- skills/contentstack-cli-content-type/SKILL.md | 109 +++++++++++++++++- .../references/architecture.md | 58 ---------- .../references/commands.md | 48 -------- skills/testing/SKILL.md | 67 ++++++++++- skills/testing/references/conventions.md | 26 ----- skills/testing/references/jest-mocking.md | 37 ------ 8 files changed, 215 insertions(+), 234 deletions(-) delete mode 100644 skills/code-review/references/checklist.md delete mode 100644 skills/contentstack-cli-content-type/references/architecture.md delete mode 100644 skills/contentstack-cli-content-type/references/commands.md delete mode 100644 skills/testing/references/conventions.md delete mode 100644 skills/testing/references/jest-mocking.md diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index ee840a4..7e1b652 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -18,6 +18,8 @@ description: >- Provide consistent **security**, **correctness**, and **maintainability** review for this repository. The plugin handles stack API keys in error messages, opens **HTML** diffs in a browser, and writes **diagram** files via Graphviz. +Use **Critical** / **Important** / **Suggestion** when leaving feedback. + ### Highlights - **Secrets**: Never approve logging of tokens, `authtoken` / `authorization` values, or raw management tokens. @@ -25,12 +27,56 @@ Provide consistent **security**, **correctness**, and **maintainability** review - **Dependencies**: axios, diff2html, git-diff, node-graphviz, tmp, cli-ux—review changelog and supply-chain for version bumps. - **Quality**: TypeScript and **eslint-config-oclif-typescript** ([.eslintrc](../../.eslintrc)); behavioral changes should include or update **Jest** tests where appropriate. -### Full checklist +### Security and privacy + +| Severity | Item | +|----------|------| +| Critical | No logging or serializing of **access tokens**, **management tokens**, or **Bearer** strings. | +| Critical | No new `console.log` of full API responses that may contain secrets. | +| Important | Stack API keys appear in user-facing errors only in line with [src/core/contentstack/client.ts](../../src/core/contentstack/client.ts) (`buildError` + optional key suffix). | + +### Correctness + +| Severity | Item | +|----------|------| +| Critical | Command flags and `setup(flags)` behavior remain consistent; **compare-remote** still resolves origin vs remote stacks correctly. | +| Important | **Compare**: left/right version logic and warning when versions are equal; HTML output path and browser open behavior unchanged unless intentionally redesigned. | +| Important | **Diagram**: output path validation; Graphviz / DOT paths; orientation and file type flags. | +| Suggestion | Edge cases for empty audit logs, missing references, or single-version content types. | + +### Compare and diagram (touching core) + +| Severity | Item | +|----------|------| +| Critical | [compare.ts](../../src/core/content-type/compare.ts): temp HTML creation does not write sensitive data beyond the diff; file handling is safe on failure paths. | +| Important | [diagram.ts](../../src/core/content-type/diagram.ts): `sanitizePath` / path usage; large stack models do not cause unbounded memory without consideration. | +| Suggestion | User messaging when Graphviz is missing or SVG generation fails. | + +### Dependencies + +| Severity | Item | +|----------|------| +| Important | **axios**: security advisories; upgrade notes. | +| Important | **diff2html**, **git-diff**, **tmp**, **cli-ux**: behavior changes affecting compare UX. | +| Important | **node-graphviz**: compatibility with supported Node and system Graphviz. | +| Suggestion | **moment** (if touched): prefer minimal churn; note maintenance status of dependencies. | + +### Tests and tooling + +| Severity | Item | +|----------|------| +| Important | New behavior in `src/core/` or `src/utils/` has **Jest** coverage or a clear reason why not. | +| Important | `npm test` and **ESLint** (`posttest` / [`.eslintrc`](../../.eslintrc)) pass. | +| Suggestion | Tests mock HTTP/SDK boundaries; no accidental live API calls. | + +### Documentation -Use [references/checklist.md](references/checklist.md) for the printable severity-labeled checklist. +| Severity | Item | +|----------|------| +| Important | If commands or flags change, **README** (generated via `oclif readme`) is updated via `prepack` / `version` workflow. | +| Suggestion | User-facing strings and examples match `src/commands/content-type/*.ts` examples. | ## References -- [references/checklist.md](references/checklist.md) - [testing/SKILL.md](../testing/SKILL.md) — test and lint expectations. - [contentstack-cli-content-type/SKILL.md](../contentstack-cli-content-type/SKILL.md) — architecture and risky areas. diff --git a/skills/code-review/references/checklist.md b/skills/code-review/references/checklist.md deleted file mode 100644 index 32d54ea..0000000 --- a/skills/code-review/references/checklist.md +++ /dev/null @@ -1,52 +0,0 @@ -# PR review checklist - -Use **Critical** / **Important** / **Suggestion** when leaving feedback. - -## Security and privacy - -| Severity | Item | -|----------|------| -| Critical | No logging or serializing of **access tokens**, **management tokens**, or **Bearer** strings. | -| Critical | No new `console.log` of full API responses that may contain secrets. | -| Important | Stack API keys appear in user-facing errors only in line with [src/core/contentstack/client.ts](../../../src/core/contentstack/client.ts) (`buildError` + optional key suffix). | - -## Correctness - -| Severity | Item | -|----------|------| -| Critical | Command flags and `setup(flags)` behavior remain consistent; **compare-remote** still resolves origin vs remote stacks correctly. | -| Important | **Compare**: left/right version logic and warning when versions are equal; HTML output path and browser open behavior unchanged unless intentionally redesigned. | -| Important | **Diagram**: output path validation; Graphviz / DOT paths; orientation and file type flags. | -| Suggestion | Edge cases for empty audit logs, missing references, or single-version content types. | - -## Compare and diagram (touching core) - -| Severity | Item | -|----------|------| -| Critical | [compare.ts](../../../src/core/content-type/compare.ts): temp HTML creation does not write sensitive data beyond the diff; file handling is safe on failure paths. | -| Important | [diagram.ts](../../../src/core/content-type/diagram.ts): `sanitizePath` / path usage; large stack models do not cause unbounded memory without consideration. | -| Suggestion | User messaging when Graphviz is missing or SVG generation fails. | - -## Dependencies - -| Severity | Item | -|----------|------| -| Important | **axios**: security advisories; upgrade notes. | -| Important | **diff2html**, **git-diff**, **tmp**, **cli-ux**: behavior changes affecting compare UX. | -| Important | **node-graphviz**: compatibility with supported Node and system Graphviz. | -| Suggestion | **moment** (if touched): prefer minimal churn; note maintenance status of dependencies. | - -## Tests and tooling - -| Severity | Item | -|----------|------| -| Important | New behavior in `src/core/` or `src/utils/` has **Jest** coverage or a clear reason why not. | -| Important | `npm test` and **ESLint** (`posttest` / [`.eslintrc`](../../../.eslintrc)) pass. | -| Suggestion | Tests mock HTTP/SDK boundaries; no accidental live API calls. | - -## Documentation - -| Severity | Item | -|----------|------| -| Important | If commands or flags change, **README** (generated via `oclif readme`) is updated via `prepack` / `version` workflow. | -| Suggestion | User-facing strings and examples match `src/commands/content-type/*.ts` examples. | diff --git a/skills/contentstack-cli-content-type/SKILL.md b/skills/contentstack-cli-content-type/SKILL.md index 056baed..e9e91c9 100644 --- a/skills/contentstack-cli-content-type/SKILL.md +++ b/skills/contentstack-cli-content-type/SKILL.md @@ -33,7 +33,43 @@ npm package `contentstack-cli-content-type`: a **Contentstack CLI** (`csdx`) plu | Types | `src/types/index.ts` | | Config (pagination limits) | `src/config/index.ts` | -Commands **parse flags**, call **`setup(flags)`**, build **`managementSDKClient`**, then call utils + core builders. See [references/architecture.md](references/architecture.md) and [references/commands.md](references/commands.md). +Commands **parse flags**, call **`setup(flags)`**, build **`managementSDKClient`**, then call utils + core builders. + +### Command → core modules + +| Command file | Core / utilities | Notes | +|--------------|------------------|--------| +| `src/commands/content-type/audit.ts` | `core/content-type/audit.ts`, `utils` (`getStack`, `getUsers`, `getContentType`), `client.getContentTypeAuditLogs` | Audit + users for display | +| `src/commands/content-type/compare.ts` | `core/content-type/compare.ts`, `utils` | Same-stack two versions; optional `--left` / `--right` | +| `src/commands/content-type/compare-remote.ts` | `core/content-type/compare.ts` (same `buildOutput`), `utils` | Two stacks; `setup` uses origin stack key only | +| `src/commands/content-type/details.ts` | `core/content-type/details.ts`, `utils`, `client.getContentTypeReferences` | `--path` / `--no-path` | +| `src/commands/content-type/diagram.ts` | `core/content-type/diagram.ts`, `utils` (`getStack`, `getContentTypes`, `getGlobalFields`) | Writes file via Graphviz | +| `src/commands/content-type/list.ts` | `core/content-type/list.ts`, `utils` | `--order title|modified` | + +Formatting helpers live under `src/core/content-type/formatting.ts` where imported by core modules. + +### Auth flow (high level) + +```mermaid +flowchart LR + subgraph setup [ContentTypeCommand.setup] + A[getAuthDetails] + B{accessToken?} + C[error auth:login] + D{alias or stack key?} + E[exit 1 missing stack] + F[getToken or use stack API key] + G[ContentstackClient] + end + A --> B + B -->|no| C + B -->|yes| D + D -->|neither| E + D -->|ok| F + F --> G +``` + +- **`compare-remote`**: `setup` is called with `{ alias: undefined, stack: flags["origin-stack"] }` so `apiKey` is the **origin** stack API key; remote stack is passed only in `getStack` / `getContentType` calls. ### Authentication and stack identity @@ -46,9 +82,76 @@ Commands **parse flags**, call **`setup(flags)`**, build **`managementSDKClient` ### Two ways to call APIs -- **Axios `ContentstackClient`**: `GET https://{cmaHost}/v3/...` with default headers `authorization` (if Bearer) or `authtoken`, plus per-request `headers: { api_key }`. Used for audit logs and references. Errors → `ContentstackError` via `buildError`. +- **Axios `ContentstackClient`**: `GET https://{cmaHost}/v3/...` with default headers `authorization` (if Bearer) or `authtoken`, plus per-request `headers: { api_key }`. Used for audit logs and CT references. Errors → `ContentstackError` via `buildError`. - **Management SDK** (`managementSDKClient({ host, 'X-CS-CLI': ... })`): stack fetch, content types, global fields, content type by version—see `src/utils/index.ts`. +**CMA request shape (`ContentstackClient`)** + +- **Base URL**: `https://{cmaHost}/v3/` (`cmaHost` from command context). +- **Default axios headers**: `authorization: ` if token string includes `Bearer`, else `authtoken: `. +- **Per-request**: `headers: { api_key: }` for stack-scoped routes. + +| Method | HTTP | Path / params | +|--------|------|----------------| +| `getContentTypeAuditLogs` | GET | `/audit-logs` — `params.query.$and`: `module: content_type`, `metadata.uid` | +| `getContentTypeReferences` | GET | `/content_types/{uid}/references` — `include_global_fields: true` | + +Errors: response `data.errors` → `ContentstackError`; optional suffix with stack API key when `data.errors.api_key` and context `api_key` are set. + +### Compare and diagram pipelines + +- **Compare**: `core/content-type/compare.ts` builds a unified diff from two JSON snapshots (`git-diff`), parses with **diff2html**, writes a **temporary HTML** file, opens it in the browser (`cli-ux` / `cli.open`). Not a terminal table. +- **Diagram**: `core/content-type/diagram.ts` builds a DOT graph, runs **node-graphviz** (`graphviz` binary must be available on the system for SVG rendering). Output path is sanitized where utilities apply. + +### Commands (flags and behavior) + +Primary sources: `README.md` and `src/commands/content-type/*.ts`. + +#### `content-type:list` + +- **Flags**: `--stack-api-key` (`-k`), `--stack` (deprecated → use stack key), `--token-alias` / `--alias` (`-a`), `--order` (`-o`) `title` \| `modified` (default `title`). +- **Files**: `src/commands/content-type/list.ts`, `src/core/content-type/list.ts`. +- **Behavior**: Lists Content Types for the stack; table output via core builder. + +#### `content-type:details` + +- **Flags**: stack identity flags as above; `--content-type` (`-c`) required; `--path` / `--no-path` (`-p`) — default shows path column; use `--no-path` on narrow terminals (README). +- **Files**: `src/commands/content-type/details.ts`, `src/core/content-type/details.ts`. +- **Behavior**: Fetches CT + **references** via `ContentstackClient.getContentTypeReferences`. + +#### `content-type:audit` + +- **Flags**: stack identity + `--content-type` (`-c`) required. +- **Files**: `src/commands/content-type/audit.ts`, `src/core/content-type/audit.ts`. +- **Behavior**: Audit logs via `getContentTypeAuditLogs`; README notes **audit log retention** (e.g. 90 days) per Contentstack docs. + +#### `content-type:compare` + +- **Flags**: stack identity + `--content-type` (`-c`); optional `--left` (`-l`) / `--right` (`-r`) **integers** (both required if either set). If omitted, command infers latest version vs previous from discovery fetch. +- **Files**: `src/commands/content-type/compare.ts`, `src/core/content-type/compare.ts`. +- **Behavior**: Side-by-side diff in **HTML** in a browser; not stdout-only. Warns if left === right. + +#### `content-type:compare-remote` + +- **Flags**: `--origin-stack` (`-o`) and `--remote-stack` (`-r`) **required** (stack API keys); `--content-type` (`-c`) required. No token-alias flow for two stacks—setup uses **origin** stack key for session. +- **Files**: `src/commands/content-type/compare-remote.ts`, same `core/content-type/compare.ts` as same-stack compare. +- **Behavior**: Same HTML diff pipeline; compares CT JSON from two stacks. Warns if origin === remote API key. + +#### `content-type:diagram` + +- **Flags**: stack identity; `--output` (`-o`) **required** (full path); `--direction` (`-d`) `portrait` \| `landscape` (required in schema, default portrait); `--type` (`-t`) `svg` \| `dot` (default svg). +- **Files**: `src/commands/content-type/diagram.ts`, `src/core/content-type/diagram.ts`. +- **Behavior**: Loads all content types + global fields; renders graph. **Graphviz** must be installed for typical SVG generation; DOT export available. README documents `-t dot` for raw DOT language. + +### Editing checklist + +| Change | Touch first | +|--------|-------------| +| New flag / description | Command file under `src/commands/content-type/`, then `oclif readme` | +| Output format / table | `src/core/content-type/*.ts`, `formatting.ts` | +| REST audit/references | `src/core/contentstack/client.ts`, `error.ts` | +| SDK pagination / fetch | `src/utils/index.ts`, `src/config/index.ts` | + ### Build and CLI metadata `package.json` scripts **`prepack`** and **`version`** drive `tsc`, `oclif manifest`, and `oclif readme`. After changing commands, flags, or descriptions, keep **README.md** and **oclif.manifest.json** in sync—see [dev-workflow/SKILL.md](../dev-workflow/SKILL.md) for commands and workflow. @@ -68,8 +171,6 @@ Commands **parse flags**, call **`setup(flags)`**, build **`managementSDKClient` ## References -- [references/architecture.md](references/architecture.md) — command → core mapping, auth flow, CMA shape. -- [references/commands.md](references/commands.md) — flags, UX notes, files to edit per command. - [dev-workflow/SKILL.md](../dev-workflow/SKILL.md) — TypeScript build, ESLint, oclif docs, `npm run prepack`. - [testing/SKILL.md](../testing/SKILL.md) — Jest layout, mocks, coverage. - [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/) (external). diff --git a/skills/contentstack-cli-content-type/references/architecture.md b/skills/contentstack-cli-content-type/references/architecture.md deleted file mode 100644 index 647a3d5..0000000 --- a/skills/contentstack-cli-content-type/references/architecture.md +++ /dev/null @@ -1,58 +0,0 @@ -# Architecture - -## Command → core modules - -| Command file | Core / utilities | Notes | -|--------------|------------------|--------| -| `src/commands/content-type/audit.ts` | `core/content-type/audit.ts`, `utils` (`getStack`, `getUsers`, `getContentType`), `client.getContentTypeAuditLogs` | Audit + users for display | -| `src/commands/content-type/compare.ts` | `core/content-type/compare.ts`, `utils` | Same-stack two versions; optional `--left` / `--right` | -| `src/commands/content-type/compare-remote.ts` | `core/content-type/compare.ts` (same `buildOutput`), `utils` | Two stacks; `setup` uses origin stack key only | -| `src/commands/content-type/details.ts` | `core/content-type/details.ts`, `utils`, `client.getContentTypeReferences` | `--path` / `--no-path` | -| `src/commands/content-type/diagram.ts` | `core/content-type/diagram.ts`, `utils` (`getStack`, `getContentTypes`, `getGlobalFields`) | Writes file via Graphviz | -| `src/commands/content-type/list.ts` | `core/content-type/list.ts`, `utils` | `--order title|modified` | - -Formatting helpers live under `src/core/content-type/formatting.ts` where imported by core modules. - -## Auth flow (high level) - -```mermaid -flowchart LR - subgraph setup [ContentTypeCommand.setup] - A[getAuthDetails] - B{accessToken?} - C[error auth:login] - D{alias or stack key?} - E[exit 1 missing stack] - F[getToken or use stack API key] - G[ContentstackClient] - end - A --> B - B -->|no| C - B -->|yes| D - D -->|neither| E - D -->|ok| F - F --> G -``` - -- **`compare-remote`**: `setup` is called with `{ alias: undefined, stack: flags["origin-stack"] }` so `apiKey` is the **origin** stack API key; remote stack is passed only in `getStack` / `getContentType` calls. - -## CMA request shape (ContentstackClient) - -- **Base URL**: `https://{cmaHost}/v3/` (`cmaHost` from command context). -- **Default axios headers**: `authorization: ` if token string includes `Bearer`, else `authtoken: `. -- **Per-request**: `headers: { api_key: }` for stack-scoped routes. - -| Method | HTTP | Path / params | -|--------|------|----------------| -| `getContentTypeAuditLogs` | GET | `/audit-logs` — `params.query.$and`: `module: content_type`, `metadata.uid` | -| `getContentTypeReferences` | GET | `/content_types/{uid}/references` — `include_global_fields: true` | - -Errors: response `data.errors` → `ContentstackError`; optional suffix with stack API key when `data.errors.api_key` and context `api_key` are set. - -## Compare output pipeline - -`core/content-type/compare.ts` builds a unified diff from two JSON snapshots (`git-diff`), parses with **diff2html**, writes a **temporary HTML** file, opens it in the browser (`cli-ux` / `cli.open`). Not a terminal table. - -## Diagram pipeline - -`core/content-type/diagram.ts` builds a DOT graph, runs **node-graphviz** (`graphviz` binary must be available on the system for SVG rendering). Output path is sanitized where utilities apply. diff --git a/skills/contentstack-cli-content-type/references/commands.md b/skills/contentstack-cli-content-type/references/commands.md deleted file mode 100644 index 33820fc..0000000 --- a/skills/contentstack-cli-content-type/references/commands.md +++ /dev/null @@ -1,48 +0,0 @@ -# Commands reference - -Primary sources: `README.md` and `src/commands/content-type/*.ts`. - -## `content-type:list` - -- **Flags**: `--stack-api-key` (`-k`), `--stack` (deprecated → use stack key), `--token-alias` / `--alias` (`-a`), `--order` (`-o`) `title` | `modified` (default `title`). -- **Files**: `src/commands/content-type/list.ts`, `src/core/content-type/list.ts`. -- **Behavior**: Lists Content Types for the stack; table output via core builder. - -## `content-type:details` - -- **Flags**: stack identity flags as above; `--content-type` (`-c`) required; `--path` / `--no-path` (`-p`) — default shows path column; use `--no-path` on narrow terminals (README). -- **Files**: `src/commands/content-type/details.ts`, `src/core/content-type/details.ts`. -- **Behavior**: Fetches CT + **references** via `ContentstackClient.getContentTypeReferences`. - -## `content-type:audit` - -- **Flags**: stack identity + `--content-type` (`-c`) required. -- **Files**: `src/commands/content-type/audit.ts`, `src/core/content-type/audit.ts`. -- **Behavior**: Audit logs via `getContentTypeAuditLogs`; README notes **audit log retention** (e.g. 90 days) per Contentstack docs. - -## `content-type:compare` - -- **Flags**: stack identity + `--content-type` (`-c`); optional `--left` (`-l`) / `--right` (`-r`) **integers** (both required if either set). If omitted, command infers latest version vs previous from discovery fetch. -- **Files**: `src/commands/content-type/compare.ts`, `src/core/content-type/compare.ts`. -- **Behavior**: Side-by-side diff in **HTML** in a browser; not stdout-only. Warns if left === right. - -## `content-type:compare-remote` - -- **Flags**: `--origin-stack` (`-o`) and `--remote-stack` (`-r`) **required** (stack API keys); `--content-type` (`-c`) required. No token-alias flow for two stacks—setup uses **origin** stack key for session. -- **Files**: `src/commands/content-type/compare-remote.ts`, same `core/content-type/compare.ts` as same-stack compare. -- **Behavior**: Same HTML diff pipeline; compares CT JSON from two stacks. Warns if origin === remote API key. - -## `content-type:diagram` - -- **Flags**: stack identity; `--output` (`-o`) **required** (full path); `--direction` (`-d`) `portrait` | `landscape` (required in schema, default portrait); `--type` (`-t`) `svg` | `dot` (default svg). -- **Files**: `src/commands/content-type/diagram.ts`, `src/core/content-type/diagram.ts`. -- **Behavior**: Loads all content types + global fields; renders graph. **Graphviz** must be installed for typical SVG generation; DOT export available. README documents `-t dot` for raw DOT language. - -## Editing checklist - -| Change | Touch first | -|--------|-------------| -| New flag / description | Command file under `src/commands/content-type/`, then `oclif readme` | -| Output format / table | `src/core/content-type/*.ts`, `formatting.ts` | -| REST audit/references | `src/core/contentstack/client.ts`, `error.ts` | -| SDK pagination / fetch | `src/utils/index.ts`, `src/config/index.ts` | diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md index c8e0017..5afbb13 100644 --- a/skills/testing/SKILL.md +++ b/skills/testing/SKILL.md @@ -32,15 +32,70 @@ description: >- When validating changes, run **`npm test`**; ensure **ESLint** still passes (posttest or `eslint` directly). Use **`npm run test:coverage`** when changing `src/core/` or `src/utils/` behavior. -### What to test +### Naming and structure -- **Pure functions** and **core builders** in `src/core/content-type/` with inputs/outputs mocked at the boundary. -- **ContentstackClient**: mock `get` on the axios instance or mock the whole module—**no live CMA** or real stack keys in unit tests. -- **Commands**: prefer testing **core** and **utils** first; command tests may require heavy mocking of `@contentstack/cli-utilities` (auth, cliux, management SDK). +- Prefer **`it` / `test`** descriptions that state behavior: `should when ` (or close variants), e.g. `should return sorted titles when order is title`. +- Group related cases with **`describe`** blocks named after the unit under test (module, function, or command behavior). + +### What to test (order) + +1. **Pure helpers** and **core builders** in `src/core/content-type/` — easiest to drive with inputs and assert outputs. +2. **`src/utils/index.ts`** — mock Management SDK / stack boundaries. +3. **Command classes** — only when needed; they pull in `@contentstack/cli-utilities` (auth, cliux) and need heavier mocks. + +In all cases: **pure functions** and **core builders** benefit from inputs/outputs mocked at the boundary; **ContentstackClient** via mock `get` on axios or mock the whole module—**no live CMA** or real stack keys in unit tests. **Commands**: prefer testing **core** and **utils** first; command tests may require heavy mocking of `@contentstack/cli-utilities` (auth, cliux, management SDK). + +### Mocking boundaries + +- **No live Contentstack API** calls and no real stack keys in unit tests. +- Mock **`ContentstackClient`** (axios), **Management SDK** chains, or **`authenticationHandler`** as in **Jest mocking** below. + +### Jest mocking (this repo) + +1. **No live API calls** — Do not hit Contentstack Management API or real stacks in unit tests. +2. **Mock at the boundary** — Prefer mocking `ContentstackClient` methods, axios, or `@contentstack/cli-utilities` pieces (e.g. `managementSDKClient`, `authenticationHandler`) when testing command flows. +3. **Coverage** — Follow global thresholds in [jest.config.js](../../jest.config.js) and the summary in [AGENTS.md](../../AGENTS.md). + +**Mocking `ContentstackClient`** + +Example pattern: spy or replace methods that perform HTTP: + +```typescript +import ContentstackClient from '../src/core/contentstack/client' + +jest.mock('../src/core/contentstack/client', () => { + return jest.fn().mockImplementation(() => ({ + getContentTypeAuditLogs: jest.fn().mockResolvedValue({ logs: [] }), + getContentTypeReferences: jest.fn().mockResolvedValue({}), + })) +}) +``` + +Adjust import paths to match the file under test. For tests that import the class from the same path as production, use `jest.mock` with the factory before importing the subject. + +**Mocking axios** + +If testing code that constructs axios directly, use `jest.mock('axios')` and mock `axios.create` to return an instance whose `get`/`post` resolve with fixture data. Align with [src/core/contentstack/client.ts](../../src/core/contentstack/client.ts). + +**Management SDK helpers** + +[src/utils/index.ts](../../src/utils/index.ts) uses the stack SDK from `managementSDKClient`. In integration-style tests, pass a **fake** `managementSdk` object with `stack().contentType()...` chains that return Promises with fixture data instead of calling real APIs. + +**Style** + +- Use `describe` / `it` or `test` with clear names: what behavior, under what condition. +- Keep tests **deterministic** — no real network, no reliance on local `csdx` auth state unless explicitly using an e2e harness (not assumed here). + +### Commits and CI hygiene + +- Do not commit **`describe.only`**, **`it.only`**, **`test.only`**, or **`.skip`** variants. +- Run **`npm test`** before pushing; use **`npm run test:coverage`** when changing core logic to confirm coverage (see [jest.config.js](../../jest.config.js) thresholds and [AGENTS.md](../../AGENTS.md)). + +### Coverage goal + +- Target and enforcement are documented in [AGENTS.md](../../AGENTS.md) and [jest.config.js](../../jest.config.js). ## References -- [references/conventions.md](references/conventions.md) — naming, what to test first, no `.only`/`.skip`, coverage goal. -- [references/jest-mocking.md](references/jest-mocking.md) — mocking boundaries and minimal patterns. - [dev-workflow/SKILL.md](../dev-workflow/SKILL.md) — ESLint and CI expectations. - [AGENTS.md](../../AGENTS.md) — coverage targets and scripts. diff --git a/skills/testing/references/conventions.md b/skills/testing/references/conventions.md deleted file mode 100644 index 70a6767..0000000 --- a/skills/testing/references/conventions.md +++ /dev/null @@ -1,26 +0,0 @@ -# Testing conventions - -## Naming - -- Prefer **`it` / `test`** descriptions that state behavior: `should when ` (or close variants), e.g. `should return sorted titles when order is title`. -- Group related cases with **`describe`** blocks named after the unit under test (module, function, or command behavior). - -## What to test first - -1. **Pure helpers** and **core builders** in `src/core/content-type/` — easiest to drive with inputs and assert outputs. -2. **`src/utils/index.ts`** — mock Management SDK / stack boundaries. -3. **Command classes** — only when needed; they pull in `@contentstack/cli-utilities` (auth, cliux) and need heavier mocks. - -## Mocking boundaries - -- **No live Contentstack API** calls and no real stack keys in unit tests. -- Mock **`ContentstackClient`** (axios), **Management SDK** chains, or **`authenticationHandler`** as described in [jest-mocking.md](jest-mocking.md). - -## Commits and CI hygiene - -- Do not commit **`describe.only`**, **`it.only`**, **`test.only`**, or **`.skip`** variants. -- Run **`npm test`** before pushing; use **`npm run test:coverage`** when changing core logic to confirm coverage (see [jest.config.js](../../../jest.config.js) thresholds and [AGENTS.md](../../../AGENTS.md)). - -## Coverage goal - -- Target and enforcement are documented in [AGENTS.md](../../../AGENTS.md) and [jest.config.js](../../../jest.config.js). diff --git a/skills/testing/references/jest-mocking.md b/skills/testing/references/jest-mocking.md deleted file mode 100644 index 793b2f0..0000000 --- a/skills/testing/references/jest-mocking.md +++ /dev/null @@ -1,37 +0,0 @@ -# Jest mocking (this repo) - -## Principles - -1. **No live API calls** — Do not hit Contentstack Management API or real stacks in unit tests. -2. **Mock at the boundary** — Prefer mocking `ContentstackClient` methods, axios, or `@contentstack/cli-utilities` pieces (e.g. `managementSDKClient`, `authenticationHandler`) when testing command flows. -3. **Coverage** — Follow global thresholds in [jest.config.js](../../../jest.config.js) and the summary in [AGENTS.md](../../../AGENTS.md). - -## Mocking ContentstackClient - -Example pattern: spy or replace methods that perform HTTP: - -```typescript -import ContentstackClient from '../src/core/contentstack/client' - -jest.mock('../src/core/contentstack/client', () => { - return jest.fn().mockImplementation(() => ({ - getContentTypeAuditLogs: jest.fn().mockResolvedValue({ logs: [] }), - getContentTypeReferences: jest.fn().mockResolvedValue({}), - })) -}) -``` - -Adjust import paths to match the file under test. For tests that import the class from the same path as production, use `jest.mock` with the factory before importing the subject. - -## Mocking axios - -If testing code that constructs axios directly, use `jest.mock('axios')` and mock `axios.create` to return an instance whose `get`/`post` resolve with fixture data. Align with [src/core/contentstack/client.ts](../../../src/core/contentstack/client.ts). - -## Management SDK helpers - -[src/utils/index.ts](../../../src/utils/index.ts) uses the stack SDK from `managementSDKClient`. In integration-style tests, pass a **fake** `managementSdk` object with `stack().contentType()...` chains that return Promises with fixture data instead of calling real APIs. - -## Style - -- Use `describe` / `it` or `test` with clear names: what behavior, under what condition. -- Keep tests **deterministic** — no real network, no reliance on local `csdx` auth state unless explicitly using an e2e harness (not assumed here).