Add a zero-tolerance TypeDoc documentation gate#47
Conversation
Add `docs-check` to `make all`: TypeDoc's `notDocumented` validation over the package entry point (`src/index.ts`, `resolve` strategy, `emit: "none"`, warnings as errors), configured by `typedoc.json` and run through `bun run docs:check`. The gate requires 100% documentation of the public surface, reports the qualified name of each undocumented declaration, and writes no documentation artefacts. CI already runs `make all`, so the gate needs no workflow changes. Document the public surface to match: the `GitHubSimulatorArgs` members in `src/simulation.ts`, and the zod schema constants tagged with documented `/** … @internal */` blocks so TypeDoc does not recurse into their inferred field types — their meaning is carried by the named `GitHub*` output types. Convert the entry point's `@file` header to TypeDoc's `@module` form (TypeDoc does not know the `@file` tag).
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
|
Warning Review limit reachedYou’ve reached a temporary PR review limit under our Fair Usage Limits Policy. Next review available in: 50 seconds Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (13)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![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: 453c40e42d
ℹ️ 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".
| docs-check: | ||
| bun run docs:check |
There was a problem hiding this comment.
On a clean checkout, make docs-check reaches TypeDoc before check:types generates the ignored src/__generated__/resolvers-types.ts, which is transitively imported from the package entry point via simulation and src/graphql/resolvers.ts; TypeDoc therefore fails on the missing module rather than checking documentation. The same race occurs under make -j all because listing typecheck before docs-check does not establish a dependency between them (make --help confirms that -j allows multiple jobs at once). Declare typecheck as a prerequisite of this target so standalone and parallel gate runs are reliable.
Useful? React with 👍 / 👎.
1 participant
Summary
This branch adds a zero-tolerance TypeDoc documentation gate to
make all. TypeDoc'snotDocumentedvalidation runs over the packageentry point (
src/index.ts,resolvestrategy) withemit: "none"and warnings treated as errors: every declaration in the public surface
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. CI already runs
make all, so it reaches thegate with no workflow changes.
A small preparatory commit fixes a pre-existing Oxford-spelling
violation in AGENTS.md that the shared typos base now flags.
Review walkthrough
for the gate's configuration, then the
Makefile
and package.json
for the wiring:
docs-checksits betweentypecheckandlintinmake all(aftertypecheckso the generated GraphQL types exist).src/simulation.ts
(the
GitHubSimulatorArgssurface) and the zod schema constants undersrc/store/entities/,
each tagged with a documented
/** … @internal */block so TypeDocdoes not recurse into their inferred field types — the named
GitHub*output types remain the public vocabulary.converts the entry header from
@file(unknown to TypeDoc) to the@moduleform, preserving the description.documents the local command.
Validation
make all(check-fmt, typecheck,docs-check, lint, test,spelling): exit 0.
InitialStatealias 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 and Replace the docstring audit with a zero-tolerance TypeDoc gate dakar#5).