@invariant-ui/cli 0.0.0-stage → 0.2.0

package/dist/shared/glob.js

@@ -0,0 +1,98 @@
+/**
+ * Minimal glob matcher for POSIX relative paths: `**`, `*`, `?`, `{a,b}`, `[abc]`, and the extglob
+ * `@(a|b)` that Storybook story globs commonly use. Other extglobs are not supported.
+ */
+export function globToRegExp(pattern) {
+    return new RegExp(`^${convert(pattern.replace(/^\.\//, ""))}$`);
+}
+export function matchesAny(path, matchers) {
+    return matchers.some((m) => m.test(path));
+}
+function convert(p) {
+    let out = "";
+    for (let i = 0; i < p.length; i++) {
+        const c = p[i];
+        if (c === "*") {
+            if (p[i + 1] === "*") {
+                if (p[i + 2] === "/") {
+                    out += "(?:.*/)?";
+                    i += 2;
+                }
+                else {
+                    out += ".*";
+                    i += 1;
+                }
+            }
+            else
+                out += "[^/]*";
+        }
+        else if (c === "?") {
+            out += "[^/]";
+        }
+        else if (c === "{") {
+            const end = matching(p, i, "{", "}");
+            if (end < 0)
+                out += "\\{";
+            else {
+                out += `(?:${splitTopLevel(p.slice(i + 1, end), ",")
+                    .map(convert)
+                    .join("|")})`;
+                i = end;
+            }
+        }
+        else if (c === "@" && p[i + 1] === "(") {
+            const end = matching(p, i + 1, "(", ")");
+            if (end < 0)
+                out += "@";
+            else {
+                out += `(?:${splitTopLevel(p.slice(i + 2, end), "|")
+                    .map(convert)
+                    .join("|")})`;
+                i = end;
+            }
+        }
+        else if (c === "[") {
+            const end = p.indexOf("]", i + 1);
+            if (end < 0)
+                out += "\\[";
+            else {
+                out += p.slice(i, end + 1);
+                i = end;
+            }
+        }
+        else {
+            out += c.replace(/[.+^$()|\\/]/g, (m) => (m === "/" ? "/" : `\\${m}`));
+        }
+    }
+    return out;
+}
+function matching(p, start, open, close) {
+    let depth = 0;
+    for (let i = start; i < p.length; i++) {
+        if (p[i] === open)
+            depth++;
+        else if (p[i] === close && --depth === 0)
+            return i;
+    }
+    return -1;
+}
+function splitTopLevel(text, separator) {
+    const parts = [];
+    let depth = 0;
+    let current = "";
+    for (const c of text) {
+        if (c === "{" || c === "(")
+            depth++;
+        if (c === "}" || c === ")")
+            depth--;
+        if (c === separator && depth === 0) {
+            parts.push(current);
+            current = "";
+        }
+        else
+            current += c;
+    }
+    parts.push(current);
+    return parts;
+}
+//# sourceMappingURL=glob.js.map

package/dist/shared/index.js

@@ -0,0 +1,4 @@
+export { canonicalStringify, hashJson, sha256Hex } from "./canonical.js";
+export { DIAGNOSTICS_FILE_VERSION, DiagnosticCollector, diagnostic, diagnosticCodeSchema, diagnosticLocationSchema, diagnosticSchema, diagnosticsFileSchema, hasErrors, severitySchema, sortDiagnostics } from "./diagnostic.js";
+export { globToRegExp, matchesAny } from "./glob.js";
+//# sourceMappingURL=index.js.map

package/dist/shared/json.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=json.js.map

package/dist/validation/card.js

@@ -0,0 +1,50 @@
+import { sortViolations } from "./report.js";
+/**
+ * The most findings a card shows before pointing at the rest. Claude Code caps hook strings at 10,000
+ * characters, and a person reads this in a chat: ten is as much as anyone acts on at once.
+ */
+export const CARD_FINDINGS_LIMIT = 10;
+const MARK = { error: "✗", warning: "⚠", info: "ℹ" };
+/**
+ * The enforcement card: the one finding list every surface shows the agent — the hook's deny reason, the
+ * validate tool's text content — so the chat the person is watching says the same thing everywhere it is
+ * checked. Rule, what is wrong, where, and the fix, in file order and capped so it stays readable in a
+ * message. Show {@link passCard} instead when there is nothing to fix.
+ */
+export function enforcementCard(input) {
+    const { findings, contractName, next } = input;
+    const file = input.file ?? "the snippet";
+    const limit = input.limit ?? CARD_FINDINGS_LIMIT;
+    const count = (severity) => findings.filter((f) => f.severity === severity).length;
+    const errors = count("error");
+    const warnings = count("warning");
+    const info = count("info");
+    const counts = [
+        errors > 0 ? `${errors} error${errors === 1 ? "" : "s"}` : undefined,
+        warnings > 0 ? `${warnings} warning${warnings === 1 ? "" : "s"}` : undefined,
+        info > 0 ? `${info} info` : undefined
+    ]
+        .filter(Boolean)
+        .join(", ");
+    const lines = [
+        `invariant ${input.blocked === true ? "blocked" : "checked"} ${file}: ${counts} against the ${contractName} contract`,
+        ""
+    ];
+    for (const f of sortViolations([...findings]).slice(0, limit)) {
+        const where = f.line !== undefined ? ` (line ${f.line})` : "";
+        lines.push(`${MARK[f.severity]} ${f.code}: ${f.message}${where}`);
+        if (f.suggestion)
+            lines.push(`    fix: ${f.suggestion}`);
+    }
+    if (findings.length > limit)
+        lines.push(input.more ? input.more(findings.length - limit) : `…and ${findings.length - limit} more`);
+    lines.push("");
+    lines.push(`${next} Facts and fixes come from the compiled contract, not guesses.`);
+    return lines.join("\n");
+}
+/** The one-line confirmation of a clean pass: what was checked, and that it follows the contract. */
+export function passCard(input) {
+    const n = input.componentsChecked.length;
+    return `invariant ✓ ${input.file ?? "the snippet"} follows the ${input.contractName} contract (${n === 0 ? "no" : n} component use${n === 1 ? "" : "s"} checked)`;
+}
+//# sourceMappingURL=card.js.map

package/dist/validation/discovery/arrangements.js

@@ -0,0 +1,162 @@
+import { walk } from "./shapes.js";
+import { candidateId, capEvidence, listNames, slug, uniqueName } from "./util.js";
+const flags = (n) => `${n.conditional ? "?" : ""}${n.repeated ? "*" : ""}${n.opaque ? "~" : ""}`;
+const bare = (id) => id.replace(/^component:/, "");
+/**
+ * The canonical form of a node and what is inside it, to a fixed depth: `card(card.header,card.body*)`.
+ * `?` marks an element that may not render, `*` one that may render many times, `~` one whose children may be
+ * incomplete. Two nodes with the same form have the same shape of design-system elements and nothing more.
+ */
+export function keyOf(node, depth, maxDepth) {
+    const head = `${bare(node.id)}${flags(node)}`;
+    if (node.children.length === 0)
+        return head;
+    if (depth >= maxDepth)
+        return `${head}(…)`;
+    return `${head}(${node.children.map((c) => keyOf(c, depth + 1, maxDepth)).join(",")})`;
+}
+function treeOf(node, depth, maxDepth) {
+    return {
+        id: node.id,
+        name: node.name,
+        optional: node.conditional || node.repeated,
+        opaque: node.opaque || (depth >= maxDepth && node.children.length > 0),
+        children: depth >= maxDepth ? [] : node.children.map((c) => treeOf(c, depth + 1, maxDepth))
+    };
+}
+const pos = (file, n) => `${file}:${n.line}:${n.column}`;
+function parts(root, maxDepth) {
+    const used = new Set();
+    const seen = new Map();
+    const order = [];
+    const visit = (n, depth) => {
+        const role = n.conditional || n.repeated ? "optional" : "required";
+        const held = seen.get(n.id);
+        if (held === undefined) {
+            seen.set(n.id, role);
+            order.push(n);
+        }
+        else if (role === "required")
+            seen.set(n.id, "required");
+        if (depth < maxDepth)
+            for (const c of n.children)
+                visit(c, depth + 1);
+    };
+    visit(root, 0);
+    return order.map((n) => ({
+        name: uniqueName(slug(n.name), used),
+        ref: n.id,
+        role: seen.get(n.id)
+    }));
+}
+/**
+ * Method: exact structure. Every design-system element with something inside it is an arrangement; arrangements
+ * with the same canonical form are grouped. A group that recurs in enough files and enough places is a
+ * candidate. Nothing here compares meaning, so two arrangements are the same only if they are written the same.
+ */
+export function findArrangements(files, options) {
+    const groups = new Map();
+    for (const f of files)
+        for (const node of walk(f.roots)) {
+            if (node.children.length === 0)
+                continue;
+            const key = keyOf(node, 0, options.maxDepth);
+            const group = groups.get(key) ?? { key, nodes: [] };
+            group.nodes.push({ file: f.file, node });
+            groups.set(key, group);
+        }
+    const kept = [...groups.values()]
+        .filter((g) => g.nodes.length >= options.minUses && new Set(g.nodes.map((n) => n.file)).size >= options.minFiles)
+        .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    const inside = new Map();
+    for (const g of kept) {
+        const set = new Set();
+        for (const { file, node } of g.nodes)
+            for (const d of walk(node.children))
+                set.add(pos(file, d));
+        inside.set(g.key, set);
+    }
+    const taken = new Set();
+    const out = kept.map((g) => {
+        const first = g.nodes[0];
+        const fileCount = new Set(g.nodes.map((n) => n.file)).size;
+        const root = first.node;
+        const children = [...new Set(walk(root.children).map((c) => c.name))];
+        const name = `${root.name} with ${listNames(children)}`;
+        const evidence = g.nodes.map(({ file, node }) => ({
+            file,
+            line: node.line,
+            column: node.column,
+            detail: `<${node.name}> containing ${listNames([...new Set(node.children.map((c) => c.name))])}`
+        }));
+        const capped = capEvidence(evidence);
+        const guarded = g.key.includes("~");
+        return {
+            id: candidateId("arrangement", g.key, taken),
+            kind: "arrangement",
+            status: "proposed",
+            basis: "inferred",
+            equivalence: "not-established",
+            suggestedName: name,
+            nameSource: "derived",
+            summary: `${root.name} containing ${listNames(children)}, written the same way ${g.nodes.length} times in ${fileCount} files.`,
+            explanation: [
+                `Every design-system element with something inside it was compared with the others by its canonical form, to a depth of ${options.maxDepth}. This form, ${g.key}, appears ${g.nodes.length} times in ${fileCount} files.`,
+                "The form counts design-system elements only. Markup and components from elsewhere between them are ignored, so an element inside another may not be its direct child.",
+                "This shows the arrangement recurs. It does not show it is intended, correct, or a standard anyone chose.",
+                ...(guarded
+                    ? [
+                        "Some elements take their children from elsewhere (marked ~), so what is inside them may be incomplete."
+                    ]
+                    : [])
+            ],
+            support: { files: fileCount, occurrences: g.nodes.length },
+            structure: {
+                key: g.key,
+                common: [],
+                frequent: [],
+                variable: [],
+                variableTruncated: false,
+                tree: treeOf(root, 0, options.maxDepth)
+            },
+            evidence: capped.evidence,
+            evidenceTruncated: capped.truncated,
+            definition: {
+                name,
+                category: "composition",
+                description: `A recurring arrangement of ${listNames([root.name, ...children])}, found ${g.nodes.length} times in ${fileCount} files by invariant discover. Review before relying on it.`,
+                composition: { parts: parts(root, options.maxDepth) }
+            },
+            derivation: {
+                method: "exact-structure",
+                version: 1,
+                parameters: { minFiles: options.minFiles, minUses: options.minUses, maxDepth: options.maxDepth }
+            }
+        };
+    });
+    // A candidate whose every occurrence lies inside another's is the same finding seen from lower down. Say so,
+    // and keep it.
+    const byKey = new Map(kept.map((g, i) => [g.key, out[i]]));
+    for (const [i, g] of kept.entries()) {
+        const mine = g.nodes.map((n) => pos(n.file, n.node));
+        let best;
+        for (const other of kept) {
+            if (other.key === g.key)
+                continue;
+            const set = inside.get(other.key);
+            if (!mine.every((p) => set.has(p)))
+                continue;
+            const candidate = byKey.get(other.key);
+            if (!best ||
+                candidate.support.occurrences > best.support.occurrences ||
+                (candidate.support.occurrences === best.support.occurrences && candidate.id < best.id))
+                best = candidate;
+        }
+        if (best)
+            out[i].subsumedBy = best.id;
+    }
+    return out.sort((a, b) => b.support.files - a.support.files ||
+        b.support.occurrences - a.support.occurrences ||
+        (a.structure.key < b.structure.key ? -1 : 1));
+}
+//# sourceMappingURL=arrangements.js.map

package/dist/validation/discovery/discover.js

@@ -0,0 +1,70 @@
+import { buildTree } from "../validate-code.js";
+import { findArrangements } from "./arrangements.js";
+import { CANDIDATES_FILE_VERSION } from "./model.js";
+import { applyReviews } from "./reviews.js";
+import { shapeOf } from "./shapes.js";
+import { findSimilarFiles } from "./similar-files.js";
+export const DEFAULT_OPTIONS = { minFiles: 3, minUses: 3, similarity: 0.7, maxDepth: 3 };
+const READABLE = /\.(tsx|jsx)$/i;
+/**
+ * Finds structures that recur in application code, as candidates for people to review. It reads React JSX by
+ * syntax and runs nothing. It resolves elements to the contract's components, so it needs a compiled contract.
+ * The result is the same for the same files, contract and options. Nothing it produces is approved or enforced.
+ */
+export function discover(input) {
+    const options = { ...DEFAULT_OPTIONS, ...input.options };
+    const diagnostics = [];
+    const files = [...input.files].sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+    const shapes = [];
+    let unreadable = 0;
+    let empty = 0;
+    for (const { file, code } of files) {
+        if (!READABLE.test(file)) {
+            unreadable++;
+            continue;
+        }
+        const shape = shapeOf(file, buildTree(input.ds, code, file));
+        if (shape.designSystemElements === 0)
+            empty++;
+        else
+            shapes.push(shape);
+    }
+    if (unreadable > 0)
+        diagnostics.push({
+            code: "discovery-unsupported-files",
+            severity: "info",
+            message: `${unreadable} file(s) were skipped: discovery reads .tsx and .jsx files only. Vue, Angular, HTML and plain script files are not analyzed.`
+        });
+    if (empty > 0)
+        diagnostics.push({
+            code: "discovery-no-design-system-elements",
+            severity: "info",
+            message: `${empty} file(s) use no component from the contract, so they say nothing about how the design system is composed.`
+        });
+    if (shapes.length === 0)
+        diagnostics.push({
+            code: "discovery-nothing-to-analyze",
+            severity: "warning",
+            message: "No file used a component from the contract, so there is nothing to compare. Check the paths and that the contract's components are imported from the packages it names."
+        });
+    const found = [
+        ...findArrangements(shapes, options),
+        ...findSimilarFiles(shapes, { minFiles: options.minFiles, similarity: options.similarity })
+    ];
+    const applied = applyReviews(found, input.reviews);
+    for (const r of applied.stale)
+        diagnostics.push({
+            code: "discovery-stale-review",
+            severity: "info",
+            message: `${r.candidate} was ${r.decision} by ${r.decidedBy}, but discovery no longer finds that structure. The decision is kept in the reviews file.`
+        });
+    return {
+        version: CANDIDATES_FILE_VERSION,
+        contract: { contentHash: input.ds.contract.integrity.contentHash },
+        parameters: options,
+        summary: { files: files.length, filesAnalyzed: shapes.length, candidates: applied.candidates.length },
+        candidates: applied.candidates,
+        diagnostics
+    };
+}
+//# sourceMappingURL=discover.js.map

package/dist/validation/discovery/index.js

@@ -0,0 +1,8 @@
+export { findArrangements, keyOf } from "./arrangements.js";
+export { DEFAULT_OPTIONS, discover } from "./discover.js";
+export { CANDIDATE_KINDS, CANDIDATE_STATUSES, CANDIDATES_FILE, candidateSchema, candidatesFileSchema, DECISIONS, REVIEWS_FILE, reviewSchema, reviewsFileSchema } from "./model.js";
+export { toDefinition } from "./promote.js";
+export { applyReviews, emptyReviews, latestReview, parseReviews, recordReview, serializeReviews } from "./reviews.js";
+export { shapeOf, walk } from "./shapes.js";
+export { findSimilarFiles, MIN_FEATURES } from "./similar-files.js";
+//# sourceMappingURL=index.js.map

package/dist/validation/discovery/model.js

@@ -0,0 +1,127 @@
+import { z } from "zod";
+export const CANDIDATES_FILE = "invariant.candidates.json";
+export const CANDIDATES_FILE_VERSION = 1;
+export const REVIEWS_FILE = "invariant.candidate-reviews.json";
+export const REVIEWS_FILE_VERSION = 1;
+export const CANDIDATE_KINDS = ["arrangement", "similar-files"];
+/** `proposed` until a person decides; the other states come only from a recorded review. */
+export const CANDIDATE_STATUSES = ["proposed", "accepted", "rejected", "deferred"];
+export const DECISIONS = ["accepted", "rejected", "deferred"];
+const occurrence = z.strictObject({
+    file: z.string().min(1),
+    line: z.number().int().positive(),
+    column: z.number().int().positive(),
+    detail: z.string().min(1)
+});
+const part = z.strictObject({
+    name: z
+        .string()
+        .regex(/^[a-z0-9][a-z0-9_-]*$/)
+        .max(64),
+    ref: z.string().min(1),
+    role: z.enum(["required", "optional"])
+});
+/** The start of a pattern definition. It has no id, no intent and no approval: those are for a person to give. */
+const definitionDraft = z.strictObject({
+    name: z.string().min(1).max(200),
+    /** Always `composition`: what the shape is for is the reviewer's call, made when promoting. */
+    category: z.literal("composition"),
+    description: z.string().min(1).max(2000),
+    composition: z.strictObject({ parts: z.array(part).min(1) })
+});
+const shapeTree = z.lazy(() => z.strictObject({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    optional: z.boolean(),
+    opaque: z.boolean(),
+    children: z.array(shapeTree)
+}));
+const featureCount = z.strictObject({ feature: z.string().min(1), files: z.number().int().positive() });
+export const reviewSchema = z.strictObject({
+    candidate: z.string().min(1),
+    decision: z.enum(DECISIONS),
+    /** Asserted, not authenticated, like every approver in the project. */
+    decidedBy: z.string().min(1).max(200),
+    decidedAt: z.iso.datetime(),
+    reason: z.string().min(1).max(1000).optional(),
+    reference: z.string().min(1).max(500).optional(),
+    /** Set when the accepted candidate was written into the definitions file, with the id it was given. */
+    promotedTo: z.string().min(1).max(200).optional()
+});
+export const candidateSchema = z.strictObject({
+    id: z.string().regex(/^candidate:(arrangement|similar-files)\.[0-9a-f]{8}(-\d+)?$/),
+    kind: z.enum(CANDIDATE_KINDS),
+    status: z.enum(CANDIDATE_STATUSES),
+    /** Always `inferred`: discovery observes recurrence, it does not learn what anyone intended. */
+    basis: z.literal("inferred"),
+    /** Always `not-established`: structural similarity is measured, never taken to mean the same purpose. */
+    equivalence: z.literal("not-established"),
+    suggestedName: z.string().min(1),
+    nameSource: z.literal("derived"),
+    summary: z.string().min(1),
+    /** Why this was found and what it does and does not say. */
+    explanation: z.array(z.string().min(1)).min(1),
+    support: z.strictObject({
+        files: z.number().int().positive(),
+        occurrences: z.number().int().positive()
+    }),
+    /** For `similar-files`: how alike the members are, measured, not estimated. */
+    consistency: z
+        .strictObject({
+        minimumPairwise: z.number().min(0).max(1),
+        meanPairwise: z.number().min(0).max(1)
+    })
+        .optional(),
+    structure: z.strictObject({
+        /** `arrangement`: the canonical form of the shape. `similar-files`: the features every member has. */
+        key: z.string().min(1),
+        common: z.array(z.string()),
+        frequent: z.array(featureCount),
+        variable: z.array(featureCount),
+        variableTruncated: z.boolean(),
+        /** `arrangement` only: the same shape as `key`, as data. */
+        tree: shapeTree.optional()
+    }),
+    evidence: z.array(occurrence).min(1),
+    evidenceTruncated: z.boolean(),
+    definition: definitionDraft,
+    derivation: z.strictObject({
+        method: z.enum(["exact-structure", "complete-linkage-overlap"]),
+        version: z.literal(1),
+        parameters: z.record(z.string(), z.union([z.number(), z.string()]))
+    }),
+    /** Another candidate whose occurrences contain every occurrence of this one. Kept, not dropped. */
+    subsumedBy: z.string().optional(),
+    /** The latest recorded decision, when there is one. */
+    review: reviewSchema.optional()
+});
+export const discoveryDiagnosticSchema = z.strictObject({
+    code: z.string().min(1),
+    severity: z.enum(["info", "warning"]),
+    message: z.string().min(1),
+    file: z.string().optional()
+});
+export const candidatesFileSchema = z.strictObject({
+    version: z.literal(CANDIDATES_FILE_VERSION),
+    /** The contract the components were resolved against. */
+    contract: z.strictObject({ contentHash: z.string().min(1) }),
+    parameters: z.strictObject({
+        minFiles: z.number().int().positive(),
+        minUses: z.number().int().positive(),
+        similarity: z.number().min(0).max(1),
+        maxDepth: z.number().int().positive()
+    }),
+    summary: z.strictObject({
+        files: z.number().int().nonnegative(),
+        filesAnalyzed: z.number().int().nonnegative(),
+        candidates: z.number().int().nonnegative()
+    }),
+    candidates: z.array(candidateSchema),
+    diagnostics: z.array(discoveryDiagnosticSchema)
+});
+export const reviewsFileSchema = z.strictObject({
+    $schema: z.string().optional(),
+    version: z.literal(REVIEWS_FILE_VERSION),
+    reviews: z.array(reviewSchema)
+});
+//# sourceMappingURL=model.js.map

package/dist/validation/discovery/promote.js

@@ -0,0 +1,24 @@
+/**
+ * A pattern definition for an accepted candidate, ready to add to the definitions file. It carries no approval,
+ * no intent and no constraints: it records what was observed, who accepted it, and where it came from. Compiling
+ * it gives `documented` facts; approving them, and writing rules to enforce, are separate steps for a person.
+ */
+export function toDefinition(candidate, input) {
+    const review = candidate.review;
+    return {
+        id: input.id,
+        name: input.name ?? candidate.definition.name,
+        category: input.category ?? candidate.definition.category,
+        description: candidate.definition.description,
+        composition: candidate.definition.composition,
+        origin: {
+            candidate: candidate.id,
+            method: candidate.derivation.method,
+            support: candidate.support.occurrences,
+            files: candidate.support.files,
+            ...(review ? { acceptedBy: review.decidedBy, acceptedAt: review.decidedAt } : {}),
+            ...(review?.reference ? { reference: review.reference } : {})
+        }
+    };
+}
+//# sourceMappingURL=promote.js.map

package/dist/validation/discovery/reviews.js

@@ -0,0 +1,63 @@
+import { REVIEWS_FILE_VERSION, reviewsFileSchema } from "./model.js";
+export function parseReviews(text, file) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: `${file} is not valid JSON: ${error instanceof Error ? error.message : error}`
+        };
+    }
+    const parsed = reviewsFileSchema.safeParse(raw);
+    if (parsed.success)
+        return { ok: true, value: parsed.data };
+    const first = parsed.error.issues[0];
+    return {
+        ok: false,
+        message: `${file}: ${first ? `${first.path.join(".") || "(root)"}: ${first.message}` : "invalid"}`
+    };
+}
+export function emptyReviews() {
+    return { version: REVIEWS_FILE_VERSION, reviews: [] };
+}
+/**
+ * Adds a decision to the history. Earlier decisions stay: the file is a record of who decided what and when,
+ * and the latest one for a candidate is the one that counts.
+ */
+export function recordReview(file, review) {
+    return { ...file, reviews: [...file.reviews, review] };
+}
+/** The decision in force for a candidate: its latest review. */
+export function latestReview(file, id) {
+    for (let i = file.reviews.length - 1; i >= 0; i--) {
+        const r = file.reviews[i];
+        if (r.candidate === id)
+            return r;
+    }
+    return undefined;
+}
+/**
+ * Sets each candidate's status from its latest review. A candidate is identified by what it is, not by where it
+ * was found, so a decision keeps applying as files change, and stops applying when the structure itself does.
+ */
+export function applyReviews(candidates, file) {
+    if (!file)
+        return { candidates: [...candidates], stale: [] };
+    const known = new Set(candidates.map((c) => c.id));
+    const latest = new Map();
+    for (const r of file.reviews)
+        latest.set(r.candidate, r);
+    return {
+        candidates: candidates.map((c) => {
+            const r = latest.get(c.id);
+            return r ? { ...c, status: r.decision, review: r } : c;
+        }),
+        stale: [...latest.values()].filter((r) => !known.has(r.candidate))
+    };
+}
+export function serializeReviews(file) {
+    return `${JSON.stringify(file, null, 2)}\n`;
+}
+//# sourceMappingURL=reviews.js.map

package/dist/validation/discovery/shapes.js

@@ -0,0 +1,47 @@
+/** The design-system elements of one scanned file as a forest. Reads the scan only; nothing is evaluated. */
+export function shapeOf(file, tree) {
+    const nodes = new Map();
+    const roots = [];
+    const nearest = (index) => {
+        for (let p = tree.uses[index]?.parent; p !== undefined; p = tree.uses[p]?.parent)
+            if (nodes.has(p))
+                return p;
+        return undefined;
+    };
+    tree.uses.forEach((use, i) => {
+        const component = tree.components[i];
+        if (tree.kinds[i] !== "component" || !component)
+            return;
+        const anchor = nearest(i);
+        const above = anchor === undefined ? undefined : tree.uses[anchor];
+        const node = {
+            id: component.id,
+            name: component.name,
+            line: use.line,
+            column: use.column,
+            conditional: above !== undefined && (use.exprDepth ?? 0) > (above.exprDepth ?? 0),
+            repeated: above !== undefined && (use.loopDepth ?? 0) > (above.loopDepth ?? 0),
+            opaque: use.opaque === true,
+            children: []
+        };
+        nodes.set(i, node);
+        if (anchor === undefined)
+            roots.push(node);
+        else
+            nodes.get(anchor)?.children.push(node);
+    });
+    return { file, roots, elements: tree.uses.length, designSystemElements: nodes.size };
+}
+/** Every node of a forest, parents before children, in source order. */
+export function walk(roots) {
+    const out = [];
+    const visit = (n) => {
+        out.push(n);
+        for (const c of n.children)
+            visit(c);
+    };
+    for (const r of roots)
+        visit(r);
+    return out;
+}
+//# sourceMappingURL=shapes.js.map