@krapwoo/ds-viewer 0.1.1 → 0.3.0

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.
@@ -52,7 +53,7 @@ export function createComponentReader(entryFiles, options = {}) {
         allowJs: false,
         noEmit: true,
         baseUrl: host.baseUrl,
-        paths: { ...host.paths, ...options.paths },
+        paths: { ...options.fallbackPaths, ...host.paths, ...options.paths },
         // `pathsBasePath` is @internal: it tells the compiler which folder `paths` are relative to when
         // the host tsconfig has `paths` but no `baseUrl` (the TypeScript 6 idiom).
         ...(host.pathsBasePath ? { pathsBasePath: host.pathsBasePath } : {}),
@@ -156,33 +157,23 @@ function readComponentRecord(checker, name, type, declaration, optionRoots) {
     const propsType = signature && signature.parameters.length > 0 ? checker.getTypeOfSymbolAtLocation(signature.parameters[0], declaration) : undefined;
     const implementationDefaults = defaultsFromImplementation(declaration);
     const props = [];
-    const inheritedFrom = new Set();
     if (propsType) {
         const branches = propsType.isUnion() ? propsType.types : [propsType];
         for (const merged of mergeUnionProps(checker, branches)) {
             const { symbol: prop, declaration: propDeclaration, branchCount } = merged;
             const propFile = propDeclaration?.getSourceFile().fileName ?? '';
-            if (propFile.includes('node_modules')) {
-                // `@types/react` itself (e.g. `ref` from `RefAttributes` on a `forwardRef` component) is
-                // not a meaningful "inherited from" fact — every component already uses React — so it's
-                // dropped rather than reported as "plus all react props". A host-type package's own props
-                // (e.g. react-native's `TextInput`) are still reported as before.
-                if (!/[/\\]@types[/\\]react[/\\]/.test(propFile) || /[/\\]@types[/\\]react-native[/\\]/.test(propFile)) {
-                    inheritedFrom.add(path.basename(path.dirname(propFile)));
-                }
+            // A prop declared in `node_modules` (e.g. `value` from react-native's `TextInputProps`) is
+            // never listed individually — `inheritedFrom` below (design §3) summarises the whole
+            // extended type as one row instead.
+            if (propFile.includes('node_modules'))
                 continue;
-            }
             const propType = propDeclaration ? checker.getTypeOfSymbolAtLocation(prop, propDeclaration) : checker.getAnyType();
-            // Under `strict`, an optional prop's type includes `| undefined` (that's how TypeScript
-            // represents `label?: string` when read via a symbol) — print its non-nullable type instead,
-            // keeping any alias name, so the Props table reads "string" rather than "string | undefined".
-            const displayType = prop.flags & ts.SymbolFlags.Optional ? checker.getNonNullableType(propType) : propType;
             const jsDocDefault = prop.getJsDocTags().find((tag) => tag.name === 'default');
-            const baseDesc = ts.displayPartsToString(prop.getDocumentationComment(checker));
+            const baseDesc = joinWrappedLines(ts.displayPartsToString(prop.getDocumentationComment(checker)));
             const isPartial = branchCount < branches.length;
             props.push({
                 name: prop.getName(),
-                type: checker.typeToString(displayType, undefined, ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope),
+                type: displayTypeString(checker, prop, propType),
                 // A prop present in only some branches is never required overall — the caller can always
                 // pick a branch that omits it — regardless of whether it's required within the branch(es)
                 // it does appear in (that's `merged.requiredInEvery`, checked only when `!isPartial`).
@@ -193,7 +184,165 @@ function readComponentRecord(checker, name, type, declaration, optionRoots) {
             });
         }
     }
-    return { name, file: path.relative(process.cwd(), sourceFile.fileName), props, inheritedFrom: [...inheritedFrom] };
+    const inheritedFrom = propsType ? nodeModulesHeritageNames(checker, propsType.isUnion() ? propsType.types : [propsType]) : [];
+    return { name, file: path.relative(process.cwd(), sourceFile.fileName), props, inheritedFrom };
+}
+/** Design §3 — "Type column: keeps alias names, not expanded unions." An optional prop's type
+ *  (as read via its symbol) includes `undefined` — printed as `"T | undefined"` when `T` has no
+ *  alias of its own (e.g. `label?: string`), but when `T` is itself an alias whose own definition
+ *  already includes `undefined` (react-native's `StyleProp<T>`, React's `ReactNode`), the type as
+ *  declared is simply `T` with no added union member, and `checker.typeToString` already prints
+ *  just the alias name (e.g. `"StyleProp<ViewStyle>"`) — no `| undefined` to strip. Dropping a
+ *  trailing/leading `undefined` segment as *text*, rather than calling `checker.getNonNullableType`
+ *  on the type and re-printing that, is what keeps the alias in both cases: `getNonNullableType`
+ *  rebuilds a fresh, unaliased union once it has to remove a member nested inside an alias's own
+ *  definition (`StyleProp`/`ReactNode`), even though the printed string never needed that member
+ *  removed in the first place. */
+function displayTypeString(checker, prop, propType) {
+    const printed = checker.typeToString(propType, undefined, ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope);
+    if (!(prop.flags & ts.SymbolFlags.Optional))
+        return printed;
+    const kept = splitTopLevelUnion(printed).filter((part) => part !== 'undefined' && part !== 'null');
+    if (kept.length === 0)
+        return printed;
+    // A single remaining part that is itself wrapped in one outer pair of parentheses (e.g. the
+    // `(() => void)` TypeScript prints around an arrow type that was a union member) no longer needs
+    // those parentheses once it is the only part left — `(t: string) => void`, not `((t: string) =>
+    // void)`.
+    if (kept.length === 1)
+        return unwrapOuterParens(kept[0]);
+    return kept.join(' | ');
+}
+/** Splits a printed type's top-level ` | ` union members — skipping any `|` nested inside
+ *  `<...>`, `(...)`, `{...}`, or `[...]` (e.g. the one inside `RecursiveArray<Falsy | ViewStyle>`)
+ *  — so `displayTypeString` can drop a top-level `undefined`/`null` member without disturbing a
+ *  union that appears only as part of a deeper type argument. An arrow type's `=>` prints a `>`
+ *  that is not a closing bracket, so it must not decrement `depth`: skip it whenever the previous
+ *  character was `=` (otherwise `(() => void) | undefined` goes to depth -1 at the arrow and the
+ *  top-level ` | ` before `undefined` is read as nested, never splitting it off). */
+function splitTopLevelUnion(typeString) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < typeString.length; i++) {
+        const ch = typeString[i];
+        if (ch === '<' || ch === '(' || ch === '{' || ch === '[')
+            depth += 1;
+        else if (ch === '>' || ch === ')' || ch === '}' || ch === ']') {
+            if (ch === '>' && typeString[i - 1] === '=')
+                continue;
+            depth -= 1;
+        }
+        else if (depth === 0 && typeString.startsWith(' | ', i)) {
+            parts.push(typeString.slice(start, i));
+            start = i + 3;
+        }
+    }
+    parts.push(typeString.slice(start));
+    return parts;
+}
+/** Strips one outer `(...)` pair from `part` when it wraps the whole string — not just any
+ *  leading `(`, e.g. `(a) => (b)` has balanced outer parens only around `a`, not around the whole
+ *  expression, so this walks depth to confirm the first `(` closes at the very last character. */
+function unwrapOuterParens(part) {
+    if (part[0] !== '(' || part[part.length - 1] !== ')')
+        return part;
+    let depth = 0;
+    for (let i = 0; i < part.length; i++) {
+        const ch = part[i];
+        if (ch === '(')
+            depth += 1;
+        else if (ch === ')') {
+            depth -= 1;
+            if (depth === 0)
+                return i === part.length - 1 ? part.slice(1, -1) : part;
+        }
+    }
+    return part;
+}
+/** Design §3 — "Inherited props declared in `node_modules` ... are summarised as one row: 'plus
+ *  all TextInput props'." Reads each branch's own `extends` heritage clause(s) — not the flattened
+ *  property list `mergeUnionProps` builds for the table above — because a `node_modules` interface
+ *  like react-native's `TextInputProps` itself extends several more `node_modules` interfaces
+ *  (`ViewProps`, `TouchableWithoutFeedbackProps`, ...), each declared in its own file; grouping by
+ *  every inherited *property*'s own declaration file (the previous approach) reported one noisy
+ *  entry per ancestor file instead of the one name the component's own Props type actually names.
+ *  A `forwardRef` component's props type is `OwnProps & RefAttributes<T>` (an intersection, not an
+ *  interface) — `heritageInterfaceDeclarations` unwraps that to reach `OwnProps`'s own declaration. */
+function nodeModulesHeritageNames(checker, branches) {
+    const names = new Set();
+    for (const branch of branches) {
+        for (const declaration of heritageInterfaceDeclarations(branch)) {
+            const declarationFile = declaration.getSourceFile().fileName;
+            if (declarationFile.includes('node_modules')) {
+                // `declaration` was pulled in directly by the branch itself (e.g. `type Props =
+                // TextInputProps & {...}`), not named in a *local* interface's own `extends` clause —
+                // report its own name. Walking its `heritageClauses` below (as the `extends
+                // TextInputProps` case does) would instead report TextInputProps's own ancestors, e.g.
+                // "View"/"TouchableWithoutFeedback".
+                if (!isReactOnlyFile(declarationFile))
+                    names.add(declaration.name.getText().replace(/Props$/, ''));
+                continue;
+            }
+            for (const clause of declaration.heritageClauses ?? []) {
+                for (const typeNode of clause.types) {
+                    // `getTypeAtLocation` on the whole `ExpressionWithTypeArguments` node (not just its
+                    // `.expression`) is required for `resolveUtilityTypeSource` below to see `Omit`/`Pick`'s
+                    // actual instantiated type arguments — on `.expression` alone they come back as the
+                    // utility type's own unbound generic parameters ("T", "K"), not `TextInputProps`.
+                    const heritageType = resolveUtilityTypeSource(checker.getTypeAtLocation(typeNode));
+                    const heritageDeclaration = (heritageType.aliasSymbol ?? heritageType.symbol)?.declarations?.[0];
+                    if (!heritageDeclaration)
+                        continue;
+                    const file = heritageDeclaration.getSourceFile().fileName;
+                    if (!file.includes('node_modules'))
+                        continue;
+                    // `@types/react` itself (e.g. `Attributes`, reached through a `forwardRef` component's
+                    // own `RefAttributes<T>`) is not a meaningful "inherited from" fact — every component
+                    // already uses React. A host-type package's own heritage (e.g. react-native's `View`,
+                    // reached through `TextInputProps`) is still reported as before.
+                    if (isReactOnlyFile(file))
+                        continue;
+                    const rawName = (heritageType.aliasSymbol ?? heritageType.symbol)?.getName() ?? typeNode.expression.getText();
+                    names.add(rawName.replace(/Props$/, ''));
+                }
+            }
+        }
+    }
+    return [...names];
+}
+/** True for a declaration file under `@types/react` that is not also under `@types/react-native`
+ *  (react-native's own `@types` package path contains `react` as a substring). */
+function isReactOnlyFile(file) {
+    return /[/\\]@types[/\\]react[/\\]/.test(file) && !/[/\\]@types[/\\]react-native[/\\]/.test(file);
+}
+/** `Omit<T, K>`/`Pick<T, K>` of a node_modules type prints its own alias symbol ("Omit"/"Pick")
+ *  rather than `T`'s name — resolve to `T` (the type's first alias type argument) instead, so
+ *  `extends Omit<TextInputProps, 'value'>` reports "TextInput", not "Omit" (Fable's review,
+ *  cli/props.ts:270-301). */
+function resolveUtilityTypeSource(type) {
+    const aliasName = type.aliasSymbol?.getName();
+    if ((aliasName === 'Omit' || aliasName === 'Pick') && type.aliasTypeArguments?.[0]) {
+        return type.aliasTypeArguments[0];
+    }
+    return type;
+}
+/** Every `InterfaceDeclaration` backing `type` — itself if `type` is one, or (recursing) each
+ *  constituent of an intersection, so a `forwardRef` component's `OwnProps & RefAttributes<T>`
+ *  still reaches `OwnProps`'s own heritage clause. */
+function heritageInterfaceDeclarations(type) {
+    if (type.isIntersection())
+        return type.types.flatMap(heritageInterfaceDeclarations);
+    return (type.symbol?.declarations ?? []).filter(ts.isInterfaceDeclaration);
+}
+/** Design §3, finding 4: a JSDoc paragraph hard-wrapped in source (`getDocumentationComment`
+ *  preserves each line break verbatim) must read as running text — join lines within a paragraph
+ *  with a single space, but keep a blank-line paragraph break as its own line break. */
+function joinWrappedLines(text) {
+    return text
+        .split(/\n{2,}/)
+        .map((paragraph) => paragraph.replace(/\s*\n\s*/g, ' ').trim())
+        .join('\n\n');
 }
 /**
  * Design §3 — "Unions of object types (e.g. `CardProps` as two intersections) are merged into one

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

@@ -33,12 +33,31 @@ export function sync(config, resolveOptions) {
     const components = [];
     const componentRefs = [];
     const seenNames = new Set();
-    const readComponent = createComponentReader(componentEntryFiles, { ...resolveOptions, optionRoots });
+    // A component entry file can live outside `config.projectRoot` (e.g. kit-host's sibling
+    // `../starter-kit/`) — `createComponentReader`'s own host-tsconfig lookup walks up from the
+    // entry file, never reaching `config.projectRoot`'s own node_modules. This fallback (lowest
+    // priority — a real host `paths`, or `resolveOptions.paths`, still wins) is what lets such a
+    // file still resolve `react`/`react-native` against the project that actually declares them.
+    // `@types/*` is listed BEFORE the plain package deliberately (confirmed by spike,
+    // `spikes/README.md` "sync-fallback-paths"): once `paths` redirects a bare specifier to an
+    // on-disk folder, TypeScript resolves it there and never falls through to a second entry just
+    // because the first has no types — the reverse order left `react`/`react-native` both
+    // resolving to "implicitly any", because the plain package folder matched first. Only computed
+    // when at least one entry file actually lies outside `config.projectRoot` — normal projects
+    // (every entry file under projectRoot) keep standard TypeScript resolution untouched.
+    const hasEntryOutsideProjectRoot = componentEntryFiles.some((file) => !file.startsWith(`${config.projectRoot}${path.sep}`));
+    const fallbackPaths = hasEntryOutsideProjectRoot
+        ? { '*': [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);
@@ -46,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));
@@ -57,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 };
 }