@krapwoo/ds-viewer 0.2.0 → 0.3.0

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 };
 }