@invariant-ui/cli 0.0.0-stage → 0.2.0

package/dist/compiler-storybook/csf.js

@@ -0,0 +1,521 @@
+import { collapse, componentNameFromFile, declarationOf, evaluate, isProjectNode, jsxTargetDeclaration, lineOf, posix, relativeFileOf, resolveSymbol, topLevelAssignments, unwrap } from "../compiler-core/index.js";
+import ts from "typescript";
+const MAX_CALLS = 50;
+/** Statically reads a Component Story Format file (CSF 2 and 3). Nothing is executed. */
+export function extractCsf(analysis, sf) {
+    const { checker } = analysis;
+    const file = relativeFileOf(analysis, sf);
+    const moduleSymbol = checker.getSymbolAtLocation(sf);
+    if (!file || !moduleSymbol)
+        return undefined;
+    const exports = checker.getExportsOfModule(moduleSymbol);
+    const defaultExport = exports.find((e) => e.name === "default");
+    const meta = defaultExport ? findMeta(analysis, defaultExport) : undefined;
+    const group = meta ? readGroup(analysis, file, meta) : undefined;
+    const selection = meta ? readStorySelection(meta.object) : { uncertain: false };
+    const assignments = topLevelAssignments(sf);
+    const stories = [];
+    const excluded = [];
+    for (const exported of exports) {
+        if (exported.name === "default" || exported.name === "__namedExportsOrder")
+            continue;
+        if (!(exported.flags & ts.SymbolFlags.Value) && !(exported.flags & ts.SymbolFlags.Alias))
+            continue;
+        const resolved = resolveSymbol(checker, exported);
+        const decl = declarationOf(resolved);
+        if (!decl || !isProjectNode(analysis, decl))
+            continue;
+        if (!isSelected(exported.name, selection)) {
+            excluded.push(exported.name);
+            continue;
+        }
+        const story = readStory(analysis, exported.name, decl, assignments);
+        if (story)
+            stories.push(story);
+    }
+    stories.sort((a, b) => a.line - b.line || (a.exportName < b.exportName ? -1 : 1));
+    return {
+        file,
+        ...(group ? { group } : {}),
+        stories,
+        excluded: excluded.sort(),
+        selectionUncertain: selection.uncertain
+    };
+}
+function findMeta(analysis, symbol) {
+    const { checker } = analysis;
+    const decl = declarationOf(symbol);
+    if (!decl)
+        return undefined;
+    let expression;
+    if (ts.isExportAssignment(decl))
+        expression = decl.expression;
+    else if (ts.isVariableDeclaration(decl))
+        expression = decl.initializer;
+    let typeArgument;
+    let current = expression;
+    for (let hops = 0; current && hops < 8; hops++) {
+        if (ts.isParenthesizedExpression(current) || ts.isNonNullExpression(current))
+            current = current.expression;
+        else if (ts.isAsExpression(current) || ts.isSatisfiesExpression(current)) {
+            typeArgument ??= metaTypeArgument(current.type);
+            current = current.expression;
+        }
+        else if (ts.isIdentifier(current)) {
+            const target = declarationOf(resolveSymbol(checker, checker.getSymbolAtLocation(current)));
+            if (!target || !ts.isVariableDeclaration(target) || !target.initializer)
+                return undefined;
+            typeArgument ??= target.type ? metaTypeArgument(target.type) : undefined;
+            current = target.initializer;
+        }
+        else
+            break;
+    }
+    if (!current || !ts.isObjectLiteralExpression(current))
+        return undefined;
+    return { object: current, ...(typeArgument ? { typeArgument } : {}), node: current };
+}
+/** `typeof Button` from `Meta<typeof Button>`. */
+function metaTypeArgument(type) {
+    if (ts.isTypeReferenceNode(type) && type.typeArguments?.[0] && ts.isTypeQueryNode(type.typeArguments[0]))
+        return type.typeArguments[0];
+    return undefined;
+}
+function readGroup(analysis, file, meta) {
+    const { checker } = analysis;
+    const props = objectProperties(meta.object);
+    const title = props.get("title");
+    const component = props.get("component");
+    let target;
+    let componentNode;
+    if (component && ts.isPropertyAssignment(component)) {
+        componentNode = component;
+        target = resolveTarget(analysis, component.initializer, "component");
+    }
+    else if (meta.typeArgument && ts.isTypeQueryNode(meta.typeArgument)) {
+        componentNode = meta.typeArgument;
+        target = resolveTarget(analysis, meta.typeArgument.exprName, "type-argument");
+    }
+    return {
+        file,
+        line: lineOf(meta.node),
+        node: meta.node,
+        ...(title && ts.isPropertyAssignment(title) && ts.isStringLiteralLike(unwrap(title.initializer))
+            ? { title: unwrap(title.initializer).text }
+            : {}),
+        ...(target ? { component: target } : {}),
+        ...(componentNode ? { componentNode } : {}),
+        ...annotations(checker, props)
+    };
+}
+function readStory(analysis, exportName, decl, assignments) {
+    const { checker } = analysis;
+    let shape;
+    let object;
+    let localName;
+    let renderNode;
+    if (ts.isVariableDeclaration(decl) && ts.isIdentifier(decl.name) && decl.initializer) {
+        localName = decl.name.text;
+        const init = unwrap(decl.initializer);
+        if (ts.isObjectLiteralExpression(init)) {
+            shape = "object";
+            object = init;
+        }
+        else if (ts.isArrowFunction(init) || ts.isFunctionExpression(init)) {
+            shape = "function";
+            renderNode = init;
+        }
+        else if (ts.isCallExpression(init) &&
+            ts.isPropertyAccessExpression(init.expression) &&
+            init.expression.name.text === "bind") {
+            shape = "template";
+            renderNode = init;
+        }
+    }
+    else if (ts.isFunctionDeclaration(decl) && decl.name) {
+        localName = decl.name.text;
+        shape = "function";
+        renderNode = decl;
+    }
+    if (!shape)
+        return undefined;
+    const props = object ? objectProperties(object) : new Map();
+    // CSF 2 style annotations: `Story.args = {…}`, `Story.storyName = "…"`, `Story.play = …`.
+    const assigned = (key) => localName ? assignments.get(`${localName}.${key}`) : undefined;
+    const synthetic = new Map(props);
+    for (const key of [
+        "args",
+        "argTypes",
+        "parameters",
+        "tags",
+        "decorators",
+        "loaders",
+        "play",
+        "render",
+        "name",
+        "storyName"
+    ]) {
+        const expr = assigned(key);
+        if (expr && !synthetic.has(key))
+            synthetic.set(key, fakeAssignment(key, expr));
+    }
+    const nameProp = synthetic.get("name") ?? synthetic.get("storyName");
+    const nameExpr = nameProp && ts.isPropertyAssignment(nameProp) ? unwrap(nameProp.initializer) : undefined;
+    const play = synthetic.get("play");
+    const playExpr = play && ts.isPropertyAssignment(play)
+        ? unwrap(play.initializer)
+        : play && ts.isMethodDeclaration(play)
+            ? play
+            : undefined;
+    const annotated = annotations(checker, synthetic);
+    const symbol = ts.isVariableDeclaration(decl) || ts.isFunctionDeclaration(decl)
+        ? checker.getSymbolAtLocation(decl.name)
+        : undefined;
+    const doc = symbol ? ts.displayPartsToString(symbol.getDocumentationComment(checker)).trim() : "";
+    const description = annotated.parameters.docsDescription?.story ?? (doc || undefined);
+    return {
+        exportName,
+        line: lineOf(decl),
+        node: decl,
+        shape,
+        ...(nameExpr && ts.isStringLiteralLike(nameExpr) ? { name: nameExpr.text } : {}),
+        ...(description ? { description } : {}),
+        ...(playExpr ? { play: inspectPlay(playExpr) } : {}),
+        hasRender: synthetic.has("render") || shape !== "object",
+        composes: composedComponents(analysis, object ?? renderNode ?? decl),
+        ...annotated
+    };
+}
+/** Collects Annotations from a property map (object literal members, or CSF 2 assignments). */
+function annotations(checker, props) {
+    const expressionOf = (key) => {
+        const p = props.get(key);
+        return p && ts.isPropertyAssignment(p) ? p.initializer : undefined;
+    };
+    const argsExpr = expressionOf("args");
+    const args = argsExpr ? evaluate(checker, argsExpr) : { unresolved: [], spies: [] };
+    const argNodes = new Map();
+    const argsObject = argsExpr ? unwrap(argsExpr) : undefined;
+    if (argsObject && ts.isObjectLiteralExpression(argsObject)) {
+        for (const [k, p] of objectProperties(argsObject))
+            argNodes.set(k, p);
+    }
+    const argTypesExpr = expressionOf("argTypes");
+    const argTypesEval = argTypesExpr ? evaluate(checker, argTypesExpr) : { unresolved: [], spies: [] };
+    const argTypeNodes = new Map();
+    const argTypesObject = argTypesExpr ? unwrap(argTypesExpr) : undefined;
+    if (argTypesObject && ts.isObjectLiteralExpression(argTypesObject)) {
+        for (const [k, p] of objectProperties(argTypesObject))
+            argTypeNodes.set(k, p);
+    }
+    const parametersExpr = expressionOf("parameters");
+    const parametersEval = parametersExpr ? evaluate(checker, parametersExpr) : { unresolved: [], spies: [] };
+    const tagsExpr = expressionOf("tags");
+    const tagsEval = tagsExpr ? evaluate(checker, tagsExpr) : undefined;
+    return {
+        args,
+        argNodes,
+        ...(argsExpr ? { argsNode: argsExpr } : {}),
+        argTypes: readArgTypes(argTypesEval, syntacticMappingKeys(argTypeNodes)),
+        argTypeNodes,
+        argTypesUnresolved: argTypesEval.unresolved,
+        parameters: readParameters(parametersEval),
+        parametersUnresolved: parametersEval.unresolved,
+        ...(Array.isArray(tagsEval?.value) && tagsEval.value.every((t) => typeof t === "string")
+            ? { tags: tagsEval.value }
+            : {}),
+        hasDecorators: props.has("decorators"),
+        hasLoaders: props.has("loaders"),
+        nodes: {
+            ...(evidenceNode(props.get("parameters"))
+                ? { parameters: evidenceNode(props.get("parameters")) }
+                : {}),
+            ...(evidenceNode(props.get("tags")) ? { tags: evidenceNode(props.get("tags")) } : {}),
+            ...(evidenceNode(props.get("decorators"))
+                ? { decorators: evidenceNode(props.get("decorators")) }
+                : {}),
+            ...(evidenceNode(props.get("loaders"))
+                ? { loaders: evidenceNode(props.get("loaders")) }
+                : {})
+        }
+    };
+}
+function readArgTypes(evaluated, mappingKeys) {
+    const out = {};
+    const root = evaluated.value;
+    if (root === null || typeof root !== "object" || Array.isArray(root))
+        return out;
+    for (const [prop, raw] of Object.entries(root)) {
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+            out[prop] = {};
+            continue;
+        }
+        const info = {};
+        const control = raw.control;
+        if (typeof control === "string" || control === false)
+            info.control = control;
+        else if (control &&
+            typeof control === "object" &&
+            !Array.isArray(control) &&
+            typeof control.type === "string")
+            info.control = control.type;
+        if (Array.isArray(raw.options) &&
+            raw.options.every((o) => ["string", "number", "boolean"].includes(typeof o)))
+            info.options = raw.options;
+        if (evaluated.unresolved.some((p) => p === `${prop}.options` || p.startsWith(`${prop}.options.`)) ||
+            (control &&
+                typeof control === "object" &&
+                evaluated.unresolved.some((p) => p.startsWith(`${prop}.control.options`))))
+            info.optionsUnresolved = true;
+        if (typeof raw.description === "string")
+            info.description = raw.description;
+        const table = raw.table;
+        if (table && typeof table === "object" && !Array.isArray(table)) {
+            const dv = table.defaultValue;
+            if (dv && typeof dv === "object" && !Array.isArray(dv) && typeof dv.summary === "string")
+                info.defaultSummary = dv.summary;
+            if (table.disable === true)
+                info.hidden = true;
+            if (typeof table.category === "string")
+                info.category = table.category;
+        }
+        // Mapping keys come from the syntax: a key whose value is JSX or `undefined` is still a key.
+        const syntactic = mappingKeys.get(prop);
+        if (syntactic)
+            info.mappingKeys = syntactic;
+        else if (raw.mapping && typeof raw.mapping === "object" && !Array.isArray(raw.mapping))
+            info.mappingKeys = Object.keys(raw.mapping).sort();
+        else if (evaluated.unresolved.some((p) => p === `${prop}.mapping`))
+            info.mappingKeys = [];
+        if (typeof raw.action === "string")
+            info.action = raw.action;
+        out[prop] = info;
+    }
+    return out;
+}
+function syntacticMappingKeys(argTypeNodes) {
+    const out = new Map();
+    for (const [prop, node] of argTypeNodes) {
+        if (!ts.isPropertyAssignment(node))
+            continue;
+        const argType = unwrap(node.initializer);
+        if (!ts.isObjectLiteralExpression(argType))
+            continue;
+        const mapping = objectProperties(argType).get("mapping");
+        const object = mapping && ts.isPropertyAssignment(mapping) ? unwrap(mapping.initializer) : undefined;
+        if (object && ts.isObjectLiteralExpression(object))
+            out.set(prop, [...objectProperties(object).keys()].sort());
+    }
+    return out;
+}
+function readParameters(evaluated) {
+    const root = evaluated.value;
+    if (root === null || typeof root !== "object" || Array.isArray(root))
+        return { keys: [] };
+    const info = { keys: Object.keys(root).sort() };
+    if (root.a11y !== undefined)
+        info.a11y = root.a11y;
+    if (typeof root.layout === "string")
+        info.layout = root.layout;
+    if (root.controls !== undefined)
+        info.controls = root.controls;
+    const docs = root.docs;
+    if (docs && typeof docs === "object" && !Array.isArray(docs)) {
+        const d = docs.description;
+        if (d && typeof d === "object" && !Array.isArray(d)) {
+            info.docsDescription = {
+                ...(typeof d.component === "string" ? { component: d.component } : {}),
+                ...(typeof d.story === "string" ? { story: d.story } : {})
+            };
+        }
+    }
+    return info;
+}
+function readStorySelection(object) {
+    const props = objectProperties(object);
+    const read = (key) => {
+        const p = props.get(key);
+        if (!p || !ts.isPropertyAssignment(p))
+            return { uncertain: false };
+        const matcher = toMatcher(unwrap(p.initializer));
+        return matcher ? { matcher, uncertain: false } : { uncertain: true };
+    };
+    const include = read("includeStories");
+    const exclude = read("excludeStories");
+    return {
+        ...(include.matcher ? { include: include.matcher } : {}),
+        ...(exclude.matcher ? { exclude: exclude.matcher } : {}),
+        uncertain: include.uncertain || exclude.uncertain
+    };
+}
+function toMatcher(node) {
+    if (ts.isRegularExpressionLiteral(node)) {
+        const body = node.text.slice(1, node.text.lastIndexOf("/"));
+        const flags = node.text.slice(node.text.lastIndexOf("/") + 1);
+        try {
+            const re = new RegExp(body, flags);
+            return (name) => re.test(name);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (ts.isStringLiteralLike(node))
+        return (name) => name === node.text;
+    if (ts.isArrayLiteralExpression(node)) {
+        const parts = node.elements.map((e) => toMatcher(unwrap(e)));
+        return parts.every((p) => p !== undefined) ? (name) => parts.some((p) => p(name)) : undefined;
+    }
+    return undefined;
+}
+function isSelected(name, selection) {
+    if (selection.include && !selection.include(name))
+        return false;
+    if (selection.exclude?.(name))
+        return false;
+    return true;
+}
+function resolveTarget(analysis, node, via) {
+    const { checker } = analysis;
+    const text = collapse(node.getText());
+    const symbolNode = ts.isIdentifier(node) || ts.isPropertyAccessExpression(node) || ts.isQualifiedName(node)
+        ? node
+        : undefined;
+    const decl = symbolNode && !ts.isQualifiedName(symbolNode)
+        ? jsxTargetDeclaration(checker, symbolNode)
+        : undefinedDeclaration(checker, node);
+    if (decl && isProjectNode(analysis, decl)) {
+        const name = declarationName(decl);
+        const file = relativeFileOf(analysis, decl);
+        if (file && name)
+            return { file, name, text, via };
+    }
+    const importSpecifier = importOf(checker, node);
+    if (importSpecifier?.startsWith(".")) {
+        // Single-file components (`./Button.vue`) are not TypeScript modules, so they are linked by file
+        // and the PascalCase component name, the same key the Vue adapter publishes.
+        const from = relativeFileOf(analysis, node);
+        const resolved = from ? posix.normalize(posix.join(posix.dirname(from), importSpecifier)) : undefined;
+        if (resolved?.endsWith(".vue") && analysis.hasFile(resolved))
+            return { file: resolved, name: componentNameFromFile(resolved), text, via };
+    }
+    if (importSpecifier) {
+        return importSpecifier.startsWith(".")
+            ? { text, via, unresolvedModule: importSpecifier }
+            : { text, via, external: importSpecifier };
+    }
+    return { text, via };
+}
+function undefinedDeclaration(checker, node) {
+    const symbol = checker.getSymbolAtLocation(node);
+    return declarationOf(resolveSymbol(checker, symbol));
+}
+/** Module specifier of the import that brought the leftmost identifier of `node` into scope. */
+function importOf(checker, node) {
+    let root = node;
+    while (ts.isPropertyAccessExpression(root))
+        root = root.expression;
+    while (ts.isQualifiedName(root))
+        root = root.left;
+    const symbol = checker.getSymbolAtLocation(root);
+    const decl = symbol?.declarations?.[0];
+    let cursor = decl;
+    while (cursor && !ts.isImportDeclaration(cursor))
+        cursor = cursor.parent;
+    return cursor && ts.isImportDeclaration(cursor) && ts.isStringLiteral(cursor.moduleSpecifier)
+        ? cursor.moduleSpecifier.text
+        : undefined;
+}
+function declarationName(decl) {
+    const named = decl;
+    if (named.name && ts.isIdentifier(named.name))
+        return named.name.text;
+    if (ts.isExportAssignment(decl)) {
+        const base = posix.basename(decl.getSourceFile().fileName).replace(/\.[^.]+$/, "");
+        return base.charAt(0).toUpperCase() + base.slice(1);
+    }
+    return undefined;
+}
+function composedComponents(analysis, root) {
+    const { checker } = analysis;
+    const counts = new Map();
+    const visit = (n) => {
+        if (ts.isJsxSelfClosingElement(n) || ts.isJsxOpeningElement(n)) {
+            const tag = n.tagName;
+            if (!(ts.isIdentifier(tag) && /^[a-z]/.test(tag.text))) {
+                const decl = jsxTargetDeclaration(checker, tag);
+                if (decl && isProjectNode(analysis, decl)) {
+                    const file = relativeFileOf(analysis, decl);
+                    const name = declarationName(decl);
+                    if (file && name) {
+                        const key = `${file}#${name}`;
+                        const entry = counts.get(key) ?? { file, name, count: 0 };
+                        entry.count++;
+                        counts.set(key, entry);
+                    }
+                }
+            }
+        }
+        ts.forEachChild(n, visit);
+    };
+    visit(root);
+    return [...counts.values()].sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : a.name < b.name ? -1 : 1);
+}
+function inspectPlay(node) {
+    const calls = new Set();
+    const steps = [];
+    const visit = (n) => {
+        if (ts.isCallExpression(n)) {
+            const callee = calleeName(n.expression);
+            if (calls.size < MAX_CALLS)
+                calls.add(callee);
+            const first = n.arguments[0];
+            if (callee === "step" && first && ts.isStringLiteralLike(first))
+                steps.push(first.text);
+        }
+        ts.forEachChild(n, visit);
+    };
+    visit(node);
+    return { calls: [...calls].sort(), steps };
+}
+/** `expect(x).toBe(y)` becomes `expect().toBe`, so call arguments never leak into the call list. */
+function calleeName(expression) {
+    if (ts.isIdentifier(expression))
+        return expression.text;
+    if (ts.isPropertyAccessExpression(expression))
+        return `${calleeName(expression.expression)}.${expression.name.text}`;
+    if (ts.isCallExpression(expression))
+        return `${calleeName(expression.expression)}()`;
+    if (ts.isAwaitExpression(expression) ||
+        ts.isParenthesizedExpression(expression) ||
+        ts.isNonNullExpression(expression))
+        return calleeName(expression.expression);
+    return "<expression>";
+}
+function objectProperties(object) {
+    const out = new Map();
+    for (const p of object.properties) {
+        const name = p.name;
+        if (name && (ts.isIdentifier(name) || ts.isStringLiteralLike(name)))
+            out.set(name.text, p);
+    }
+    return out;
+}
+/** A real syntax node to cite as evidence: synthetic assignment wrappers are replaced by their initializer. */
+function evidenceNode(property) {
+    if (!property)
+        return undefined;
+    return property.synthetic && ts.isPropertyAssignment(property)
+        ? property.initializer
+        : property;
+}
+/** Adapts a `Story.key = value` assignment to the property-assignment shape the readers expect. */
+function fakeAssignment(key, expression) {
+    return {
+        kind: ts.SyntaxKind.PropertyAssignment,
+        name: { kind: ts.SyntaxKind.Identifier, text: key },
+        initializer: expression,
+        synthetic: true
+    };
+}
+//# sourceMappingURL=csf.js.map