Repository navigation
Conversation
Checks that every public package export is either documented on the site or tagged @experimental/@internal/@deprecated, with a --fix mode that adds @experimental. The documented-name rule is still being decided; not yet wired into CI. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
✅ Deploy Preview for vjs-registry ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
✅ Deploy Preview for vjs10-site ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
@videojs/cdn
@videojs/cli
@videojs/core
@videojs/element
@videojs/html
@videojs/media
@videojs/react
@videojs/spf
@videojs/store
@videojs/utils
@videojs/cloudflare-video
@videojs/dash-video
@videojs/hlsjs-video
@videojs/mux-audio
@videojs/mux-video
@videojs/native-hls-video
@videojs/shaka-video
@videojs/spotify-audio
@videojs/tiktok-video
@videojs/twitch-video
@videojs/vimeo-video
@videojs/wistia-video
@videojs/youtube-video
@videojs/google-cast
@videojs/mux-data
commit: |
The site typechecks against the ES2022 lib, so astro check rejected it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
📦 Bundle Size Report🎨 @videojs/html — no changesPresets (7)
Media (18)
Players (5)
Skins (41)
UI Components (62)
⚛️ @videojs/react — no changesPresets (7)
Media (22)
Extensions (2)
Players (5)
Skins (26)
UI Components (39)
🧩 @videojs/core — no changesEntries (76)
🏷️ @videojs/element — no changesEntries (2)
📦 @videojs/store — no changesEntries (3)
🔧 @videojs/utils — no changesEntries (13)
📦 @videojs/cdn — no changes📦 @videojs/cloudflare-video — no changes📦 @videojs/dash-video — no changes📦 @videojs/google-cast — no changes📦 @videojs/hlsjs-video — no changes📦 @videojs/media — no changesEntries (3)
📦 @videojs/mux — no changes📦 @videojs/mux-audio — no changesEntries (2)
📦 @videojs/mux-data — no changes📦 @videojs/mux-video — no changesEntries (2)
📦 @videojs/native-hls-video — no changes📦 @videojs/shaka-video — no changes📦 @videojs/spf — no changesEntries (7)
📦 @videojs/spotify-audio — no changes📦 @videojs/tiktok-video — no changes📦 @videojs/twitch-video — no changes📦 @videojs/other — no changesEntries (3)
📦 @videojs/vimeo-video — no changes📦 @videojs/wistia-video — no changesEntries (2)
📦 @videojs/youtube-video — no changesℹ️ How to interpretEach entry is independently bundled, minified, and brotli-compressed. Initial size includes its static import graph; lazy dynamic chunks are reported separately. Entries are not additive because their dependency graphs overlap. Preset rows represent realistic combined bundles. Changes of 300 B or less across initial, lazy, and total size are collapsed, not discarded. Run |
An export of a published package is stable only when a reference page documents it: its subject, companion types, parts, feature selectors, or names listed in the new `apis` frontmatter field. Every other export must be tagged @internal, or @experimental when a `stability: unstable` page documents it. `--fix` adds the missing tags to the source declaration. SPF and store declarations are not checked yet. Docs imports of internal packages or non-stable exports are reported as warnings. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
Each overload carries its own JSDoc, so tagging only the first left the others looking stable in editor hovers. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
Matching `PlayerContext` against a documented `playerContext` made an undocumented type stable. Case folding is only meant for a hook's companion types, such as `UseHotkeyOptions` for `useHotkey`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
Builds rename some entries (src/core/i18n/text built to i18n/text) and copy private packages into another's dist, so their declarations don't mirror src/. Match the path after the last dist/ against authored files that declare the name, and use it only when the match is unique. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
- Fail when a stable or experimental export's public type surface (heritage, public members, aliased type, parameters, return and type parameters, declared type) names another public export that is internal. Private, protected, and @internal members are skipped, and --fix leaves these for a person to resolve. Report them grouped by the referenced export. - Treat exports only @videojs/core, media, utils, element, icons, or skins entries expose as internal, whatever their name. - Let the page win over the tag: a documented export tagged @internal (or @experimental on a stable page) fails, and --fix removes the tag or replaces @internal with @experimental, keeping any text the tag carried and deleting a comment it leaves empty. - Walk `export * as X` namespaces and check each member, named `SliderBuffer` for `Slider.Buffer` and merged with its direct export. - Require the tag on every declaration of a merged name and every overload signature, ignoring overload implementations. - Insert tags where the formatter keeps them: after an @example block with a blank line, and before @see and @todo. - Warn about exports that resolve to no declaration. - Read `export default x` JSDoc from the declaration of `x`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
- Replace the failing "references internal" check with propagation to a fixed point: an export a stable export's public surface names becomes stable, and one only experimental exports name becomes experimental, whichever package exposes it. The surface is the one the reference check used (heritage, public members, aliased type, parameters, return and type parameters, declared type), with qualified names resolved to the rightmost public export and bundle copies matched by source. - Keep heritage propagation behind PROPAGATE_THROUGH_HERITAGE (on), also exposed as the `heritage` option of resolveStabilities. - Apply the tag rules to exports stable or experimental by reference: they lose a contradicting @internal (or get @experimental), --fix applies it, and the message names one referrer plus a count. - Fail when a stable or experimental export is importable only from an internal or adapter package, suggesting the framework or /media/* entry to re-export it from. --fix leaves these alone. - Print the exports stable and experimental by reference, grouped by package, with one referrer each. - Update write-references and AGENTS.md for the transitive rule. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
… stability check Types no entry exports (local helper interfaces, mixin _base constants) now pass their own references on, so their public surface is checked. Undocumented exports need @internal or @deprecated; @experimental is replaced. --fix inserts tags above directive comments and skips overload implementations. Only react, html, store and extension packages count as importable. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
…een-mccarthy-7ams8m
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
…een-mccarthy-7ams8m # Conflicts: # site/package.json
|
The Website Tests Generated by Claude Code |
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 1e67ed0. Configure here.
mihar-22
left a comment
There was a problem hiding this comment.
Stack review (Claude, cross-checked with Codex gpt-6.1-sol). I built the top of the stack at f30ca59. check:api-stability passes (1,901 exports), its 65 tests pass, and pnpm typecheck passes uncached. Three items below, none blocking: one medium, two low. Everything already raised and resolved in earlier threads is left out.
…een-mccarthy-7ams8m
- Feature pages no longer cover their title: `Volume`, `Error`, and
the other feature titles are labels, and the `*Feature` the page's
reference names is the subject.
- Destructured exports, such as the presets'
`export const { Player: VideoPlayer, usePlayer } = …`, resolve to
their source, so `--fix` can tag them.
- The stale check covers code headings and Exports-table names as well
as `apis`, so a rename fails wherever a page names the export.
- Namespace and side-effect imports, and `export … from`, reach the
internal-package warning.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
…een-mccarthy-7ams8m
…een-mccarthy-7ams8m
…een-mccarthy-7ams8m
…een-mccarthy-7ams8m

Part 2 of the API stability stack: #3073 (radio groups) → this PR → #3066 (docs rewrites) → #3067 (reference pages) → #3082 (exports) → #3068 (tags and CI) → #3083 (store).
Summary
Adds
pnpm -F site check:api-stability(site/scripts/check-api-stability.ts). It reads the public surface from the built.d.tsfiles that each published package'sexportsmap points at, so runpnpm build:packagesfirst. Each export is resolved to its declaration, because that's where TypeScript reads JSDoc tags from.Rules:
Documented means stable. An export is stable when a reference page documents it. It's experimental when only a
stability: unstablepage documents it. A page documents:frameworkTitleand doc-component props).media-is dropped only from a framework title, somedia-play-buttonnamesPlayButton.*Props,*State,*Element,*Options,*Result,*Config, and hookUse*types), when@videojs/react,@videojs/htmlor an extension package declares them. A same-named core or store type, such as core'sMenuOptionsbeside theMenupage, isn't one.Subject.Partselect*selectors named on feature pages### `isMediaPauseCapable`## Exportsheadingapisfrontmatter field: an export name, an exact@videojs/...entry point (every export it has), or a*module pattern (each matched module's default export)Guides and examples don't count.
Stability spreads through public types. An export named in a stable export's public types is stable too. That covers heritage clauses (
extends/implements), public and protected members, type-alias targets, parameters, return types, type-parameter constraints and defaults, and declared types. The same applies to experimental.corekeeps its*Coreclass internal.@internalmembers don't count._baseconstant a mixin class extends, passes its own references on, because readers reach them through the export that names it.@videojs/utilstype alias (Constructor,MixinReturn, …) counts as written out where it's used: it stays internal, and its target is checked instead.HTMLElementTagNameMap, doesn't spread stability to every element registered on it.Stable exports must be importable from a public package. Every stable or experimental export must be importable from
@videojs/react,@videojs/html,@videojs/storeor an extension package. Core, media, utils, element, SPF and the adapter packages don't count.--fixcan't resolve this; you re-export the type or change the signature.Everything else is
@internal.@deprecatedalso satisfies the rule.@experimentalhas to be earned by an unstable page or an experimental referrer; on an export nothing documents or references,--fixreplaces it with@internal.A page overrides a tag. A stable export that still carries
@internalor@experimentalfails, and--fixremoves the tag.Every declaration carries the tag: each declaration of a merged name, and each overload signature (not the implementation).
Other behaviour:
apisentries fail. An entry that matches no public export or entry point fails the check, so a rename or removal can't leave one behind.export * as Slidernamespaces are walked, so parts such asSlider.Bufferare checked asSliderBuffer.--fix: adds, replaces or removes tags on the matchingsrc/declaration. New comments go above// @ts-expect-error-style directives so those keep applying. Its output passesvp fmt.@videojs/spf(its maintainers own it) and@videojs/cdn(it re-bundles@videojs/html).@videojs/storeis skipped here and checked in chore(store): check and tag store's public exports #3083.writing-style/write-referencesexplains the rules andapis, thewrite-api-referenceskill has a new step, andAGENTS.mdhas a one-line policy.#3068 turns the check on in CI.
Preview pages
The only page this PR changes is Writing references. The Writing Style section is dev-only, so it isn't in the Netlify preview. Read the source on this branch, or run
pnpm dev:siteand open/docs/framework/react/writing-style/write-references.Testing
site/scripts/tests/check-api-stability.test.ts: 65 tests pass.pnpm -F site astro check --minimumSeverity warning: 0 errors, 0 warnings.pnpm lint,pnpm check:workspace: pass.🤖 Generated with Claude Code
https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
Note
Low Risk
Adds an opt-in site script and documentation; it does not change runtime packages or enable CI until a follow-up PR.
Overview
Adds
pnpm -F site check:api-stability, a TypeScript checker that walks published package.d.tssurfaces (afterbuild:packages), reference MDX coverage, and JSDoc tags to enforce the public API stability model.The script classifies exports as stable, experimental, or internal from what reference pages document (title, components,
## Exports, new optionalapisfrontmatter, module patterns, etc.) and transitive type references; it fails on wrong or missing@internal/@experimentaltags, stable APIs not re-exported from framework-facing packages, and stale documented names.--fixrewrites tags in matchingsrc/declarations.Contributor docs expand
write-references,AGENTS.md, and thewrite-api-referenceskill;content.config.tsvalidates optionalapis. ~65 unit tests cover parsing, propagation, and fix behavior. SPF/store are excluded for now.Reviewed by Cursor Bugbot for commit f33e3b6. Bugbot is set up for automated code reviews on this repo. Configure here.