docs(check-doc-links): re-derive two stale scan-surface claims from SCAN_ROOTS

.changeset/6280-scan-surface-claims.md

@@ -0,0 +1,24 @@
+---
+---
+
+Doc-only fixes in `@object-ui/components` and the docs site: two stale claims about
+`scripts/check-doc-links.mjs`'s scan surface, both frozen at an earlier `SCAN_ROOTS`
+shape (objectui#6280).
+
+- `packages/components/src/__tests__/readme-shadcn-sync-categories.test.ts`'s
+  `## Scan surface` docblock said `README_SHADCN_SYNC.md` had "never been scanned by
+  anything" — false since objectui#4938, whose `packages/*` row excludes only the
+  basenames `README.md`/`CHANGELOG.md` and so does include this file. Rewritten to
+  argue from the current tree: the file IS scanned, but check-doc-links only inspects
+  `[text](href)` markdown-link syntax (never the backticked code spans this README
+  uses for every in-repo path) and has no notion of prose-vs-manifest consistency —
+  so the hand-rolled checks below survive regardless of scan surface, for reasons
+  unrelated to whether the surface reaches this file.
+- `content/docs/guide/ci-cd-pipeline.md` described the scan surface twice (prose and
+  the two-link-checkers table), both frozen at the objectui#3622 shape ("the internal
+  `docs/` tree and every package `README.md`"). Re-derived from the live `SCAN_ROOTS`
+  table (17 rows) and rewritten to include the app READMEs and root-level markdown
+  (objectui#4148), the rest of each package/app directory tree (objectui#4938), and
+  every nested `README.md` (objectui#6026).
+
+No source or behaviour change; text and a test docblock only.

content/docs/guide/ci-cd-pipeline.md

@@ -423,9 +423,13 @@ all**, which is the point of the workflow. It appears in the checks list as **In
 Check**.
 
 Runs `scripts/check-doc-links.mjs`, which walks every `.md` / `.mdx` file in the surfaces listed in
-its `SCAN_ROOTS` — `content/docs/`, `examples/`, the root `README.md`, `CONTRIBUTING.md`,
-`ROADMAP.md`, the internal `docs/` tree and every package `README.md` — and asks of each internal
-markdown link whether its target is really there.
+its `SCAN_ROOTS` (17 rows as of objectui#6280) — `content/docs/`, `examples/`, the internal `docs/`
+tree, every package and app `README.md`, the rest of each package's and app's directory tree (every
+file except `README.md` and `CHANGELOG.md`, the latter excluded everywhere as changesets output
+rather than authored prose), every nested `README.md` a package or app carries below its top level,
+and the root-level markdown files (`README.md`, `CONTRIBUTING.md`, `ROADMAP.md`, `AGENTS.md`,
+`CHANGELOG.md`, `CLAUDE.md`, `LICENSE-THIRD-PARTY.md`, `QUICK_REFERENCE.md`) — and asks of each
+internal markdown link whether its target is really there.
 
 **Two rules, because the two groups are read through different machinery** (objectui#3536). For
 `content/docs/` the question is the one a site reader cares about, **does the site serve this URL?**
@@ -1058,7 +1062,7 @@ There are **two** link checkers, and they cover different things (objectui#3213)
 
 | | Covers | Network | Runs |
 |---|---|---|---|
-| `scripts/check-doc-links.mjs` | **Internal** links in `content/docs/` (relative hrefs, `/docs/...` routes, every other site-absolute href against `apps/site`), in `examples/`, `README.md`, `CONTRIBUTING.md`, `ROADMAP.md`, `docs/` and every package `README.md` (as paths on disk), plus this repo's own `blob/main/` and `tree/main/` GitHub URLs and this site's own `objectui.org` URLs everywhere — **except** anything inside a code fence | No | `docs-links.yml` — every push and PR, no path filter (previous section) |
+| `scripts/check-doc-links.mjs` | **Internal** links in `content/docs/` (relative hrefs, `/docs/...` routes, every other site-absolute href against `apps/site`), and, as paths on disk: `examples/`, the internal `docs/` tree, every package and app `README.md`, the rest of each package's and app's directory tree (everything but `README.md`/`CHANGELOG.md`), every nested `README.md`, and the root-level markdown files (`README.md`, `CONTRIBUTING.md`, `ROADMAP.md`, `AGENTS.md`, `CHANGELOG.md`, `CLAUDE.md`, `LICENSE-THIRD-PARTY.md`, `QUICK_REFERENCE.md`) — plus this repo's own `blob/main/` and `tree/main/` GitHub URLs and this site's own `objectui.org` URLs everywhere — **except** anything inside a code fence | No | `docs-links.yml` — every push and PR, no path filter (previous section) |
 | Lychee (this workflow) | **External** URLs, plus **relative** in-repo file links, in `content/docs/`, `docs/` and `README.md` | Yes | Weekly cron and manual dispatch |
 
 Lychee sweeps **both** documentation trees: `content/docs/` (the 183 pages the site publishes) and

packages/components/src/__tests__/readme-shadcn-sync-categories.test.ts

@@ -90,14 +90,44 @@
  * components (`pnpm shadcn:update button`) legitimately — fenced blocks are
  * stripped before the section is judged for that reason.
  *
- * The path check is here because no link gate can see this file:
- * `check-doc-links.mjs`'s per-package `SCAN_ROOTS` row globs one directory level
- * and then matches the exact filename `README.md`, so `README_SHADCN_SYNC.md` has
- * never been scanned by anything — which is also how its `## Files` section came
- * to claim `shadcn-sync.js` sits in this directory when it has always been at the
- * repo root. Widening that scan root is a separate change with its own entry
- * price (the objectui#3603 / objectui#3622 shape: one row plus whatever it turns
- * red) and is deliberately not taken here.
+ * **`check-doc-links.mjs` DOES scan this file today.** The claim that stood
+ * here — that no link gate can see it, because the per-package `SCAN_ROOTS` row
+ * globbed one directory level and matched only the exact filename `README.md` —
+ * became false with objectui#4938: that row now walks every markdown file under
+ * each package directory and excludes only the basenames `README.md` and
+ * `CHANGELOG.md`, at every depth. `README_SHADCN_SYNC.md` is neither, so it is
+ * inside that row (re-verified against the live `SCAN_ROOTS` table for
+ * objectui#6280 — 17 rows total, this file collected by the `packages/*` row
+ * and by no other).
+ *
+ * That does not make the checks below redundant, for two reasons that would
+ * each independently survive `check-doc-links.mjs` scanning every byte of this
+ * README:
+ *
+ *   - **It cannot see the paths this file names.** Every in-repo path here —
+ *     `shadcn-components.json`, `scripts/shadcn-sync.js`,
+ *     `scripts/shadcn-local-patches.mjs` — is written as a backticked code
+ *     span, never as a `[text](href)` markdown link, and `check-doc-links.mjs`
+ *     blanks every inline code span (`stripCode()`) before its link regex ever
+ *     runs, by design — a command example like `` `pnpm shadcn:update button` ``
+ *     must not be misread as a broken link. This README's only actual markdown
+ *     links (8, all external: `ui.shadcn.com`, `github.com/shadcn-ui/...`, and
+ *     the Radix/Tailwind/CVA sites) carry nothing check-doc-links would resolve
+ *     against this repo. So scanning this file today asserts nothing about the
+ *     paths the last `it` block below checks — the objectui#3881 path drift
+ *     (`## Files` claiming `shadcn-sync.js` sits in this directory when it has
+ *     always been at the repo root) would go just as uncaught by that gate
+ *     under today's widened surface as it did before objectui#4938.
+ *   - **It has no notion of this file's actual defect class.** objectui#3881
+ *     was two prose censuses disagreeing with `shadcn-components.json` about
+ *     which components belong where — a comparison against a JSON manifest,
+ *     not a link target. No widening of `SCAN_ROOTS`, at any width, gives a
+ *     link checker that question to ask.
+ *
+ * The first reason is why the path check (the last `it` block) survives; the
+ * second is why the category/manifest comparisons above it do. Both hold
+ * regardless of `check-doc-links.mjs`'s scan surface — not because that
+ * surface stops short of this file, since it no longer does.
  */
 
 import { describe, it, expect } from 'vitest';