@invariant-ui/cli 0.0.0-stage → 0.1.0

package/dist/reconciliation/components.js

@@ -0,0 +1,401 @@
+import { cmp, sameDomain, sameValue, setNested, slug, unique } from "./util.js";
+const ATTRS = {
+    props: ["type.text", "type.kind", "required", "default", "allowedValues", "description", "deprecated"],
+    events: ["payload.text", "description", "deprecated", "declared"],
+    slots: ["required", "description", "declared"],
+    variants: ["values", "default", "description"]
+};
+const COLLECTIONS = Object.keys(ATTRS);
+const IMPL_ATTRS = ["packageName", "exportName", "importPath"];
+const NAMESPACE = /^[a-z0-9][a-z0-9._-]*$/;
+const FRAMEWORKS = new Set(["react", "angular", "vue"]);
+function translate(path, impl) {
+    const seg = path.split(".");
+    const [head, second, ...tail] = seg;
+    const invariant = { t: "invariant", path: seg };
+    if (seg.length === 1 && (head === "name" || head === "description" || head === "lifecycle"))
+        return { t: head };
+    if (head && COLLECTIONS.includes(head) && second) {
+        const collection = head;
+        if (tail[0] === "extensions" &&
+            tail.length >= 3 &&
+            collection !== "variants" &&
+            NAMESPACE.test(tail[1]))
+            return { t: "item-ext", collection, name: second, ns: tail[1], rest: tail.slice(2) };
+        return ATTRS[collection].includes(tail.join("."))
+            ? { t: "item", collection, name: second, attr: tail.join(".") }
+            : invariant;
+    }
+    if (head === "accessibility" && seg.length === 2 && (second === "role" || second === "attributes"))
+        return { t: "a11y", attr: second };
+    if (head === "implementations" && second === impl.code.framework) {
+        if (tail.length === 1 && IMPL_ATTRS.includes(tail[0]))
+            return { t: "impl", attr: tail[0] };
+        if (tail.length === 1 && tail[0] === "framework")
+            return undefined;
+        if (tail[0] === "extensions" && tail.length >= 3 && NAMESPACE.test(tail[1]))
+            return { t: "impl-ext", ns: tail[1], rest: tail.slice(2) };
+        return invariant;
+    }
+    if (head === "examples" && second && tail.length === 1 && (tail[0] === "language" || tail[0] === "code"))
+        return { t: "example", id: second, attr: tail[0] };
+    if (head === "composition" && seg.length === 2 && (second === "subcomponents" || second === "renders"))
+        return { t: "composition", attr: second };
+    if (head === "extensions" && second && tail.length >= 1 && second !== "invariant" && NAMESPACE.test(second))
+        return { t: "ext", ns: second, rest: tail };
+    return invariant;
+}
+function cpathOf(target, impl, exampleId) {
+    switch (target.t) {
+        case "name":
+        case "description":
+        case "lifecycle":
+            return target.t;
+        case "item":
+            return `${target.collection}.${target.name}.${target.attr}`;
+        case "item-ext":
+            return `${target.collection}.${target.name}.extensions.${target.ns}.${target.rest.join(".")}`;
+        case "a11y":
+            return `accessibility.${target.attr}`;
+        case "impl":
+            return `implementations.${impl.id}.${target.attr}`;
+        case "impl-ext":
+            return `implementations.${impl.id}.extensions.${target.ns}.${target.rest.join(".")}`;
+        case "example":
+            return `examples.${exampleId(target.id)}.${target.attr}`;
+        case "ext":
+            return `extensions.${target.ns}.${target.rest.join(".")}`;
+        case "composition":
+            return `extensions.invariant.composition.${target.attr}`;
+        case "invariant":
+            return `extensions.invariant.${target.path.join(".")}`;
+    }
+}
+/** Comparison rule for a path when implementations disagree. Unlisted paths are never compared. */
+function comparison(target) {
+    switch (target.t) {
+        case "description":
+            return { type: "value-mismatch", severity: "info" };
+        case "lifecycle":
+            return { type: "deprecation-mismatch", severity: "warning" };
+        case "a11y":
+            return target.attr === "role"
+                ? { type: "value-mismatch", severity: "warning" }
+                : { type: "value-mismatch", severity: "info", domain: true };
+        case "item": {
+            const a = target.attr;
+            if (a === "required" || a === "default" || a === "values")
+                return { type: "value-mismatch", severity: "warning", domain: a === "values" };
+            if (a === "allowedValues")
+                return { type: "value-mismatch", severity: "warning", domain: true };
+            if (target.collection === "variants" && a === "default")
+                return { type: "value-mismatch", severity: "warning" };
+            if (a === "deprecated")
+                return undefined;
+            return { type: "value-mismatch", severity: "info" };
+        }
+        default:
+            return undefined;
+    }
+}
+const statusRank = (s) => (s === "discovered" ? 0 : 1);
+function choose(claims) {
+    return [...claims].sort((a, b) => statusRank(a.status) - statusRank(b.status) ||
+        cmp(a.impl.code.sourceId, b.impl.code.sourceId) ||
+        cmp(a.impl.id, b.impl.id))[0];
+}
+const evidenceOfImpl = (impl, path) => impl.facts.find((f) => f.path === path)?.evidenceIds ?? impl.facts[0]?.evidenceIds ?? [];
+/**
+ * Builds one contract component from the implementations judged to be the same. Facts, evidence and status
+ * come from the IR; nothing is added. Disagreeing implementations keep one value (see `choose`) and every
+ * claim is recorded as a conflict.
+ */
+export function buildComponent(resolved, ctx) {
+    const impls = resolved.implementations;
+    const multi = impls.length > 1;
+    const placed = [];
+    for (const impl of impls) {
+        const exampleId = (raw) => (multi ? slug(`${impl.id}-${raw}`) : raw);
+        for (const fact of impl.facts) {
+            const target = translate(fact.path, impl);
+            if (!target)
+                continue;
+            placed.push({
+                cpath: cpathOf(target, impl, exampleId),
+                target,
+                claim: {
+                    impl,
+                    value: fact.value,
+                    status: fact.origin === "extracted" ? "discovered" : "documented",
+                    evidenceIds: fact.evidenceIds
+                }
+            });
+        }
+    }
+    const byPath = new Map();
+    for (const p of placed)
+        byPath.set(p.cpath, [...(byPath.get(p.cpath) ?? []), p]);
+    const facts = {};
+    const chosen = new Map();
+    for (const [cpath, group] of [...byPath.entries()].sort((a, b) => cmp(a[0], b[0]))) {
+        const winner = choose(group.map((g) => g.claim));
+        const first = group.find((g) => g.claim === winner);
+        chosen.set(cpath, first);
+        const rule = comparison(first.target);
+        const same = rule?.domain ? sameDomain : sameValue;
+        const agreeing = group.filter((g) => same(g.claim.value, winner.value)).map((g) => g.claim);
+        const status = agreeing.some((c) => c.status === "discovered") ? "discovered" : "documented";
+        facts[cpath] = { status, evidenceIds: unique(agreeing.flatMap((c) => c.evidenceIds)).sort() };
+        const distinct = group.filter((g) => !same(g.claim.value, winner.value));
+        if (rule && distinct.length > 0) {
+            ctx.conflicts.push({
+                type: rule.type,
+                severity: rule.severity,
+                subject: resolved.id,
+                path: cpath,
+                claims: group
+                    .map((g) => ({
+                    sourceId: g.claim.impl.code.sourceId,
+                    value: g.claim.value,
+                    status: g.claim.status,
+                    evidenceIds: g.claim.evidenceIds
+                }))
+                    .sort((a, b) => cmp(a.sourceId, b.sourceId) || cmp(JSON.stringify(a.value), JSON.stringify(b.value))),
+                suggestedResolution: `Decide which ${cpath} is intended and align the other implementation, or accept the difference.`
+            });
+        }
+    }
+    const component = assemble(resolved, chosen, facts, ctx);
+    findMissingProps(resolved, ctx);
+    return component;
+}
+function assemble(resolved, chosen, facts, ctx) {
+    const items = {
+        props: new Map(),
+        events: new Map(),
+        slots: new Map(),
+        variants: new Map()
+    };
+    const item = (c, name) => {
+        const found = items[c].get(name);
+        if (found)
+            return found;
+        const created = { value: {}, ext: {} };
+        items[c].set(name, created);
+        return created;
+    };
+    const implementations = new Map(resolved.implementations.map((i) => [i.id, { value: {}, ext: {} }]));
+    const a11y = {};
+    const examples = new Map();
+    const extensions = {};
+    let description;
+    let lifecycle;
+    const place = (store, ns, rest, value, cpath) => {
+        store[ns] ??= {};
+        if (!setNested(store[ns], rest, value)) {
+            delete facts[cpath];
+            ctx.diagnostics.warning("reconcile.extension-collision", `${resolved.id}: ${cpath} collides with another extension path and was not placed`, { entityId: resolved.id });
+        }
+    };
+    const implOf = (cpath) => cpath.split(".")[1];
+    for (const [cpath, p] of chosen) {
+        const value = p.claim.value;
+        const t = p.target;
+        switch (t.t) {
+            case "name":
+                break;
+            case "description":
+                if (typeof value === "string")
+                    description = value;
+                break;
+            case "lifecycle":
+                if (value === "stable" || value === "experimental" || value === "deprecated")
+                    lifecycle = value;
+                break;
+            case "item": {
+                const draft = item(t.collection, t.name);
+                if (t.attr === "type.text" || t.attr === "type.kind") {
+                    const type = (draft.value.type ?? {});
+                    type[t.attr === "type.text" ? "text" : "kind"] = value;
+                    draft.value.type = type;
+                }
+                else if (t.attr === "payload.text") {
+                    draft.value.payload = { text: value };
+                }
+                else if (t.attr === "declared") {
+                    facts[`${t.collection}.${t.name}`] = facts[cpath];
+                    delete facts[cpath];
+                }
+                else if (t.attr === "deprecated") {
+                    draft.value.deprecated =
+                        typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+                }
+                else
+                    draft.value[t.attr] = value;
+                break;
+            }
+            case "item-ext": {
+                const draft = item(t.collection, t.name);
+                place(draft.ext, t.ns, t.rest, value, cpath);
+                break;
+            }
+            case "a11y":
+                a11y[t.attr] = value;
+                break;
+            case "impl":
+                ;
+                implementations.get(implOf(cpath)).value[t.attr] = value;
+                break;
+            case "impl-ext":
+                place(implementations.get(implOf(cpath)).ext, t.ns, t.rest, value, cpath);
+                break;
+            case "example": {
+                const id = cpath.split(".")[1];
+                const ex = examples.get(id) ?? {};
+                ex[t.attr] = value;
+                examples.set(id, ex);
+                break;
+            }
+            case "ext":
+                place(extensions, t.ns, t.rest, value, cpath);
+                break;
+            case "composition":
+                place(extensions, "invariant", ["composition", t.attr], value, cpath);
+                break;
+            case "invariant":
+                place(extensions, "invariant", t.path, value, cpath);
+                break;
+        }
+    }
+    const sources = new Map(resolved.implementations.map((i) => [i.id, i.code.sourceId]));
+    const composition = relationships(resolved, ctx, facts);
+    const sorted = (list) => list.sort((a, b) => cmp(a.name, b.name));
+    const withExt = (d) => Object.keys(d.ext).length > 0 ? { ...d.value, extensions: d.ext } : d.value;
+    for (const name of items.events.keys())
+        facts[`events.${name}`] ??= facts[`events.${name}.payload.text`];
+    const component = {
+        id: resolved.id,
+        name: resolved.name,
+        ...(description ? { description } : {}),
+        ...(lifecycle ? { lifecycle } : {}),
+        implementations: resolved.implementations
+            .map((i) => {
+            const d = implementations.get(i.id);
+            return {
+                id: i.id,
+                framework: FRAMEWORKS.has(i.code.framework) ? i.code.framework : "other",
+                sourceId: sources.get(i.id),
+                ...d.value,
+                ...(Object.keys(d.ext).length > 0 ? { extensions: d.ext } : {})
+            };
+        })
+            .sort((a, b) => cmp(a.id, b.id)),
+        props: sorted([...items.props].map(([name, d]) => ({
+            name,
+            type: { text: "unknown" },
+            required: false,
+            ...withExt(d)
+        }))),
+        events: sorted([...items.events].map(([name, d]) => ({ name, ...withExt(d) }))),
+        slots: sorted([...items.slots].map(([name, d]) => ({ name, ...withExt(d) }))),
+        variants: sorted([...items.variants]
+            .map(([name, d]) => ({ name, ...d.value, ...withoutEmptyValues(d.value) }))
+            .filter((v) => Array.isArray(v.values) && v.values.length > 0)),
+        states: [],
+        ...(Object.keys(a11y).length > 0 ? { accessibility: a11y } : {}),
+        examples: [...examples]
+            .filter(([, e]) => typeof e.code === "string" && e.code !== "" && typeof e.language === "string")
+            .map(([id, e]) => ({ id, language: e.language, code: e.code, sourceId: [...sources.values()][0] }))
+            .sort((a, b) => cmp(a.id, b.id)),
+        composition,
+        facts: sortedRecord(facts),
+        ...(Object.keys(extensions).length > 0 ? { extensions } : {})
+    };
+    return component;
+}
+/**
+ * The contract has no way to say "empty string" (a variant value and a default are at least one character), but a
+ * union such as `size?: "" | "small" | "large"` is common (Element Plus, Angular Material). Dropping the value keeps the
+ * contract valid; the rest of the domain is still enforced.
+ */
+function withoutEmptyValues(value) {
+    const values = Array.isArray(value.values) ? value.values.filter((v) => v !== "") : value.values;
+    return {
+        ...(values !== undefined ? { values: values } : {}),
+        ...(value.default === "" ? { default: undefined } : {})
+    };
+}
+function sortedRecord(record) {
+    return Object.fromEntries(Object.entries(record).sort((a, b) => cmp(a[0], b[0])));
+}
+/** `contains` relationships from static composition facts, resolved to contract component ids. */
+function relationships(resolved, ctx, facts) {
+    const targets = new Map();
+    for (const impl of resolved.implementations) {
+        for (const fact of impl.facts) {
+            if (fact.path !== "composition.subcomponents" && fact.path !== "composition.renders")
+                continue;
+            if (!Array.isArray(fact.value))
+                continue;
+            for (const entry of fact.value) {
+                const ref = typeof entry === "object" && entry !== null && !Array.isArray(entry)
+                    ? (entry.ref ?? entry.target)
+                    : undefined;
+                if (typeof ref !== "string")
+                    continue;
+                const id = ctx.refToId.get(ref);
+                if (!id) {
+                    ctx.diagnostics.info("reconcile.composition-target-unresolved", `${resolved.id} refers to ${ref}, which is not a public component`, {
+                        entityId: resolved.id,
+                        sourceId: impl.code.sourceId
+                    });
+                    continue;
+                }
+                if (id === resolved.id)
+                    continue;
+                targets.set(id, unique([...(targets.get(id) ?? []), ...fact.evidenceIds]).sort());
+            }
+        }
+    }
+    const list = [...targets.entries()].sort((a, b) => cmp(a[0], b[0]));
+    return list.map(([target, evidenceIds], index) => {
+        facts[`composition.${index}`] = { status: "discovered", evidenceIds };
+        return { type: "contains", target: target };
+    });
+}
+/** A prop one implementation declares and another, whose props are fully known, lacks. */
+function findMissingProps(resolved, ctx) {
+    const impls = resolved.implementations;
+    if (impls.length < 2)
+        return;
+    const names = unique(impls.flatMap((i) => [...i.code.props.values()].filter((p) => !p.role || p.role === "prop").map((p) => p.name))).sort();
+    for (const name of names) {
+        const has = impls.filter((i) => i.code.props.has(name));
+        const lacks = impls.filter((i) => !i.code.props.has(name) && i.code.propsComplete);
+        if (lacks.length === 0)
+            continue;
+        ctx.conflicts.push({
+            type: "existence-mismatch",
+            severity: "info",
+            subject: resolved.id,
+            path: `props.${name}`,
+            claims: [
+                ...has.map((i) => ({
+                    sourceId: i.code.sourceId,
+                    value: true,
+                    status: "discovered",
+                    evidenceIds: i.code.props.get(name)?.evidence.declared.length
+                        ? i.code.props.get(name)?.evidence.declared
+                        : evidenceOfImpl(i, `props.${name}.type.text`)
+                })),
+                ...lacks.map((i) => ({
+                    sourceId: i.code.sourceId,
+                    status: "discovered",
+                    evidenceIds: evidenceOfImpl(i, `implementations.${i.code.framework}.extensions.${i.code.framework}.propsComplete`)
+                }))
+            ].sort((a, b) => cmp(a.sourceId, b.sourceId)),
+            suggestedResolution: "Frameworks may differ legitimately; confirm the prop is meant to exist in every implementation."
+        });
+    }
+}
+//# sourceMappingURL=components.js.map

package/dist/reconciliation/conflicts.js

@@ -0,0 +1,126 @@
+import { cmp, sameValue, slug, unique } from "./util.js";
+/**
+ * Storybook findings that cite evidence on both sides become conflicts: a story or control says one thing
+ * and the implementation another. Coverage findings (not demonstrated, unlinked, unverifiable) stay
+ * diagnostics, because a conflict needs two evidenced claims.
+ */
+export function storybookConflicts(discrepancies, refToId, implementations) {
+    const drafts = [];
+    for (const d of discrepancies) {
+        const subject = d.component ? refToId.get(d.component) : undefined;
+        const impl = d.component ? implementations.get(d.component) : undefined;
+        if (!subject || !d.prop || !d.claim || d.storybookEvidence.length === 0)
+            continue;
+        const code = d.code.replace("reconcile.storybook.", "");
+        const base = { subject: subject, severity: d.severity };
+        const storybook = (value) => ({
+            sourceId: d.sourceId,
+            ...(value === undefined ? {} : { value }),
+            status: "discovered",
+            evidenceIds: d.storybookEvidence
+        });
+        const codeEvidence = d.codeEvidence.length > 0
+            ? d.codeEvidence
+            : (impl?.facts.find((f) => f.path.endsWith(".propsComplete"))?.evidenceIds ?? []);
+        if (codeEvidence.length === 0 || !impl)
+            continue;
+        const codeClaim = (value) => ({
+            sourceId: impl.code.sourceId,
+            ...(value === undefined ? {} : { value }),
+            status: "discovered",
+            evidenceIds: codeEvidence
+        });
+        if (code === "arg-value-not-allowed" || code === "control-option-not-allowed")
+            drafts.push({
+                ...base,
+                type: "value-mismatch",
+                path: `props.${d.prop}.allowedValues`,
+                claims: [codeClaim(d.claim.code), storybook(d.claim.storybook)],
+                suggestedResolution: "Change the story or control to a declared value, or add the value to the component."
+            });
+        else if (code === "default-mismatch")
+            drafts.push({
+                ...base,
+                type: "value-mismatch",
+                path: `props.${d.prop}.default`,
+                claims: [codeClaim(d.claim.code), storybook(d.claim.storybook)],
+                suggestedResolution: "Update the documented default or the code default."
+            });
+        else if (code === "arg-undeclared" || code === "control-undeclared")
+            drafts.push({
+                ...base,
+                type: "existence-mismatch",
+                path: `props.${d.prop}`,
+                claims: [codeClaim(), storybook(true)],
+                suggestedResolution: "Remove the arg or control, or add the prop to the component."
+            });
+        else if (code === "deprecated-demonstrated")
+            drafts.push({
+                ...base,
+                type: "deprecation-mismatch",
+                path: `props.${d.prop}.deprecated`,
+                claims: [codeClaim(true), storybook()],
+                suggestedResolution: "Stop demonstrating the deprecated prop, or mark it as supported."
+            });
+    }
+    return drafts;
+}
+export function ambiguityConflicts(ambiguities, refToId) {
+    const out = [];
+    for (const a of ambiguities) {
+        const first = a.candidates[0];
+        const subject = first ? refToId.get(first.code.ref) : undefined;
+        if (!first || !subject)
+            continue;
+        out.push({
+            type: "identity-ambiguity",
+            severity: "warning",
+            subject: subject,
+            claims: a.candidates.map((c) => ({
+                sourceId: c.code.sourceId,
+                value: c.code.ref,
+                status: "discovered",
+                evidenceIds: c.facts.find((f) => f.path === "name")?.evidenceIds ?? c.facts[0]?.evidenceIds ?? []
+            })),
+            suggestedResolution: `Several implementations match the name "${a.key}" and no single pairing is certain. They were not merged; link the ones that are the same component.`
+        });
+    }
+    return out;
+}
+/** Merges drafts about the same subject and path, then mints stable ids. Claims are never dropped. */
+export function mintConflicts(drafts) {
+    const grouped = new Map();
+    for (const d of drafts) {
+        const key = `${d.type}\u0000${d.subject}\u0000${d.path ?? ""}`;
+        let existing = grouped.get(key);
+        if (!existing) {
+            existing = { ...d, claims: [] };
+            grouped.set(key, existing);
+        }
+        else if (d.severity === "warning" || (d.severity === "error" && existing.severity !== "error"))
+            existing.severity = d.severity;
+        for (const claim of d.claims) {
+            const same = existing.claims.find((c) => c.sourceId === claim.sourceId && c.status === claim.status && sameValue(c.value, claim.value));
+            if (same)
+                same.evidenceIds = unique([...same.evidenceIds, ...claim.evidenceIds]).sort();
+            else
+                existing.claims.push({ ...claim });
+        }
+    }
+    const used = new Set();
+    const out = [];
+    for (const [, d] of [...grouped.entries()].sort((a, b) => cmp(a[0], b[0]))) {
+        const subject = d.subject.slice(d.subject.indexOf(":") + 1);
+        const base = `conflict:${d.type}/${slug(subject)}${d.path ? `/${slug(d.path)}` : ""}`;
+        let id = base;
+        for (let n = 2; used.has(id); n++)
+            id = `${base}-${n}`;
+        used.add(id);
+        const claims = d.claims
+            .map((c) => ({ ...c, evidenceIds: unique(c.evidenceIds).sort() }))
+            .sort((a, b) => cmp(a.sourceId, b.sourceId) || cmp(JSON.stringify(a.value ?? null), JSON.stringify(b.value ?? null)));
+        out.push({ ...d, id: id, claims, resolution: { state: "open" } });
+    }
+    return out;
+}
+//# sourceMappingURL=conflicts.js.map

package/dist/reconciliation/facts.js

@@ -0,0 +1,41 @@
+/** Facts of one document grouped by subject and path, for cheap lookup. */
+export class FactIndex {
+    doc;
+    bySubject = new Map();
+    evidence = new Map();
+    constructor(doc) {
+        this.doc = doc;
+        for (const e of doc.evidence)
+            this.evidence.set(e.id, e);
+        for (const fact of doc.facts) {
+            const paths = this.bySubject.get(fact.subject) ?? new Map();
+            paths.set(fact.path, [...(paths.get(fact.path) ?? []), fact]);
+            this.bySubject.set(fact.subject, paths);
+        }
+    }
+    get(subject, path) {
+        return this.bySubject.get(subject)?.get(path)?.[0];
+    }
+    value(subject, path) {
+        return this.get(subject, path)?.value;
+    }
+    /** Paths under `prefix.` for a subject, as the first segment after the prefix. */
+    children(subject, prefix) {
+        const names = new Set();
+        for (const path of this.bySubject.get(subject)?.keys() ?? []) {
+            if (path.startsWith(`${prefix}.`))
+                names.add(path.slice(prefix.length + 1).split(".")[0]);
+        }
+        return [...names].sort();
+    }
+    evidenceIds(subject, path) {
+        return this.get(subject, path)?.evidenceIds ?? [];
+    }
+    location(evidenceId) {
+        const location = (evidenceId ? this.evidence.get(evidenceId) : undefined)?.location;
+        if (location?.type !== "file")
+            return undefined;
+        return { path: location.path, ...(location.line ? { line: location.line } : {}) };
+    }
+}
+//# sourceMappingURL=facts.js.map

package/dist/reconciliation/index.js

@@ -0,0 +1,7 @@
+export { codeComponents } from "./code.js";
+export { FactIndex } from "./facts.js";
+export { finalizeAndVerify, reconcile } from "./reconcile.js";
+export { resolveComponents, sharedPrefix } from "./resolve.js";
+export { buildReviewQueue } from "./review.js";
+export { reconcileStorybook } from "./storybook.js";
+//# sourceMappingURL=index.js.map