@invariant-ui/cli 0.0.0-stage → 0.1.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/scan.js

@@ -0,0 +1,164 @@
+import ts from "typescript";
+const dyn = (text) => ({ expression: text.replace(/\s+/g, " ").trim().slice(0, 80) });
+function jsxValue(init, sf) {
+    if (!init)
+        return true;
+    if (ts.isStringLiteral(init))
+        return init.text;
+    if (ts.isJsxExpression(init) && init.expression) {
+        const e = init.expression;
+        if (ts.isStringLiteralLike(e))
+            return e.text;
+        if (ts.isNumericLiteral(e))
+            return Number(e.text);
+        if (e.kind === ts.SyntaxKind.TrueKeyword)
+            return true;
+        if (e.kind === ts.SyntaxKind.FalseKeyword)
+            return false;
+        if (e.kind === ts.SyntaxKind.NullKeyword)
+            return null;
+        return dyn(e.getText(sf));
+    }
+    return dyn(init.getText(sf));
+}
+/** JSX elements in a TypeScript/JavaScript snippet, by syntax only. Nothing is evaluated. */
+export function scanJsx(code, filename = "snippet.tsx") {
+    const kind = /\.jsx?$/i.test(filename) ? ts.ScriptKind.JSX : ts.ScriptKind.TSX;
+    const sf = ts.createSourceFile(filename, code, ts.ScriptTarget.Latest, true, kind);
+    const uses = [];
+    const visit = (node) => {
+        if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+            const opening = ts.isJsxElement(node) ? node.openingElement : node;
+            const attrs = {};
+            let spread = false;
+            for (const a of opening.attributes.properties) {
+                if (ts.isJsxSpreadAttribute(a))
+                    spread = true;
+                else
+                    attrs[a.name.getText(sf)] = jsxValue(a.initializer, sf);
+            }
+            const hasChildren = ts.isJsxElement(node)
+                ? node.children.some((c) => !(ts.isJsxText(c) && c.containsOnlyTriviaWhiteSpaces))
+                : false;
+            uses.push({
+                tag: opening.tagName.getText(sf),
+                line: sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1,
+                attrs,
+                hasChildren,
+                hasSpread: spread
+            });
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return uses;
+}
+const RAW_TEXT = new Set(["script", "style"]);
+const camel = (n) => /^(data|aria)-/.test(n) ? n : n.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+/**
+ * Element start tags in an HTML-like template (Vue, Angular, HTML). A single linear pass: no DOM, no
+ * expression evaluation. Event handlers, structural directives and references are skipped; bindings are
+ * kept as dynamic values.
+ */
+export function scanMarkup(code) {
+    const uses = [];
+    let i = 0;
+    let line = 1;
+    const n = code.length;
+    const advance = (to) => {
+        for (; i < to && i < n; i++)
+            if (code[i] === "\n")
+                line++;
+    };
+    while (i < n) {
+        const lt = code.indexOf("<", i);
+        if (lt < 0)
+            break;
+        advance(lt);
+        if (code.startsWith("<!--", i)) {
+            const end = code.indexOf("-->", i + 4);
+            advance(end < 0 ? n : end + 3);
+            continue;
+        }
+        const m = /^<([A-Za-z][A-Za-z0-9_.:-]*)/.exec(code.slice(i, i + 130));
+        if (!m) {
+            advance(i + 1);
+            continue;
+        }
+        const tag = m[1];
+        const startLine = line;
+        let j = i + m[0].length;
+        const attrs = {};
+        let spread = false;
+        let selfClosing = false;
+        while (j < n) {
+            while (j < n && /\s/.test(code[j]))
+                j++;
+            const c = code[j];
+            if (c === undefined)
+                break;
+            if (c === ">") {
+                j++;
+                break;
+            }
+            if (c === "/" && code[j + 1] === ">") {
+                selfClosing = true;
+                j += 2;
+                break;
+            }
+            const nm = /^[^\s=>/"']+/.exec(code.slice(j, j + 200));
+            if (!nm) {
+                j++;
+                continue;
+            }
+            const raw = nm[0];
+            j += raw.length;
+            let value;
+            let k = j;
+            while (k < n && /\s/.test(code[k]))
+                k++;
+            if (code[k] === "=") {
+                k++;
+                while (k < n && /\s/.test(code[k]))
+                    k++;
+                const q = code[k];
+                if (q === '"' || q === "'") {
+                    const end = code.indexOf(q, k + 1);
+                    value = code.slice(k + 1, end < 0 ? n : end);
+                    j = end < 0 ? n : end + 1;
+                }
+                else {
+                    const um = /^[^\s>]+/.exec(code.slice(k, k + 200));
+                    value = um?.[0] ?? "";
+                    j = k + value.length;
+                }
+            }
+            if (/^(@|\(|v-on:|v-on$|#|\*|v-if|v-else|v-for|v-show|v-model|v-slot|ng)/.test(raw) &&
+                !/^\[/.test(raw)) {
+                if (raw === "v-bind" || raw.startsWith("v-bind="))
+                    spread = true;
+                continue;
+            }
+            const bound = /^(:|v-bind:|\[)/.test(raw);
+            const name = camel(raw
+                .replace(/^(:|v-bind:)/, "")
+                .replace(/^\[|\]$/g, "")
+                .replace(/^attr\./, ""));
+            attrs[name] = bound ? dyn(value ?? "") : value === undefined ? true : value;
+        }
+        uses.push({
+            tag,
+            line: startLine,
+            attrs,
+            hasChildren: selfClosing ? false : undefined,
+            hasSpread: spread
+        });
+        advance(j);
+        if (RAW_TEXT.has(tag.toLowerCase()) && !selfClosing) {
+            const close = code.toLowerCase().indexOf(`</${tag.toLowerCase()}`, i);
+            advance(close < 0 ? n : close);
+        }
+    }
+    return uses;
+}
+//# sourceMappingURL=scan.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