Add a frontend zero-tolerance TypeDoc documentation gate#156
Conversation
Prepare for a zero-tolerance TypeDoc documentation gate over `frontend-pwa/src`: add JSDoc to every exported declaration and property across the task slice (domain, ports, application, adapters), the app shell, router factory, route pages, and the i18n runtime. Tag the `en-gb` message catalogue `@internal` — it is a data seam whose keys need no per-entry documentation — and document the `MessageKey` union that keeps `t()` calls checked against it.
Add `make frontend-docs-check`, wrapping `bun run docs:check` inside `frontend-pwa`: TypeDoc's `notDocumented` validation over `frontend-pwa/src` (`entryPointStrategy: "expand"`, `emit: "none"`, validation warnings as errors), configured by `frontend-pwa/typedoc.json`. The gate requires 100% documentation of the frontend surface, reports the qualified name of each undocumented declaration, and writes no documentation artefacts. The frontend CI path runs it after `frontend-typecheck`; the Rust documentation gate is unaffected.
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
Summary
WalkthroughThe change adds a strict, non-emitting TypeDoc gate for ChangesFrontend TypeDoc gate
Possibly related PRs
Poem
Caution Pre-merge checks failedPlease resolve all errors before merging. Addressing warnings is optional.
❌ Failed checks (1 error, 2 warnings)
✅ Passed checks (17 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
⚔️ Resolve merge conflicts
Comment |
![codescene-access[bot]](https://avatars.githubusercontent.com/in/3755875?s=60&v=4){kind=small}
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 050e808281
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| /** | ||
| * Render an issue origin as `provider/repository/#number` for display. | ||
| */ |
There was a problem hiding this comment.
This JSDoc block, like the other function documentation added in this commit, only summarizes the function and does not demonstrate a call and its resulting output. The repository explicitly requires every function’s documentation to contain a clear usage-and-outcome example, so add an @example section here and to the other newly documented functions.
AGENTS.md reference: AGENTS.md:L27-L30
Useful? React with 👍 / 👎.
| "**/tests/**", | ||
| "**/test/**", | ||
| "**/fixtures/**" |
There was a problem hiding this comment.
With the expand entry-point strategy rooted at src, these patterns exclude only directories named test or tests; they do not match the eight existing co-located files such as src/routes/task-routes.test.tsx. Consequently those test modules are part of the documentation gate, and exporting a shared fixture or helper from one will unexpectedly require production API documentation and fail CI. Add filename exclusions such as **/*.test.* and **/*.spec.*.
Useful? React with 👍 / 👎.
|
@coderabbitai review |
✅ Action performedReview finished.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@frontend-pwa/src/task_slice/application/task-queries.ts`:
- Around line 12-15: The documentation above the task creation flow inaccurately
promises that seeding the detail cache avoids a redundant fetch. Update the
comment to state that cached data is rendered while the detail query revalidates
under React Query defaults, or modify useTaskDetailQuery with an explicit
staleTime/refetchOnMount policy only if avoiding the immediate request is
required.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 53fb3405-b0fc-44a0-aec8-510184eeb34b
⛔ Files ignored due to path filters (1)
frontend-pwa/bun.lockis excluded by!**/*.lock
📒 Files selected for processing (17)
.github/workflows/ci.ymlMakefiledocs/developers-guide.mdfrontend-pwa/package.jsonfrontend-pwa/src/app/app-shell.tsxfrontend-pwa/src/app/router.tsxfrontend-pwa/src/i18n/en-gb.tsfrontend-pwa/src/i18n/runtime.tsxfrontend-pwa/src/routes/task-create-page.tsxfrontend-pwa/src/routes/task-detail-page.tsxfrontend-pwa/src/task_slice/adapters/http/http-task-gateway.tsfrontend-pwa/src/task_slice/application/task-queries.tsfrontend-pwa/src/task_slice/domain/task-form.tsfrontend-pwa/src/task_slice/domain/task-view-model.tsfrontend-pwa/src/task_slice/domain/task.tsfrontend-pwa/src/task_slice/ports/task-slice-gateway.tsfrontend-pwa/typedoc.json
🔗 Linked repositories identified
CodeRabbit considers these linked repositories for cross-repo context during reviews:
leynos/whitaker(auto-detected)leynos/podbot(auto-detected)leynos/frankie(auto-detected)leynos/weaver(auto-detected)leynos/rstest-bdd(auto-detected)
| /** | ||
| * Create a task through the gateway and seed the detail query cache with | ||
| * the result so the next detail view avoids a redundant fetch. | ||
| */ |
There was a problem hiding this comment.
🚀 Performance & Scalability | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
git ls-files frontend-pwa/src/task_slice/application/task-queries.ts frontend-pwa/src/task_slice -z | tr '\0' '\n'
printf '\n--- task-queries.ts ---\n'
cat -n frontend-pwa/src/task_slice/application/task-queries.ts
printf '\n--- search for useTaskDetailQuery ---\n'
rg -n "useTaskDetailQuery|staleTime|refetchOnMount|setQueryData|queryKey" frontend-pwa/src/task_slice -SRepository: leynos/corbusier
Length of output: 3069
Clarify the cache behaviour in frontend-pwa/src/task_slice/application/task-queries.ts:12-15. setQueryData primes ['task', task.id], but useTaskDetailQuery still uses React Query defaults, so a mounted detail view can refetch immediately. Rewrite this to say it renders cached data while revalidating, or set an explicit staleTime/refetchOnMount policy if skipping that request is required.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@frontend-pwa/src/task_slice/application/task-queries.ts` around lines 12 -
15, The documentation above the task creation flow inaccurately promises that
seeding the detail cache avoids a redundant fetch. Update the comment to state
that cached data is rendered while the detail query revalidates under React
Query defaults, or modify useTaskDetailQuery with an explicit
staleTime/refetchOnMount policy only if avoiding the immediate request is
required.
Source: MCP tools
2 participants
Summary
This branch adds a zero-tolerance TypeDoc documentation gate for the
frontend PWA. TypeDoc's
notDocumentedvalidation runs overfrontend-pwa/src(entryPointStrategy: "expand") withemit: "none"and validation warnings treated as errors: everyexported declaration must carry a JSDoc comment. The gate reports the
qualified name of each undocumented declaration, writes no
documentation artefacts, and fails on a single omission. It is exposed
as
make frontend-docs-checkand runs in the frontend CI path afterfrontend-typecheck; the Rust documentation gate is unaffected.The first commit documents the frontend surface (131 initial
warnings); the second wires the gate.
Review walkthrough
for the gate's configuration, then the root
Makefile
(
frontend-docs-checktarget) and.github/workflows/ci.yml
(gate step after
frontend-typecheck).frontend-pwa/src/task_slice/domain/task.ts
and
frontend-pwa/src/task_slice/ports/task-slice-gateway.ts
(port-vocabulary docs on the gateway contract).
shows the catalogue treatment: the message map is tagged
@internal(a data seam; its keys need no per-entry documentation) while the
MessageKeyunion stays public and documented.documents the local command.
Validation
make frontend-lint,make frontend-typecheck,make frontend-docs-check,make frontend-test,make frontend-test-a11y,make frontend-localizability,make frontend-semantic.AppShellcomponent makesbun run docs:checkexit 4 naming thesymbol; restoring it returns the gate to green.
docs:checkrun emits no files and no output.Notes
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,
Add a zero-tolerance TypeDoc documentation gate simulacat-core#58, and Add a zero-tolerance TypeDoc documentation gate vibe-coder#110).