Gate the working diff before it becomes a commit or PR. Consistency and completeness, not bug
hunting — logic bugs are /code-review, refactors /simplify, vulnerabilities
/security-review. CODING_GUIDELINES.md holds the rules; Step 4
verifies the diff against them. There are no git hooks in this repository, so every gate below is a CI job or
nothing — which is why .claude/settings.json bounces the first git commit of a session here.
Fix: Biome autofixes, generated churn, stale references after a rename, doc rows derivable from the code, debug artifacts, Step 4. Report: anything needing invented intent — new prose or guide sections, naming judgement, whether an untracked file belongs in the commit, whether a public-API change deserves a deprecation alias.
Step 1: Scope
documentation/docs-portal/api-reference/ is committed but typedoc-generated; only the release
PR's bot commit updates it. If the diff touches it, git checkout -- it and change the JSDoc
behind it instead. Stage explicit paths afterwards, not git add -A.
Then git status --short, git diff, git diff --cached → the touched files and the workspaces
driving Step 2. Scope everything below to those; never audit the whole repo. Read untracked files
fully — no baseline, and the likeliest source of Step 5 problems.
Step 2: Gates
From the repo root. Order matters: dependents resolve @tomtom-org/maps-sdk/* through
core/dist, services/dist, map/dist, so type-checking or testing downstream of an unbuilt
change reads stale declarations. CI's chain (.github/actions/install-analysis-build) is
pnpm install --frozen-lockfile --strict-peer-dependencies → lint → build:sdk →
type-check:sdk, unit suites after.
| Touched | Run |
|---|---|
| anything | pnpm lint |
core/, services/, map/, shared-configs/ |
pnpm build:sdk → type-check:sdk → test:sdk |
plugins/** |
pnpm build:sdk → type-check:plugins → test:plugins |
examples/** |
pnpm build:sdk (+ build:plugins if the example uses one) → type-check:examples → test:examples |
map-integration-tests/ |
pnpm type-check:sdk (included) — plus Step 3 |
agent-eval/ |
pnpm test:agent-eval |
testing/* |
no root script — pnpm -F @testing/<name> test / type-check (core-utils, ai-eval have both; agent-tool-calling, ai-eval-explorer type-check only) |
Collect every failure in one pass rather than stopping at the first, and attribute each to
biome / tsc / vitest so the user knows what CI blocks on.
Judge every gate by its exit code. Run it, then read $? — or run it without piping and read
the tool's own summary line (Found N errors, error TSxxxx, Test Files N failed). Never
conclude a gate passed from a grep over its output: these commands colour and wrap their
diagnostics, and pnpm prefixes them, so an anchored pattern can match nothing while the gate is
failing. A grep that returns zero is only evidence the pattern was wrong.
pnpm lint > /dev/null 2>&1; echo "lint exit=$?" # 0 or it blocks CI
pnpm lintisbiome lint .only — no formatter, noorganizeImports, so an unformatted file passes CI's lint job.pnpm lint:fixwrites all three.pnpm lint:fixleaves error-level findings behind. It isbiome check . --write && biome lint . --write, and neither pass applies a fix Biome considers unsafe —noUnusedImportsamong them. It printsNo fixes appliedand still exits non-zero, so a refactor that strips the last use of an import needs the import removed by hand. This is the commonest way a redlintjob reaches CI.- Warn-level rules never fail, so CI never shows them:
noExcessiveCognitiveComplexity(max 25),noExcessiveLinesPerFunction(max 50),noExplicitAny,useConsistentTypeDefinitions,noUnusedVariables,noNonNullAssertion,useAsConstAssertion,noInferrableTypes. Warnings on touched files are findings; ignore pre-existing ones.noExplicitAny,noExcessiveLinesPerFunctionanduseConsistentTypeDefinitionseach carry a repository-wide backlog, so read their counts per file and never as a total.noUnusedImports, by contrast, is error-level: unlike itsnoUnusedVariablesneighbour it blocks the build. pnpm test:sdkincludes the live-API*Integration.test.tsfiles underservices/, so it needs a key and spends quota. Fix the code if a test encodes intended behaviour; if the change intentionally alters behaviour, update the test and say so.- Changed
package.jsonneeds a matchingpnpm-lock.yaml— CI's--frozen-lockfilefails every job before running any code. A version shared by two workspaces belongs incatalog:(pnpm-workspace.yaml);--strict-peer-dependenciesmakes an unmet peer a hard failure. A new runtime dependency incore/services/mapmoves the bundle, andmonitor-bundle-size.ymlcomments the delta — note it in the report.
Step 3: Expensive suites — run, or leave to CI
pnpm e2e-test:sdk when the diff touches map module public behaviour (event payloads, events
surfaces, source/layer IDs, module wiring, style-change restoration): ~160 tests in under three
minutes, the cheapest way to catch a shape change CI finds twenty minutes later. The page loads
core/dist (aliased in map-integration-tests/vite.config.ts) and map/dist (through the
workspace export), so pnpm build:sdk first or the browser runs the previous build. The key
self-loads from shared-configs/.env* outside CI. Pass --reporter=list (the local default html
prints nothing until it opens a server); @flaky tests need INCLUDE_FLAKY=1.
pnpm e2e-test:map-effects when the diff touches plugins/map-effects/: the visual suite over a
synthetic map, no key and no build, about ten seconds. A new effect or knob without a measured case
there is a Step 6 finding — plugins/map-effects/AGENTS.md makes it part of done.
Example E2E needs three builds — @prod serves dist/prod, @sandpack serves
dist/sandpack, neither from a dev server: pnpm -F map build, pnpm -F @examples/<name> build
and … build:sandpack, else a half serves stale or missing assets. Same before
pnpm e2e-test:examples:update-snapshot <name> and generate-thumbnails:examples <name>.
tomtom-maps-sdk-js-example-authoring carries the workflow and the blank-map diagnosis — including
that update-all-snapshots must never run against a dead key, since it overwrites every
committed baseline with blank maps.
Agent-toolkit scenario tests are LLM-in-the-loop with real model cost, and pnpm test:plugins
excludes them (--exclude '**/tests/scenarios/**'):
pnpm agent-tool-calling-test:agent-toolkit— the canonical suite.scenario-tests.ymlruns it on push tomain, after merge, so it never gates the PR. Every scenario runs against each model inAZURE_MODEL_IDS, so cost scales with that list.pnpm -F @tomtom-org/maps-sdk-plugin-agent-toolkit test:agent-tool-calling:full— the registry fanout. No CI job runs it. Required when the diff touches a tool'sdescription,classificationPromptorexamplePrompts; editingexamplePrompts[0]also changes what the canonical suite asserts.pnpm e2e-test:agent-toolkit:sandbox— Playwright over the code-execution sandbox.
Name whatever you skip in the report, with the CI job covering it.
Step 4: The coding guidelines
CODING_GUIDELINES.md is the rule set; this step verifies the diff
against it, on changed lines only. Do not restate the rules in the report — cite the section.
Four of the nine sections need active searching rather than reading; the rest you catch by reading
the diff.
§ 1 Reuse — the commonest and costliest slip, because nothing flags it. For every new function, type, constant or literal block in the diff:
git grepa distinctive token from it across the repo. A hit outside the diff is a finding: name both locations and which one should survive.- New geometry / bbox / distance / formatting / unit helper → confirm
core/src/util/has no equivalent. New map-style layer ID literal → confirm it is not already inmap/src/shared/layers/layerIDs.ts. - A helper now used by two packages belongs in
core/src/util/, not copied into both. - Duplicated data counts: layer-ID lists, style-key tables, unit factors, category maps.
- Sonar's copy-paste detector decorates the PR without blocking, and skips
**/*.test.ts,**/*.data.tsand**/vite.config.ts— so this is inspection, not a gate. - Hand a large extraction to
/simplifyrather than doing it unasked.
§ 2 Types — tsc proves the code compiles, never that the type says what is possible:
- Two or more optional properties on one new or changed type → can they legally coexist? If not, it should be a discriminated union. Same for a property that is mandatory only in some mode.
git diff -U0 | rg 'as [A-Z]'on the diff → eachaseither narrows instead or justifies itself. Theanyand!cases are Biome's, undernoExplicitAnyandnoNonNullAssertion.- A new type that restates an existing one or a Zod schema → derive it (
Pick,Omit,z.infer). - New
string/numberparameter with a known value set → literal union.
§ 3 Comments and docs — read every comment, TSDoc block and guide paragraph the diff adds.
Flag one that narrates the next line, runs past three lines, repeats the parameter name in
@param, or carries history rather than the end state ("no longer", "was renamed", "used to").
Then git grep a distinctive phrase from each new explanation: a concept spelled out at several
call sites belongs at the definition that owns it, with the call sites pointing there.
§ 5 Naming — rg -n '\b(res|req|err|params|idx|el|ref|arg|dest|src|msg|prev|curr)\b'
over the changed files; loop counters and config are the sanctioned exceptions.
Everything else — arrow functions, the blank line after a single-line if, [longitude, latitude]
order, tests/ placement, no re-exports — is a read of the diff against §§ 4, 6, 7 and 8.
Step 5: Strays and debug leftovers
- Untracked files — for each
??, does it belong here? A throwaway live-API probe test must not be committed: it runs in CI and burns quota. Report; nevergit addor delete a file the user hasn't accounted for. - Debug artifacts —
*probe*,*dump*,*scratch*,tmp-*; a.test.tswith noexpect; a test thatconsole.logs a response instead of asserting. - Focused / disabled tests —
it.only,describe.only,.skip,test.todo. Vitest.onlysilently shrinks CI coverage; inmap-integration-tests, Playwright'sforbidOnlyfails the run. - Leftover debugging —
console.log,debugger, commented-out blocks, a context-freeTODO. - New example completeness —
upon-load.png,upon-load-sandpack.pngandcontent/thumbnail.pngcommitted, plus a row in theexamples/AGENTS.mdcatalog. Then the four things nothing compiles or tests, so each one fails silently: thethumbnail: "./thumbnail.png"frontmatter key (without it the committed image is never read), a type tag fromexamples/src/constants/tags.tsalongside the feature and platform tags, a two-lineplaywright.config.ts, and thetest:e2e/start-test-server:*scripts plus the@playwright/testdevDependency inpackage.json—diffthe four againstexamples/default-map. The examples-rootpnpm e2e-test:examplessweeps everye2e-tests/**/*.test.ts, so CI stays green whilepnpm -F @examples/<name> test:e2ecannot run at all.
Step 6: Cross-surface consistency — the check nothing else performs
A change to the public interface of the SDK or a plugin must land in the same PR as the
developer-facing documentation of that interface: both the customer MDX guides
(documentation/docs-portal/guides/, 70 pages) and the AI skill docs
(.claude/skills/tomtom-maps-sdk-js/) that consumers' agents read. Until both move, every
developer reading a guide and every agent loading the skill is told something the code no longer
does — so treat a public-interface diff with no matching guide + skill change as blocked, not a
finding, unless the user said the docs land separately (which the report then states).
"Public interface" = anything a consumer can name: an export from @tomtom-org/maps-sdk/core,
/services, /map; a plugin's factory, options object, tool or type; a map module method or
event; a service function's parameters or returned shape; a TomTomConfig key; an observable
default.
| Changed | Guides | Skill docs (.claude/skills/tomtom-maps-sdk-js/) |
|---|---|---|
core/ types or utilities |
guides/core/** |
docs/core-types.md, docs/core-utilities.md |
a services/ function, its parameters or response |
guides/services/** |
docs/places.md, docs/routing.md, docs/traffic.md, docs/services-config.md |
| a map module's API, events or config | guides/map/** (a page per module) |
docs/map-setup.md, docs/map-styles.md, docs/user-events.md, docs/module-events.md, docs/custom.md, docs/maplibre.md |
plugins/agent-toolkit/ |
guides/plugins/agent-toolkit/*.mdx (10 pages) |
docs/agent-toolkit.md + docs/agent-toolkit/*.md |
plugins/viewport-places/, plugins/landmarks-3d/, plugins/map-effects/ |
guides/plugins/viewport-places.mdx, guides/plugins/landmarks-3d.mdx, guides/plugins/map-effects.mdx |
docs/places.md, docs/landmarks-3d.md, docs/map-effects.md |
A new page or doc must reach its registry too: navigation.yml for guides; the
Topic → Filename table plus the description: keyword list for the skill.
Start every rename or removal with git grep -l '<oldName>' from the root, then walk:
- The package's own
src/**— barrels, registries, schemas, tests, mocks, fixtures. AGENTS.mdof every touched directory (git ls-files '*AGENTS.md'lists all 12). Their command lists, module tables and "Important Notes" describe behaviour: fix a sentence the diff falsified, report one needing new explanation. A new top-level workspace needs a row in the root tables.- Every guide and skill doc naming the symbol, not just the feature's owner. Two traps: guides
embed examples by directory name (
<GuideDemo demo="…" />, or<SDKGuideLiveCodingExample exampleDirectory="…" />for anodejs-*one), so renaming an example breaks a guide with no compile error —grep -rn '<name>"' documentation/docs-portal/first; and in the consumer skill a new API name must reach theTopic → Filenamekeyword column and thedescription:keyword list, or the skill stops auto-loading on that name. tomtom-maps-sdk-js-contributionand this skill — when a command, convention or workflow changed, not for ordinary API changes. A skill directory name is a public install identifier, so adding or renaming one must also reach the guides enumerating the family.examples/**— they compile against the public API, so a renamed export breaks them and a new capability usually deserves one.pnpm type-check:examplescovers the compile half; the report says whether a new example is warranted.
Package extras stack on top: the agent-toolkit has per-change wiring checklists and its own
three-surface docs matrix, which tomtom-maps-sdk-js-agent-toolkit-internals walks. Follow any
"after adding X, also touch Y" rule in a touched package's AGENTS.md.
Release surface:
- Changed a public type shape — make the JSDoc
@typeParam/ property docs match the real signature (a JSDoc contradicting the code is the commonest automated-review nag here) and decide whether consumers need a deprecated alias. - Breaking public API — the PR title carries the conventional-commit
!(feat(map)!: …).commisery.ymlvalidates the title, not the commits, because the repo squash-merges, and it caps the title at 80 characters — the one failure with nothing to do with the code. The PR's changeset carries the bump:minorpre-1.0. - Added external-resource fetching — confirm bounded handling: protocol allowlist,
AbortControllertimeout, streamed size cap.new URL()alone is not validation.
Step 7: Report
Lead with the verdict — ready to push or blocked, and by what. Then briefly:
- Fixed — what changed, grouped by kind, with paths.
- Findings — most important first (
path:line, what's wrong, why it matters, suggested fix), grouped by the step that found them so the failing gate is obvious. - Docs surfaces — for a public-interface change, the guides and skill docs updated and any still outstanding; if none were needed, why.
- Not run — every skipped suite and the CI job covering it.
- PR title — if a PR is next, the proposed conventional-commit title (
!if breaking, ≤80 characters). The body istomtom-maps-sdk-js-pr-description, which takes this report's breaking-change rows as its own source; hand off rather than drafting one here. The "Not run" list stops with this report — CI reports what ran, so the body never restates it.
Paste failing output rather than summarising it. If a gate didn't pass, say so in the verdict — never "ready to push" with the failure buried below.