fix(console): the docs portal renders the book resolver's answer; the… #5229
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
| name: Doc Example Ids | |
| # Why this is its own workflow instead of a step in `ci.yml` or `lint.yml`: the | |
| # defect this gate exists for arrives in a DOCS-ONLY pull request, and that is | |
| # precisely the shape both of those workflows skip. `ci.yml`'s `type-check` job | |
| # decides whether to run its expensive steps with a `git diff` that excludes | |
| # `content/**`, `'**/*.md'`, `docs/**` and `apps/site/**` — so a pull request | |
| # that edits only `content/docs/**` reports the context and runs none of the | |
| # gates inside it. A gate against a stale `<SchemaExample id="…" />`, wired | |
| # there, would be blind to every change that can introduce one: the id is typed | |
| # into an MDX page and nothing else has to move. | |
| # | |
| # The reasoning is borrowed rather than invented — `doc-component-types.yml`'s | |
| # header records it for the neighbouring gate over these same pages, and | |
| # `control-bytes.yml`'s names the consequence: a gate that cannot see a | |
| # markdown-only change "rebuilds the hole it exists to close". | |
| # | |
| # Hence: no `paths` and no `paths-ignore` here, deliberately. | |
| # `scripts/__tests__/check-doc-example-ids.test.ts` fails if either is ever | |
| # added, and fails too if a second workflow starts running the same script — one | |
| # gate, one home. | |
| # | |
| # It needs no install and no build. The script reads the checkout with `node:fs` | |
| # only: every `.mdx` and `.md` page under `content/docs/**` for its | |
| # `<SchemaExample>` references, and the generated schema-catalog index for the | |
| # id universe it resolves them against. A few seconds. Keep it that way — the | |
| # moment this needs `pnpm install` it stops being cheap enough to run | |
| # unfiltered, and the filter is the hole. | |
| # | |
| # ⛔ Deliberately NO population count is written here, and none may be added. | |
| # The neighbouring gate paid for that lesson (objectui#7448): a total in a | |
| # comment has nothing that fails when it drifts, which is exactly why it rots, | |
| # and refreshing the literal only restarts the clock. Two durable readings, | |
| # neither a copy: | |
| # | |
| # * HOW MANY — the run below prints it, in the gate's own funnel line: | |
| # "Doc example ids — walked N page(s) …, found M reference(s) …". `pnpm | |
| # check:doc-example-ids` reprints it on demand. | |
| # * WHICH — `scanDocs` in `scripts/check-doc-example-ids.mjs`, which derives | |
| # the population from the tree on every run. | |
| # | |
| # `scripts/__tests__/check-doc-example-ids.test.ts` fails if a population count | |
| # reappears here, so the rule above is a gate rather than an intention. | |
| on: | |
| pull_request: | |
| branches: [main, develop] | |
| push: | |
| branches: [main, develop] | |
| # Merge queue (objectui#3523 — see `ci.yml`'s trigger block for the full note | |
| # and the measurements behind it). A required check that does not report on a | |
| # queue build stalls the queue until the ruleset's 60-minute timeout fails it, | |
| # so an unfiltered gate that could become required subscribes here from the | |
| # start. `types:` is named although `checks_requested` is currently the only | |
| # activity type GitHub defines for `merge_group`. | |
| merge_group: | |
| types: [checks_requested] | |
| workflow_dispatch: | |
| concurrency: | |
| group: doc-example-ids-${{ github.event.pull_request.number || github.ref }} | |
| cancel-in-progress: true | |
| permissions: | |
| contents: read | |
| jobs: | |
| doc-example-ids: | |
| name: Doc Example Id Check | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 5 | |
| steps: | |
| - name: Checkout code | |
| uses: actions/checkout@v7 | |
| - name: Setup Node.js | |
| uses: actions/setup-node@v7 | |
| with: | |
| node-version: '22.x' | |
| # A `<SchemaExample id="…" />` in a docs page resolves through | |
| # `getExample(id)`, which THROWS on an unknown id rather than degrading — | |
| # the honest runtime behaviour, and the reason a mistyped or stale id is a | |
| # crash in the published docs rather than a blank tile. Nothing asked the | |
| # question before render: the catalog's own suite resolves every registry | |
| # ENTRY, which cannot see a page pointing at an id that is not there. | |
| # Reads the checkout and nothing else, so no install. | |
| - name: Check documented example ids against the catalog registry | |
| run: node scripts/check-doc-example-ids.mjs |