From dd02c7c3b0bae542f892c1e607c7b2bd5c6daa9e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 23 Oct 2026 08:46:57 -0700 Subject: [PATCH 1/2] quest: plan API Extractor checks and a generated JS API reference Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 2 ++ quest/m1/api-extractor-checks.md | 36 ++++++++++++++++++++++++++++++++ quest/m1/js-api-reference.md | 29 +++++++++++++++++++++++++ 3 files changed, 67 insertions(+) create mode 100644 quest/m1/api-extractor-checks.md create mode 100644 quest/m1/js-api-reference.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 6cbceb66931..8ee12f05962 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -142,6 +142,8 @@ tracks, so per-group stats stop costing cluster announces. - [Error cleanups](/quest/m1/error-cleanups.md) - delete the unused `Error::SessionClosed`; raw transport failures already map to `Unroutable` - [FromStr parsers](/quest/m1/from-str-trait.md) - hang, moq-auth, and moq-msf implement `FromStr` instead of inherent `from_str` - [API-diff check](/quest/m1/api-diff.md) - a recipe diffs every published package's API against its last release, run on PRs into release and against main before the cut +- [API Extractor checks](/quest/m1/api-extractor-checks.md) - API Extractor fails a PR on a forgotten export, an unresolved declaration, or an undocumented export, replacing the hand-rolled `.d.ts` checkers +- [Generated JS API reference](/quest/m1/js-api-reference.md) - the doc site renders an API reference for every `@moq/*` package from API Extractor's doc model - [IETF lazy discovery](/quest/m1/ietf-lazy-discovery.md) - moq-transport sessions ask for announcements only under watched prefixes, starting with UNSUBSCRIBE_NAMESPACE on d14/15 - [Interop coverage](/quest/m1/interop-coverage/README.md) - the riskiest moq-transport features moq-net exposes get cross-implementation tests over the even drafts 14 to 22 - [Runner nightly](/quest/m1/interop-runner-nightly.md) - a nightly job runs the upstream interop runner against our relay and clients, so newly registered implementations with a published image are tested without a change here diff --git a/quest/m1/api-extractor-checks.md b/quest/m1/api-extractor-checks.md new file mode 100644 index 00000000000..116792d4e34 --- /dev/null +++ b/quest/m1/api-extractor-checks.md @@ -0,0 +1,36 @@ +# [M] API Extractor checks for @moq/* declarations + +## Goal + +Every published `@moq/*` entrypoint is checked by API Extractor on every PR, +with its messages as errors: a type the public API uses but does not export +(`ae-forgotten-export`), a declaration that does not resolve, and an exported +item without a doc comment (`ae-undocumented`) fail the build. +`js/common/docs.ts` and `js/common/declarations.ts` are deleted. + +## Plan + +Decided 2026-10-23 (maintainer interview): + +- Builds on the per-package API Extractor config and committed `.api.md` + reports that [the API-diff check](/quest/m1/api-diff.md) adds + ([moq-dev/moq#6477](https://github.com/moq-dev/moq/pull/6477)). One config + serves the reports, these checks, and the + [reference](/quest/m1/js-api-reference.md); do not add a second. +- Keep only the rules API Extractor enforces. A `docs.ts` rule with no + API Extractor equivalent is dropped, not kept in a reduced checker. +- JSR reads `@module` blocks, so define `@module` in `tsdoc.json` instead of + switching entrypoints to `@packageDocumentation`. +- `stripInternal` stays: rolling declarations up with release tags + (`dtsRollup`) is a non-goal. +- Prove the replacement: reintroducing the `@moq/auth` `AccessInput` bug + and dropping an export's doc comment must each fail `just check`. +- Rust is a non-goal: docs.rs and cargo-semver-checks cover it. + +## Required + +- [API-diff check](/quest/m1/api-diff.md) - adds the shared config and committed reports these checks extend + +## Related + +- [Generated JS API reference](/quest/m1/js-api-reference.md) - renders the doc model from the same config diff --git a/quest/m1/js-api-reference.md b/quest/m1/js-api-reference.md new file mode 100644 index 00000000000..2ab4a54e603 --- /dev/null +++ b/quest/m1/js-api-reference.md @@ -0,0 +1,29 @@ +# [L] Generated JS API reference + +## Goal + +The doc site has an API reference for every published `@moq/*` package, +including `@moq/watch`, `@moq/publish`, `@moq/libav`, and `@moq/moq-boy`, +which JSR cannot host because of their global type augmentation. Each package +page under `doc/lib/js/` links its reference. + +## Plan + +Decided 2026-10-23 (maintainer interview): + +- API Extractor's doc model (`.api.json`), from the shared per-package config + that [the checks](/quest/m1/api-extractor-checks.md) finish, is the only + source. The reference is TSDoc next to the code, rendered; update the + "not the reference" line in `doc/AGENTS.md` to say so. +- Our own renderer, not api-documenter: a small script turns the doc model + into VitePress pages styled like the rest of the site. +- One page per entrypoint (such as `/lib/js/net/api`), with an anchor per + symbol: the same split as the `.api.md` reports. +- Generated at doc build time from the checkout being built, so it always + matches the guides beside it. Nothing generated is committed. +- JSR keeps publishing its own reference; this does not replace it. +- Rust is a non-goal: docs.rs covers it. + +## Required + +- [API Extractor checks](/quest/m1/api-extractor-checks.md) - finishes the shared config and makes every exported item documented From e9625b622c0100c451df70a1b88a3759bb16d260 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 23 Oct 2026 09:05:12 -0700 Subject: [PATCH 2/2] quest: tag entrypoints for API Extractor package docs; fix @moq/boy name Co-Authored-By: Claude Opus 5.5 --- quest/m1/api-extractor-checks.md | 5 ++++- quest/m1/js-api-reference.md | 2 +- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/quest/m1/api-extractor-checks.md b/quest/m1/api-extractor-checks.md index 116792d4e34..0cd20afe74f 100644 --- a/quest/m1/api-extractor-checks.md +++ b/quest/m1/api-extractor-checks.md @@ -20,7 +20,10 @@ Decided 2026-10-23 (maintainer interview): - Keep only the rules API Extractor enforces. A `docs.ts` rule with no API Extractor equivalent is dropped, not kept in a reduced checker. - JSR reads `@module` blocks, so define `@module` in `tsdoc.json` instead of - switching entrypoints to `@packageDocumentation`. + switching entrypoints to `@packageDocumentation`. API Extractor reads an + entrypoint's summary only from a block tagged `@packageDocumentation`, so + add that tag beside `@module` (or an equivalent transform) to keep module + summaries in the doc model for the reference. - `stripInternal` stays: rolling declarations up with release tags (`dtsRollup`) is a non-goal. - Prove the replacement: reintroducing the `@moq/auth` `AccessInput` bug diff --git a/quest/m1/js-api-reference.md b/quest/m1/js-api-reference.md index 2ab4a54e603..3f1643554e8 100644 --- a/quest/m1/js-api-reference.md +++ b/quest/m1/js-api-reference.md @@ -3,7 +3,7 @@ ## Goal The doc site has an API reference for every published `@moq/*` package, -including `@moq/watch`, `@moq/publish`, `@moq/libav`, and `@moq/moq-boy`, +including `@moq/watch`, `@moq/publish`, `@moq/libav`, and `@moq/boy`, which JSR cannot host because of their global type augmentation. Each package page under `doc/lib/js/` links its reference.