Two files, one repository

contentstack/contentstack-utils-javascript ships 2 formats across 5 indexed files. The question worth asking is whether the second one says anything the first does not.

CompareAGENTS.md ↔ Cursor rules

A · AGENTS.md · 439 words B · .cursor/rules/code-review.mdc · 249 words

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	7	8	0%
Commands	1	8	1	10%
Section tags	2	8	3	15%

What each file covers

Sections

0 shared · 7 only in A · 8 only in B

− Agent guidance — `@contentstack/utils`
− What this package is
− Tech stack
− Source layout and public API
− Common commands
− Credentials / environment
− More detail for AI / IDE rules
+ Code review checklist — `@contentstack/utils`
+ Public API and documentation
+ Backward compatibility
+ Errors
+ Null safety and RTE edge cases
+ Dependencies and SCA
+ Tests
+ Terminology

Commands

1 shared · 8 only in A · 1 only in B

− tsc
− jest.config.ts
− eslint.config.js
− npm run format
− npx eslint
− npm run build
− npm run test:debug
− npm run download-regions
+ npm audit
npm test

Section tags

2 shared · 8 only in A · 3 only in B

− setup
− build
− lint-format
− architecture
− testing-strategy
− security
− do-not
− agent-behaviour
+ git-pr
+ dependencies
+ docs
test
api

Line diff

+27 added−38 removed15 unchanged28.3% identical

contentstack/contentstack-utils-javascript · AGENTS.md

@@ −1 @@

1# Agent guidance — `@contentstack/utils`

3## What this package is

5**[@contentstack/utils](https://www.npmjs.com/package/@contentstack/utils)** (`contentstack-utils-javascript`) is a **JavaScript/TypeScript utilities library** for Contentstack. It is **not** the Content Delivery API (CDA) SDK or the Content Management API (CMA) SDK. It focuses on **JSON RTE / Supercharged RTE** rendering (`jsonToHTML`), **embedded entry and asset** rendering (`render`, `renderContent`), **GraphQL-oriented helpers** (`GQL`, `updateAssetURLForGQL`), **Live Preview–style editable tags** (`addEditableTags` / `addTags`), and **region endpoint lookup** (`getContentstackEndpoint`). Typical usage is **alongside** the Delivery SDK (see repository `README.md` examples with `@contentstack/delivery-sdk`).

7- **Repository:** [github.com/contentstack/contentstack-utils-javascript](https://github.com/contentstack/contentstack-utils-javascript)

9## Tech stack

11| Area | Details |

12|------|---------|

13| Language | TypeScript **4.9** (`tsconfig.json`, `strict: true`, `strictNullChecks: false`) |

14| Build | **TypeScript** (`tsc`) → `dist/lib`; **Rollup** (`rollup -c`) → `dist/index.es.js`; types in `dist/types/` |

15| Test | **Jest 29** + **ts-jest**, **jsdom** environment (`jest.config.ts`) |

16| Lint / format | **ESLint 9** flat config (`eslint.config.js`); **Prettier 3** (`npm run format`) — there is **no** `lint` npm script; use `npx eslint` as needed |

17| Runtime HTTP / JSON for API calls | **None** in library code; `regions.json` is a **build-time** asset (see below) |

19## Source layout and public API

21| Role | Path |

22|------|------|

23| Public entry (sources) | `src/index.ts` |

24| Options / render types | `src/options/` |

25| RTE / node model | `src/Models/`, `src/nodes/` |

26| Helpers | `src/helper/` |

27| GQL + asset URL rewrite | `src/gql.ts`, `src/updateAssetURLForGQL.ts` |

28| Endpoints helper | `src/endpoints.ts` + `src/assets/regions.json` (generated; see build) |

29| Published bundle | `dist/` (per `package.json` `main` / `types`) |

31## Common commands

33| Command | Purpose |

34|---------|---------|

35| `npm run build` | Cleans `dist`, ensures `src/assets/regions.json` (download or warning), runs `tsc` + Rollup |

36| `npm test` | Runs `pretest` → **build**, then Jest with coverage; outputs under `reports/` |

37| `npm run test:debug` | Jest watch, in-band |

38| `npm run format` | Prettier on `src/**/*.ts` |

39| `npm run download-regions` | Fetches `regions.json` only (used by `prebuild`) |

41**Tests:** Unit tests only, under `__test__/**/*.test.ts`, with mocks in `__test__/mock/`. There are **no** live/integration tests requiring stack credentials in this repository.

43## Credentials / environment

45- **Unit tests:** No API keys or `.env` required.

46- **Build:** `download-regions` calls a public URL (`artifacts.contentstack.com`); offline builds may warn and rely on an existing `src/assets/regions.json`. Note `regions.json` is listed in `.gitignore`; clones may need a successful `npm run build` (or manual file) before tests pass.

47- **Publish:** GitHub release workflow uses `NPM_TOKEN` / `GIT_TOKEN` secrets (maintainers only).

49## More detail for AI / IDE rules

51- [`.cursor/rules/README.md`](.cursor/rules/README.md) — Cursor rules index (`alwaysApply`, globs, when to use).

52- [`skills/README.md`](skills/README.md) — Topic skills (testing, code review, package mental model).

contentstack/contentstack-utils-javascript · .cursor/rules/code-review.mdc

@@ +1 @@

1---

2description: PR review checklist for @contentstack/utils — API docs, compatibility, security, testing

3alwaysApply: true

4---

6# Code review checklist — `@contentstack/utils`

8Use severity labels (**Blocker / Major / Minor**) when triaging findings.

10## Public API and documentation

12- **Blocker/Major:** New or changed **exports** from `src/index.ts` need accurate **JSDoc** (or clear type names) matching runtime behavior.

13- **Major:** README / CHANGELOG updates when behavior is user-visible or migration is needed.

15## Backward compatibility

17- **Blocker:** Unplanned breaking changes to **function signatures** or **default behavior** consumed by Delivery SDK integrations or documented `renderOption` contracts.

18- **Major:** Stricter throwing on inputs that previously passed (especially `getContentstackEndpoint`, RTE traversals).

20## Errors

22- This package uses **plain `Error`** (e.g. `endpoints.ts`); new code should keep messages actionable. **Major:** Silent failures where callers need to detect bad input.

24## Null safety and RTE edge cases

26- **Major:** Missing guards on **null/undefined** node or entry fragments (historically sensitive in `entry-editable` / RTE paths).

27- **Minor:** Align with **`strictNullChecks: false`** legacy but avoid widening undefined leaks into public types.

29## Dependencies and SCA

31- **Major:** New runtime deps are rare—justify any addition; **`prepublishOnly`** and hooks assume **`npm test`** and Snyk-friendly trees.

32- Use **`npm audit` / Snyk** expectations per org policy.

34## Tests

36- **Blocker:** Behavioral fixes or new branches without **`__test__`** coverage when risk is high (RTE nesting, GQL URL rewriting, endpoint resolution).

37- **Minor:** Snapshot-only tests where a small assertion would be clearer.

39## Terminology

41- **Major:** Docs/comments must describe this as **utils** alongside **CDA / Delivery / JSON RTE / GraphQL**, not as **CMA** unless the change is explicitly management-related.

@@ −1 +1 @@

1−# Agent guidance — `@contentstack/utils`

1+---

2+description: PR review checklist for @contentstack/utils — API docs, compatibility, security, testing

3+alwaysApply: true

4+---

3−## What this package is

6+# Code review checklist — `@contentstack/utils`

5−**[@contentstack/utils](https://www.npmjs.com/package/@contentstack/utils)** (`contentstack-utils-javascript`) is a **JavaScript/TypeScript utilities library** for Contentstack. It is **not** the Content Delivery API (CDA) SDK or the Content Management API (CMA) SDK. It focuses on **JSON RTE / Supercharged RTE** rendering (`jsonToHTML`), **embedded entry and asset** rendering (`render`, `renderContent`), **GraphQL-oriented helpers** (`GQL`, `updateAssetURLForGQL`), **Live Preview–style editable tags** (`addEditableTags` / `addTags`), and **region endpoint lookup** (`getContentstackEndpoint`). Typical usage is **alongside** the Delivery SDK (see repository `README.md` examples with `@contentstack/delivery-sdk`).

8+Use severity labels (**Blocker / Major / Minor**) when triaging findings.

7−- **Repository:** [github.com/contentstack/contentstack-utils-javascript](https://github.com/contentstack/contentstack-utils-javascript)

10+## Public API and documentation

811

9−## Tech stack

12+- **Blocker/Major:** New or changed **exports** from `src/index.ts` need accurate **JSDoc** (or clear type names) matching runtime behavior.

13+- **Major:** README / CHANGELOG updates when behavior is user-visible or migration is needed.

1014

11−| Area | Details |

12−|------|---------|

13−| Language | TypeScript **4.9** (`tsconfig.json`, `strict: true`, `strictNullChecks: false`) |

14−| Build | **TypeScript** (`tsc`) → `dist/lib`; **Rollup** (`rollup -c`) → `dist/index.es.js`; types in `dist/types/` |

15−| Test | **Jest 29** + **ts-jest**, **jsdom** environment (`jest.config.ts`) |

16−| Lint / format | **ESLint 9** flat config (`eslint.config.js`); **Prettier 3** (`npm run format`) — there is **no** `lint` npm script; use `npx eslint` as needed |

17−| Runtime HTTP / JSON for API calls | **None** in library code; `regions.json` is a **build-time** asset (see below) |

15+## Backward compatibility

1816

19−## Source layout and public API

17+- **Blocker:** Unplanned breaking changes to **function signatures** or **default behavior** consumed by Delivery SDK integrations or documented `renderOption` contracts.

18+- **Major:** Stricter throwing on inputs that previously passed (especially `getContentstackEndpoint`, RTE traversals).

2019

21−| Role | Path |

22−|------|------|

23−| Public entry (sources) | `src/index.ts` |

24−| Options / render types | `src/options/` |

25−| RTE / node model | `src/Models/`, `src/nodes/` |

26−| Helpers | `src/helper/` |

27−| GQL + asset URL rewrite | `src/gql.ts`, `src/updateAssetURLForGQL.ts` |

28−| Endpoints helper | `src/endpoints.ts` + `src/assets/regions.json` (generated; see build) |

29−| Published bundle | `dist/` (per `package.json` `main` / `types`) |

20+## Errors

3021

31−## Common commands

22+- This package uses **plain `Error`** (e.g. `endpoints.ts`); new code should keep messages actionable. **Major:** Silent failures where callers need to detect bad input.

3223

33−| Command | Purpose |

34−|---------|---------|

35−| `npm run build` | Cleans `dist`, ensures `src/assets/regions.json` (download or warning), runs `tsc` + Rollup |

36−| `npm test` | Runs `pretest` → **build**, then Jest with coverage; outputs under `reports/` |

37−| `npm run test:debug` | Jest watch, in-band |

38−| `npm run format` | Prettier on `src/**/*.ts` |

39−| `npm run download-regions` | Fetches `regions.json` only (used by `prebuild`) |

24+## Null safety and RTE edge cases

4025

41−**Tests:** Unit tests only, under `__test__/**/*.test.ts`, with mocks in `__test__/mock/`. There are **no** live/integration tests requiring stack credentials in this repository.

26+- **Major:** Missing guards on **null/undefined** node or entry fragments (historically sensitive in `entry-editable` / RTE paths).

27+- **Minor:** Align with **`strictNullChecks: false`** legacy but avoid widening undefined leaks into public types.

4228

43−## Credentials / environment

29+## Dependencies and SCA

4430

45−- **Unit tests:** No API keys or `.env` required.

46−- **Build:** `download-regions` calls a public URL (`artifacts.contentstack.com`); offline builds may warn and rely on an existing `src/assets/regions.json`. Note `regions.json` is listed in `.gitignore`; clones may need a successful `npm run build` (or manual file) before tests pass.

47−- **Publish:** GitHub release workflow uses `NPM_TOKEN` / `GIT_TOKEN` secrets (maintainers only).

31+- **Major:** New runtime deps are rare—justify any addition; **`prepublishOnly`** and hooks assume **`npm test`** and Snyk-friendly trees.

32+- Use **`npm audit` / Snyk** expectations per org policy.

4833

49−## More detail for AI / IDE rules

34+## Tests

5035

51−- [`.cursor/rules/README.md`](.cursor/rules/README.md) — Cursor rules index (`alwaysApply`, globs, when to use).

52−- [`skills/README.md`](skills/README.md) — Topic skills (testing, code review, package mental model).

36+- **Blocker:** Behavioral fixes or new branches without **`__test__`** coverage when risk is high (RTE nesting, GQL URL rewriting, endpoint resolution).

37+- **Minor:** Snapshot-only tests where a small assertion would be clearer.

38+

39+## Terminology

40+

41+- **Major:** Docs/comments must describe this as **utils** alongside **CDA / Delivery / JSON RTE / GraphQL**, not as **CMA** unless the change is explicitly management-related.

5342