@invariant-ui/cli 0.0.0-stage → 0.1.0

package/dist/validation/discovery/similar-files.js

@@ -0,0 +1,146 @@
+import { walk } from "./shapes.js";
+import { candidateId, capEvidence, listNames, MAX_VARIABLE, round3, slug, uniqueName } from "./util.js";
+/** A file with fewer design-system features than this is too small to say anything about its structure. */
+export const MIN_FEATURES = 4;
+/** A feature in at least this share of a group, but not all of it, is reported as frequent. */
+const FREQUENT_SHARE = 0.8;
+const bare = (id) => id.replace(/^component:/, "");
+/** What a file contains: its top-level design-system elements and each element-inside-element pair. */
+function featuresOf(shape) {
+    const out = new Set();
+    for (const r of shape.roots)
+        out.add(`^${bare(r.id)}`);
+    for (const n of walk(shape.roots))
+        for (const c of n.children)
+            out.add(`${bare(n.id)} > ${bare(c.id)}`);
+    return out;
+}
+function jaccard(a, b) {
+    let both = 0;
+    for (const x of a)
+        if (b.has(x))
+            both++;
+    const all = a.size + b.size - both;
+    return all === 0 ? 0 : both / all;
+}
+const idsIn = (feature) => feature.startsWith("^") ? [feature.slice(1)] : feature.split(" > ");
+/**
+ * Method: overlap of structure. Each file is described by the design-system elements at its top level and the
+ * pairs of elements nested in each other. Files are put in a group when every pair in it overlaps by at least the
+ * threshold, taking files in path order, so the result does not depend on how they were listed. A group says its
+ * files are built from much the same parts. It does not say they do the same job.
+ */
+export function findSimilarFiles(files, options) {
+    const members = files
+        .map((shape) => ({ shape, features: featuresOf(shape) }))
+        .filter((m) => m.features.size >= MIN_FEATURES)
+        .sort((a, b) => (a.shape.file < b.shape.file ? -1 : a.shape.file > b.shape.file ? 1 : 0));
+    const clusters = [];
+    for (const m of members) {
+        const home = clusters.find((c) => c.every((o) => jaccard(m.features, o.features) >= options.similarity));
+        if (home)
+            home.push(m);
+        else
+            clusters.push([m]);
+    }
+    const names = new Map();
+    for (const f of files)
+        for (const n of walk(f.roots))
+            names.set(bare(n.id), n.name);
+    const taken = new Set();
+    const out = [];
+    for (const cluster of clusters.filter((c) => c.length >= options.minFiles)) {
+        const total = cluster.length;
+        const counts = new Map();
+        for (const m of cluster)
+            for (const f of m.features)
+                counts.set(f, (counts.get(f) ?? 0) + 1);
+        const sorted = [...counts.entries()].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+        const common = sorted.filter(([, n]) => n === total).map(([f]) => f);
+        const frequent = sorted
+            .filter(([, n]) => n < total && n / total >= FREQUENT_SHARE)
+            .map(([feature, files]) => ({ feature, files }));
+        const rest = sorted
+            .filter(([, n]) => n / total < FREQUENT_SHARE)
+            .map(([feature, files]) => ({ feature, files }))
+            .sort((a, b) => b.files - a.files || (a.feature < b.feature ? -1 : 1));
+        const pairs = [];
+        for (let i = 0; i < total; i++)
+            for (let j = i + 1; j < total; j++)
+                pairs.push(jaccard(cluster[i].features, cluster[j].features));
+        const key = common.join("|");
+        const rolesById = new Map();
+        for (const f of common)
+            for (const id of idsIn(f))
+                rolesById.set(id, "required");
+        for (const { feature } of frequent)
+            for (const id of idsIn(feature))
+                if (!rolesById.has(id))
+                    rolesById.set(id, "optional");
+        const used = new Set();
+        const parts = [...rolesById.entries()]
+            .sort((a, b) => (a[0] < b[0] ? -1 : 1))
+            .map(([id, role]) => ({
+            name: uniqueName(slug(names.get(id) ?? id), used),
+            ref: `component:${id}`,
+            role
+        }));
+        if (parts.length === 0)
+            continue;
+        const named = [...rolesById.keys()].sort().map((id) => names.get(id) ?? id);
+        const topNames = common.filter((f) => f.startsWith("^")).map((f) => names.get(f.slice(1)) ?? f.slice(1));
+        const label = listNames(topNames.length > 0 ? topNames : named);
+        const evidence = cluster.map((m) => {
+            const first = m.shape.roots[0];
+            return {
+                file: m.shape.file,
+                line: first.line,
+                column: first.column,
+                detail: `${m.features.size} design-system features, ${common.length} shared by the whole group`
+            };
+        });
+        const capped = capEvidence(evidence);
+        const minimum = Math.min(...pairs);
+        const mean = pairs.reduce((a, b) => a + b, 0) / pairs.length;
+        out.push({
+            id: candidateId("similar-files", key, taken),
+            kind: "similar-files",
+            status: "proposed",
+            basis: "inferred",
+            equivalence: "not-established",
+            suggestedName: `Files built from ${label}`,
+            nameSource: "derived",
+            summary: `${total} files built from much the same design-system parts: ${listNames(named)}.`,
+            explanation: [
+                `Each file was described by the design-system elements at its top level and the pairs of elements nested in each other. These ${total} files were grouped because every pair of them overlaps by at least ${options.similarity}; the lowest overlap in the group is ${round3(minimum)}.`,
+                `${common.length} features are in every file, ${frequent.length} in at least ${Math.round(FREQUENT_SHARE * 100)}% of them, and ${rest.length} in fewer.`,
+                "Overlap of structure is measured here. It is not evidence that the files serve the same purpose or that one should look like another.",
+                "Files are grouped in path order, one group at a time, so a group depends on the files present."
+            ],
+            support: { files: total, occurrences: total },
+            consistency: { minimumPairwise: round3(minimum), meanPairwise: round3(mean) },
+            structure: {
+                key,
+                common,
+                frequent,
+                variable: rest.slice(0, MAX_VARIABLE),
+                variableTruncated: rest.length > MAX_VARIABLE
+            },
+            evidence: capped.evidence,
+            evidenceTruncated: capped.truncated,
+            definition: {
+                name: `Files built from ${label}`,
+                category: "composition",
+                description: `The design-system parts shared by ${total} similar files, found by invariant discover. Parts in every file are required; parts in most are optional. Review before relying on it.`,
+                composition: { parts }
+            },
+            derivation: {
+                method: "complete-linkage-overlap",
+                version: 1,
+                parameters: { minFiles: options.minFiles, similarity: options.similarity, minFeatures: MIN_FEATURES }
+            }
+        });
+    }
+    return out.sort((a, b) => b.support.files - a.support.files || (a.structure.key < b.structure.key ? -1 : 1));
+}
+//# sourceMappingURL=similar-files.js.map

package/dist/validation/discovery/util.js

@@ -0,0 +1,47 @@
+import { sha256Hex } from "../../shared/index.js";
+export const MAX_EVIDENCE = 25;
+export const MAX_VARIABLE = 30;
+/** A stable id from what the candidate is, so the same finding keeps its id from run to run and reviews stay attached. */
+export function candidateId(kind, key, taken) {
+    const base = `candidate:${kind}.${sha256Hex(`${kind}\n${key}`).slice(0, 8)}`;
+    let id = base;
+    for (let n = 2; taken.has(id); n++)
+        id = `${base}-${n}`;
+    taken.add(id);
+    return id;
+}
+/** `CardHeader` and `Card.Header` become `card-header`: a legal part name, readable, and the same every time. */
+export function slug(name) {
+    const out = name
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^[^a-z0-9]+/, "")
+        .replace(/-+$/, "");
+    return (out === "" ? "part" : out).slice(0, 56);
+}
+/** Part names must be unique in a pattern; a repeat gets a number. */
+export function uniqueName(base, used) {
+    let name = base;
+    for (let n = 2; used.has(name); n++)
+        name = `${base}-${n}`;
+    used.add(name);
+    return name;
+}
+export const byPosition = (a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line || a.column - b.column;
+/** Evidence capped to a fixed number, always the same ones (the first in file order), with a flag saying so. */
+export function capEvidence(all) {
+    const sorted = [...all].sort(byPosition);
+    return { evidence: sorted.slice(0, MAX_EVIDENCE), truncated: sorted.length > MAX_EVIDENCE };
+}
+export const round3 = (n) => Math.round(n * 1000) / 1000;
+export function listNames(names) {
+    if (names.length <= 1)
+        return names.join("");
+    const shown = names.slice(0, 3);
+    const more = names.length - shown.length;
+    const head = shown.slice(0, -1).join(", ");
+    const last = shown[shown.length - 1];
+    return more > 0 ? `${shown.join(", ")} and ${more} more` : `${head} and ${last}`;
+}
+//# sourceMappingURL=util.js.map

package/dist/validation/index.js

@@ -0,0 +1,11 @@
+export { CARD_FINDINGS_LIMIT, enforcementCard, passCard } from "./card.js";
+export * from "./discovery/index.js";
+export { evaluatePatternRules, PATTERN_RULE_CODES, patternRules } from "./pattern-rules.js";
+export { activePolicies, evaluateUse, policyRuleSchema, relationshipRules } from "./policy.js";
+export { formatGithub, formatText, patternSummaryText, shouldFail, sortEvaluations, sortViolations, summarize, toJson, toSarif } from "./report.js";
+export { PLAN_RULES, RULES, ruleFor } from "./rules.js";
+export { scanJsx, scanMarkup } from "./scan.js";
+export { distance, nearest } from "./text.js";
+export { buildTree, defaultFramework, MAX_CODE_CHARS, validateCode } from "./validate-code.js";
+export { isDynamic, validateUsage } from "./validate-usage.js";
+//# sourceMappingURL=index.js.map

package/dist/validation/interaction-facts.js

@@ -0,0 +1,341 @@
+import ts from "typescript";
+const KNOWN_HOOKS = new Set([
+    "useState",
+    "useReducer",
+    "useEffect",
+    "useLayoutEffect",
+    "useRef",
+    "useMemo",
+    "useCallback",
+    "useContext",
+    "useId",
+    "useTransition",
+    "useDeferredValue",
+    "useFormStatus",
+    "useActionState",
+    "useFormState",
+    "useImperativeHandle",
+    "useQuery",
+    "useMutation",
+    "useSWR",
+    "useForm",
+    "useNavigate",
+    "useRouter"
+]);
+export const lineOf = (sf, node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+export const unwrap = (node) => {
+    let n = node;
+    while (ts.isParenthesizedExpression(n) ||
+        ts.isAsExpression(n) ||
+        ts.isNonNullExpression(n) ||
+        ts.isSatisfiesExpression(n))
+        n = n.expression;
+    return n;
+};
+export function bindingNames(name) {
+    if (ts.isIdentifier(name))
+        return [name.text];
+    return name.elements.flatMap((el) => (ts.isOmittedExpression(el) ? [] : bindingNames(el.name)));
+}
+const isFunction = (n) => ts.isArrowFunction(n) || ts.isFunctionExpression(n) || ts.isFunctionDeclaration(n);
+export function argKind(node) {
+    if (!node)
+        return "other";
+    const e = unwrap(node);
+    if (e.kind === ts.SyntaxKind.TrueKeyword)
+        return "true";
+    if (e.kind === ts.SyntaxKind.FalseKeyword)
+        return "false";
+    if (e.kind === ts.SyntaxKind.NullKeyword)
+        return "null";
+    if (ts.isStringLiteralLike(e) && e.text === "")
+        return "empty";
+    return "other";
+}
+function calleeNames(e) {
+    const c = unwrap(e);
+    if (ts.isIdentifier(c))
+        return { name: c.text, full: c.text };
+    if (ts.isPropertyAccessExpression(c)) {
+        const inner = calleeNames(c.expression);
+        return { name: c.name.text, full: `${inner?.full ?? "?"}.${c.name.text}` };
+    }
+    return undefined;
+}
+/** What a function does, in the order it is written. Nested functions are read only as promise callbacks. */
+export function analyzeFunction(sf, fn, name) {
+    const info = {
+        ...(name ? { name } : {}),
+        line: lineOf(sf, fn),
+        setters: [],
+        calls: [],
+        guards: [],
+        hasCatch: false
+    };
+    const body = fn.body;
+    if (!body)
+        return info;
+    const catchRanges = [];
+    const finallyRanges = [];
+    const within = (ranges, pos) => ranges.some(([a, b]) => pos >= a && pos < b);
+    const markAwait = (pos) => {
+        if (info.awaitPos === undefined || pos < info.awaitPos)
+            info.awaitPos = pos;
+    };
+    // First pass: where the awaits, catches and finallys are, so the second pass can classify every call.
+    const scan = (n, top) => {
+        if (!top && isFunction(n) && !isPromiseCallback(n))
+            return;
+        if (ts.isAwaitExpression(n))
+            markAwait(n.getStart(sf));
+        if (ts.isTryStatement(n)) {
+            if (n.catchClause) {
+                info.hasCatch = true;
+                catchRanges.push([n.catchClause.getStart(sf), n.catchClause.getEnd()]);
+            }
+            if (n.finallyBlock)
+                finallyRanges.push([n.finallyBlock.getStart(sf), n.finallyBlock.getEnd()]);
+        }
+        if (ts.isCallExpression(n) && ts.isPropertyAccessExpression(n.expression)) {
+            const m = n.expression.name.text;
+            if (m === "then" || m === "catch" || m === "finally") {
+                markAwait(n.expression.name.getStart(sf));
+                if (m === "catch") {
+                    info.hasCatch = true;
+                    for (const a of n.arguments)
+                        catchRanges.push([a.getStart(sf), a.getEnd()]);
+                }
+                if (m === "finally")
+                    for (const a of n.arguments)
+                        finallyRanges.push([a.getStart(sf), a.getEnd()]);
+            }
+        }
+        ts.forEachChild(n, (c) => scan(c, false));
+    };
+    scan(body, true);
+    const walk = (n, top) => {
+        if (!top && isFunction(n) && !isPromiseCallback(n))
+            return;
+        if (ts.isCallExpression(n)) {
+            const callee = calleeNames(n.expression);
+            if (callee) {
+                const pos = n.getStart(sf);
+                const inCatch = within(catchRanges, pos);
+                if (/^set[A-Z0-9_]/.test(callee.name) && callee.name === callee.full)
+                    info.setters.push({
+                        setter: callee.name,
+                        arg: argKind(n.arguments[0]),
+                        pos,
+                        line: lineOf(sf, n),
+                        inCatch,
+                        inFinally: within(finallyRanges, pos)
+                    });
+                else
+                    info.calls.push({ name: callee.name, full: callee.full, pos, line: lineOf(sf, n), inCatch });
+            }
+        }
+        if (top && ts.isBlock(n))
+            for (const stmt of n.statements) {
+                // `if (x) return` near the top: a guard against running twice.
+                if (ts.isIfStatement(stmt) && (isReturn(stmt.thenStatement) || returnsInBlock(stmt.thenStatement)))
+                    collectIdentifiers(stmt.expression, info.guards);
+            }
+        ts.forEachChild(n, (c) => walk(c, false));
+    };
+    walk(body, true);
+    return info;
+}
+function isReturn(n) {
+    return ts.isReturnStatement(n);
+}
+function returnsInBlock(n) {
+    return (ts.isBlock(n) &&
+        n.statements.length > 0 &&
+        n.statements.every((s) => ts.isReturnStatement(s) || ts.isExpressionStatement(s)) &&
+        n.statements.some((s) => ts.isReturnStatement(s)));
+}
+function collectIdentifiers(n, into) {
+    if (ts.isIdentifier(n))
+        into.push(n.text);
+    ts.forEachChild(n, (c) => collectIdentifiers(c, into));
+}
+/** An arrow or function passed to `.then`, `.catch` or `.finally` is part of the same flow as its caller. */
+function isPromiseCallback(n) {
+    const p = n.parent;
+    return (p !== undefined &&
+        ts.isCallExpression(p) &&
+        ts.isPropertyAccessExpression(p.expression) &&
+        ["then", "catch", "finally"].includes(p.expression.name.text));
+}
+/** Identifiers, and `obj.prop` pairs, read in the JSX of a subtree. */
+export function consumedIn(root) {
+    const out = new Set();
+    const collect = (n) => {
+        if (ts.isIdentifier(n))
+            out.add(n.text);
+        if (ts.isPropertyAccessExpression(n) && ts.isIdentifier(n.expression))
+            out.add(`${n.expression.text}.${n.name.text}`);
+        ts.forEachChild(n, collect);
+    };
+    const visit = (n) => {
+        if (ts.isJsxExpression(n) || ts.isJsxAttribute(n) || ts.isJsxSpreadAttribute(n))
+            collect(n);
+        else
+            ts.forEachChild(n, visit);
+    };
+    visit(root);
+    return out;
+}
+export function enclosingFunctions(node) {
+    const out = [];
+    for (let p = node.parent; p; p = p.parent)
+        if (isFunction(p) || ts.isMethodDeclaration(p))
+            out.push(p);
+    return out;
+}
+/** Reads the declarations of one function: state, hook results, handlers, effects and parameters. */
+export function buildScope(sf, fn, parent) {
+    const scope = {
+        fn,
+        parent,
+        params: new Set(),
+        states: new Map(),
+        hookNames: new Map(),
+        hookObjects: new Map(),
+        unknownHooks: [],
+        handlers: new Map(),
+        effects: [],
+        consumed: consumedIn(fn)
+    };
+    const f = fn;
+    for (const p of f.parameters ?? [])
+        for (const n of bindingNames(p.name))
+            scope.params.add(n);
+    const body = f.body;
+    if (!body || !ts.isBlock(body))
+        return scope;
+    for (const stmt of body.statements) {
+        if (ts.isFunctionDeclaration(stmt) && stmt.name)
+            scope.handlers.set(stmt.name.text, analyzeFunction(sf, stmt, stmt.name.text));
+        if (ts.isExpressionStatement(stmt) && ts.isCallExpression(unwrap(stmt.expression))) {
+            const call = unwrap(stmt.expression);
+            if (ts.isIdentifier(call.expression) &&
+                (call.expression.text === "useEffect" || call.expression.text === "useLayoutEffect")) {
+                const cb = call.arguments[0];
+                if (cb && isFunction(cb)) {
+                    scope.effects.push(analyzeFunction(sf, cb));
+                    // An effect usually declares the async function it then calls; read those too.
+                    const inner = cb.body;
+                    if (inner && ts.isBlock(inner))
+                        for (const s of inner.statements) {
+                            if (ts.isFunctionDeclaration(s))
+                                scope.effects.push(analyzeFunction(sf, s, s.name?.text));
+                            if (ts.isVariableStatement(s))
+                                for (const d of s.declarationList.declarations) {
+                                    const init = d.initializer && unwrap(d.initializer);
+                                    if (init && isFunction(init))
+                                        scope.effects.push(analyzeFunction(sf, init));
+                                }
+                        }
+                }
+            }
+        }
+        if (!ts.isVariableStatement(stmt))
+            continue;
+        for (const decl of stmt.declarationList.declarations) {
+            const init = decl.initializer ? unwrap(decl.initializer) : undefined;
+            if (!init)
+                continue;
+            if (isFunction(init) && ts.isIdentifier(decl.name)) {
+                scope.handlers.set(decl.name.text, analyzeFunction(sf, init, decl.name.text));
+                continue;
+            }
+            if (!ts.isCallExpression(init) || !ts.isIdentifier(init.expression))
+                continue;
+            const hook = init.expression.text;
+            if (hook === "useCallback" && ts.isIdentifier(decl.name)) {
+                const cb = init.arguments[0] && unwrap(init.arguments[0]);
+                if (cb && isFunction(cb))
+                    scope.handlers.set(decl.name.text, analyzeFunction(sf, cb, decl.name.text));
+                continue;
+            }
+            if (hook === "useState" && ts.isArrayBindingPattern(decl.name)) {
+                const [a, b] = decl.name.elements;
+                if (a &&
+                    b &&
+                    !ts.isOmittedExpression(a) &&
+                    !ts.isOmittedExpression(b) &&
+                    ts.isIdentifier(a.name) &&
+                    ts.isIdentifier(b.name)) {
+                    const arg = init.arguments[0] && unwrap(init.arguments[0]);
+                    const kind = argKind(init.arguments[0]);
+                    scope.states.set(a.name.text, {
+                        name: a.name.text,
+                        setter: b.name.text,
+                        init: kind !== "other"
+                            ? kind
+                            : arg && ts.isArrayLiteralExpression(arg)
+                                ? "array"
+                                : arg && ts.isStringLiteralLike(arg)
+                                    ? "string"
+                                    : arg && ts.isNumericLiteral(arg)
+                                        ? "number"
+                                        : "other",
+                        line: lineOf(sf, decl)
+                    });
+                }
+                continue;
+            }
+            if (/^use[A-Z]/.test(hook)) {
+                for (const n of bindingNames(decl.name)) {
+                    scope.hookNames.set(n, hook);
+                    if (ts.isIdentifier(decl.name))
+                        scope.hookObjects.set(n, hook);
+                }
+                if (!KNOWN_HOOKS.has(hook))
+                    scope.unknownHooks.push(hook);
+            }
+        }
+    }
+    return scope;
+}
+export const chainStates = (c) => c.scopes.flatMap((s) => [...s.states.values()]);
+export const chainConsumed = (c) => new Set(c.scopes.flatMap((s) => [...s.consumed]));
+export const chainHandler = (c, name) => {
+    for (const s of c.scopes) {
+        const h = s.handlers.get(name);
+        if (h)
+            return h;
+    }
+    return undefined;
+};
+export const chainUnknownHooks = (c) => c.scopes.flatMap((s) => s.unknownHooks);
+/**
+ * Names in scope that look like a given kind of flag, by name: state, values a hook returns, props, and
+ * properties read off a hook's result. This is a naming heuristic, and the evidence says so.
+ */
+export function candidates(c, test) {
+    const out = [];
+    for (const s of c.scopes) {
+        for (const st of s.states.values())
+            if (test.test(st.name))
+                out.push({ name: st.name, source: "state", setter: st.setter });
+        for (const [n, hook] of s.hookNames)
+            if (test.test(n))
+                out.push({ name: n, source: "hook", hook });
+        for (const p of s.params)
+            if (test.test(p))
+                out.push({ name: p, source: "prop" });
+        for (const [obj, hook] of s.hookObjects)
+            for (const used of s.consumed) {
+                const m = new RegExp(`^${obj}\\.(.+)$`).exec(used);
+                if (m && test.test(m[1]))
+                    out.push({ name: used, source: "hook", hook });
+            }
+    }
+    return [...new Map(out.map((x) => [x.name, x])).values()];
+}
+/** True when a name is read in the JSX of this component, directly or as a property of a hook's result. */
+export const shown = (c, name) => chainConsumed(c).has(name);
+export const isDeleteLike = (name) => /(?:^|[^a-z])(delete|remove|destroy|discard|erase|purge)|(?:Delete|Remove|Destroy|Discard|Erase|Purge)/.test(name);
+//# sourceMappingURL=interaction-facts.js.map