Add a zero-tolerance TypeDoc documentation gate

[leynos]

Summary

This branch adds a zero-tolerance TypeDoc documentation gate to the
test:all aggregate. TypeDoc's notDocumented validation runs over
src (entryPointStrategy: "expand") with emit: "none" and
validation warnings treated as errors: every exported declaration must
carry a JSDoc comment (unexported local helpers are not counted). The
gate reports the qualified name of each undocumented declaration,
writes no documentation artefacts, and fails on a single omission. It
is also exposed as make docs-check, and the semantic-lint workflow
gains a bun run docs:check step so CI reaches it.

The first commit documents the nineteen declarations TypeDoc flagged —
the existing Oxlint JSDoc rules had already kept the surface almost
fully documented; the second wires the gate and fixes a pre-existing
dependency problem that broke the aggregate (see notes).

Review walkthrough

• Start with typedoc.json
  and tsconfig.typedoc.json:
  the surface (src, expanded), the generated-file and test
  exclusions, and the scoped compiler view (skipLibCheck, src
  only — check:types passes --skipLibCheck on the command line,
  which TypeDoc cannot see).
• Then package.json
  (docs:check inserted into test:all after check:types),
  the Makefile
  (docs-check target), and
  .github/workflows/semantic-lint.yml.
• The documentation pass touches
  src/application/machines/app.machine.ts
  (union discriminants documented per variant),
  src/app/observability/logger.ts,
  the display-mode provider, the mobile shell, route props, and
  src/main.tsx;
  the two application barrels convert @file headers to @module.

Validation

• Gate components run individually, all green: bun lint,
  bun check:types, bun run docs:check, bun test,
  bun run test:a11y, bun run lint:ftl-vars, bun run semantic,
  make spelling, and bash scripts/e2e.sh (1 passed, with the dev
  server up and tokens:build run first).
• Mutation check: deleting the JSDoc line from the exported
  AppRoutesProps interface makes bun run docs:check exit 4 naming
  the symbol; restoring it returns the gate to green.
• A clean docs:check run emits no files and no output.

Notes

• check:types (and therefore test:all) was already failing on
  main: the lockfile pinned a stale transitive
  playwright-core@1.59.1 beside playwright@1.61.1, and the
  duplicated package made the Playwright Page types incompatible in
  tests/e2e/a11y.pw.ts. The gate commit bumps playwright-core to
  1.61.1 so it deduplicates and the aggregate passes end to end.
• Part of the estate-wide TypeDoc gate rollout (same shape as
  Replace docstring-coverage with a zero-tolerance TypeDoc gate df12-build#62, Replace the docstring audit with a zero-tolerance TypeDoc gate dakar#5, Add a zero-tolerance TypeDoc documentation gate digitalpuddle#47, and
  Add a zero-tolerance TypeDoc documentation gate simulacat-core#58).

[sourcery-ai]

Sorry @leynos, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: c03f8e1c-3f3f-4bea-af76-a6d584b26689

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch typedoc-rollout

---

_{Comment @coderabbitai help to get the list of available commands.}