@invariant-ui/cli 0.0.0-stage → 0.1.0

package/dist/reconciliation/storybook.js

@@ -0,0 +1,370 @@
+import { sortDiagnostics } from "../shared/index.js";
+import { codeComponents } from "./code.js";
+import { FactIndex } from "./facts.js";
+const PREFIX = { group: "group", story: "story" };
+/**
+ * Compares Storybook sources with code sources. A Storybook control or arg is never taken as proof that
+ * an API exists: it is checked against the implementation's own facts, and claims are only made when the
+ * implementation's props are fully known (`propsComplete`). Findings carry evidence from both sides.
+ */
+export function reconcileStorybook(docs) {
+    const components = codeComponents(docs);
+    const byKey = new Map(components.map((c) => [`${c.file}#${c.localName}`, c]));
+    const links = [];
+    const found = [];
+    const demonstrated = new Map();
+    for (const doc of docs.filter((d) => d.source.type === "storybook")) {
+        const index = new FactIndex(doc);
+        const storiesByGroup = new Map();
+        for (const e of doc.entities.filter((x) => x.kind === "story")) {
+            const group = index.value(e.ref, "story.group");
+            if (group)
+                storiesByGroup.set(group, [...(storiesByGroup.get(group) ?? []), e.ref]);
+        }
+        for (const groupEntity of doc.entities.filter((e) => e.kind === "story-group")) {
+            const target = index.value(groupEntity.ref, "group.component");
+            if (!target?.file || !target.name)
+                continue;
+            const component = byKey.get(`${target.file}#${target.name}`);
+            const storyRefs = (storiesByGroup.get(groupEntity.ref) ?? []).sort();
+            if (!component) {
+                found.push({
+                    code: "reconcile.storybook.component-unlinked",
+                    severity: "info",
+                    message: `${groupEntity.name} points at ${target.name} in ${target.file}, but no compiled source has a public component there`,
+                    sourceId: doc.source.id,
+                    entityId: groupEntity.ref,
+                    storybookEvidence: index.evidenceIds(groupEntity.ref, "group.component"),
+                    codeEvidence: [],
+                    ...locationOf(index, index.evidenceIds(groupEntity.ref, "group.component"))
+                });
+                continue;
+            }
+            links.push({
+                group: groupEntity.ref,
+                storySourceId: doc.source.id,
+                stories: storyRefs,
+                component: component.ref,
+                componentSourceId: component.sourceId,
+                via: target.via ?? "component",
+                matchedBy: "file+localName"
+            });
+            const storyViews = storyRefs.map((ref) => view(index, ref, PREFIX.story, doc.entities.find((e) => e.ref === ref)?.name ?? ref, index.value(ref, "story.hasRender") === false));
+            // Meta-level args reach the component only through stories that use the default render.
+            const groupView = view(index, groupEntity.ref, PREFIX.group, groupEntity.name, storyViews.some((v) => v.defaultRender));
+            const seen = demonstrated.get(component) ?? {
+                names: new Set(),
+                values: new Map(),
+                uncertain: new Set(),
+                storyCount: 0
+            };
+            demonstrated.set(component, seen);
+            seen.storyCount += storyViews.length;
+            const unverifiable = { inherited: new Set(), render: new Set() };
+            // Meta-level annotations are checked once; each story's own annotations are checked at the story.
+            for (const v of [groupView, ...storyViews]) {
+                checkView({ doc, index, view: v, inherited: groupView, component, found, seen, unverifiable });
+            }
+            for (const [names, reason] of [
+                [unverifiable.inherited, `whose props are inherited from types that were not enumerated`],
+                [
+                    unverifiable.render,
+                    `because the stories that pass them use a custom render, so the args may not be ${component.name}'s props`
+                ]
+            ]) {
+                if (names.size === 0)
+                    continue;
+                found.push({
+                    code: "reconcile.storybook.unverifiable-names",
+                    severity: "info",
+                    message: `${groupEntity.name}: ${[...names].sort().slice(0, 10).join(", ")}${names.size > 10 ? ", …" : ""} could not be verified against ${component.name}, ${reason}`,
+                    sourceId: doc.source.id,
+                    entityId: groupEntity.ref,
+                    component: component.ref,
+                    storybookEvidence: [],
+                    codeEvidence: []
+                });
+            }
+            if (component.deprecated) {
+                found.push({
+                    code: "reconcile.storybook.deprecated-demonstrated",
+                    severity: "warning",
+                    message: `${groupEntity.name} demonstrates ${component.name}, which is marked deprecated`,
+                    sourceId: doc.source.id,
+                    entityId: groupEntity.ref,
+                    component: component.ref,
+                    storybookEvidence: index.evidenceIds(groupEntity.ref, "group.component"),
+                    codeEvidence: component.index.evidenceIds(component.ref, "lifecycle"),
+                    ...locationOf(index, index.evidenceIds(groupEntity.ref, "group.component"))
+                });
+            }
+        }
+    }
+    for (const [component, seen] of demonstrated)
+        coverage(component, seen, found);
+    const discrepancies = found.sort(compare);
+    return {
+        links: links.sort((a, b) => (a.group < b.group ? -1 : 1)),
+        discrepancies,
+        diagnostics: sortDiagnostics(discrepancies.map(toDiagnostic))
+    };
+}
+function view(index, ref, prefix, name, defaultRender) {
+    const args = new Map();
+    for (const arg of index.children(ref, `${prefix}.args`))
+        args.set(arg, {
+            value: index.value(ref, `${prefix}.args.${arg}`),
+            evidence: index.evidenceIds(ref, `${prefix}.args.${arg}`)
+        });
+    const unresolved = new Set();
+    for (const path of [...(index.value(ref, `${prefix}.argsUnresolved`) ?? [])]) {
+        const first = path.split(".")[0];
+        if (first && first !== "..." && first !== "<computed>")
+            unresolved.add(first);
+    }
+    const argTypes = new Map();
+    for (const prop of index.children(ref, `${prefix}.argTypes`)) {
+        if (prop === "")
+            continue;
+        const base = `${prefix}.argTypes.${prop}`;
+        const options = index.value(ref, `${base}.options`);
+        const optionsFact = index.get(ref, `${base}.options`);
+        const mapping = index.value(ref, `${base}.mappingKeys`);
+        const summary = index.value(ref, `${base}.defaultSummary`);
+        argTypes.set(prop, {
+            ...(options ? { options } : {}),
+            optionsUncertain: index.get(ref, `${base}.optionsUnresolved`) !== undefined || optionsFact?.completeness === "partial",
+            ...(mapping ? { mappingKeys: mapping } : {}),
+            ...(summary === undefined ? {} : { defaultSummary: summary }),
+            hidden: index.value(ref, `${base}.hidden`) === true,
+            evidence: index.evidenceIds(ref, `${base}.declared`),
+            defaultEvidence: index.evidenceIds(ref, `${base}.defaultSummary`)
+        });
+    }
+    return { ref, name, defaultRender, args, unresolvedArgs: unresolved, argTypes };
+}
+function checkView(input) {
+    const { doc, index, view: v, inherited, component, found, seen, unverifiable } = input;
+    const declared = (name) => component.props.has(name) ||
+        component.variantNames.has(name) ||
+        (name === "children" && (component.slotNames.has("default") || component.props.has("children")));
+    const add = (d) => {
+        found.push({
+            ...d,
+            sourceId: doc.source.id,
+            entityId: v.ref,
+            component: component.ref,
+            ...locationOf(index, d.storybookEvidence)
+        });
+    };
+    const argNames = new Set([...v.args.keys(), ...v.unresolvedArgs]);
+    for (const name of argNames) {
+        seen.names.add(name);
+        const prop = component.props.get(name);
+        const arg = v.args.get(name);
+        // With a mapping at either level, an arg value is a mapping key rather than the real prop value.
+        const mapped = v.argTypes.get(name)?.mappingKeys !== undefined ||
+            inherited.argTypes.get(name)?.mappingKeys !== undefined;
+        if (v.unresolvedArgs.has(name))
+            seen.uncertain.add(name);
+        if (!v.defaultRender) {
+            // Args of a custom-render story are not attributed to the component: no claim either way.
+            if (!declared(name))
+                unverifiable.render.add(name);
+            continue;
+        }
+        if (!declared(name)) {
+            if (component.propsComplete) {
+                add({
+                    code: "reconcile.storybook.arg-undeclared",
+                    severity: "warning",
+                    message: `${v.name} passes arg "${name}", which ${component.name} does not declare as a prop`,
+                    prop: name,
+                    storybookEvidence: arg?.evidence ?? [],
+                    codeEvidence: [],
+                    claim: { storybook: true }
+                });
+            }
+            else
+                unverifiable.inherited.add(name);
+            continue;
+        }
+        if (prop?.deprecated) {
+            add({
+                code: "reconcile.storybook.deprecated-demonstrated",
+                severity: "warning",
+                message: `${v.name} uses arg "${name}", a deprecated prop of ${component.name}`,
+                prop: name,
+                storybookEvidence: arg?.evidence ?? [],
+                codeEvidence: prop.evidence.deprecated,
+                claim: { storybook: true, code: "deprecated" }
+            });
+        }
+        if (arg && prop?.allowedValues && isScalar(arg.value) && !mapped) {
+            const key = String(arg.value);
+            const values = valuesFor(seen, name);
+            values.add(key);
+            if (!prop.allowedValues.some((a) => a === arg.value)) {
+                add({
+                    code: "reconcile.storybook.arg-value-not-allowed",
+                    severity: "warning",
+                    message: `${v.name} sets ${component.name}.${name} to ${JSON.stringify(arg.value)}, which is not one of its declared values (${prop.allowedValues.map((a) => JSON.stringify(a)).join(", ")})`,
+                    prop: name,
+                    storybookEvidence: arg.evidence,
+                    codeEvidence: prop.evidence.allowedValues,
+                    claim: { storybook: arg.value, code: prop.allowedValues }
+                });
+            }
+        }
+    }
+    for (const [name, at] of v.argTypes) {
+        seen.names.add(name);
+        const prop = component.props.get(name);
+        if (!declared(name)) {
+            if (at.hidden)
+                continue;
+            if (component.propsComplete) {
+                add({
+                    code: "reconcile.storybook.control-undeclared",
+                    severity: "warning",
+                    message: `${v.name} documents a control for "${name}", which ${component.name} does not declare as a prop`,
+                    prop: name,
+                    storybookEvidence: at.evidence,
+                    codeEvidence: [],
+                    claim: { storybook: true }
+                });
+            }
+            else
+                unverifiable.inherited.add(name);
+            continue;
+        }
+        if (prop?.deprecated && !at.hidden) {
+            add({
+                code: "reconcile.storybook.deprecated-demonstrated",
+                severity: "warning",
+                message: `${v.name} documents a control for "${name}", a deprecated prop of ${component.name}`,
+                prop: name,
+                storybookEvidence: at.evidence,
+                codeEvidence: prop.evidence.deprecated,
+                claim: { storybook: true, code: "deprecated" }
+            });
+        }
+        if (at.options && !at.mappingKeys && !at.optionsUncertain) {
+            const values = valuesFor(seen, name);
+            for (const o of at.options)
+                values.add(String(o));
+            if (prop?.allowedValues) {
+                const extra = at.options.filter((o) => !prop.allowedValues?.some((a) => a === o));
+                if (extra.length > 0) {
+                    add({
+                        code: "reconcile.storybook.control-option-not-allowed",
+                        severity: "warning",
+                        message: `${v.name}: the control for ${component.name}.${name} offers ${extra.map((o) => JSON.stringify(o)).join(", ")}, which the component does not declare`,
+                        prop: name,
+                        storybookEvidence: at.evidence,
+                        codeEvidence: prop.evidence.allowedValues,
+                        claim: { storybook: extra, code: prop.allowedValues }
+                    });
+                }
+            }
+        }
+        else if (at.options || at.optionsUncertain || at.mappingKeys)
+            seen.uncertain.add(name);
+        if (at.defaultSummary !== undefined &&
+            prop &&
+            prop.default !== undefined &&
+            normalize(at.defaultSummary) !== normalize(prop.default)) {
+            add({
+                code: "reconcile.storybook.default-mismatch",
+                severity: "warning",
+                message: `${v.name} documents the default of ${component.name}.${name} as ${at.defaultSummary}, but the code default is ${JSON.stringify(prop.default)}`,
+                prop: name,
+                storybookEvidence: at.defaultEvidence,
+                codeEvidence: prop.evidence.default,
+                claim: { storybook: normalize(at.defaultSummary), code: prop.default }
+            });
+        }
+    }
+}
+/** Props and declared values no linked story demonstrates. Only claimed where the story side is fully known. */
+function coverage(component, seen, found) {
+    if (seen.storyCount === 0)
+        return;
+    const skipRoles = new Set(["children", "ref", "event-handler"]);
+    const missing = [...component.props.values()]
+        .filter((p) => !skipRoles.has(p.role ?? "") && !seen.names.has(p.name) && !component.variantNames.has(p.name))
+        .map((p) => p.name);
+    if (missing.length > 0) {
+        found.push({
+            code: "reconcile.storybook.prop-not-demonstrated",
+            severity: "info",
+            message: `${component.name} declares ${missing.slice(0, 10).join(", ")}${missing.length > 10 ? ", …" : ""}, which no story passes as an arg or documents as a control`,
+            sourceId: component.sourceId,
+            entityId: component.ref,
+            component: component.ref,
+            storybookEvidence: [],
+            codeEvidence: missing.flatMap((m) => component.props.get(m)?.evidence.declared ?? [])
+        });
+    }
+    for (const prop of component.props.values()) {
+        if (!prop.allowedValues ||
+            prop.allowedValues.length < 2 ||
+            seen.uncertain.has(prop.name) ||
+            !seen.names.has(prop.name))
+            continue;
+        const shown = seen.values.get(prop.name) ?? new Set();
+        const absent = prop.allowedValues.filter((v) => !shown.has(String(v)));
+        if (absent.length > 0) {
+            found.push({
+                code: "reconcile.storybook.value-not-demonstrated",
+                severity: "info",
+                message: `${component.name}.${prop.name} declares ${absent
+                    .slice(0, 8)
+                    .map((v) => JSON.stringify(v))
+                    .join(", ")}${absent.length > 8 ? `, … (${absent.length} in all)` : ""}, which no story or control demonstrates`,
+                sourceId: component.sourceId,
+                entityId: component.ref,
+                component: component.ref,
+                prop: prop.name,
+                storybookEvidence: [],
+                codeEvidence: prop.evidence.allowedValues
+            });
+        }
+    }
+}
+function valuesFor(seen, name) {
+    const existing = seen.values.get(name);
+    if (existing)
+        return existing;
+    const created = new Set();
+    seen.values.set(name, created);
+    return created;
+}
+function isScalar(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+/** Compares a documented default (`'md'`, `"md"`, `md`, `false`) with a code default. */
+function normalize(value) {
+    const text = String(value).trim();
+    return text.replace(/^(["'`])(.*)\1$/s, "$2");
+}
+function locationOf(index, evidenceIds) {
+    const location = index.location(evidenceIds[0]);
+    return location ? { location } : {};
+}
+function compare(a, b) {
+    const key = (d) => `${d.code}\u0000${d.sourceId}\u0000${d.entityId}\u0000${d.prop ?? ""}\u0000${d.message}`;
+    const order = { error: 0, warning: 1, info: 2 };
+    return order[a.severity] - order[b.severity] || (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0);
+}
+function toDiagnostic(d) {
+    return {
+        code: d.code,
+        severity: d.severity,
+        message: d.message,
+        sourceId: d.sourceId,
+        entityId: d.entityId,
+        ...(d.location ? { location: d.location } : {})
+    };
+}
+//# sourceMappingURL=storybook.js.map

package/dist/reconciliation/tokens.js

@@ -0,0 +1,179 @@
+import { cmp, normalizeName, sameValue, setNested, slug, unique } from "./util.js";
+const STATUS = (f) => f.origin === "extracted" ? "discovered" : "documented";
+const rank = (s) => (s === "discovered" ? 0 : 1);
+const themeId = (mode) => `theme:${slug(mode).replace(/\./g, "-")}`;
+/** Token entities from design-token adapters: the ones that state a value. Inventory entries do not. */
+function sourcesOf(docs) {
+    const out = [];
+    for (const doc of docs) {
+        const bySubject = new Map();
+        for (const f of doc.facts)
+            bySubject.set(f.subject, [...(bySubject.get(f.subject) ?? []), f]);
+        for (const e of doc.entities.filter((x) => x.kind === "token")) {
+            const facts = bySubject.get(e.ref) ?? [];
+            if (!facts.some((f) => f.path === "value.value" || f.path === "value.aliasOf"))
+                continue;
+            const name = facts.find((f) => f.path === "name" && typeof f.value === "string")?.value;
+            out.push({ doc, ref: e.ref, name: typeof name === "string" ? name : e.name, facts });
+        }
+    }
+    return out.sort((a, b) => cmp(a.doc.source.id, b.doc.source.id) || cmp(a.ref, b.ref));
+}
+export function buildTokens(docs, ctx) {
+    const sources = sourcesOf(docs);
+    const groups = new Map();
+    for (const s of sources)
+        groups.set(normalizeName(s.name), [...(groups.get(normalizeName(s.name)) ?? []), s]);
+    const ids = new Map();
+    const used = new Set();
+    const names = new Map();
+    for (const [key, members] of [...groups.entries()].sort((a, b) => cmp(a[0], b[0]))) {
+        const name = members.find((m) => m.name.includes("."))?.name ?? members[0].name;
+        let id = `token:${slug(name)}`;
+        for (let n = 2; used.has(id); n++)
+            id = `token:${slug(name)}-${n}`;
+        used.add(id);
+        ids.set(key, id);
+        names.set(key, name);
+    }
+    const themes = new Map();
+    const identities = [];
+    const tokens = [];
+    for (const [key, members] of [...groups.entries()].sort((a, b) => cmp(a[0], b[0]))) {
+        const id = ids.get(key);
+        const spellings = unique(members.map((m) => m.name)).sort();
+        if (spellings.length > 1) {
+            identities.push({
+                tokenId: id,
+                link: {
+                    rule: "name-match.token",
+                    confidence: 0.8,
+                    reasoning: `${spellings.map((s) => `"${s}"`).join(", ")} differ only in case or separators and are treated as one token`,
+                    inputs: members.map((m) => m.ref).sort(),
+                    evidenceIds: unique(members.flatMap((m) => m.facts.find((f) => f.path === "name")?.evidenceIds ?? [])).sort()
+                }
+            });
+        }
+        const facts = {};
+        const extensions = {};
+        const slots = new Map();
+        let description;
+        let deprecated;
+        for (const src of members) {
+            for (const f of src.facts) {
+                const seg = f.path.split(".");
+                if (f.path === "value.value" ||
+                    f.path === "value.aliasOf" ||
+                    (seg[0] === "modes" && seg.length === 3 && (seg[2] === "value" || seg[2] === "aliasOf"))) {
+                    const slot = seg[0] === "modes" ? `modes.${themeId(seg[1])}` : "value";
+                    if (seg[0] === "modes") {
+                        const tid = themeId(seg[1]);
+                        if (!themes.has(tid))
+                            themes.set(tid, { id: tid, name: seg[1] });
+                    }
+                    let form;
+                    if (seg[seg.length - 1] === "aliasOf") {
+                        const target = ids.get(normalizeName(String(f.value)));
+                        if (!target) {
+                            ctx.diagnostics.warning("reconcile.token-alias-unresolved", `${id} aliases "${String(f.value)}", which is not a known token; its source text is kept as a literal`, { entityId: id, sourceId: src.doc.source.id });
+                            const raw = src.facts.find((x) => /^extensions\.[^.]+\.(root\.)?rawValue$/.test(x.path))?.value;
+                            form = { value: raw ?? String(f.value) };
+                        }
+                        else
+                            form = { aliasOf: target };
+                    }
+                    else
+                        form = { value: f.value };
+                    slots.set(slot, [
+                        ...(slots.get(slot) ?? []),
+                        { src, form, status: STATUS(f), evidenceIds: f.evidenceIds }
+                    ]);
+                }
+                else if (f.path === "description" && typeof f.value === "string")
+                    description ??= { value: f.value, claim: f };
+                else if (f.path === "deprecated") {
+                    deprecated ??= {
+                        value: typeof f.value === "object" && f.value !== null && !Array.isArray(f.value)
+                            ? f.value
+                            : {},
+                        claim: f
+                    };
+                }
+                else if (seg[0] === "extensions" &&
+                    seg.length >= 3 &&
+                    /^[a-z0-9][a-z0-9._-]*$/.test(seg[1]) &&
+                    seg[1] !== "invariant") {
+                    extensions[seg[1]] ??= {};
+                    if (setNested(extensions[seg[1]], seg.slice(2), f.value))
+                        facts[f.path] = { status: STATUS(f), evidenceIds: f.evidenceIds };
+                }
+            }
+        }
+        const formOf = (slot) => {
+            const claims = slots.get(slot);
+            if (!claims)
+                return undefined;
+            const win = [...claims].sort((a, b) => rank(a.status) - rank(b.status) ||
+                cmp(a.src.doc.source.id, b.src.doc.source.id) ||
+                cmp(a.src.ref, b.src.ref))[0];
+            const agreeing = claims.filter((c) => sameValue(c.form, win.form));
+            const field = "aliasOf" in win.form ? "aliasOf" : "value";
+            facts[slot === "value" ? `value.${field}` : `${slot}.${field}`] = {
+                status: agreeing.some((c) => c.status === "discovered") ? "discovered" : "documented",
+                evidenceIds: unique(agreeing.flatMap((c) => c.evidenceIds)).sort()
+            };
+            if (agreeing.length < claims.length) {
+                ctx.conflicts.push({
+                    type: "token-value-mismatch",
+                    severity: "warning",
+                    subject: id,
+                    path: slot,
+                    claims: claims
+                        .map((c) => ({
+                        sourceId: c.src.doc.source.id,
+                        value: c.form,
+                        status: c.status,
+                        evidenceIds: c.evidenceIds
+                    }))
+                        .sort((a, b) => cmp(a.sourceId, b.sourceId) || cmp(JSON.stringify(a.value), JSON.stringify(b.value))),
+                    suggestedResolution: "Decide which value is intended and remove the other definition."
+                });
+            }
+            return win.form;
+        };
+        const main = formOf("value");
+        const modes = {};
+        for (const slot of [...slots.keys()].filter((s) => s.startsWith("modes.")).sort()) {
+            const form = formOf(slot);
+            if (form)
+                modes[slot.slice("modes.".length)] = form;
+        }
+        const name = names.get(key);
+        facts.name = {
+            status: "discovered",
+            evidenceIds: unique(members.flatMap((m) => m.facts.find((f) => f.path === "name")?.evidenceIds ?? [])).sort()
+        };
+        if (description) {
+            facts.description = { status: STATUS(description.claim), evidenceIds: description.claim.evidenceIds };
+        }
+        if (deprecated)
+            facts.deprecated = { status: STATUS(deprecated.claim), evidenceIds: deprecated.claim.evidenceIds };
+        tokens.push({
+            id: id,
+            name,
+            category: "other",
+            ...(description ? { description: description.value } : {}),
+            value: main,
+            ...(Object.keys(modes).length > 0 ? { modes: modes } : {}),
+            ...(deprecated ? { deprecated: deprecated.value } : {}),
+            facts: Object.fromEntries(Object.entries(facts).sort((a, b) => cmp(a[0], b[0]))),
+            ...(Object.keys(extensions).length > 0 ? { extensions } : {})
+        });
+    }
+    return {
+        tokens: tokens.sort((a, b) => cmp(a.id, b.id)),
+        themes: [...themes.values()].sort((a, b) => cmp(a.id, b.id)),
+        identities
+    };
+}
+//# sourceMappingURL=tokens.js.map

package/dist/reconciliation/util.js

@@ -0,0 +1,55 @@
+import { canonicalStringify } from "../shared/index.js";
+export function cmp(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Lower-case id segment matching the contract's name grammar `[a-z0-9][a-z0-9._-]*`. */
+export function slug(text) {
+    const s = text
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^[^a-z0-9]+/, "")
+        .replace(/-{2,}/g, "-")
+        .replace(/[-.]+$/, "");
+    return s === "" ? "x" : s;
+}
+/** Equality key for names: case and separators are ignored. */
+export function normalizeName(text) {
+    return text.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+export function sameValue(a, b) {
+    return (canonicalStringify(a ?? null) === canonicalStringify(b ?? null) && (a === undefined) === (b === undefined));
+}
+/** Order-insensitive equality for arrays of scalars (value domains); other values compare exactly. */
+export function sameDomain(a, b) {
+    if (Array.isArray(a) && Array.isArray(b)) {
+        const key = (v) => canonicalStringify(v);
+        return canonicalStringify([...a].map(key).sort()) === canonicalStringify([...b].map(key).sort());
+    }
+    return sameValue(a, b);
+}
+/** Sets `value` at a nested path. Returns false when the path collides with an existing leaf or branch. */
+export function setNested(target, segments, value) {
+    let node = target;
+    for (let i = 0; i < segments.length - 1; i++) {
+        const key = segments[i];
+        const next = node[key];
+        if (next === undefined) {
+            const created = {};
+            node[key] = created;
+            node = created;
+        }
+        else if (next !== null && typeof next === "object" && !Array.isArray(next))
+            node = next;
+        else
+            return false;
+    }
+    const last = segments[segments.length - 1];
+    if (last in node)
+        return false;
+    node[last] = value;
+    return true;
+}
+export function unique(items) {
+    return [...new Set(items)];
+}
+//# sourceMappingURL=util.js.map

package/dist/semantic-engine/additive.js

@@ -0,0 +1,51 @@
+import { canonicalStringify } from "../shared/index.js";
+const same = (a, b) => canonicalStringify(a ?? null) === canonicalStringify(b ?? null);
+function entityViolations(kind, before, after, ignore) {
+    const out = [];
+    const afterById = new Map(after.map((e) => [e.id, e]));
+    for (const b of before) {
+        const a = afterById.get(b.id);
+        if (!a) {
+            out.push(`${kind} ${b.id} was removed`);
+            continue;
+        }
+        for (const key of new Set([...Object.keys(b), ...Object.keys(a)])) {
+            if (key === "facts" || ignore(key, b.id))
+                continue;
+            if (!same(b[key], a[key]))
+                out.push(`${kind} ${b.id}: ${key} changed`);
+        }
+        for (const [path, fact] of Object.entries(b.facts))
+            if (!same(fact, a.facts[path]))
+                out.push(`${kind} ${b.id}: fact ${path} changed`);
+    }
+    return out;
+}
+/**
+ * Enrichment may add entities, facts, and relationships. It may not change or remove anything reconciliation
+ * produced, except the token `category` placeholder (and only while that has no fact). Returns violations.
+ */
+export function assertAdditive(before, after) {
+    const out = [];
+    for (const key of ["contractVersion", "metadata", "sources", "themes", "conflicts"])
+        if (!same(before[key], after[key]))
+            out.push(`${key} changed`);
+    if (after.policies.length !== 0 || before.policies.length !== 0) {
+        if (!same(before.policies, after.policies))
+            out.push("policies changed: the engine never produces policies");
+    }
+    out.push(...entityViolations("guideline", before.guidelines, after.guidelines, () => false));
+    out.push(...entityViolations("pattern", before.patterns, after.patterns, () => false));
+    out.push(...entityViolations("constraint", before.constraints, after.constraints, () => false));
+    const placeholderOnly = (id) => before.tokens.find((t) => t.id === id)?.facts.category === undefined;
+    out.push(...entityViolations("token", before.tokens, after.tokens, (key, id) => key === "category" && placeholderOnly(id)));
+    const beforeComponents = new Map(before.components.map((c) => [c.id, c]));
+    out.push(...entityViolations("component", before.components, after.components, (key) => key === "composition"));
+    for (const a of after.components) {
+        const b = beforeComponents.get(a.id);
+        if (b && !same(b.composition, a.composition.slice(0, b.composition.length)))
+            out.push(`component ${a.id}: existing composition entries changed`);
+    }
+    return out;
+}
+//# sourceMappingURL=additive.js.map