From 92fcb9935c33af355641656afb776063f46f5aa2 Mon Sep 17 00:00:00 2001 From: marttec <89842189+marttec@users.noreply.github.com> Date: Fri, 13 Nov 2026 17:22:21 +0000 Subject: [PATCH] docs(TA-4127): add CLAUDE.md for Claude Code One committed CLAUDE.md per repo in the Platform format, replacing the untracked local AGENTS.md guides. Workspace-wide guidance lives in talis/talis-dev-root. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..76ace48 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,75 @@ +# CLAUDE.md + +`@talisdev/jsonapi-transformers` is a TypeScript library that converts between [JSON:API](https://jsonapi.org/) documents and decorated TypeScript classes. It has no HTTP layer; it only serialises and deserialises. It is published to the public npm registry and consumed by the Talis front-end repos (for example `shipshape-app` and `otis-app`). Default branch: `main`. + +**Risk:** a release is published to the public npm registry and reaches every consumer on its next dependency bump, so a wrong version or a breaking change is hard to take back. + +## Layout + +- `src/decorators/` - `@Entity`, `@Attribute`, `@Relationship`, `@Link`, `@Meta` and the metadata map they fill. +- `src/jsonapi/` - JSON:API types, the base entity class, unresolved identifiers. +- `src/serialisation/` - serialisers and deserialisers. +- `spec/` - Jest tests, with fixtures in `spec/test-data/` (classes) and `spec/test-data/jsonapi/` (JSON:API documents). + +## Setup and commands + +Standalone repo: no other Talis repo and no local services. Run from the repo root with the Node version in `.nvmrc` (`nvm use`), after `npm ci` (which also runs `prepare`, and so the build). + +| Task | Command | +|---|---| +| Unit tests (with coverage) | `npm test` | +| Lint (eslint + prettier check) | `npm run lint` | +| Format | `npm run format` | +| Build both module formats into `lib/` | `npm run build` | +| Validate fixture documents against the JSON:API schema | `npm run validate_jsonapi_examples` | + +CI (CircleCI) runs, in order: commit message lint, `npm run lint`, `npm run validate_jsonapi_examples`, `npm test`, `npm run build`. Run the same set before opening a PR. The suite needs no services, so a full local run is fine. Run one spec with `npx jest spec/serialisation/serialisers.spec.ts`. + +## Conventions + +- Source is TypeScript, formatted by prettier and linted by eslint. Match the style of the closest existing file. +- New behaviour needs a spec next to its siblings in `spec/`. If it changes the JSON:API output, add or update a fixture in `spec/test-data/jsonapi/`; `validate_jsonapi_examples` checks every file there against `spec/jsonapi-schema.json`. +- Record public API changes that break consumers in `BREAKING_CHANGES.md` (maintained by hand). +- Do not edit `lib/` (git-ignored build output), `CHANGELOG.md` or the `version` in `package.json` (release-please writes them), or `package-lock.json` by hand. + +## Guardrails + +- **Claude may run:** `npm ci`, `npm run lint`, `npm test`, `npm run build`, `npm run validate_jsonapi_examples`, and read-only `git` commands. +- **Ask first:** anything that merges or tags. Merging the release PR that release-please opens publishes to npm, so a person does that. +- **Never:** `npm publish` by hand, or edit the version, changelog or tags to force a release. Only `.github/workflows/release-please.yml` publishes. + +## Commit and PR titles decide the release + +Releases are automated with release-please: merging to `main` opens or updates a release PR, and merging that publishes to npm. + +- Commit messages and PR titles follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `chore:`, `feat!:` for breaking). CI runs commitlint on the latest commit message, and a workflow lints the PR title (skipped for PRs labelled `dependencies`). +- The prefix chooses the version bump, so a wrong prefix ships the wrong version. + +## Traps + +- `README.markdown` is partly stale: it says Node 14-18 and shows `npm install jsonapi-transformers`. The package name is `@talisdev/jsonapi-transformers`, `engines` allows Node `>=14 <25`, and CI uses the version in `.nvmrc`. `MIGRATION.md` explains the move from the old unscoped name. Do not copy the old name into new docs. +- The package must keep working as both CommonJS and ES modules. `scripts/fixup` writes the `package.json` type markers into `lib/cjs` and `lib/mjs`; keep it in the build. +- Dependency updates come from Dependabot (configured centrally, not in this repo), which replaced Renovate. Do not re-add `renovate.json`. +- Check the npm registry directly (`curl -s https://registry.npmjs.org/@talisdev%2fjsonapi-transformers`) for published versions; `npm view` has returned stale data for this package. + +## Where other things live + +- Workspace guidance (what the other Talis repos are, safety rules for remote operations): `CLAUDE.md` in the workspace root repo `talis/talis-dev-root`, at `$DEVELOPMENT_WORK_DIR`. +- `README.markdown` - worked blog example of the decorators. `MIGRATION.md`, `BREAKING_CHANGES.md` - consumer-facing changes. + +## PR conventions + +- Branch from `main`, one change per PR. Put the ticket key in the conventional-commit scope when there is one, as recent history does (for example `chore(TA-3890): ...`). +- The description says what changed, why, and how it was tested. CI (CircleCI) must pass. +- Open as a draft when Claude-authored; a human reviews and merges. + +## Skills + +- `talis:ci` - Talis rules for reading and re-running CircleCI. +- `talis:pr-review-feedback` - work through review comments on a PR. +- `talis:npm-cve-patch` - patch npm audit findings; the fix still needs a conventional-commit title here. +- `talis:node-runtime-bump` - move to a newer Node version consistently. + +## Keeping this file current + +If a change alters anything described here (commands, release flow, layout), update this file in the same PR. Link detail rather than copying it.