@invariant-ui/cli 0.0.0-stage → 0.2.0

package/dist/contract-query/patterns.js

@@ -0,0 +1,298 @@
+import { search } from "./search.js";
+import { cmp } from "./system.js";
+import { page } from "./views.js";
+/**
+ * What is known about a pattern, derived from its facts. There is no stored pattern status (ADR 0002): a single
+ * field could disagree with the facts it summarizes. A pattern with no facts has no stated basis (`none`); one
+ * whose facts share a status has that status; otherwise it is `mixed`. Only `approved` means every fact is.
+ */
+export function patternStatus(p) {
+    const counts = {};
+    for (const f of Object.values(p.facts))
+        counts[f.status] = (counts[f.status] ?? 0) + 1;
+    const present = Object.keys(counts);
+    const total = Object.values(counts).reduce((a, b) => a + b, 0);
+    const overall = present.length === 0 ? "none" : present.length === 1 ? present[0] : "mixed";
+    return { overall, counts, total };
+}
+const kindOf = (id) => id.slice(0, Math.max(0, id.indexOf(":")));
+function describe(ds, id) {
+    const name = ds.component(id)?.name ??
+        ds.pattern(id)?.name ??
+        ds.contract.tokens.find((t) => t.id === id)?.name ??
+        ds.contract.constraints.find((c) => c.id === id)?.name;
+    return { id, kind: kindOf(id), ...(name ? { name } : {}) };
+}
+/** Policies that make a pattern enforceable: they name it in their scope, or are based on a constraint it owns. */
+function enforcement(ds, p) {
+    const owned = new Set(p.constraints ?? []);
+    return ds.contract.policies
+        .flatMap((policy) => {
+        const via = policy.basedOn.filter((id) => owned.has(id));
+        const scoped = (policy.scope.entities ?? []).includes(p.id);
+        if (via.length === 0 && !scoped)
+            return [];
+        return [
+            {
+                policy: policy.id,
+                name: policy.name,
+                severity: policy.severity,
+                enforcement: policy.enforcement,
+                approvedBy: policy.approval.approvedBy,
+                ...(via.length > 0 ? { constraints: via } : {})
+            }
+        ];
+    })
+        .sort((a, b) => cmp(String(a.policy), String(b.policy)));
+}
+const evidenceEntry = (ds, e) => ({
+    id: e.id,
+    sourceId: e.sourceId,
+    method: e.method,
+    location: ds.location([e.id]) ?? e.sourceRef,
+    ...(e.original ? { original: e.original.length > 200 ? `${e.original.slice(0, 199)}…` : e.original } : {})
+});
+function summary(ds, p) {
+    const status = patternStatus(p);
+    return {
+        id: p.id,
+        name: p.name,
+        category: p.category,
+        description: p.description,
+        ...(p.intent ? { intent: p.intent } : {}),
+        components: p.components,
+        status: { overall: status.overall, counts: status.counts, total: status.total },
+        approved: status.overall === "approved",
+        enforcedBy: enforcement(ds, p).map((e) => e.policy)
+    };
+}
+/** The pattern catalog, filterable by category, derived status and text. Ordered by relevance, else by id. */
+export function patternsView(ds, filters = {}) {
+    const all = ds.contract.patterns;
+    let rows = all;
+    if (filters.query?.trim()) {
+        const hits = search(ds, filters.query, ["pattern"], 100).hits;
+        const byId = new Map(all.map((p) => [p.id, p]));
+        rows = hits.flatMap((h) => byId.get(h.id) ?? []);
+    }
+    else
+        rows = [...all].sort((a, b) => cmp(a.id, b.id));
+    rows = rows.filter((p) => (!filters.category || p.category === filters.category) &&
+        (!filters.status || patternStatus(p).overall === filters.status));
+    const view = page(rows, filters.offset, filters.limit);
+    const notes = [];
+    if (all.length === 0)
+        notes.push("No patterns are defined. Invariant does not infer patterns from code, and no source documents one yet.");
+    else if (rows.length === 0)
+        notes.push(`No pattern matches these filters; the contract has ${all.length} pattern(s).`);
+    const unapproved = view.items.filter((p) => patternStatus(p).overall !== "approved").length;
+    if (unapproved > 0)
+        notes.push(`${unapproved} of ${view.items.length} pattern(s) are not fully approved. Each shows its status: treat documented, inferred or mixed patterns as proposals, not organizational standards.`);
+    return {
+        total: view.total,
+        offset: view.offset,
+        limit: view.limit,
+        truncated: view.truncated,
+        patterns: view.items.map((p) => summary(ds, p)),
+        notes
+    };
+}
+function factEntries(ds, p) {
+    return Object.keys(p.facts)
+        .sort(cmp)
+        .map((path) => {
+        const fact = p.facts[path];
+        const view = ds.factView(p.facts, path);
+        return {
+            path,
+            ...view,
+            evidence: ds.evidenceEntries(fact.evidenceIds).map((e) => evidenceEntry(ds, e))
+        };
+    });
+}
+/** One pattern in full: what it is made of, what is required of it, how sure we are, and where that comes from. */
+export function patternView(ds, p) {
+    const status = patternStatus(p);
+    const fact = (path) => ds.factView(p.facts, path) ?? null;
+    const constraints = (p.constraints ?? []).map((id) => {
+        const c = ds.contract.constraints.find((x) => x.id === id);
+        return c
+            ? {
+                id: c.id,
+                name: c.name,
+                kind: c.kind,
+                description: c.description,
+                ...(c.details ? { details: c.details } : {}),
+                status: (ds.factView(c.facts, "description")?.status ?? null)
+            }
+            : { id, missing: true };
+    });
+    const notes = [];
+    if (status.overall !== "approved")
+        notes.push(status.overall === "none"
+            ? "This pattern states no basis (no facts), so it is not approved."
+            : `This pattern is not fully approved (${status.overall}). Treat it as a proposal until it is approved.`);
+    if ((status.counts.inferred ?? 0) > 0)
+        notes.push(`${status.counts.inferred} fact(s) are inferred, with a confidence; confirm them before relying on them.`);
+    if (constraints.length === 0)
+        notes.push("No constraints are attached, so validation cannot enforce anything from this pattern.");
+    const open = ds.conflictsFor(p.id).filter((c) => c.resolution.state === "open");
+    if (open.length > 0)
+        notes.push(`${open.length} open conflict(s) concern this pattern.`);
+    const inheritanceActive = p.inheritsConstraints === true &&
+        p.appliesTo?.paths !== undefined &&
+        p.facts.appliesTo?.status === "approved" &&
+        p.facts.inheritsConstraints?.status === "approved";
+    if (p.inheritsConstraints === true && !inheritanceActive)
+        notes.push("This pattern opts in to inheriting the constraints of what it composes, but inheritance is off until its paths and the opt-in are approved.");
+    return {
+        id: p.id,
+        name: p.name,
+        category: p.category,
+        description: p.description,
+        ...(p.intent ? { intent: p.intent } : {}),
+        ...(p.appliesTo || p.inheritsConstraints !== undefined
+            ? {
+                scope: {
+                    ...(p.appliesTo?.paths ? { paths: p.appliesTo.paths } : {}),
+                    ...(p.appliesTo?.frameworks ? { frameworks: p.appliesTo.frameworks } : {}),
+                    inheritsConstraints: p.inheritsConstraints === true,
+                    inheritanceActive
+                }
+            }
+            : {}),
+        status: { overall: status.overall, counts: status.counts, total: status.total },
+        approved: status.overall === "approved",
+        components: p.components.map((id) => describe(ds, id)),
+        guidelines: p.guidelines.map((id) => ({
+            id,
+            name: ds.contract.guidelines.find((g) => g.id === id)?.name ?? null
+        })),
+        ...(p.composition
+            ? {
+                composition: {
+                    parts: p.composition.parts.map((part) => ({
+                        name: part.name,
+                        role: part.role,
+                        ref: describe(ds, part.ref),
+                        ...(part.region ? { region: part.region } : {}),
+                        ...(part.description ? { description: part.description } : {}),
+                        fact: fact(`composition.parts.${part.name}`)
+                    }))
+                }
+            }
+            : {}),
+        ...(p.layout ? { layout: p.layout } : {}),
+        ...(p.behavior ? { behavior: p.behavior } : {}),
+        ...(p.accessibility ? { accessibility: p.accessibility } : {}),
+        relationships: (p.relationships ?? []).map((r) => ({
+            id: r.id,
+            type: r.type,
+            target: describe(ds, r.target),
+            ...(r.description ? { description: r.description } : {}),
+            fact: fact(`relationships.${r.id}`)
+        })),
+        constraints,
+        enforcedBy: enforcement(ds, p),
+        facts: factEntries(ds, p),
+        conflicts: ds.conflictsFor(p.id).map((c) => ({ id: c.id, type: c.type, state: c.resolution.state })),
+        notes
+    };
+}
+const MAX_NODES = 200;
+function outgoing(p) {
+    return [
+        ...(p.relationships ?? []).map((r) => ({
+            from: p.id,
+            to: r.target,
+            type: r.type,
+            via: "relationship",
+            id: r.id,
+            fact: `relationships.${r.id}`
+        })),
+        ...(p.composition?.parts ?? []).map((part) => ({
+            from: p.id,
+            to: part.ref,
+            type: "part",
+            via: "composition",
+            id: part.name,
+            role: part.role,
+            fact: `composition.parts.${part.name}`
+        }))
+    ];
+}
+/**
+ * The relationships around a pattern, walked breadth-first to `depth` (default 1, at most 5). Components are
+ * leaves. A node is expanded once, so cycles (`uses` may be cyclic) cannot loop. Composition parts appear as
+ * `part` edges with their role.
+ */
+export function patternRelationships(ds, root, options = {}) {
+    const direction = options.direction ?? "both";
+    const depth = Math.max(1, Math.min(options.depth ?? 1, 5));
+    const wanted = options.types && options.types.length > 0 ? new Set(options.types) : undefined;
+    const everyEdge = ds.contract.patterns.flatMap(outgoing);
+    const edges = new Map();
+    const seen = new Set([root.id]);
+    let frontier = [root.id];
+    let truncated = false;
+    for (let level = 0; level < depth && frontier.length > 0; level++) {
+        const next = [];
+        for (const id of frontier) {
+            const found = [
+                ...(direction !== "in" ? everyEdge.filter((e) => e.from === id) : []),
+                ...(direction !== "out" ? everyEdge.filter((e) => e.to === id) : [])
+            ].filter((e) => !wanted || wanted.has(e.type));
+            for (const e of found) {
+                edges.set(`${e.from}|${e.type}|${e.id}|${e.to}`, e);
+                for (const end of [e.from, e.to]) {
+                    if (seen.has(end))
+                        continue;
+                    if (seen.size >= MAX_NODES) {
+                        truncated = true;
+                        continue;
+                    }
+                    seen.add(end);
+                    if (end.startsWith("pattern:"))
+                        next.push(end);
+                }
+            }
+        }
+        frontier = next;
+    }
+    const nodes = [...seen].sort(cmp).map((id) => {
+        const p = ds.pattern(id);
+        return {
+            ...describe(ds, id),
+            ...(p ? { category: p.category, status: patternStatus(p).overall } : {}),
+            ...(id === root.id ? { root: true } : {})
+        };
+    });
+    const list = [...edges.values()].sort((a, b) => cmp(a.from, b.from) || cmp(a.type, b.type) || cmp(a.to, b.to) || cmp(a.id, b.id));
+    return {
+        pattern: { id: root.id, name: root.name },
+        direction,
+        depth,
+        edges: list.map((e) => {
+            const from = ds.pattern(e.from);
+            const view = from && e.fact ? ds.factView(from.facts, e.fact) : undefined;
+            return {
+                from: e.from,
+                to: e.to,
+                type: e.type,
+                via: e.via,
+                id: e.id,
+                ...(e.role ? { role: e.role } : {}),
+                status: (view?.status ?? null),
+                ...(view?.source ? { source: view.source } : {})
+            };
+        }),
+        nodes,
+        truncated,
+        notes: list.length === 0
+            ? ["This pattern has no relationships in the requested direction."]
+            : [
+                "Relationships are only what the contract states; none is inferred from name similarity. Each edge shows the status of the fact behind it."
+            ]
+    };
+}
+//# sourceMappingURL=patterns.js.map

package/dist/contract-query/search.js

@@ -0,0 +1,132 @@
+import { cmp, normalize } from "./system.js";
+const words = (text) => text
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean);
+/** Plural and `-ing` endings only: `buttons` and `button`, `variants` and `variant`, `loading` and `load`. */
+const stem = (w) => w.length > 4 && w.endsWith("ies")
+    ? `${w.slice(0, -3)}y`
+    : w.length > 4 && w.endsWith("ing")
+        ? w.slice(0, -3)
+        : w.length > 3 && w.endsWith("s") && !w.endsWith("ss")
+            ? w.slice(0, -1)
+            : w;
+/** True when two words differ by at most one inserted, deleted or substituted letter. */
+function oneEdit(a, b) {
+    if (Math.abs(a.length - b.length) > 1)
+        return false;
+    let i = 0;
+    let j = 0;
+    let edits = 0;
+    while (i < a.length && j < b.length) {
+        if (a[i] === b[j]) {
+            i++;
+            j++;
+            continue;
+        }
+        if (++edits > 1)
+            return false;
+        if (a.length > b.length)
+            i++;
+        else if (a.length < b.length)
+            j++;
+        else {
+            i++;
+            j++;
+        }
+    }
+    return edits + (a.length - i) + (b.length - j) <= 1;
+}
+/**
+ * Fixed, explainable ranking: name matches beat structure matches beat description matches. Matching is
+ * lexical: exact words, plural and `-ing` stems, word prefixes and one-letter typos. There are no synonyms,
+ * embeddings or models, so the same query always gives the same answer and every hit says what it matched.
+ */
+function score(query, fields) {
+    const qn = normalize(query);
+    const qw = words(query);
+    let total = 0;
+    const matchedOn = [];
+    for (const f of fields) {
+        if (!f.text)
+            continue;
+        const tn = normalize(f.text);
+        const tw = words(f.text);
+        let s = 0;
+        if (tn === qn)
+            s = 10;
+        else if (tn.startsWith(qn) && qn.length >= 2)
+            s = 6;
+        else if (qw.length > 0 && qw.every((w) => tw.includes(w)))
+            s = 5;
+        else if (qn.length >= 3 && tn.includes(qn))
+            s = 3;
+        else if (qw.length > 0 && qw.every((w) => tw.some((x) => stem(x) === stem(w))))
+            s = 4;
+        else if (qw.length > 0 && qw.every((w) => w.length >= 3 && tw.some((x) => x.startsWith(w))))
+            s = 2;
+        else if (qw.some((w) => w.length >= 3 && tw.includes(w)))
+            s = 1;
+        else if (qw.length > 0 && qw.every((w) => w.length >= 5 && tw.some((x) => oneEdit(w, x)))) {
+            total += f.weight * 0.5;
+            matchedOn.push(`${f.label} (approximate)`);
+            continue;
+        }
+        if (s > 0) {
+            total += s * f.weight;
+            matchedOn.push(f.label);
+        }
+    }
+    return { score: total, matchedOn };
+}
+export function search(ds, query, kinds = ["component", "token", "guideline", "pattern"], limit = 20) {
+    const hits = [];
+    const add = (kind, id, name, r) => {
+        if (r.score > 0)
+            hits.push({ kind, id, name, score: r.score, matchedOn: r.matchedOn });
+    };
+    if (kinds.includes("component"))
+        for (const c of ds.contract.components)
+            add("component", c.id, c.name, score(query, [
+                { label: "name", text: c.name, weight: 10 },
+                { label: "prop", text: c.props.map((p) => p.name).join(" "), weight: 3 },
+                { label: "variant", text: c.variants.flatMap((v) => [v.name, ...v.values]).join(" "), weight: 3 },
+                { label: "slot", text: c.slots.map((s) => s.name).join(" "), weight: 2 },
+                { label: "event", text: c.events.map((e) => e.name).join(" "), weight: 2 },
+                { label: "description", text: c.description ?? "", weight: 1 }
+            ]));
+    if (kinds.includes("token"))
+        for (const t of ds.contract.tokens)
+            add("token", t.id, t.name, score(query, [
+                { label: "name", text: t.name, weight: 10 },
+                { label: "category", text: t.category, weight: 2 },
+                { label: "value", text: typeof t.value.value === "string" ? t.value.value : "", weight: 2 },
+                { label: "description", text: t.description ?? "", weight: 1 }
+            ]));
+    if (kinds.includes("guideline"))
+        for (const g of ds.contract.guidelines)
+            add("guideline", g.id, g.name, score(query, [
+                { label: "title", text: g.name, weight: 8 },
+                { label: "kind", text: g.kind, weight: 1 }
+            ]));
+    if (kinds.includes("pattern"))
+        for (const p of ds.contract.patterns)
+            add("pattern", p.id, p.name, score(query, [
+                { label: "name", text: p.name, weight: 10 },
+                { label: "intent", text: p.intent ?? "", weight: 3 },
+                { label: "category", text: p.category, weight: 2 },
+                {
+                    label: "part",
+                    text: (p.composition?.parts ?? []).map((x) => `${x.name} ${x.ref}`).join(" "),
+                    weight: 3
+                },
+                { label: "region", text: (p.layout?.regions ?? []).map((r) => r.name).join(" "), weight: 2 },
+                { label: "state", text: (p.behavior?.states ?? []).map((x) => x.name).join(" "), weight: 2 },
+                { label: "description", text: p.description, weight: 1 }
+            ]));
+    hits.sort((a, b) => b.score - a.score || cmp(a.kind, b.kind) || cmp(a.id, b.id));
+    return { total: hits.length, hits: hits.slice(0, Math.max(1, Math.min(limit, 100))) };
+}
+export const searchJson = (r) => r;
+//# sourceMappingURL=search.js.map

package/dist/contract-query/system.js

@@ -0,0 +1,148 @@
+export const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+export const normalize = (text) => text.toLowerCase().replace(/[^a-z0-9]/g, "");
+/**
+ * Read model over one compiled contract and its evidence. Pure and deterministic: it never touches the
+ * file system, a network or a model, and everything it returns is plain JSON.
+ */
+export class DesignSystem {
+    contract;
+    contentHash;
+    evidence = new Map();
+    byId = new Map();
+    patternsById = new Map();
+    containers = new Map();
+    constructor(contract, evidence) {
+        this.contract = contract;
+        this.contentHash = contract.integrity.contentHash;
+        for (const e of evidence?.evidence ?? [])
+            this.evidence.set(e.id, e);
+        for (const c of contract.components)
+            this.byId.set(c.id, c);
+        for (const p of contract.patterns)
+            this.patternsById.set(p.id, p);
+        for (const c of contract.components)
+            c.composition.forEach((r, i) => {
+                if (r.type !== "contains")
+                    return;
+                const list = this.containers.get(r.target) ?? [];
+                const fact = c.facts[`composition.${i}`];
+                list.push({ id: c.id, ...(fact ? { fact } : {}) });
+                this.containers.set(r.target, list);
+            });
+    }
+    component(id) {
+        return this.byId.get(id);
+    }
+    /** Resolves an id, an id without its prefix, or a name (ignoring case and separators). */
+    findComponent(query) {
+        const q = query.trim();
+        const exact = this.byId.get(q) ?? this.byId.get(`component:${q.toLowerCase()}`);
+        if (exact)
+            return { match: exact, candidates: [exact] };
+        const n = normalize(q);
+        const named = this.contract.components.filter((c) => normalize(c.name) === n || normalize(c.id.slice(10)) === n);
+        if (named.length === 1)
+            return { match: named[0], candidates: named };
+        if (named.length > 1)
+            return { candidates: named };
+        const near = this.contract.components
+            .filter((c) => n.length >= 2 && (normalize(c.name).includes(n) || n.includes(normalize(c.name))))
+            .slice(0, 8);
+        return { candidates: near };
+    }
+    pattern(id) {
+        return this.patternsById.get(id);
+    }
+    /**
+     * Resolves a pattern by id, by id without its prefix (`page.data-management`), by the part after the
+     * category (`data-management`), or by name, ignoring case and separators. Several matches yield candidates only.
+     */
+    findPattern(query) {
+        const q = query.trim();
+        const exact = this.patternsById.get(q) ?? this.patternsById.get(`pattern:${q.toLowerCase()}`);
+        if (exact)
+            return { match: exact, candidates: [exact] };
+        const n = normalize(q);
+        const named = this.contract.patterns.filter((p) => {
+            const body = p.id.slice("pattern:".length);
+            const afterCategory = body.includes(".") ? body.slice(body.indexOf(".") + 1) : body;
+            return normalize(p.name) === n || normalize(body) === n || normalize(afterCategory) === n;
+        });
+        if (named.length === 1)
+            return { match: named[0], candidates: named };
+        if (named.length > 1)
+            return { candidates: named };
+        const near = this.contract.patterns
+            .filter((p) => n.length >= 2 && (normalize(p.name).includes(n) || n.includes(normalize(p.name))))
+            .slice(0, 8);
+        return { candidates: near };
+    }
+    /** The evidence entries for these ids, in the given order. Ids missing from the evidence file are skipped. */
+    evidenceEntries(ids) {
+        return ids.flatMap((id) => {
+            const e = this.evidence.get(id);
+            return e ? [e] : [];
+        });
+    }
+    containedBy(id) {
+        return this.containers.get(id) ?? [];
+    }
+    location(ids) {
+        for (const id of ids) {
+            const e = this.evidence.get(id);
+            if (!e)
+                continue;
+            if (e.location.type === "file")
+                return `${e.location.path}${e.location.line ? `:${e.location.line}` : ""}`;
+            return e.sourceRef;
+        }
+        return undefined;
+    }
+    factView(facts, path) {
+        const f = facts[path];
+        if (!f)
+            return undefined;
+        const source = this.location(f.evidenceIds);
+        return {
+            status: f.status,
+            ...(f.confidence === undefined ? {} : { confidence: f.confidence }),
+            ...(f.derivation ? { rule: f.derivation.rule } : {}),
+            ...(source ? { source } : {})
+        };
+    }
+    /** True when the implementation's props are fully enumerated, so an absent prop really is absent. */
+    propsComplete(c, framework) {
+        const impls = c.implementations.filter((i) => !framework || i.framework === framework);
+        if (impls.length === 0)
+            return false;
+        return impls.every((i) => i.extensions?.[i.framework]?.propsComplete === true);
+    }
+    conflictsFor(subject) {
+        return this.contract.conflicts.filter((c) => c.subject === subject);
+    }
+    /** Follows aliases to a literal. A cycle or a missing target yields no value rather than a guess. */
+    resolveToken(token, theme) {
+        const chain = [token.id];
+        let current = token;
+        for (let i = 0; i < 20 && current; i++) {
+            const form = theme
+                ? (current.modes?.[theme] ?? current.value)
+                : current.value;
+            if (form.aliasOf === undefined)
+                return { value: form.value, chain };
+            const next = this.contract.tokens.find((t) => t.id === form.aliasOf);
+            if (!next)
+                return {
+                    chain: [...chain, form.aliasOf],
+                    note: `alias target ${form.aliasOf} is not in the contract`
+                };
+            if (chain.includes(next.id))
+                return { chain: [...chain, next.id], note: "alias cycle" };
+            chain.push(next.id);
+            current = next;
+        }
+        return { chain, note: "alias chain too long" };
+    }
+}
+export const sanitizeName = (text) => text.replace(/[^A-Za-z0-9 ._:/@-]/g, "").slice(0, 80);
+//# sourceMappingURL=system.js.map