@invariant-ui/cli 0.0.0-stage → 0.2.0

package/dist/reconciliation/reconcile.js

@@ -0,0 +1,134 @@
+import { CONTRACT_VERSION, createEvidenceFile, finalizeContract, verifyContract } from "../contract/index.js";
+import { DiagnosticCollector } from "../shared/index.js";
+import { buildComponent } from "./components.js";
+import { ambiguityConflicts, mintConflicts, storybookConflicts } from "./conflicts.js";
+import { resolveComponents } from "./resolve.js";
+import { reconcileStorybook } from "./storybook.js";
+import { buildTokens } from "./tokens.js";
+import { cmp, slug, unique } from "./util.js";
+function inferredFact(link) {
+    return {
+        status: "inferred",
+        evidenceIds: link.evidenceIds,
+        confidence: link.confidence,
+        derivation: { rule: link.rule, reasoning: link.reasoning, inputs: link.inputs }
+    };
+}
+function sourceOf(doc) {
+    return {
+        id: doc.source.id,
+        type: doc.source.type,
+        location: doc.source.location,
+        ...(doc.source.version ? { version: doc.source.version } : {}),
+        capabilities: [...doc.capabilities].sort(),
+        health: {
+            status: doc.completeness === "complete" ? "ok" : doc.completeness === "partial" ? "degraded" : "failed",
+            diagnosticCount: doc.diagnostics.length
+        }
+    };
+}
+/**
+ * Turns IR documents into one contract draft. Deterministic: same documents and options, same bytes. Every
+ * value and fact comes from an IR claim; the only things reconciliation adds are identity links between
+ * differently named entities, and those are `inferred` with a rule and confidence.
+ */
+export function reconcile(docs, options) {
+    const diagnostics = new DiagnosticCollector();
+    const conflicts = [];
+    const resolution = resolveComponents(docs);
+    const refToId = new Map();
+    const byRef = new Map();
+    for (const rc of resolution.components)
+        for (const impl of rc.implementations) {
+            refToId.set(impl.code.ref, rc.id);
+            byRef.set(impl.code.ref, impl);
+        }
+    const components = resolution.components.map((rc) => {
+        const component = buildComponent(rc, { refToId, diagnostics, conflicts });
+        const facts = { ...component.facts };
+        for (const impl of rc.implementations) {
+            facts[`implementations.${impl.id}`] = rc.identity
+                ? inferredFact(rc.identity)
+                : {
+                    status: "discovered",
+                    evidenceIds: impl.facts.find((f) => f.path === "name")?.evidenceIds ?? impl.facts[0]?.evidenceIds ?? []
+                };
+        }
+        return { ...component, facts: Object.fromEntries(Object.entries(facts).sort((a, b) => cmp(a[0], b[0]))) };
+    });
+    const tokenResult = buildTokens(docs, { diagnostics, conflicts });
+    const tokens = tokenResult.tokens.map((t) => {
+        const link = tokenResult.identities.find((i) => i.tokenId === t.id)?.link;
+        return link ? { ...t, facts: { ...t.facts, name: inferredFact(link) } } : t;
+    });
+    const storybook = reconcileStorybook(docs);
+    diagnostics.addAll(storybook.diagnostics);
+    conflicts.push(...storybookConflicts(storybook.discrepancies, refToId, byRef));
+    conflicts.push(...ambiguityConflicts(resolution.ambiguities, refToId));
+    for (const doc of docs)
+        for (const e of doc.entities)
+            if (e.kind === "component" && !refToId.has(e.ref))
+                diagnostics.info("reconcile.component-skipped", `${e.name} publishes no framework link key and was not placed in the contract`, {
+                    sourceId: doc.source.id,
+                    entityId: e.ref
+                });
+    const minted = mintConflicts(conflicts);
+    const sources = new Map();
+    for (const doc of [...docs].sort((a, b) => cmp(a.source.id, b.source.id)))
+        if (!sources.has(doc.source.id))
+            sources.set(doc.source.id, sourceOf(doc));
+    const cited = new Set();
+    for (const c of components)
+        for (const f of Object.values(c.facts))
+            for (const id of f.evidenceIds)
+                cited.add(id);
+    for (const t of tokens)
+        for (const f of Object.values(t.facts))
+            for (const id of f.evidenceIds)
+                cited.add(id);
+    for (const c of minted)
+        for (const claim of c.claims)
+            for (const id of claim.evidenceIds)
+                cited.add(id);
+    const pool = new Map();
+    for (const doc of docs)
+        for (const e of doc.evidence)
+            if (!pool.has(e.id))
+                pool.set(e.id, e);
+    const evidence = [];
+    for (const id of [...cited].sort()) {
+        const found = pool.get(id);
+        if (found)
+            evidence.push(found);
+        else
+            diagnostics.error("reconcile.missing-evidence", `A fact cites evidence ${id}, which no IR document contains`);
+    }
+    const contract = {
+        contractVersion: CONTRACT_VERSION,
+        metadata: {
+            contractId: options.contractId ?? slug(options.name),
+            name: options.name,
+            ...(options.description ? { description: options.description } : {}),
+            compilerVersion: options.compilerVersion,
+            frameworks: unique(components.flatMap((c) => c.implementations.map((i) => i.framework))).sort(),
+            compiledAt: (options.clock ?? (() => new Date().toISOString()))()
+        },
+        sources: [...sources.values()],
+        themes: tokenResult.themes,
+        components,
+        tokens,
+        patterns: [],
+        guidelines: [],
+        constraints: [],
+        policies: [],
+        conflicts: minted
+    };
+    return { contract, evidence, diagnostics: diagnostics.toArray() };
+}
+/** Hashes the draft and verifies it, with its evidence, against the contract's own rules. */
+export function finalizeAndVerify(draft, evidence) {
+    const contract = finalizeContract(draft);
+    const evidenceFile = createEvidenceFile(contract.integrity.contentHash, evidence);
+    return { contract, evidenceFile, diagnostics: verifyContract(contract, evidenceFile) };
+}
+//# sourceMappingURL=reconcile.js.map

package/dist/reconciliation/resolve.js

@@ -0,0 +1,158 @@
+import { codeComponents } from "./code.js";
+import { cmp, normalizeName, slug, unique } from "./util.js";
+const MIN_PREFIX_COMPONENTS = 3;
+const MAX_PREFIX_LENGTH = 5;
+const PREFIX_SHARE = 0.8;
+/**
+ * A design-system prefix such as `Lds` in `LdsButton`: a short capitalized word that most components of one
+ * source start with. Components that are the prefix itself prove nothing about it, so it is rejected then.
+ */
+export function sharedPrefix(names) {
+    if (names.length < MIN_PREFIX_COMPONENTS)
+        return undefined;
+    const counts = new Map();
+    for (const name of names) {
+        const word = /^[A-Z][a-z0-9]*/.exec(name)?.[0];
+        if (word && word.length >= 2 && word.length <= MAX_PREFIX_LENGTH && name.length > word.length)
+            counts.set(word, (counts.get(word) ?? 0) + 1);
+    }
+    const best = [...counts.entries()].sort((a, b) => b[1] - a[1] || cmp(a[0], b[0]))[0];
+    if (!best || best[1] / names.length < PREFIX_SHARE)
+        return undefined;
+    return names.includes(best[0]) ? undefined : best[0];
+}
+/** The leading word of an Angular class name, when it equals the first word of the component's selector. */
+function selectorPrefix(impl) {
+    const selector = impl.facts.find((f) => /^implementations\.angular\.extensions\.angular\.selector$/.test(f.path))?.value;
+    if (typeof selector !== "string")
+        return undefined;
+    const first = /^[a-z][a-z0-9]*/.exec(selector)?.[0];
+    if (!first || selector === first)
+        return undefined;
+    const lead = first.charAt(0).toUpperCase() + first.slice(1);
+    return impl.code.name.startsWith(lead) && impl.code.name.length > lead.length ? lead : undefined;
+}
+function evidenceOf(impl) {
+    const named = impl.facts.find((f) => f.path === "name") ?? impl.facts[0];
+    return named ? named.evidenceIds : [];
+}
+/**
+ * Groups implementations into conceptual components. Same-framework implementations are never merged. Across
+ * frameworks a merge needs an equal normalized name where each framework has exactly one candidate; otherwise
+ * the match is reported as an ambiguity and nothing is merged.
+ */
+export function resolveComponents(docs) {
+    const factsByDoc = new Map();
+    for (const doc of docs) {
+        const map = new Map();
+        for (const f of doc.facts)
+            map.set(f.subject, [...(map.get(f.subject) ?? []), f]);
+        factsByDoc.set(doc, map);
+    }
+    const implementations = [];
+    for (const code of codeComponents(docs)) {
+        const doc = docs.find((d) => d.source.id === code.sourceId && d.entities.some((e) => e.ref === code.ref));
+        if (!doc)
+            continue;
+        const packageName = code.index.value(code.ref, `implementations.${code.framework}.packageName`);
+        implementations.push({
+            code,
+            doc,
+            facts: factsByDoc.get(doc)?.get(code.ref) ?? [],
+            id: "",
+            ...(packageName ? { packageName } : {})
+        });
+    }
+    implementations.sort((a, b) => cmp(a.code.sourceId, b.code.sourceId) || cmp(a.code.ref, b.code.ref));
+    const prefixBySource = new Map();
+    for (const sourceId of unique(implementations.map((i) => i.code.sourceId)))
+        prefixBySource.set(sourceId, sharedPrefix(implementations.filter((i) => i.code.sourceId === sourceId).map((i) => i.code.name)));
+    const keyed = implementations.map((impl) => {
+        const prefix = prefixBySource.get(impl.code.sourceId);
+        if (prefix && impl.code.name.startsWith(prefix) && impl.code.name.length > prefix.length)
+            return { impl, key: normalizeName(impl.code.name.slice(prefix.length)), via: "shared-prefix", prefix };
+        const fromSelector = selectorPrefix(impl);
+        if (fromSelector)
+            return {
+                impl,
+                key: normalizeName(impl.code.name.slice(fromSelector.length)),
+                via: "selector-prefix",
+                prefix: fromSelector
+            };
+        return { impl, key: normalizeName(impl.code.name), via: "name" };
+    });
+    const groups = new Map();
+    for (const k of keyed)
+        groups.set(k.key, [...(groups.get(k.key) ?? []), k]);
+    const resolved = [];
+    const ambiguities = [];
+    for (const [key, members] of [...groups.entries()].sort((a, b) => cmp(a[0], b[0]))) {
+        const frameworks = unique(members.map((m) => m.impl.code.framework));
+        const perFramework = frameworks.map((f) => members.filter((m) => m.impl.code.framework === f).length);
+        if (frameworks.length === 1) {
+            for (const m of members)
+                resolved.push({ name: m.impl.code.name, members: [m.impl] });
+            continue;
+        }
+        if (perFramework.some((n) => n > 1)) {
+            ambiguities.push({ key, candidates: members.map((m) => m.impl) });
+            for (const m of members)
+                resolved.push({ name: m.impl.code.name, members: [m.impl] });
+            continue;
+        }
+        const usedPrefix = members.some((m) => m.via !== "name");
+        const rule = usedPrefix ? "name-match.stripped-prefix" : "name-match.exact";
+        const confidence = usedPrefix ? 0.75 : 0.9;
+        const names = members.map((m) => m.impl.code.name);
+        const display = [...members].sort((a, b) => a.impl.code.name.length - b.impl.code.name.length || cmp(a.impl.code.ref, b.impl.code.ref))[0];
+        resolved.push({
+            name: display?.impl.code.name ?? names[0] ?? key,
+            members: members.map((m) => m.impl),
+            identity: {
+                rule,
+                confidence,
+                reasoning: usedPrefix
+                    ? `${names.join(", ")} are in different frameworks and share the name "${key}" once the prefix ${unique(members.flatMap((m) => (m.prefix ? [`"${m.prefix}"`] : []))).join(", ")} is removed`
+                    : `${names.join(", ")} are in different frameworks and share the name "${key}" ignoring case and separators`,
+                inputs: members.map((m) => m.impl.code.ref).sort(),
+                evidenceIds: unique(members.flatMap((m) => evidenceOf(m.impl))).sort()
+            }
+        });
+    }
+    return { components: assignIds(resolved), ambiguities };
+}
+function assignIds(resolved) {
+    const byBase = new Map();
+    for (const r of resolved)
+        byBase.set(slug(r.name), (byBase.get(slug(r.name)) ?? 0) + 1);
+    const used = new Set();
+    const out = [];
+    for (const r of [...resolved].sort((a, b) => cmp(a.members[0]?.code.ref ?? "", b.members[0]?.code.ref ?? ""))) {
+        const base = slug(r.name);
+        const pkg = r.members.find((m) => m.packageName)?.packageName;
+        let id = `component:${(byBase.get(base) ?? 0) > 1 && pkg ? `${base}.${slug(pkg)}` : base}`;
+        for (let n = 2; used.has(id); n++)
+            id = `component:${base}-${n}`;
+        used.add(id);
+        out.push({
+            id,
+            name: r.name,
+            implementations: assignImplementationIds(r.members),
+            ...(r.identity ? { identity: r.identity } : {})
+        });
+    }
+    return out.sort((a, b) => cmp(a.id, b.id));
+}
+function assignImplementationIds(members) {
+    const used = new Set();
+    return members.map((m) => {
+        let id = slug(m.code.framework);
+        if (used.has(id))
+            id = slug(`${m.code.framework}-${m.code.sourceId}`);
+        for (let n = 2; used.has(id); n++)
+            id = slug(`${m.code.framework}-${m.code.sourceId}-${n}`);
+        used.add(id);
+        return { ...m, id };
+    });
+}
+//# sourceMappingURL=resolve.js.map

package/dist/reconciliation/review.js

@@ -0,0 +1,81 @@
+import { hashJson } from "../shared/index.js";
+import { cmp } from "./util.js";
+const PRIORITY = { high: 0, medium: 1, low: 2 };
+/**
+ * Everything a person must look at: open conflicts and every inferred fact. Derived from the contract and
+ * not stored in it; rebuilding it from the same contract gives the same list.
+ */
+export function buildReviewQueue(contract) {
+    const items = [];
+    for (const c of contract.conflicts) {
+        if (c.resolution.state !== "open")
+            continue;
+        items.push({
+            id: `rv_${hashJson({ kind: "conflict", id: c.id }).slice(0, 16)}`,
+            kind: "conflict",
+            conflictId: c.id,
+            subject: c.subject,
+            ...(c.path ? { path: c.path } : {}),
+            priority: c.severity === "error" ? "high" : c.severity === "warning" ? "medium" : "low",
+            reason: `${c.type}: ${c.claims.length} claims disagree${c.suggestedResolution ? `. ${c.suggestedResolution}` : ""}`,
+            evidenceIds: [...new Set(c.claims.flatMap((x) => x.evidenceIds))].sort(),
+            approvalRequired: true,
+            state: "open"
+        });
+    }
+    const entities = [
+        ...contract.components,
+        ...contract.tokens,
+        ...contract.guidelines,
+        ...contract.patterns,
+        ...contract.constraints
+    ];
+    for (const e of entities) {
+        for (const [path, fact] of Object.entries(e.facts)) {
+            if (fact.status !== "inferred")
+                continue;
+            const confidence = fact.confidence ?? 0;
+            items.push({
+                id: `rv_${hashJson({ kind: "inferred-fact", subject: e.id, path }).slice(0, 16)}`,
+                kind: "inferred-fact",
+                subject: e.id,
+                path,
+                priority: confidence < 0.6 ? "high" : confidence < 0.85 ? "medium" : "low",
+                reason: fact.derivation?.reasoning ?? "inferred",
+                confidence,
+                ...(fact.derivation ? { rule: fact.derivation.rule } : {}),
+                evidenceIds: [...fact.evidenceIds].sort(),
+                approvalRequired: true,
+                state: "pending"
+            });
+        }
+    }
+    // A pattern written by a person is `documented`, not approved: someone must still say it is the standard.
+    // Its constraints are listed too, so each fact can be approved on its own.
+    const owned = new Set(contract.patterns.flatMap((p) => p.constraints ?? []));
+    const authored = [
+        ...contract.patterns,
+        ...contract.constraints.filter((c) => owned.has(c.id))
+    ];
+    for (const e of authored)
+        for (const [path, fact] of Object.entries(e.facts)) {
+            if (fact.status !== "documented")
+                continue;
+            items.push({
+                id: `rv_${hashJson({ kind: "pattern-fact", subject: e.id, path }).slice(0, 16)}`,
+                kind: "pattern-fact",
+                subject: e.id,
+                path,
+                priority: "low",
+                reason: "Authored pattern definition that has not been approved. Approve it to make it a standard.",
+                evidenceIds: [...fact.evidenceIds].sort(),
+                approvalRequired: true,
+                state: "pending"
+            });
+        }
+    return items.sort((a, b) => PRIORITY[a.priority] - PRIORITY[b.priority] ||
+        cmp(a.subject, b.subject) ||
+        cmp(a.path ?? "", b.path ?? "") ||
+        cmp(a.kind, b.kind));
+}
+//# sourceMappingURL=review.js.map