@krapwoo/ds-viewer 0.2.0 → 0.3.0

package/README.md

@@ -61,6 +61,8 @@ Either way, then:
 ```bash
 npm run ds-viewer dev    # opens the catalog in a browser, re-syncing on every file change
 npm run ds-viewer sync   # regenerates component/token/page data without starting a server
+npm run ds-viewer doctor   # checks every page for drift and coverage gaps (--json, --ci)
+npm run ds-viewer explain <Page>   # prints why a page's specimens are laid out the way they are
 ```
 
 `ds-viewer.config.ts` fields: `name`, `logo` (optional — a path to an image asset, shown in the
@@ -204,6 +206,86 @@ data, not a component — see `ColorsGallery`/`SpacingGallery`/`TypographyGaller
 output full width under a "Tokens" label and shows only a Quick reference card with the source
 path.
 
+## Keeping the catalog current
+
+### Binding examples to props
+
+A grid's row or column axis can name the real prop it demonstrates:
+
+```tsx
+import { defineCatalogPage, grid } from '@krapwoo/ds-viewer';
+
+comparison: grid(
+  'Variant', 'State',
+  { prop: 'variant', items: [
+    { key: 'primary', label: 'Primary' },
+    { key: 'ghost', label: 'Ghost' },
+  ] },
+  [{ key: 'default', label: 'Default' }, { key: 'disabled', label: 'Disabled' }],
+  (row, column) => <Button variant={row} disabled={column === 'disabled'} onPress={() => {}} />,
+),
+```
+
+Only a prop typed as a string-literal union (2 or more options) can be bound this way; each item's
+`key` must then be a real option of that prop. An axis that doesn't name a single real prop (e.g.
+"which of three optional props is set," or a continuous `number`) stays a plain array of
+`{ key, label }` — just as valid, and never flagged by `doctor`. `variants`/`states` list items use
+the existing `props` tag (`{ key: 'ghost', props: { variant: 'ghost' }, node: ... }`) the same way.
+Binding is what lets `doctor` tell you precisely when a renamed or removed option leaves a stale
+example behind, instead of you finding out by reading the diff.
+
+### `npx ds-viewer doctor`
+
+Reads every page with the TypeScript compiler — it never imports a page file or runs app code.
+Human output is grouped by page, each issue with a one-line fix:
+
+```
+Button
+  [error] bound-option-removed: The row "outline" is bound to "variant", which no longer has that option.
+    Fix: Delete this row, or update its key to a current option of "variant".
+
+0 errors, 1 warning — 38 components (37 with examples), 2 unbound examples.
+```
+
+- `--json` prints the same report as stable, versioned data: `{ version: 1, summary: { errors, warnings, components, withExamples, unboundExamples }, update: null, issues: [{ id, severity, page?, file?, line?, message, fix }] }`. `update` is always `null` in this release (filled in starting 0.4's update check); `file` is always relative to the project root. `line` is populated for a `page-parse-error` found by typechecking a page file (see below), and always `undefined` for every other issue id — threading a real position through every rule is future work.
+- `--ci` exits 1 only when an error was found — a warning alone never fails CI, and `--ci` never makes a network call.
+- `doctor.strict: true` in `ds-viewer.config.ts` promotes every warning to an error, for both the summary counts and `--ci`'s exit code.
+- A page whose layout data (`specimenSize`, `group`, grid `rows`/`columns`, list items' `key`/`name`/`props`/`group`, `propNotes` keys) isn't a literal — written as something other than a literal value, array, object, or a same-file `const` reference — gets one "page not statically checkable" warning. A page file that fails to parse *or typecheck* is `page-parse-error` instead: every page file is also run through the TypeScript type checker (the same way a component file already is), so a genuine syntax or type error in a page is reported with its line.
+
+## Known gaps
+
+- The viewer's own dev-mode console warnings only cover `duplicate-page-id` (design §4's "the same rules appear as development warnings naming the page" — scoped to that one rule in 0.3). Bound-axis drift (`bound-option-removed`, `bound-axis-prop-removed`) has no viewer-side warning yet; `npx ds-viewer doctor` (and its `--ci` workflow) is the only place that catches it today.
+
+### `npx ds-viewer explain <Page>`
+
+Prints each layout decision with its reason, using the exact same pure functions the catalog itself
+renders with:
+
+```
+Button
+Grid (Variant × State)
+  5 rows × 3 columns (regular); 3 of 3 max regular columns used — fits a 1280px laptop.
+```
+
+Side-by-side placement depends on a real measured height, so by default `explain` reports it as
+"decided in the viewer." Pass `--heights <firstBlockPx>,<secondBlockPx>` to check that decision here
+too, assuming a 1280px laptop (952px content width) the same way `doctor`'s own column-limit check
+does. `--json` is available on `explain` as well.
+
+### The `AGENTS.md` section and GitHub Action
+
+`npx @krapwoo/ds-viewer init` (either path) appends a short section to `AGENTS.md` between
+`<!-- ds-viewer:start v1 -->`/`<!-- ds-viewer:end -->` markers — creating the file if it doesn't
+exist — telling an AI working on the project to update a page alongside its component, bind
+examples to props, never invent grid cells or groups, and run `doctor`/`explain` before finishing.
+It also writes `.github/workflows/ds-viewer.yml`, a SHA-pinned Action that installs dependencies
+(picking `npm ci`, `pnpm install --frozen-lockfile`, or `yarn install --immutable` from whichever
+lockfile the project has at that moment) and then runs `npx ds-viewer doctor --ci` on every pull
+request. Both are written once; re-running `init` adds
+either one only if it's missing (an `AGENTS.md` without the start marker counts as missing the
+section, even if the file already has other content) and never touches anything outside its own
+markers or its own file.
+
 ## What's included
 
 Tokens · Icons (45) · and generic components:

package/dist/cli/agentsFile.js

@@ -0,0 +1,31 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+const START_MARKER = '<!-- ds-viewer:start v1 -->';
+const END_MARKER = '<!-- ds-viewer:end -->';
+// Design §4's four numbered lines, verbatim — no heading added: the design names only these four
+// lines as the section's content.
+const SECTION_BODY = [
+    "1. When you add or change a component's props or a token, update its \`*.catalog.tsx\` in the same change.",
+    "2. Bind examples to props (\`prop\` on grid axes, \`props\` on list items) so drift is detected.",
+    '3. Never invent grid cells or groups; author only combinations that exist.',
+    "4. Run \`npx ds-viewer doctor\` before finishing and fix every error. Use \`npx ds-viewer explain <Page>\` to check layout; see the README's page-authoring guide.",
+].join('\n');
+/** Design §4 "AGENTS.md section", §1 Ownership, §2 step 3. Appends between the exact markers,
+ *  creating the file when absent — never touches a byte outside them, and never runs at all once
+ *  the start marker is already present, even if the rest of the file looks nothing like what this
+ *  function would have written (design: "An AGENTS.md without the markers counts as missing the
+ *  section" — the converse is also true: a file WITH the marker is never rewritten in 0.3). */
+export function ensureAgentsFileSection(projectRoot) {
+    const agentsPath = path.join(projectRoot, 'AGENTS.md');
+    const existing = existsSync(agentsPath) ? readFileSync(agentsPath, 'utf8') : '';
+    if (existing.includes(START_MARKER))
+        return [];
+    // Minor finding (Fable's review): a CRLF `AGENTS.md` must not end up with mixed line endings
+    // after the append — the separator and the whole section below use whichever newline the
+    // existing file already uses.
+    const newline = existing.includes('\r\n') ? '\r\n' : '\n';
+    const separator = existing === '' ? '' : existing.endsWith(`${newline}${newline}`) ? '' : existing.endsWith(newline) ? newline : `${newline}${newline}`;
+    const body = newline === '\n' ? SECTION_BODY : SECTION_BODY.replace(/\n/g, newline);
+    writeFileSync(agentsPath, `${existing}${separator}${START_MARKER}${newline}${body}${newline}${END_MARKER}${newline}`);
+    return [agentsPath];
+}

package/dist/cli/doctor.js

@@ -0,0 +1,492 @@
+import * as ts from 'typescript';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { discoverAllPageFiles, resolvePageId } from "./pageIndex.js";
+import { readHostTsconfigOptions } from "./props.js";
+import { readStaticPages } from "./staticPage.js";
+import { resolveGlob } from "./glob.js";
+import { sync } from "./sync.js";
+import { gridColumnLimit } from "../native/catalog/comparison.js";
+function issue(fields) {
+    return fields;
+}
+function pageRef(page) {
+    return { page: resolvePageId(page, page.file), file: page.file };
+}
+/** Errata (controller, binding): a page discovered from a component folder (a `components` glob's
+ *  folder, not a `pages` glob) with no explicit `component:` documents the component named by its
+ *  own file (design §2; the viewer already applies this same default via `page.component ??
+ *  page.id`, and the generated page index already defaults a missing `id` to the file stem). A
+ *  page from a standalone `pages` glob is never touched — `componentFolders` only ever contains
+ *  folders resolved from `config.components`, so a standalone page's own folder is never a member. */
+export function applyComponentDefaults(pages, componentFolders) {
+    return pages.map((page) => page.component === undefined && componentFolders.has(path.dirname(page.file))
+        ? { ...page, component: resolvePageId(page, page.file) }
+        : page);
+}
+function checkParseErrors(pages) {
+    return pages
+        .filter((p) => Boolean(p.parseError))
+        .map((p) => issue({ id: 'page-parse-error', severity: 'error', file: p.file, message: `Failed to parse: ${p.parseError}`, fix: 'Fix the syntax error, then rerun doctor.' }));
+}
+function checkNotCheckable(pages) {
+    return pages
+        .filter((p) => !p.checkable && !p.parseError)
+        .map((p) => issue({
+        id: 'page-not-checkable', severity: 'warning', ...pageRef(p),
+        message: 'Page not statically checkable — some of its layout data is not a literal doctor can read.',
+        fix: 'Write rows/columns/items/propNotes as literal arrays/objects (or a same-file const), not a function call.',
+    }));
+}
+function checkComponentExportRemoved(pages, components) {
+    const names = new Set(components.map((c) => c.name));
+    return pages
+        .filter((p) => p.component && !names.has(p.component))
+        .map((p) => issue({
+        id: 'component-export-removed', severity: 'error', ...pageRef(p),
+        message: `Documents "${p.component}", which no longer exists as a component export.`,
+        fix: 'Delete this page, or update "component" to the export\'s new name.',
+    }));
+}
+/** True when a page documents at least one example by any mechanism design §4 recognizes — a
+ *  grid, a `variants` item, a `states` item, or `render`. A page can be "fully covered" by
+ *  `checkComponentExportRemoved`'s standard (it names a real component) and still have none of
+ *  these — e.g. `init`'s own "Needs examples" draft, which sets only `component`/`group`/
+ *  `description` — in which case the viewer shows the exact same "No examples documented." an
+ *  undocumented component would. */
+function pageHasExamples(page) {
+    return Boolean(page.comparison) || Boolean(page.variantsItems?.length) || Boolean(page.statesItems?.length) || page.hasRender === true;
+}
+function checkComponentNoExamples(pages, components) {
+    const byComponent = new Map();
+    for (const page of pages) {
+        if (page.component)
+            byComponent.set(page.component, [...(byComponent.get(page.component) ?? []), page]);
+    }
+    return components
+        .filter((c) => {
+        const componentPages = byComponent.get(c.name) ?? [];
+        // A not-statically-checkable page is given the benefit of the doubt here — it might have
+        // real examples this reader simply couldn't read (Global Constraint: never a partial read;
+        // its own `page-not-checkable` warning already covers it). Only "every page is checkable
+        // and genuinely empty" (or "no page at all") fires this rule.
+        return componentPages.length === 0 || componentPages.every((p) => p.checkable && !pageHasExamples(p));
+    })
+        .map((c) => {
+        const hasPage = (byComponent.get(c.name) ?? []).length > 0;
+        return issue({
+            id: 'component-no-examples', severity: 'warning', page: c.name, file: c.file,
+            message: hasPage
+                ? `"${c.name}" has a catalog page with no variants, states, comparison, or render — it will show "No examples documented."`
+                : `"${c.name}" has no catalog page — it will show "No examples documented."`,
+            fix: hasPage ? `Add variants/states/comparison, or render, to ${c.name}'s catalog page.` : `Add ${c.name}.catalog.tsx beside ${c.name}'s own file.`,
+        });
+    });
+}
+function checkDuplicatePageId(pages) {
+    const byId = new Map();
+    for (const page of pages) {
+        const id = resolvePageId(page, page.file);
+        byId.set(id, [...(byId.get(id) ?? []), page]);
+    }
+    const issues = [];
+    for (const [id, group] of byId) {
+        if (group.length < 2)
+            continue;
+        for (const page of group) {
+            const others = group.filter((p) => p !== page).map((p) => p.file).join(', ');
+            issues.push(issue({
+                id: 'duplicate-page-id', severity: 'error', page: id, file: page.file,
+                message: `Page id "${id}" is also used by ${others}.`,
+                fix: 'Give one of these pages its own "id".',
+            }));
+        }
+    }
+    return issues;
+}
+function checkGridAxisKeys(pages) {
+    const issues = [];
+    for (const page of pages) {
+        // Global Constraints: "never a partial read" — a not-checkable page gets only
+        // `page-not-checkable` (`checkNotCheckable` above); a *different* field on it happening to be
+        // literal (e.g. its grid, while its `propNotes` wasn't) is never grounds for a second opinion.
+        if (!page.checkable || !page.comparison)
+            continue;
+        for (const [axisName, axis] of [['row', page.comparison.rows], ['column', page.comparison.columns]]) {
+            const seen = new Set();
+            for (const item of axis.items) {
+                if (item.key === '') {
+                    issues.push(issue({ id: 'grid-axis-key-invalid', severity: 'error', ...pageRef(page), message: `A ${axisName} has an empty key.`, fix: `Give every ${axisName} a non-empty, unique key.` }));
+                }
+                else if (seen.has(item.key)) {
+                    issues.push(issue({ id: 'grid-axis-key-invalid', severity: 'error', ...pageRef(page), message: `Duplicate ${axisName} key "${item.key}".`, fix: `Give each ${axisName} its own key.` }));
+                }
+                seen.add(item.key);
+            }
+        }
+    }
+    return issues;
+}
+function checkGridColumnLimit(pages) {
+    const issues = [];
+    for (const page of pages) {
+        if (!page.checkable || !page.comparison)
+            continue; // same "never a partial read" reasoning as checkGridAxisKeys above.
+        const size = (page.comparison.size ?? page.specimenSize ?? 'regular');
+        const limit = gridColumnLimit(size);
+        const count = page.comparison.columns.items.length;
+        if (count > limit) {
+            issues.push(issue({
+                id: 'grid-column-limit', severity: 'error', ...pageRef(page),
+                message: `Grid has ${count} columns; at most ${limit} ${size} columns fit a 1280px laptop.`,
+                fix: 'Swap the axes, use two lists, or pick a smaller specimenSize.',
+            }));
+        }
+    }
+    return issues;
+}
+/** Everything that needs a page's own matching `ComponentRecord` to check: `propNotes`, bound
+ *  axes, tagged list items, coverage, grouped-state matching, and guidance/a11y presence. One
+ *  function because every one of these checks shares the same per-page `component`/`propsByName`
+ *  lookup — splitting it further would only duplicate that lookup, not clarify anything. */
+function checkComponentPages(pages, components) {
+    const componentsByName = new Map(components.map((c) => [c.name, c]));
+    const issues = [];
+    for (const page of pages) {
+        if (!page.component)
+            continue;
+        if (!page.checkable)
+            continue; // never a partial read — see checkGridAxisKeys's own note.
+        const component = componentsByName.get(page.component);
+        if (!component)
+            continue; // already reported by checkComponentExportRemoved
+        const ref = pageRef(page);
+        const propsByName = new Map(component.props.map((p) => [p.name, p]));
+        for (const key of page.propNoteKeys ?? []) {
+            if (!propsByName.has(key)) {
+                issues.push(issue({
+                    id: 'propnotes-prop-removed', severity: 'error', ...ref,
+                    message: `propNotes names "${key}", which is no longer a prop of ${component.name}.`,
+                    fix: `Delete the "${key}" entry from propNotes, or rename it to the prop's new name.`,
+                }));
+            }
+        }
+        if (page.comparison) {
+            for (const [axisName, axis] of [['row', page.comparison.rows], ['column', page.comparison.columns]]) {
+                if (axis.prop === undefined)
+                    continue;
+                const prop = propsByName.get(axis.prop);
+                if (!prop) {
+                    issues.push(issue({
+                        id: 'bound-axis-prop-removed', severity: 'error', ...ref,
+                        message: `The ${axisName} axis is bound to "${axis.prop}", which is no longer a prop of ${component.name}.`,
+                        fix: 'Update "prop" to the prop\'s new name, or unbind this axis.',
+                    }));
+                    continue;
+                }
+                if (!prop.options) {
+                    issues.push(issue({
+                        id: 'bound-axis-not-union', severity: 'error', ...ref,
+                        message: `The ${axisName} axis is bound to "${axis.prop}", which is not a string-literal-union prop.`,
+                        fix: 'Only a prop with a fixed set of string options can be bound; unbind this axis.',
+                    }));
+                    continue;
+                }
+                for (const item of axis.items) {
+                    if (!prop.options.includes(item.key)) {
+                        issues.push(issue({
+                            id: 'bound-option-removed', severity: 'error', ...ref,
+                            message: `The ${axisName} "${item.key}" is bound to "${axis.prop}", which no longer has that option.`,
+                            fix: `Delete this ${axisName}, or update its key to a current option of "${axis.prop}".`,
+                        }));
+                    }
+                }
+            }
+        }
+        const listItems = [...(page.variantsItems ?? []), ...(page.statesItems ?? [])];
+        for (const item of listItems) {
+            for (const [propName, value] of Object.entries(item.props ?? {})) {
+                if (typeof value !== 'string')
+                    continue;
+                const prop = propsByName.get(propName);
+                if (!prop) {
+                    // A name missing from `props` is only real drift when the component has nothing
+                    // inherited to explain it — `component.props` deliberately omits a node_modules-declared
+                    // prop (cli/props.ts:200), so e.g. `autoCapitalize` on a `TextInput`-extending component
+                    // is expected to be absent here, not a removed prop (design: `inheritedFrom` summarises
+                    // those instead of listing them).
+                    if (component.inheritedFrom.length > 0)
+                        continue;
+                    // The tagged prop *name* itself no longer exists — arguably the same drift as
+                    // `bound-axis-prop-removed`, but a tagged list item (unlike a bound axis) has no
+                    // "prop" field of its own to report that id against, so it's reported here instead.
+                    // Previously silently skipped (`!prop?.options` was true for both "prop missing" and
+                    // "prop exists but isn't a union"), masking exactly the drift this rule exists to catch.
+                    issues.push(issue({
+                        id: 'bound-option-removed', severity: 'error', ...ref,
+                        message: `"${item.name}" is tagged props.${propName} = "${value}", but "${propName}" is no longer a prop of ${component.name}.`,
+                        fix: 'Delete the tag, or update it to a current prop name.',
+                    }));
+                    continue;
+                }
+                if (!prop.options || prop.options.includes(value))
+                    continue;
+                issues.push(issue({
+                    id: 'bound-option-removed', severity: 'error', ...ref,
+                    message: `"${item.name}" is tagged props.${propName} = "${value}", which is no longer an option of "${propName}".`,
+                    fix: 'Update the tagged value, or delete this item if the option no longer exists.',
+                }));
+            }
+        }
+        for (const prop of component.props) {
+            if (!prop.options)
+                continue;
+            const covered = new Set();
+            if (page.comparison) {
+                for (const axis of [page.comparison.rows, page.comparison.columns]) {
+                    if (axis.prop === prop.name)
+                        for (const item of axis.items)
+                            covered.add(item.key);
+                }
+            }
+            for (const item of listItems) {
+                const value = item.props?.[prop.name];
+                if (typeof value === 'string')
+                    covered.add(value);
+            }
+            for (const option of prop.options.filter((o) => !covered.has(o))) {
+                issues.push(issue({
+                    id: 'option-not-covered', severity: 'warning', ...ref,
+                    message: `"${prop.name}" option "${option}" has no bound or tagged example.`,
+                    fix: `Bind a grid axis to "${prop.name}", or add { props: { ${prop.name}: '${option}' } } to a variants/states item.`,
+                }));
+            }
+        }
+        const variantKeys = new Set((page.variantsItems ?? []).map((i) => i.key));
+        for (const item of page.statesItems ?? []) {
+            if (item.group !== undefined && !variantKeys.has(item.group)) {
+                issues.push(issue({
+                    id: 'group-unmatched', severity: 'warning', ...ref,
+                    message: `"${item.name}" names group "${item.group}", which matches no variant key; it will show under "Other configurations".`,
+                    fix: 'Fix the group value, or remove it if this item isn\'t tied to a specific variant.',
+                }));
+            }
+        }
+        // Design §4 names this one rule, "missing guidance or accessibility notes" — one id, and (per
+        // the controller) both halves: a missing `whenToUse` and a missing `a11y` each get their own
+        // message under `missing-guidance-or-a11y`, since the viewer renders a visible placeholder
+        // ("No usage guidance documented."/"No accessibility notes documented.") for either gap, not
+        // just the second. Never invented content — both messages only ever point the author at
+        // writing their own, real sentence.
+        if (!page.tokenGallery && page.hasWhenToUse === false) {
+            issues.push(issue({
+                id: 'missing-guidance-or-a11y', severity: 'warning', ...ref,
+                message: 'No "whenToUse" guidance documented.',
+                fix: 'Add a one-sentence whenToUse note disambiguating this component from its closest look-alike(s), or omit it only when there genuinely is none.',
+            }));
+        }
+        if (!page.tokenGallery && page.hasA11y === false && !page.hidesAccessibility) {
+            issues.push(issue({
+                id: 'missing-guidance-or-a11y', severity: 'warning', ...ref,
+                message: 'No "a11y" notes documented.',
+                fix: 'Add a one-sentence a11y note, grounded in the component\'s real behavior — even "no explicit handling beyond defaults" is better than leaving it blank.',
+            }));
+        }
+    }
+    return issues;
+}
+/** Every page-scoped issue, from every rule above. */
+export function collectIssues(pages, components) {
+    return [
+        ...checkParseErrors(pages),
+        ...checkNotCheckable(pages),
+        ...checkComponentExportRemoved(pages, components),
+        ...checkComponentNoExamples(pages, components),
+        ...checkDuplicatePageId(pages),
+        ...checkGridAxisKeys(pages),
+        ...checkGridColumnLimit(pages),
+        ...checkComponentPages(pages, components),
+    ];
+}
+/** Issues that aren't tied to one page: `sync`'s own "Could not read" warnings, and a configured
+ *  project with no token modules at all. */
+export function collectGlobalIssues(input) {
+    const issues = input.syncWarnings.map((warning) => issue({ id: 'props-unreadable', severity: 'warning', message: warning, fix: 'Fix the file so sync can read it, or exclude it from the components/tokens globs.' }));
+    if (input.tokenFileCount === 0) {
+        issues.push(issue({ id: 'no-token-modules', severity: 'warning', message: 'No token modules are configured.', fix: 'Add a tokens glob to ds-viewer.config.ts.' }));
+    }
+    return issues;
+}
+/** Design §4's other half of "fails to parse or typecheck" — the half `cli/staticPage.ts` (Task 3)
+ *  deliberately never attempts, since it has no type checker and no module resolution at all.
+ *  This builds exactly one `ts.Program` over every page file, using the identical compiler-host
+ *  construction `cli/props.ts`'s `createComponentReader` already uses for component files (same
+ *  `compilerOptions` shape, same `fallbackPaths` mechanism for a page outside the project root —
+ *  `runDoctor`, Task 5, computes `fallbackPaths` the same way `cli/sync.ts` already does for
+ *  component files), and reports every syntactic *and* semantic diagnostic as `page-parse-error`,
+ *  with a real `line` (unlike every other rule in this file — see this task's own resolved-scope
+ *  note above). Errata (controller, binding): a page that already has a `parseError` from
+ *  `cli/staticPage.ts`'s own syntactic reader is skipped here — its syntax error was already
+ *  reported once by `checkParseErrors`, and this program would otherwise report it again (its own
+ *  syntactic diagnostics are a superset of what `ts.transpileModule` already found). A spike
+ *  against the real kit (`spikes/page-typecheck/` in this plan's spike folder) found exactly one
+ *  real, previously-uncaught diagnostic, fixed in Task 2. */
+export function checkPageTypeErrors(pages, options = {}) {
+    const checkablePages = pages.filter((p) => !p.parseError);
+    const pageFiles = checkablePages.map((p) => p.file);
+    if (pageFiles.length === 0)
+        return [];
+    const byFile = new Map(checkablePages.map((p) => [p.file, p]));
+    // Important finding 2 (Fable's review): the host project's own tsconfig decides every option —
+    // its ambient declarations (expo-env.d.ts's `*.png`/`*.svg` modules, a project's own
+    // declarations.d.ts) and its `strict`/`lib`/etc. settings — not a fixed set copied from
+    // `createComponentReader` (where a mismatch only degrades prop reading silently; here it would
+    // produce CI-failing errors the host's own `tsc` would never raise). Only `noEmit`,
+    // `skipLibCheck`, and the merged `paths` are forced on top.
+    const host = readHostTsconfigOptions(pageFiles[0]);
+    const compilerOptions = {
+        ...host.options,
+        noEmit: true,
+        skipLibCheck: true,
+        paths: { ...options.fallbackPaths, ...host.paths },
+    };
+    const program = ts.createProgram([...pageFiles, ...host.declarationFiles], compilerOptions);
+    const issues = [];
+    for (const file of pageFiles) {
+        const sourceFile = program.getSourceFile(file);
+        if (!sourceFile)
+            continue;
+        const diagnostics = [...program.getSyntacticDiagnostics(sourceFile), ...program.getSemanticDiagnostics(sourceFile)];
+        const page = byFile.get(file);
+        const ref = page ? pageRef(page) : { file };
+        for (const d of diagnostics) {
+            const line = d.start !== undefined ? sourceFile.getLineAndCharacterOfPosition(d.start).line + 1 : undefined;
+            issues.push(issue({
+                id: 'page-parse-error', severity: 'error', ...ref, line,
+                message: `Failed to typecheck: ${ts.flattenDiagnosticMessageText(d.messageText, '\n')}`,
+                fix: 'Fix the error, then rerun doctor.',
+            }));
+        }
+    }
+    return issues;
+}
+/** "With examples" means what `checkComponentNoExamples` (Task 4) checks the *absence* of: at
+ *  least one checkable page with a real example, not merely "has a page" (an `init`-drafted
+ *  "Needs examples" page has one, with none). */
+function countWithExamples(pages, components) {
+    const byComponent = new Map();
+    for (const page of pages) {
+        if (page.component)
+            byComponent.set(page.component, [...(byComponent.get(page.component) ?? []), page]);
+    }
+    return components.filter((c) => (byComponent.get(c.name) ?? []).some((p) => p.checkable && pageHasExamples(p))).length;
+}
+function countUnboundExamples(pages) {
+    let count = 0;
+    for (const page of pages) {
+        if (page.comparison) {
+            if (page.comparison.rows.prop === undefined)
+                count += page.comparison.rows.items.length;
+            if (page.comparison.columns.prop === undefined)
+                count += page.comparison.columns.items.length;
+        }
+        for (const item of [...(page.variantsItems ?? []), ...(page.statesItems ?? [])]) {
+            if (!item.props || Object.keys(item.props).length === 0)
+                count += 1;
+        }
+    }
+    return count;
+}
+/** Runs `sync`, reads every page `cli/staticPage.ts` can find (`discoverAllPageFiles` —
+ *  deliberately wider than the viewer's own page list, so a renamed/removed component's orphaned
+ *  page is still seen), applies the component-folder default (Errata, `applyComponentDefaults`
+ *  above), and applies every rule from Task 4. `config.doctor.strict` promotes every warning to an
+ *  error for both the summary counts and the exit code (design §2 Config: "`strict: true` promotes
+ *  `doctor` warnings to errors"). */
+export function runDoctor(config) {
+    const syncResult = sync(config);
+    const components = JSON.parse(readFileSync(path.join(syncResult.generatedDir, 'components.json'), 'utf8'));
+    // Same exclusion `sync` already applies to `componentEntryFiles` (cli/sync.ts:29-30) — without
+    // it, an excluded folder's own `*.catalog.tsx` is still discovered below (`discoverAllPageFiles`)
+    // even though its component never makes it into `components.json`, firing a false
+    // `component-export-removed`.
+    const excluded = new Set((config.exclude ?? []).flatMap((pattern) => resolveGlob(config.projectRoot, pattern)));
+    const componentFolders = [
+        ...new Set(config.components
+            .flatMap((pattern) => resolveGlob(config.projectRoot, pattern))
+            .filter((file) => !excluded.has(file))
+            .map((file) => path.dirname(file))),
+    ];
+    const tokenFileCount = config.tokens.flatMap((pattern) => resolveGlob(config.projectRoot, pattern)).length;
+    const pageFiles = discoverAllPageFiles({ componentFolders, standalonePageGlobs: config.pages ?? [], projectRoot: config.projectRoot });
+    const pages = applyComponentDefaults(readStaticPages(pageFiles), new Set(componentFolders));
+    // Same "a page outside the project root needs a fallback paths entry" rule `cli/sync.ts` already
+    // applies to component entry files (e.g. `kit-host`'s own component pages, which physically live
+    // in the sibling `../starter-kit/`) — mirrored here for page files, since `checkPageTypeErrors`
+    // below needs it for the identical reason `createComponentReader` does. `@krapwoo/ds-viewer`
+    // itself resolves from `../starter-kit` pages through Node's own self-name resolution (the repo
+    // root `package.json`'s `name` + `exports`), not this fallback — never a `starter-kit/package.json`.
+    const hasPageOutsideProjectRoot = pageFiles.some((file) => !file.startsWith(`${config.projectRoot}${path.sep}`));
+    const fallbackPaths = hasPageOutsideProjectRoot
+        ? { '*': [path.join(config.projectRoot, 'node_modules', '@types', '*'), path.join(config.projectRoot, 'node_modules', '*')] }
+        : undefined;
+    let issues = [
+        ...collectIssues(pages, components),
+        ...checkPageTypeErrors(pages, { fallbackPaths }),
+        ...collectGlobalIssues({ syncWarnings: syncResult.warnings, tokenFileCount }),
+    ];
+    // Design's own `--json` example gives a project-relative `file`; `StaticPage.file` is absolute
+    // (`discoverAllPageFiles`) and `ComponentRecord.file` is cwd-relative (`cli/props.ts`) — cwd
+    // equals `config.projectRoot` for every real CLI invocation, so resolving against one and
+    // re-relativizing against the other normalizes both to the same, documented shape.
+    issues = issues.map((i) => (i.file ? { ...i, file: path.relative(config.projectRoot, path.resolve(config.projectRoot, i.file)) } : i));
+    if (config.doctor?.strict)
+        issues = issues.map((i) => (i.severity === 'warning' ? { ...i, severity: 'error' } : i));
+    const summary = {
+        errors: issues.filter((i) => i.severity === 'error').length,
+        warnings: issues.filter((i) => i.severity === 'warning').length,
+        components: components.length,
+        withExamples: countWithExamples(pages, components),
+        unboundExamples: countUnboundExamples(pages),
+    };
+    return { version: 1, summary, update: null, issues, exitCode: summary.errors > 0 ? 1 : 0 };
+}
+export function toDoctorJson(result) {
+    const { version, summary, update, issues } = result;
+    return { version, summary, update, issues };
+}
+/** Human report (design §4 "Output"): grouped by page, each issue with its one-line fix; issues
+ *  with no `page` (`props-unreadable`, `no-token-modules`) are listed under "General". Ends with
+ *  the same counts `--json`'s `summary` carries. */
+export function formatHuman(result) {
+    const byPage = new Map();
+    const general = [];
+    for (const issue of result.issues) {
+        if (issue.page)
+            byPage.set(issue.page, [...(byPage.get(issue.page) ?? []), issue]);
+        else
+            general.push(issue);
+    }
+    const lines = [];
+    const renderIssue = (issue) => {
+        const location = issue.file ? ` (${issue.file}${issue.line ? `:${issue.line}` : ''})` : '';
+        lines.push(`  [${issue.severity}] ${issue.id}: ${issue.message}${location}`);
+        lines.push(`    Fix: ${issue.fix}`);
+    };
+    for (const [page, issues] of [...byPage].sort(([a], [b]) => a.localeCompare(b))) {
+        lines.push(page);
+        for (const issue of issues)
+            renderIssue(issue);
+        lines.push('');
+    }
+    if (general.length > 0) {
+        lines.push('General');
+        for (const issue of general)
+            renderIssue(issue);
+        lines.push('');
+    }
+    const { errors, warnings, components, withExamples, unboundExamples } = result.summary;
+    lines.push(`${errors} error${errors === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'} — ` +
+        `${components} components (${withExamples} with examples), ${unboundExamples} unbound examples.`);
+    return lines.join('\n');
+}