chore(build): enforce JSDoc presence on public-API exports in check:workspace#1646
Draft
R-Delfino95 wants to merge 2 commits into
Draft
chore(build): enforce JSDoc presence on public-API exports in check:workspace#1646R-Delfino95 wants to merge 2 commits into
R-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>
👷 Deploy request for vjs10-site pending review.Visit the deploys page to approve it
|
|
@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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.