From 1d05e86a1ab16c9c4d336c88e968abfdff27d077 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 6 Sep 2026 16:46:51 +0000 Subject: [PATCH] docs(gates): record the package-README census and defer check:doc-types' fourth leg (objectui#7896) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `check:doc-types` does not walk `packages/NAME/README.md` while its two sibling doc gates both do, so a package README's `type` literals are read twice and judged never. The `domain:ui` ruling on objectui#7896 orders the move census-first: the widening may land in the same pull request only if the census reads zero. It does not. All 39 files walked with this gate's own extractor and registry read 26 unregistered `type` literals across 12 files, plus 4 blind spots. So the leg does not land here. This commit records the measurement, the one real defect it found (`packages/plugin-detail/README.md:168` teaches a detail tab whose `content.type` is `activity-timeline`, rendered through `SchemaRenderer` and registered by nothing), the 25 other-vocabulary candidates, and the two couplings the implementing change will owe — the leg's slot in `scanDocs` and the expression-carriage census's surface-equality pin. Documentation only: no walk, no counter and no verdict moves. The header's ⛔ against treating this gate's widenings as a precedent stays verbatim. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr --- scripts/check-doc-component-types.mjs | 61 +++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/scripts/check-doc-component-types.mjs b/scripts/check-doc-component-types.mjs index ddba2f99b5..66e5621d52 100644 --- a/scripts/check-doc-component-types.mjs +++ b/scripts/check-doc-component-types.mjs @@ -263,6 +263,67 @@ export function appDocsDirs(root) { return out; } +/** + * `packages/NAME/README.md` — MEASURED, DELIBERATELY NOT WALKED (objectui#7896). + * + * This gate does not walk the package READMEs, while its two sibling doc gates + * both do: `check-doc-snippet-types.mjs` compiles their `ts` / `tsx` / + * `typescript` fences, and `check-doc-fence-languages.mjs` labels every fence in + * them (`join(pkgDir, entry, 'README.md')`). So a package README's `type` + * literals are read twice and judged never — objectui#7115's geometry rebuilt one + * directory over, on a surface that ships to npm inside each package's `files`. + * objectui#7896 measured the gap two ways, and it still reproduces on + * `59a3a233d`: a component `type` mutated in `packages/app-shell/README.md` + * leaves this gate at `EXIT=0` with byte-identical counters, while the same + * mutation in the root `README.md` gives `EXIT=1` at `README.md:272`. Identical + * counters are the proof the file is not in the scan population at all, rather + * than judged and forgiven. + * + * ⚠️ Why the leg is NOT here yet, and what has to happen first. The `domain:ui` + * ruling on objectui#7896 orders this move census-first: a change that moves a + * gate's scan population reports before it enforces, and the widening may land in + * the same pull request ONLY if the census reads zero. It does not. All 39 files + * were walked with this gate's own extractor and registry, and the census read + * **26 unregistered `type` literals across 12 files**, plus 4 blind spots (four + * unquoted YAML scalars in `packages/data-objectstack/README.md`, an object + * field-type vocabulary the same-line string-literal matcher cannot read). + * Landing the leg today would turn `main` red on 26 sites this card is not + * authorised to touch. Twenty-five of the 26 are other vocabularies with real declaration sites + * — dashboard widget kinds (`DashboardRenderer.tsx`), flow-graph node kinds, + * gesture kinds, Gantt task and dependency kinds, grid selection modes and + * summary aggregates, report kinds, view actions and filter kinds — i.e. + * candidate `DOC_TYPE_EXEMPTIONS` entries, each owed the reason that table + * demands. One is a real defect of the shape this gate exists to catch: + * `packages/plugin-detail/README.md:168` teaches a detail tab whose + * `content.type` is `activity-timeline`, and that content goes through + * `SchemaRenderer` (`DetailTabs.tsx:72`) while nothing registers that key — the + * registry's `OBJUI-001` panel, the same failure as the `line-chart` widget + * objectui#7896 recorded in `packages/plugin-dashboard/README.md`. + * + * ⛔ Do NOT reach for the exemption table to make a first run of the widened walk + * green. `DOC_TYPE_EXEMPTIONS` records rulings, not a switch for turning red into + * green, and stuffing it here would bury the one real defect among 25 entries + * nobody read. + * + * ⚠️ And when the leg does land, it is not the precedent the ⛔ above refuses. + * That ⛔ refuses widening onto an ARBITRARY unscanned tree; + * `packages/NAME/README.md` is not one, it is the surface this gate's own two + * siblings already walk, so the move aligns the third gate to its family rather + * than reaching into a new tree. The distinction is the whole of the ruling, and + * the ⛔ stays where it is. + * + * Two things the implementing change owes, recorded here so they are not + * rediscovered: the leg belongs BEFORE the root pages in `scanDocs`, which is the + * slot the two sibling walks append it in and what keeps the three lists + * comparable element by element; and `check-doc-expression-carriage.mjs` IMPORTS + * this file's surface constants and pins its own walk as an EQUALITY against a + * walk rebuilt from them — that pin compares against the CONSTANTS, not against + * this gate's actual walk, so a fourth leg added here alone leaves the pin GREEN + * while the two surfaces silently diverge, which is objectui#7115's shape again. + * The carriage census must take the same leg, and its `SURFACE_LABEL` test + * enumerates every leg by name. + */ + /** * Pages at the repository ROOT that join the walk by name. *