@krapwoo/ds-viewer 0.2.0 → 0.4.0

package/dist/cli/migrations/index.js

@@ -0,0 +1,14 @@
+// cli/migrations/index.ts
+import { compareVersions, parseVersion } from "../semver.js";
+/** The real, production migration registry. Empty in 0.4 — design §5 "Versioning": "From 0.4,
+ *  every breaking change ships an automatic migration" describes the *mechanism* this plan builds,
+ *  not a requirement to invent a breaking change 0.4 does not have. The framework itself is proven
+ *  by a test-only fixture migration (`cli/__tests__/migrate.test.ts`) that is never added here. */
+export const MIGRATIONS = [];
+/** Every migration after `fromVersion`, oldest first. */
+export function migrationsAfter(fromVersion) {
+    const from = parseVersion(fromVersion);
+    return MIGRATIONS
+        .filter((migration) => compareVersions(parseVersion(migration.version), from) > 0)
+        .sort((a, b) => compareVersions(parseVersion(a.version), parseVersion(b.version)));
+}

package/dist/cli/migrations/types.js

@@ -0,0 +1,9 @@
+// cli/migrations/types.ts
+//
+// This file, and every file `cli/migrateEntry.ts` transitively imports through `Migration` values
+// placed in `cli/migrations/index.ts` (`migrate.ts`, `migrations/index.ts`, `semver.ts`), must
+// never import the `typescript` npm package (directly or transitively) — `migrateEntry.ts` is the
+// one thing this plan runs from inside an `npm pack`-extracted tarball that has no `node_modules`
+// of its own, and `typescript` is a real `dependencies` entry (Task 9's own `buildUpdatePlan`,
+// spiked for real in `spikes/migrate-entry/`).
+export {};

package/dist/cli/packageManager.js

@@ -0,0 +1,29 @@
+// cli/packageManager.ts
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+/** The same lockfile-sniffing `cli/githubAction.ts`'s own `installStep` already did inline (0.3)
+ *  — promoted here so `cli/update.ts` (Task 10) can detect the same thing without duplicating it.
+ *  A v1 yarn.lock's own first line is always exactly `# yarn lockfile v1`; anything else (Berry's
+ *  own header/`__metadata`) is Berry. */
+export function detectPackageManager(projectRoot) {
+    if (existsSync(path.join(projectRoot, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    const yarnLockPath = path.join(projectRoot, 'yarn.lock');
+    if (existsSync(yarnLockPath)) {
+        const firstLine = readFileSync(yarnLockPath, 'utf8').split('\n', 1)[0];
+        return firstLine === '# yarn lockfile v1' ? 'yarn-classic' : 'yarn-berry';
+    }
+    return 'npm'; // package-lock.json, or no lockfile at all (npm's own documented default either way).
+}
+/** The one command `cli/update.ts`'s "Upgrades with the project's package manager" step (design
+ *  §5 "`npx ds-viewer update`" step 3) runs, for whichever manager `detectPackageManager` found.
+ *  Yarn (classic and Berry both) use the same `yarn add --dev` syntax for upgrading a single
+ *  package to an exact version. */
+export function installUpgradeCommand(pm, pkg, version) {
+    const spec = `${pkg}@${version}`;
+    if (pm === 'npm')
+        return { command: 'npm', args: ['install', '--save-dev', spec] };
+    if (pm === 'pnpm')
+        return { command: 'pnpm', args: ['add', '--save-dev', spec] };
+    return { command: 'yarn', args: ['add', '--dev', spec] };
+}

package/dist/cli/packageVersion.js

@@ -0,0 +1,24 @@
+// cli/packageVersion.ts
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+/** Walks up from `startDir` looking for the `package.json` named `@krapwoo/ds-viewer` — needed
+ *  because this file sits one level under the repo root as `cli/packageVersion.ts` (how tests and
+ *  `init`/`main` run it from source) but two levels under it once compiled, as
+ *  `dist/cli/packageVersion.js`. Throws when it reaches the filesystem root without finding one,
+ *  which should never happen for a real install (`readOwnVersion` is only ever called from code
+ *  that is itself inside the installed/running package). */
+export function readOwnVersion(startDir) {
+    let dir = startDir;
+    while (true) {
+        const candidate = path.join(dir, 'package.json');
+        if (existsSync(candidate)) {
+            const pkg = JSON.parse(readFileSync(candidate, 'utf8'));
+            if (pkg.name === '@krapwoo/ds-viewer' && pkg.version)
+                return pkg.version;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            throw new Error("Could not find @krapwoo/ds-viewer's own package.json to read its version.");
+        dir = parent;
+    }
+}

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.

package/dist/cli/semver.js

@@ -0,0 +1,26 @@
+// cli/semver.ts
+const VERSION_RE = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/;
+export function parseVersion(raw) {
+    const match = VERSION_RE.exec(raw.trim());
+    if (!match)
+        throw new Error(`Not a version: "${raw}"`);
+    const [, major, minor, patch, prerelease] = match;
+    return { major: Number(major), minor: Number(minor), patch: Number(patch), prerelease };
+}
+/** -1 when `a` is older than `b`, 1 when newer, 0 when equal — prerelease tags are ignored for
+ *  ordering (this package only ever compares a real installed version against a real registry
+ *  "latest", which is never a prerelease; the throwaway spike tag above is test-only). */
+export function compareVersions(a, b) {
+    for (const key of ['major', 'minor', 'patch']) {
+        if (a[key] !== b[key])
+            return a[key] < b[key] ? -1 : 1;
+    }
+    return 0;
+}
+/** Design §5 "Releasing" — "From 1.0, breaking changes only in major versions"; before that, this
+ *  plan still needs one consistent rule to decide the banner vs. the quiet footer line (design
+ *  §5 "Viewer notice"), and a major-version bump is the only rule that needs no per-release
+ *  judgment call. */
+export function isBreakingUpgrade(current, latest) {
+    return latest.major > current.major;
+}

package/dist/cli/staticPage.js

@@ -0,0 +1,356 @@
+import * as ts from 'typescript';
+import { readFileSync } from 'node:fs';
+const TRANSPILE_OPTIONS = {
+    compilerOptions: { jsx: ts.JsxEmit.ReactJSX, module: ts.ModuleKind.ESNext, target: ts.ScriptTarget.ES2022 },
+    reportDiagnostics: true,
+};
+/** Reads every page file's literal-checkable fields (design §4 "Static checking"). Never imports
+ *  the file and never builds a `ts.Program` across files — no module resolution happens at all, so
+ *  this cannot fail because of an unresolved import, a missing `node_modules`, or a stale type.
+ *  One broken file never stops the rest (Global Constraints, Error-handling rule): each file is
+ *  read independently. */
+export function readStaticPages(pageFiles) {
+    // Error-handling rule (design, Global Constraints): one broken file never stops the rest of a
+    // read. `readStaticPage` already guards its own `readFileSync` call, but an unexpected throw
+    // from deeper in its AST walk (e.g. a pathological same-file `const` chain overflowing the call
+    // stack) must be caught per file too, not just per-read, or it aborts every other page in the
+    // same `doctor`/`explain` run.
+    return pageFiles.map((file) => {
+        try {
+            return readStaticPage(file);
+        }
+        catch (error) {
+            return { file, checkable: false, parseError: error.message };
+        }
+    });
+}
+function readStaticPage(file) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        return { file, checkable: false, parseError: error.message };
+    }
+    // `transpileModule` parses a single file with no module resolution at all — its `diagnostics`
+    // are syntactic only (it never type-checks), which is exactly "fails to parse" (design §4's
+    // error rule) and nothing more; a semantic/type error in a page file is out of this reader's
+    // scope (it never had enough information — no resolved `node_modules` — to find one anyway).
+    const { diagnostics } = ts.transpileModule(text, TRANSPILE_OPTIONS);
+    if (diagnostics && diagnostics.length > 0) {
+        return { file, checkable: false, parseError: ts.flattenDiagnosticMessageText(diagnostics[0].messageText, '\n') };
+    }
+    const sourceFile = ts.createSourceFile(file, text, ts.ScriptTarget.ES2022, true, ts.ScriptKind.TSX);
+    const imports = importedNames(sourceFile, '@krapwoo/ds-viewer');
+    const defineCatalogPageNames = localNamesFor(imports, 'defineCatalogPage');
+    const gridNames = localNamesFor(imports, 'grid');
+    const call = defaultExportCall(sourceFile);
+    if (!call || !ts.isIdentifier(call.expression) || !defineCatalogPageNames.has(call.expression.text) || call.arguments.length !== 1) {
+        // Not a recognized `defineCatalogPage(...)` default export — e.g. a hand-written object, or a
+        // shadowed/renamed import this reader can't trace. Not a parse error: the file is valid
+        // TypeScript, just not literal-checkable.
+        return { file, checkable: false };
+    }
+    const consts = topLevelConsts(sourceFile);
+    const pageObject = resolve(call.arguments[0], consts, new Set());
+    if (!ts.isObjectLiteralExpression(pageObject))
+        return { file, checkable: false };
+    const page = { file, checkable: true };
+    const idProp = findProp(pageObject, 'id');
+    const componentProp = findProp(pageObject, 'component');
+    const groupProp = findProp(pageObject, 'group');
+    const specimenSizeProp = findProp(pageObject, 'specimenSize');
+    const tokenGalleryProp = findProp(pageObject, 'tokenGallery');
+    if (idProp)
+        page.id = stringLiteral(resolve(idProp.initializer, consts, new Set()));
+    if (componentProp)
+        page.component = stringLiteral(resolve(componentProp.initializer, consts, new Set()));
+    if (groupProp)
+        page.group = stringLiteral(resolve(groupProp.initializer, consts, new Set()));
+    if (specimenSizeProp)
+        page.specimenSize = stringLiteral(resolve(specimenSizeProp.initializer, consts, new Set()));
+    if (tokenGalleryProp)
+        page.tokenGallery = resolve(tokenGalleryProp.initializer, consts, new Set()).kind === ts.SyntaxKind.TrueKeyword;
+    page.hasWhenToUse = findProp(pageObject, 'whenToUse') !== undefined;
+    page.hasA11y = findProp(pageObject, 'a11y') !== undefined;
+    page.hasRender = findProp(pageObject, 'render') !== undefined;
+    const hideProp = findProp(pageObject, 'hide');
+    if (hideProp) {
+        const hideObject = resolve(hideProp.initializer, consts, new Set());
+        const literalBool = (name) => {
+            const prop = ts.isObjectLiteralExpression(hideObject) ? findProp(hideObject, name) : undefined;
+            return prop ? resolve(prop.initializer, consts, new Set()).kind === ts.SyntaxKind.TrueKeyword : false;
+        };
+        page.hidesAccessibility = literalBool('accessibility');
+        page.hideVariants = literalBool('variants');
+        page.hideStates = literalBool('states');
+    }
+    const previewWidthsProp = findProp(pageObject, 'previewWidths');
+    if (previewWidthsProp) {
+        const resolved = resolve(previewWidthsProp.initializer, consts, new Set());
+        if (ts.isStringLiteral(resolved) && resolved.text === 'full') {
+            page.previewWidths = 'full';
+        }
+        else if (ts.isArrayLiteralExpression(resolved) && resolved.elements.every(ts.isNumericLiteral)) {
+            page.previewWidths = resolved.elements.map((element) => Number(element.text));
+        }
+        // Anything else (a function call, a non-literal expression) is simply left unset — `previewWidths`
+        // isn't in design §4's literal-checkable list, so it's never a reason to flip `checkable`.
+    }
+    const fullWidthLabelProp = findProp(pageObject, 'fullWidthLabel');
+    if (fullWidthLabelProp)
+        page.fullWidthLabel = stringLiteral(resolve(fullWidthLabelProp.initializer, consts, new Set()));
+    const propNotesProp = findProp(pageObject, 'propNotes');
+    if (propNotesProp) {
+        const resolved = resolve(propNotesProp.initializer, consts, new Set());
+        if (ts.isObjectLiteralExpression(resolved)) {
+            page.propNoteKeys = resolved.properties.filter(ts.isPropertyAssignment).map((p) => propertyName(p.name));
+        }
+        else {
+            page.checkable = false;
+        }
+    }
+    const comparisonProp = findProp(pageObject, 'comparison');
+    if (comparisonProp) {
+        const comparison = readComparison(comparisonProp.initializer, consts, gridNames);
+        if (comparison)
+            page.comparison = comparison;
+        else
+            page.checkable = false;
+    }
+    const variants = readSlotItems(findProp(pageObject, 'variants'), consts);
+    if (!variants.checkable)
+        page.checkable = false;
+    else {
+        page.variantsItems = variants.items;
+        page.variantsItemsFill = variants.itemsFill;
+    }
+    const states = readSlotItems(findProp(pageObject, 'states'), consts);
+    if (!states.checkable)
+        page.checkable = false;
+    else {
+        page.statesItems = states.items;
+        page.statesItemsFill = states.itemsFill;
+    }
+    return page;
+}
+/** Local name -> imported name, for every named import from `moduleSpecifier`. */
+function importedNames(sourceFile, moduleSpecifier) {
+    const names = new Map();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== moduleSpecifier) {
+            continue;
+        }
+        const bindings = statement.importClause?.namedBindings;
+        if (!bindings || !ts.isNamedImports(bindings))
+            continue;
+        for (const element of bindings.elements) {
+            names.set(element.name.text, element.propertyName ? element.propertyName.text : element.name.text);
+        }
+    }
+    return names;
+}
+function localNamesFor(imports, importedName) {
+    const locals = new Set();
+    for (const [local, imported] of imports)
+        if (imported === importedName)
+            locals.add(local);
+    return locals;
+}
+function defaultExportCall(sourceFile) {
+    for (const statement of sourceFile.statements) {
+        if (ts.isExportAssignment(statement) && !statement.isExportEquals && ts.isCallExpression(statement.expression)) {
+            return statement.expression;
+        }
+    }
+    return undefined;
+}
+function topLevelConsts(sourceFile) {
+    const consts = new Map();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (ts.isIdentifier(declaration.name) && declaration.initializer)
+                consts.set(declaration.name.text, declaration.initializer);
+        }
+    }
+    return consts;
+}
+/** Unwraps `as`/parenthesized/`satisfies` expressions and chases a same-file top-level `const`
+ *  reference to its own initializer (same pattern as `cli/tokens.ts`'s `readExpression`) — returns
+ *  the resolved expression node itself, not a value, so callers can pattern-match on its kind
+ *  (array/object literal, call expression, …). `seen` guards a reference cycle. */
+function resolve(node, consts, seen) {
+    if (ts.isAsExpression(node) || ts.isParenthesizedExpression(node) || ts.isSatisfiesExpression(node)) {
+        return resolve(node.expression, consts, seen);
+    }
+    if (ts.isIdentifier(node) && !seen.has(node.text)) {
+        const target = consts.get(node.text);
+        if (target)
+            return resolve(target, consts, new Set(seen).add(node.text));
+    }
+    return node;
+}
+function stringLiteral(node) {
+    return ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node) ? node.text : undefined;
+}
+function propertyName(name) {
+    return ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : name.getText();
+}
+function findProp(obj, name) {
+    const prop = obj.properties.find((p) => ts.isPropertyAssignment(p) && propertyName(p.name) === name);
+    return prop;
+}
+function propertyStringLiteral(obj, name, consts) {
+    const prop = findProp(obj, name);
+    return prop ? stringLiteral(resolve(prop.initializer, consts, new Set())) : undefined;
+}
+/** A literal array of `{ key, label }` object literals — each element may itself be a same-file
+ *  const reference. Undefined (not literal) for anything else: a `.map()`/other call, a spread, a
+ *  cross-file import. */
+function readAxisItemArray(node, consts) {
+    const resolved = resolve(node, consts, new Set());
+    if (!ts.isArrayLiteralExpression(resolved))
+        return undefined;
+    const items = [];
+    for (const element of resolved.elements) {
+        const resolvedElement = resolve(element, consts, new Set());
+        if (!ts.isObjectLiteralExpression(resolvedElement))
+            return undefined;
+        const key = propertyStringLiteral(resolvedElement, 'key', consts);
+        const label = propertyStringLiteral(resolvedElement, 'label', consts);
+        if (key === undefined || label === undefined)
+            return undefined;
+        items.push({ key, label });
+    }
+    return items;
+}
+/** A `GridAxis` (design §4): a plain literal array, or `{ prop, items }` (`items` itself read by
+ *  `readAxisItemArray`). Undefined for anything else. */
+function readAxis(node, consts) {
+    const resolved = resolve(node, consts, new Set());
+    if (ts.isArrayLiteralExpression(resolved)) {
+        const items = readAxisItemArray(resolved, consts);
+        return items ? { items } : undefined;
+    }
+    if (ts.isObjectLiteralExpression(resolved)) {
+        const propProp = findProp(resolved, 'prop');
+        const itemsProp = findProp(resolved, 'items');
+        if (!propProp || !itemsProp)
+            return undefined;
+        const prop = stringLiteral(resolve(propProp.initializer, consts, new Set()));
+        const items = readAxisItemArray(itemsProp.initializer, consts);
+        if (prop === undefined || !items)
+            return undefined;
+        return { prop, items };
+    }
+    return undefined;
+}
+/** A page's `comparison` field: either a direct `ComparisonDef`-shaped object literal, or (the
+ *  starter kit's own convention since Task 1/2) a call to this package's own `grid()` helper — the
+ *  one call shape this reader specially recognizes, reading its `rows`/`columns` arguments and
+ *  skipping its `cell` argument entirely (design §4: "Specimen nodes and `cell(...)` functions are
+ *  not evaluated"). `gridNames` is the set of local identifiers that import resolved to `grid` from
+ *  `@krapwoo/ds-viewer` — a page's own unrelated local function named `grid` is never matched. */
+function readComparison(node, consts, gridNames) {
+    const resolved = resolve(node, consts, new Set());
+    if (ts.isCallExpression(resolved) && ts.isIdentifier(resolved.expression) && gridNames.has(resolved.expression.text)) {
+        const [rowLabelArg, columnLabelArg, rowsArg, columnsArg, , sizeArg] = resolved.arguments;
+        const rows = rowsArg && readAxis(rowsArg, consts);
+        const columns = columnsArg && readAxis(columnsArg, consts);
+        if (!rows || !columns)
+            return undefined;
+        return {
+            rowLabel: rowLabelArg ? stringLiteral(resolve(rowLabelArg, consts, new Set())) : undefined,
+            columnLabel: columnLabelArg ? stringLiteral(resolve(columnLabelArg, consts, new Set())) : undefined,
+            rows,
+            columns,
+            size: sizeArg ? stringLiteral(resolve(sizeArg, consts, new Set())) : undefined,
+        };
+    }
+    if (ts.isObjectLiteralExpression(resolved)) {
+        const rowsProp = findProp(resolved, 'rows');
+        const columnsProp = findProp(resolved, 'columns');
+        if (!rowsProp || !columnsProp)
+            return undefined;
+        const rows = readAxis(rowsProp.initializer, consts);
+        const columns = readAxis(columnsProp.initializer, consts);
+        if (!rows || !columns)
+            return undefined;
+        const rowLabelProp = findProp(resolved, 'rowLabel');
+        const columnLabelProp = findProp(resolved, 'columnLabel');
+        const sizeProp = findProp(resolved, 'size');
+        return {
+            rowLabel: rowLabelProp ? stringLiteral(resolve(rowLabelProp.initializer, consts, new Set())) : undefined,
+            columnLabel: columnLabelProp ? stringLiteral(resolve(columnLabelProp.initializer, consts, new Set())) : undefined,
+            rows,
+            columns,
+            size: sizeProp ? stringLiteral(resolve(sizeProp.initializer, consts, new Set())) : undefined,
+        };
+    }
+    return undefined;
+}
+/** A literal array of list-item object literals — `key`/`name` required; `props` (read as a flat
+ *  literal map, non-literal values simply omitted) and `group` optional. Each item's `node` field
+ *  (always present, always JSX) is never inspected — reading the sibling fields never depends on it. */
+function readListItems(node, consts) {
+    const resolved = resolve(node, consts, new Set());
+    if (!ts.isArrayLiteralExpression(resolved))
+        return undefined;
+    const items = [];
+    for (const element of resolved.elements) {
+        const resolvedElement = resolve(element, consts, new Set());
+        if (!ts.isObjectLiteralExpression(resolvedElement))
+            return undefined;
+        const key = propertyStringLiteral(resolvedElement, 'key', consts);
+        const name = propertyStringLiteral(resolvedElement, 'name', consts);
+        if (key === undefined || name === undefined)
+            return undefined;
+        const group = propertyStringLiteral(resolvedElement, 'group', consts);
+        const propsProp = findProp(resolvedElement, 'props');
+        items.push({ key, name, group, props: propsProp ? readLiteralProps(propsProp.initializer, consts) : undefined });
+    }
+    return items;
+}
+function readLiteralProps(node, consts) {
+    const resolved = resolve(node, consts, new Set());
+    if (!ts.isObjectLiteralExpression(resolved))
+        return undefined;
+    const result = {};
+    for (const property of resolved.properties) {
+        if (!ts.isPropertyAssignment(property))
+            continue;
+        const value = resolve(property.initializer, consts, new Set());
+        if (ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value))
+            result[propertyName(property.name)] = value.text;
+        else if (ts.isNumericLiteral(value))
+            result[propertyName(property.name)] = Number(value.text);
+        else if (value.kind === ts.SyntaxKind.TrueKeyword)
+            result[propertyName(property.name)] = true;
+        else if (value.kind === ts.SyntaxKind.FalseKeyword)
+            result[propertyName(property.name)] = false;
+        // Anything else (e.g. a token reference) is skipped, not a reason to reject the whole item —
+        // `props` tags are only ever compared against a prop's string options (design §4).
+    }
+    return result;
+}
+/** A `variants`/`states` field: `{ itemsFill?, items: [...] }`, `items` read by `readListItems`.
+ *  Distinguishes "field absent" (always checkable, everything undefined) from "field present but
+ *  not literal" (not checkable). `itemsFill` is read only if present and literal — like
+ *  `previewWidths`/`fullWidthLabel`, it isn't in design §4's literal-checkable list, so a
+ *  non-literal `itemsFill` is simply left unset, never a reason to reject the whole slot. */
+function readSlotItems(prop, consts) {
+    if (!prop)
+        return { checkable: true };
+    const resolved = resolve(prop.initializer, consts, new Set());
+    const itemsProp = ts.isObjectLiteralExpression(resolved) ? findProp(resolved, 'items') : undefined;
+    if (!itemsProp)
+        return { checkable: false };
+    const items = readListItems(itemsProp.initializer, consts);
+    if (!items)
+        return { checkable: false };
+    const itemsFillProp = ts.isObjectLiteralExpression(resolved) ? findProp(resolved, 'itemsFill') : undefined;
+    const itemsFill = itemsFillProp ? resolve(itemsFillProp.initializer, consts, new Set()).kind === ts.SyntaxKind.TrueKeyword : undefined;
+    return { items, itemsFill, checkable: true };
+}

package/dist/cli/sync.js

@@ -50,11 +50,14 @@ export function sync(config, resolveOptions) {
         ? { '*': [path.join(config.projectRoot, 'node_modules', '@types', '*'), path.join(config.projectRoot, 'node_modules', '*')] }
         : undefined;
     const readComponent = createComponentReader(componentEntryFiles, { ...resolveOptions, optionRoots, fallbackPaths });
+    const warnings = [];
     for (const entryFile of componentEntryFiles) {
         try {
             for (const record of readComponent(entryFile)) {
                 if (seenNames.has(record.name)) {
-                    console.warn(`Duplicate component name "${record.name}" (${path.relative(config.projectRoot, entryFile)}); the catalog will show only one.`);
+                    const message = `Duplicate component name "${record.name}" (${path.relative(config.projectRoot, entryFile)}); the catalog will show only one.`;
+                    console.warn(message);
+                    warnings.push(message);
                 }
                 seenNames.add(record.name);
                 components.push(record);
@@ -62,7 +65,9 @@ export function sync(config, resolveOptions) {
             }
         }
         catch (error) {
-            console.warn(`Could not read ${path.relative(config.projectRoot, entryFile)}: ${error.message}`);
+            const message = `Could not read ${path.relative(config.projectRoot, entryFile)}: ${error.message}`;
+            console.warn(message);
+            warnings.push(message);
         }
     }
     components.sort((a, b) => a.name.localeCompare(b.name));
@@ -73,12 +78,14 @@ export function sync(config, resolveOptions) {
             tokenRecords.push(...readTokenModules([tokenFile]));
         }
         catch (error) {
-            console.warn(`Could not read ${path.relative(config.projectRoot, tokenFile)}: ${error.message}`);
+            const message = `Could not read ${path.relative(config.projectRoot, tokenFile)}: ${error.message}`;
+            console.warn(message);
+            warnings.push(message);
         }
     }
     writeFileSync(path.join(generatedDir, 'tokens.json'), `${JSON.stringify(tokenRecords, null, 2)}\n`);
     writeFileSync(path.join(generatedDir, 'index.ts'), GENERATED_INDEX);
     const pageFiles = discoverPages({ components: componentRefs, standalonePageGlobs: config.pages ?? [], projectRoot: config.projectRoot });
     writePageIndex(generatedDir, pageFiles);
-    return { componentCount: components.length, pageCount: pageFiles.length, generatedDir };
+    return { componentCount: components.length, pageCount: pageFiles.length, generatedDir, warnings };
 }