@krapwoo/ds-viewer 0.2.0 → 0.3.0

package/dist/cli/explain.js

@@ -0,0 +1,151 @@
+import path from 'node:path';
+import { readStaticPages } from "./staticPage.js";
+import { discoverAllPageFiles, resolvePageId } from "./pageIndex.js";
+import { resolveGlob } from "./glob.js";
+import { axisItems, choosePlacement, gridColumnLimit, listGeometry, presentationBlocks, MATRIX_LAYOUT, } from "../native/catalog/comparison.js";
+import { CATALOG_LAYOUT } from "../native/catalog/tokens.js";
+function placeholderItem(item) {
+    return { key: item.key, name: item.name, node: null, group: item.group };
+}
+/** A throwaway `SectionDef` built from a `StaticPage` (Task 3) — every specimen's `node` is `null`
+ *  (design §4: specimen nodes are never evaluated), since none of the layout functions below ever
+ *  look at it; only the counts/keys/sizes they do look at are carried over. Every field Task 3
+ *  reads is carried through here, including `previewWidths`/`fullWidthLabel`/`hide`/`itemsFill` —
+ *  an earlier draft dropped these four, so `explain` reported different geometry than the real
+ *  viewer for any page that set one of them (25 kit pages set `itemsFill`; every `kit-host`
+ *  Viewer page sets `hide`). */
+function toSectionDef(page) {
+    const comparison = page.comparison && {
+        rowLabel: page.comparison.rowLabel ?? '',
+        columnLabel: page.comparison.columnLabel ?? '',
+        rows: page.comparison.rows.prop !== undefined ? { prop: page.comparison.rows.prop, items: page.comparison.rows.items } : page.comparison.rows.items,
+        columns: page.comparison.columns.prop !== undefined ? { prop: page.comparison.columns.prop, items: page.comparison.columns.items } : page.comparison.columns.items,
+        cells: [],
+        size: page.comparison.size,
+    };
+    return {
+        id: resolvePageId(page, page.file),
+        description: '',
+        path: page.file,
+        tokenGallery: page.tokenGallery,
+        fullWidthLabel: page.fullWidthLabel,
+        specimenSize: page.specimenSize,
+        previewWidths: page.previewWidths,
+        variants: page.variantsItems ? { itemsFill: page.variantsItemsFill, items: page.variantsItems.map(placeholderItem) } : undefined,
+        states: page.statesItems ? { itemsFill: page.statesItemsFill, items: page.statesItems.map(placeholderItem) } : undefined,
+        comparison,
+        render: page.hasRender ? () => null : undefined,
+        hide: (page.hideVariants || page.hideStates) ? { variants: page.hideVariants, states: page.hideStates } : undefined,
+    };
+}
+function explainBlock(block) {
+    if (block.kind === 'grid') {
+        const rows = axisItems(block.comparison.rows).length;
+        const columns = axisItems(block.comparison.columns).length;
+        const limit = gridColumnLimit(block.size);
+        return {
+            kind: 'grid', title: block.title,
+            reason: `${rows} rows × ${columns} columns (${block.size}); ${columns} of ${limit} max ${block.size} columns used — ` +
+                `${columns <= limit ? 'fits' : 'does NOT fit'} a 1280px laptop.`,
+        };
+    }
+    if (block.kind === 'list') {
+        const geometry = listGeometry(block.items.length, MATRIX_LAYOUT.laptopContentWidth, block.size);
+        return {
+            kind: 'list', title: block.title,
+            reason: `${block.items.length} items (${block.size}) → ${geometry.columns} columns × ${geometry.rows} row${geometry.rows === 1 ? '' : 's'}` +
+                (geometry.fillers > 0 ? ` (${geometry.fillers} filler${geometry.fillers === 1 ? '' : 's'})` : '') + '.',
+        };
+    }
+    if (block.kind === 'grouped') {
+        return { kind: 'grouped', title: block.title, reason: `${block.groups.length} variant row(s), each with its own configurations.` };
+    }
+    if (block.kind === 'preview') {
+        const widths = block.widths === 'full' ? 'full width' : `${block.widths.join('/')}px`;
+        return { kind: 'preview', title: block.title, reason: `render() content at ${widths}.` };
+    }
+    return { kind: 'empty', title: block.title, reason: block.message };
+}
+/** Mirrors `native/catalog/SectionBlock.tsx`'s own `blockWidth` helper: a list block's width is its
+ *  own natural, content-hugging width (`listGeometry`'s `containerWidth`) — the real viewer only
+ *  ever moves a *second* block beside a *first* one when that first block doesn't already fill the
+ *  whole row, so `choosePlacement` only reads `first.width` (never `second.width`) — but it's
+ *  computed uniformly here for either role, since setting it on `second` is simply unused, not wrong. */
+function toPlacementBlock(block, height, available) {
+    if (block.kind === 'list') {
+        return { kind: 'list', height, itemCount: block.items.length, size: block.size, width: listGeometry(block.items.length, available, block.size).containerWidth };
+    }
+    return { kind: block.kind, height };
+}
+/** Finds `pageId` among every page `cli/doctor.ts`'s own `discoverAllPageFiles` would find, builds
+ *  its throwaway `SectionDef`, and asks the viewer's own pure layout functions for each block's
+ *  decision — undefined when no page resolves to that id. */
+export function explainPage(config, pageId, options = {}) {
+    // Same exclusion `cli/doctor.ts`'s `runDoctor` applies (mirroring `sync`) — an excluded folder's
+    // page should never resolve here either.
+    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 pageFiles = discoverAllPageFiles({ componentFolders, standalonePageGlobs: config.pages ?? [], projectRoot: config.projectRoot });
+    const page = readStaticPages(pageFiles).find((p) => resolvePageId(p, p.file) === pageId);
+    if (!page)
+        return undefined;
+    // Important finding 4 (Fable's review): a page whose layout data isn't a literal (or that has a
+    // syntax error) must never be explained from partial/empty data — design §4 requires `explain`
+    // to never drift from what the viewer actually renders.
+    if (!page.checkable)
+        return { pageId, notCheckable: true, blocks: [] };
+    const def = toSectionDef(page);
+    const blocks = presentationBlocks(def, { defaultPreviewWidths: [402] });
+    const explained = blocks.map(explainBlock);
+    let placement;
+    if (blocks.length === 2) {
+        if (options.heights) {
+            const [firstHeight, secondHeight] = options.heights;
+            const decision = choosePlacement({
+                available: MATRIX_LAYOUT.laptopContentWidth,
+                gap: CATALOG_LAYOUT.blockGap,
+                first: toPlacementBlock(blocks[0], firstHeight, MATRIX_LAYOUT.laptopContentWidth),
+                second: toPlacementBlock(blocks[1], secondHeight, MATRIX_LAYOUT.laptopContentWidth),
+            });
+            placement = {
+                decision,
+                reason: `With heights ${firstHeight}px/${secondHeight}px on a 1280px laptop (${MATRIX_LAYOUT.laptopContentWidth}px content width): ${decision}.`,
+            };
+        }
+        else {
+            placement = {
+                decision: 'decided-in-viewer',
+                reason: "Side-by-side placement depends on each block's measured height — decided in the viewer at runtime. Pass --heights <first>,<second> to check it here.",
+            };
+        }
+    }
+    return { pageId, blocks: explained, placement };
+}
+export function formatExplain(result) {
+    if (result.notCheckable) {
+        return `${result.pageId}\n\nPage not statically checkable — some of its layout data is not a literal doctor can read.`;
+    }
+    const lines = [result.pageId, ''];
+    for (const block of result.blocks) {
+        lines.push(block.title);
+        lines.push(`  ${block.reason}`);
+        lines.push('');
+    }
+    if (result.placement) {
+        lines.push('Placement');
+        lines.push(`  ${result.placement.reason}`);
+    }
+    return lines.join('\n').replace(/\n+$/, '');
+}
+/** `"80,300"` → `[80, 300]`; undefined for anything else (not exactly two positive numbers). */
+export function parseHeights(raw) {
+    const parts = raw.split(',').map((part) => Number(part.trim()));
+    if (parts.length !== 2 || parts.some((n) => !Number.isFinite(n) || n <= 0))
+        return undefined;
+    return [parts[0], parts[1]];
+}

package/dist/cli/githubAction.js

@@ -0,0 +1,68 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+// Design §4 "GitHub Action" + §5's lockfile-detection assumption. `checkout`/`setup-node` pins
+// reused verbatim from this repository's own `.github/workflows/ci.yml` (Global Constraints);
+// `pnpm/action-setup` is the one new SHA this plan resolves (`gh api
+// repos/pnpm/action-setup/git/refs/tags/v6.1.0`, dereferenced to its commit). `node-version: '20'`
+// matches the package's own published `engines` floor (`>=20.19.0`): a user's project only ever
+// runs the compiled `dist/cli/main.js` via `npx ds-viewer`, which needs no type-stripping (unlike
+// this repo's own CI, which type-strips its *source* and therefore needs Node 22).
+// Errata #5: `pnpm/action-setup` needs an explicit pnpm version — it has no lockfile to infer one
+// from. Read the project's own `packageManager` field (`"pnpm@9.1.0"`) when present; otherwise
+// default to 10, matching the pin's own major version line.
+function pnpmVersion(projectRoot) {
+    const packageJsonPath = path.join(projectRoot, 'package.json');
+    if (!existsSync(packageJsonPath))
+        return '10';
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    const match = packageJson.packageManager?.match(/^pnpm@(\d+)/);
+    return match ? match[1] : '10';
+}
+// Important finding 6 (Fable's review): Yarn 1 (still the common Expo lockfile) has no
+// `--immutable` flag — its equivalent is `--frozen-lockfile`. Yarn Berry needs `corepack enable`
+// first, since `actions/setup-node` ships Yarn 1 on `ubuntu-latest`. A v1 lockfile's own first line
+// is always exactly `# yarn lockfile v1`; anything else (Berry's own header/`__metadata`) is Berry.
+function yarnInstallStep(projectRoot) {
+    const firstLine = readFileSync(path.join(projectRoot, 'yarn.lock'), 'utf8').split('\n', 1)[0];
+    if (firstLine === '# yarn lockfile v1')
+        return '      - run: yarn install --frozen-lockfile\n';
+    return '      - run: corepack enable\n      - run: yarn install --immutable\n';
+}
+function installStep(projectRoot) {
+    if (existsSync(path.join(projectRoot, 'pnpm-lock.yaml'))) {
+        return `      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0\n        with:\n          version: ${pnpmVersion(projectRoot)}\n      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0\n        with:\n          node-version: '20'\n      - run: pnpm install --frozen-lockfile\n`;
+    }
+    const setupNode = `      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0\n        with:\n          node-version: '20'\n`;
+    if (existsSync(path.join(projectRoot, 'yarn.lock')))
+        return `${setupNode}${yarnInstallStep(projectRoot)}`;
+    // `package-lock.json`, or no lockfile at all (a fresh project before its first commit) — `npm
+    // ci` is npm's own documented behavior for the latter: it installs from `package.json` and
+    // writes a fresh lockfile, exactly like a plain `npm install` would.
+    return `${setupNode}      - run: npm ci\n`;
+}
+function workflowContent(projectRoot) {
+    return `name: DS Viewer
+
+on:
+  pull_request:
+
+jobs:
+  doctor:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+${installStep(projectRoot)}      - run: npx ds-viewer doctor --ci
+`;
+}
+/** Design §4 "GitHub Action", §1 Ownership: written once, never overwritten — a user's own edits
+ *  to this file (or a differently-named workflow they wrote instead) are never touched again. The
+ *  install step is picked from whichever lockfile is present *right now*, at `init` time — never
+ *  re-picked later, since this function never runs again once the file exists. */
+export function ensureGithubAction(projectRoot) {
+    const workflowPath = path.join(projectRoot, '.github', 'workflows', 'ds-viewer.yml');
+    if (existsSync(workflowPath))
+        return [];
+    mkdirSync(path.dirname(workflowPath), { recursive: true });
+    writeFileSync(workflowPath, workflowContent(projectRoot));
+    return [workflowPath];
+}

package/dist/cli/init.js

@@ -4,6 +4,8 @@ import { createInterface } from 'node:readline/promises';
 import { execFileSync } from 'node:child_process';
 import { preflight } from "./preflight.js";
 import { detectComponentFolders, detectTokenFiles } from "./detect.js";
+import { ensureAgentsFileSection } from "./agentsFile.js";
+import { ensureGithubAction } from "./githubAction.js";
 async function promptConfirm(message) {
     // A closed, non-interactive stdin (CI, piped npx) would reject `question` with an AbortError;
     // say how to proceed instead.
@@ -104,8 +106,8 @@ export async function initExistingProject(projectRoot, options = {}) {
     return { messages, written };
 }
 /** Design §2, "Both paths then write what is missing": `ds-viewer.config.ts` is written by each
- *  path separately (its contents differ), but the package script, the devDependency entry, and the
- *  `.gitignore` entry are identical either way. */
+ *  path separately (its contents differ), but the package script, the devDependency entry, the
+ *  `.gitignore` entry, and (from 0.3) the `AGENTS.md` section are identical either way. */
 function ensureSharedProjectFiles(projectRoot) {
     const written = [];
     const packageJsonPath = path.join(projectRoot, 'package.json');
@@ -134,6 +136,8 @@ function ensureSharedProjectFiles(projectRoot) {
         writeFileSync(gitignorePath, `${existingGitignore}${separator}${gitignoreEntry}\n`);
         written.push(gitignorePath);
     }
+    written.push(...ensureAgentsFileSection(projectRoot));
+    written.push(...ensureGithubAction(projectRoot));
     return written;
 }
 const KIT_REQUIRED_PACKAGES = ['react-native-svg', 'react-native-safe-area-context'];

package/dist/cli/main.js

@@ -6,6 +6,8 @@ import { resolveConfig } from "./config.js";
 import { initExistingProject, initNewProject, promptInitMode } from "./init.js";
 import { dev } from "./dev.js";
 import { sync } from "./sync.js";
+import { formatHuman, runDoctor, toDoctorJson } from "./doctor.js";
+import { explainPage, formatExplain, parseHeights } from "./explain.js";
 const USAGE = `Usage: ds-viewer <command>
 
 Commands:
@@ -16,6 +18,13 @@ Commands:
            --yes           accept the detected components and tokens without asking (--existing only)
   sync     Regenerate the component, props, token, and page data from source
   dev      Sync, then serve the catalog on a local web address and keep it current as files change
+  doctor   Check every page for drift and coverage gaps
+           --json          print the machine-readable report instead
+           --ci            exit 1 when any error was found (never on a warning alone)
+  explain <Page>
+           Print why a page's specimens are laid out the way they are
+           --heights <first>,<second>  check side-by-side placement with these measured heights
+           --json          print the machine-readable report instead
 
 Options:
   -h, --help     Show this help
@@ -95,6 +104,31 @@ export async function runInit(projectRoot, rest, options = {}) {
         ? initNewProject(projectRoot, { kitRoot, installer: options.installer })
         : initExistingProject(projectRoot, { yes: rest.includes('--yes'), confirm: options.confirm });
 }
+/** Pulled out of `main()` for the same reason `runInit` was in 0.1/0.2 (Fable's review): testable
+ *  without spawning a process. `--ci`'s exit code is read from `runDoctor`'s own `exitCode` — a
+ *  plain `doctor` (no `--ci`) always returns 0 here regardless of errors found. */
+export function runDoctorCommand(projectRoot, rest) {
+    const config = resolveConfig(projectRoot);
+    const result = runDoctor(config);
+    const output = rest.includes('--json') ? JSON.stringify(toDoctorJson(result), null, 2) : formatHuman(result);
+    return { output, exitCode: rest.includes('--ci') ? result.exitCode : 0 };
+}
+/** Same "testable without spawning" shape as `runDoctorCommand` above. */
+export function runExplainCommand(projectRoot, pageId, rest) {
+    if (!pageId)
+        return { output: 'Usage: ds-viewer explain <Page> [--heights <first>,<second>] [--json]', exitCode: 1 };
+    const heightsIndex = rest.indexOf('--heights');
+    const heightsRaw = heightsIndex !== -1 ? rest[heightsIndex + 1] : undefined;
+    const heights = heightsRaw ? parseHeights(heightsRaw) : undefined;
+    if (heightsRaw && !heights) {
+        return { output: `--heights must be two comma-separated numbers, e.g. --heights 420,610 (got "${heightsRaw}")`, exitCode: 1 };
+    }
+    const config = resolveConfig(projectRoot);
+    const result = explainPage(config, pageId, { heights });
+    if (!result)
+        return { output: `No page named "${pageId}" was found.`, exitCode: 1 };
+    return { output: rest.includes('--json') ? JSON.stringify(result, null, 2) : formatExplain(result), exitCode: 0 };
+}
 async function main() {
     const [command, ...rest] = process.argv.slice(2);
     const projectRoot = process.cwd();
@@ -122,6 +156,21 @@ async function main() {
         console.log(`Synced ${result.componentCount} components, ${result.pageCount} pages.`);
         return;
     }
+    if (command === 'doctor') {
+        const { output, exitCode } = runDoctorCommand(projectRoot, rest);
+        console.log(output);
+        if (exitCode)
+            process.exitCode = exitCode;
+        return;
+    }
+    if (command === 'explain') {
+        const [pageId, ...explainRest] = rest;
+        const { output, exitCode } = runExplainCommand(projectRoot, pageId, explainRest);
+        console.log(output);
+        if (exitCode)
+            process.exitCode = exitCode;
+        return;
+    }
     if (command === 'dev') {
         const config = resolveConfig(projectRoot);
         await dev(config);

package/dist/cli/pageIndex.js

@@ -1,4 +1,4 @@
-import { existsSync, writeFileSync } from 'node:fs';
+import { existsSync, readdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { resolveGlob } from "./glob.js";
 /** Component pages: `<Export>.catalog.tsx` beside the component's entry file (design §2). A
@@ -10,6 +10,25 @@ export function discoverPages(input) {
     const standalonePages = input.standalonePageGlobs.flatMap((pattern) => resolveGlob(input.projectRoot, pattern));
     return [...componentPages, ...standalonePages].sort();
 }
+/** Every `*.catalog.tsx`/`.catalog.ts` file `doctor` should read — unlike `discoverPages`, this
+ *  also finds a page beside a component whose folder still exists but whose export was renamed or
+ *  removed (that page's file never changed, so it's still sitting right there). `componentFolders`
+ *  is every distinct folder containing a currently-resolved component entry file — `cli/doctor.ts`
+ *  derives it the same way `cli/sync.ts` does, by resolving `config.components` and taking each
+ *  match's `path.dirname`. A folder that was deleted entirely (not just renamed within) has nothing
+ *  left to find here, which is correct: there's no stale page file left on disk to warn about. */
+export function discoverAllPageFiles(input) {
+    const componentPages = input.componentFolders.flatMap((folder) => {
+        try {
+            return readdirSync(folder).filter((name) => /\.catalog\.tsx?$/.test(name)).map((name) => path.join(folder, name));
+        }
+        catch {
+            return [];
+        }
+    });
+    const standalonePages = input.standalonePageGlobs.flatMap((pattern) => resolveGlob(input.projectRoot, pattern));
+    return [...new Set([...componentPages, ...standalonePages])].sort();
+}
 /** Writes `.ds-viewer/generated/pages.ts`: imports every discovered page's default export,
  *  resolves each one's id (design §2 "Page id": `id ?? component ?? <file stem>` — a component
  *  page defaults to its export name, a standalone page to its own file's stem) and `file` (the
@@ -25,6 +44,13 @@ export function writePageIndex(generatedDir, pageFiles) {
     writeFileSync(outFile, `${importLines.join('\n')}\n\n${resolveLines.join('\n')}\n\n${exportLine}\n`);
     return outFile;
 }
+/** `page.id ?? page.component ?? <file's own stem>` (design §2 "Page id") — factored out of
+ *  `writePageIndex`'s own inline logic above so `cli/doctor.ts` resolves a page's id exactly the
+ *  same way, never a second, drifting copy of this rule. Takes the same two fields `StaticPage`
+ *  (Task 3) and the generated page index both already carry. */
+export function resolvePageId(page, file) {
+    return page.id ?? page.component ?? fileStem(file);
+}
 function toImportPath(fromDir, toFile) {
     const withoutExt = toFile.replace(/\.tsx?$/, '');
     const relativePath = path.relative(fromDir, withoutExt).split(path.sep).join('/');

package/dist/cli/props.js

@@ -11,15 +11,16 @@ const COMPONENT_TYPE_HINT = /MemoExoticComponent|ForwardRefExoticComponent|Named
  *  fixtures have no tsconfig of their own, so lookup reaches this repository's root
  *  `tsconfig.json` (Task 1); it declares no `paths`, `baseUrl`, or `jsx`, so `options.paths`
  *  alone decides resolution in tests. */
-function readHostTsconfigOptions(entryFile) {
+export function readHostTsconfigOptions(entryFile) {
     const tsconfigPath = ts.findConfigFile(path.dirname(entryFile), ts.sys.fileExists);
     if (!tsconfigPath)
-        return {};
+        return { options: {}, declarationFiles: [] };
     const { config } = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
     const parsed = ts.parseJsonConfigFileContent(config, ts.sys, path.dirname(tsconfigPath));
     const { baseUrl, paths, jsx } = parsed.options;
     const pathsBasePath = parsed.options.pathsBasePath;
-    return { baseUrl, paths, jsx, pathsBasePath };
+    const declarationFiles = parsed.fileNames.filter((file) => file.endsWith('.d.ts'));
+    return { baseUrl, paths, jsx, pathsBasePath, options: parsed.options, declarationFiles };
 }
 /** What is a component (design §3): an export whose type has a call signature returning
  *  JSX/ReactNode, or is typed as a Memo/ForwardRef/NamedExotic/ComponentType wrapper.