Skip to content

No gate holds the hand-written docs enumerations of @objectstack/spec subpaths and protocol namespaces equal to the exports map #17388

Description

@hotlong

The observation

Three hand-written pages under content/docs/ enumerate @objectstack/spec's subpaths or protocol namespaces, and nothing holds them equal to the package's exports map:

page what it enumerates
content/docs/deployment/troubleshooting.mdx ("Bundle size is too large" → "Available subpaths") the importable subpaths
content/docs/plugins/packages.mdx (@objectstack/spec → Exports) the 15 protocol namespaces
content/docs/getting-started/glossary.mdx ("Protocol Namespace", the layers table, and the per-namespace ### X Protocol sections) the 15 protocol namespaces, twice, plus one section per namespace

When PR #17372 (step 3 of #16325 — which remains open there; this card does not close it) deleted the ./cloud exports entry and added ./marketplace, every mechanical counter of the subpath set moved with it (packages/runtime/src/spec-subpath-alias-coverage.pin.test.ts, packages/spec/scripts/export-origins.test.ts, root-meta.test.ts, llms.txt via check:llms-txt, quick-reference.mdx via check:quick-reference-counts) — and all three pages above kept advertising cloud and never listed marketplace, because no gate reads them. The contract-review pass on that PR caught troubleshooting.mdx; the sweep it asked for found the other two. They were corrected by hand in the PR's patch round (ef1fda259).

Measured on that head: git grep -n -E 'Kernel, Cloud|Security, Cloud|cloud, qa' -- content/docs returns 0 lines (same-shape control naming Marketplace returns 4), so the pages are current today — the finding is that nothing keeps them current.

What a fix could look like

Any one of these; the first is the cheapest:

  1. Extend packages/runtime/src/spec-subpath-alias-coverage.pin.test.ts (it already reads packages/spec/package.json's exports and derives PUBLISHED_SUBPATHS) — or a root check:docs-* gate — to read the three enumerations and hold them equal to the derived set, the way check:quick-reference-counts holds quick-reference.mdx's per-section counts.
  2. Have packages/spec/scripts/build-docs.ts emit a generated subpath / namespace snippet that the three pages include, so the enumeration is produced rather than typed.
  3. Reduce the hand-written enumerations to one page and link the other two to it.

Note the troubleshooting list and the namespace lists are two different sets: the exports map has 16 ./* entries (meta-spelling is a subpath but not a protocol namespace), the namespace lists have 15.


Generated by Claude Code

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions