chore(build): enforce JSDoc presence on public-API exports in check:workspace#1646
chore(build): enforce JSDoc presence on public-API exports in check:workspace#1646R-Delfino95 wants to merge 2 commits into
Conversation
…orkspace Adds a "JSDoc presence" check to `pnpm check:workspace` that fails CI when any top-level public-API export in @videojs/react, @videojs/html, or @videojs/core lacks a JSDoc summary. Parses source via the TypeScript Compiler API, follows barrel re-exports, and applies the documented carve-outs (leaf wrappers, @internal, cross-package, namespace descent for compound components). The engine lives under site/scripts/jsdoc-presence/ because site/ is the only workspace with `typescript` and `tsx` available; build/scripts/check-workspace.mjs invokes it as a subprocess and maps exit codes to the existing { ok, warnings } contract. Refs videojs#1571. Blocked by videojs#1570 (the JSDoc-writing sweep): the check is expected to report real gaps in the three packages until videojs#1570 lands. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
| Name | Link |
|---|---|
| 🔨 Latest commit | 8877ebd |
|
@R-Delfino95 is attempting to deploy a commit to the Mux Team on Vercel. A member of the Team first needs to authorize it. |
Adds focused test cases for each rule the JSDoc-presence check enforces, so a failing test points directly at the rule that broke: - Tag-only JSDoc: @see-only (in addition to @deprecated-only) - @internal carve-out applies even with a summary - Leaf-wrapper carve-out: qualified-name type alias (type X = A.B) - Not leaf wrappers: type args, union, object literal, extends-with-members - Ring 1 / Ring 2 boundary: documented class passes regardless of member documentation; undocumented class itself is flagged Total tests grew from 6 to 18; fixture cases consolidate into a single cases.ts with section-headed groupings. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
I love the thought behind this PR, you noticed a repeated issue and built some guardrails 👌 I'm going to close this out because when I originally created I'm currently not sure we want to document all public exported APIs. Sounds reasonable but I would need to test what errors are surfaced from this to determine next steps. Important to understand how this impacts PR reviews and general workflows. Small concern that with AI and lack of guidance via a skill or something that it could just create bloat. Again, thank you and likely once we resolve the above we can and should circle back to exploring this check! |
3 participants
PR Description
Why
Resolves #1571.
We agreed to require JSDoc for all public API exports back in #1558 and #1570, but up until now, it was just a review-time guideline. This meant reviewers had to catch missing docs manually, and some gaps inevitably slipped through.
This PR automates that process by adding an automated check to
pnpm check:workspace. Now, if any public export in a published package is missing a JSDoc summary, the CI build will fail.The check inspects the source code directly, meaning it runs quickly and doesn't require a full build step to test locally or in CI.
What's in this PR
We added a JSDoc presence check to our workspace tools. It scans public exports for the following initial packages:
@videojs/react@videojs/html@videojs/coreIt ensures each public export has an actual descriptive summary.
How it works (High Level)
tsdown.config.tsfor each package to find the official public entry files.@internal.Why is this located under
site/?The script relies on the TypeScript Compiler API and
tsxto run. Instead of adding these heavy development dependencies to the repository root, we placed the script insidesite/scripts/jsdoc-presence/because the documentation builder there already uses them.How to add more packages later
When we are ready to expand coverage, you just need to add the package name to the
PACKAGESlist insidesite/scripts/jsdoc-presence/cli.ts.Test Plan
pnpm check:workspaceon the currentmainbranch correctly flags the existing missing JSDocs with clear error messages.site/scripts/tests/jsdoc-presence.test.tsto cover edge cases like internal tags, re-exports, and empty extensions.pnpm lintandpnpm astro checkpass successfully with the new files.