diff --git a/.changeset/6280-scan-surface-claims.md b/.changeset/6280-scan-surface-claims.md new file mode 100644 index 000000000..e4cdf7472 --- /dev/null +++ b/.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. diff --git a/content/docs/guide/ci-cd-pipeline.md b/content/docs/guide/ci-cd-pipeline.md index 7acfc63a6..17ff62755 100644 --- a/content/docs/guide/ci-cd-pipeline.md +++ b/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 diff --git a/packages/components/src/__tests__/readme-shadcn-sync-categories.test.ts b/packages/components/src/__tests__/readme-shadcn-sync-categories.test.ts index f1eaa27dc..e993e3095 100644 --- a/packages/components/src/__tests__/readme-shadcn-sync-categories.test.ts +++ b/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';