@invariant-ui/cli 0.0.0-stage → 0.1.0

package/dist/semantic-engine/compounds.js

@@ -0,0 +1,91 @@
+import { cmp, inferredFact } from "./infer.js";
+const SAME_FILE = 0.7;
+const SAME_PACKAGE = 0.4;
+function view(component) {
+    return {
+        component,
+        impls: component.implementations.map((i) => {
+            const ext = i.extensions?.[i.framework];
+            return {
+                id: i.id,
+                framework: i.framework,
+                ...(i.packageName ? { packageName: i.packageName } : {}),
+                ...(typeof ext?.file === "string" ? { file: ext.file } : {})
+            };
+        })
+    };
+}
+/**
+ * Compound components by naming and location: `DialogTrigger` and `DialogContent` next to `Dialog` in one
+ * package. A parent needs at least two such children, and a child in the parent's own file is more likely
+ * than one elsewhere in the package. Existing `contains` relationships are never repeated or changed.
+ */
+export function inferCompounds(components) {
+    const views = components.map(view);
+    const additions = new Map();
+    for (const parent of views) {
+        const candidates = [];
+        for (const child of views) {
+            if (child === parent)
+                continue;
+            const rest = child.component.name.slice(parent.component.name.length);
+            if (!child.component.name.startsWith(parent.component.name) || !/^[A-Z]/.test(rest))
+                continue;
+            for (const p of parent.impls) {
+                const match = child.impls.find((c) => c.framework === p.framework && c.packageName && c.packageName === p.packageName);
+                if (!match)
+                    continue;
+                candidates.push({
+                    child,
+                    sameFile: Boolean(p.file && p.file === match.file),
+                    parentImpl: p.id,
+                    childImpl: match.id
+                });
+                break;
+            }
+        }
+        if (candidates.length < 2)
+            continue;
+        const known = new Set(parent.component.composition.map((r) => `${r.type}\u0000${r.target}`));
+        for (const c of candidates) {
+            if (known.has(`contains\u0000${c.child.component.id}`))
+                continue;
+            const list = additions.get(parent.component.id) ?? [];
+            list.push({
+                target: c.child.component.id,
+                confidence: c.sameFile ? SAME_FILE : SAME_PACKAGE,
+                reasoning: `${c.child.component.name} is named ${parent.component.name} plus a suffix, in the same package${c.sameFile ? " and the same file" : ""}, and ${parent.component.name} has ${candidates.length} such components`,
+                evidenceIds: [
+                    ...(parent.component.facts[`implementations.${c.parentImpl}`]?.evidenceIds ?? []),
+                    ...(c.child.component.facts[`implementations.${c.childImpl}`]?.evidenceIds ?? [])
+                ],
+                inputs: [`implementations.${c.parentImpl}`, c.child.component.id]
+            });
+            additions.set(parent.component.id, list);
+        }
+    }
+    return components.map((component) => {
+        const add = additions.get(component.id);
+        if (!add || add.length === 0)
+            return component;
+        const sorted = [...add].sort((a, b) => cmp(a.target, b.target));
+        const facts = { ...component.facts };
+        const composition = [...component.composition];
+        for (const a of sorted) {
+            facts[`composition.${composition.length}`] = inferredFact({
+                rule: "compound.name-prefix",
+                confidence: a.confidence,
+                reasoning: a.reasoning,
+                inputs: a.inputs,
+                evidenceIds: a.evidenceIds
+            });
+            composition.push({ type: "contains", target: a.target });
+        }
+        return {
+            ...component,
+            composition,
+            facts: Object.fromEntries(Object.entries(facts).sort((a, b) => cmp(a[0], b[0])))
+        };
+    });
+}
+//# sourceMappingURL=compounds.js.map

package/dist/semantic-engine/documents.js

@@ -0,0 +1,157 @@
+import { cmp, inferredFact, slugSegment, words } from "./infer.js";
+const KIND_RULES = [
+    {
+        kind: "accessibility",
+        pattern: /\ba11y\b|accessib|\bwcag\b|\baria\b|screen[- ]reader|keyboard/,
+        confidence: 0.7
+    },
+    {
+        kind: "do-dont",
+        pattern: /do and don'?t|dos and don'?ts|do'?s? ?& ?don'?ts?|do\/don'?t/,
+        confidence: 0.7
+    },
+    { kind: "composition", pattern: /composition|compos(?:e|ing)\b|layout/, confidence: 0.6 },
+    {
+        kind: "visual-principle",
+        pattern: /principle|philosophy|foundations?|brand|voice and tone|visual/,
+        confidence: 0.6
+    },
+    {
+        kind: "usage",
+        pattern: /usage|guidelines?|how to use|when to use|best practices?|getting started|overview/,
+        confidence: 0.6
+    }
+];
+function classify(text) {
+    for (const rule of KIND_RULES) {
+        const m = rule.pattern.exec(text);
+        if (m)
+            return { kind: rule.kind, confidence: rule.confidence, matched: m[0] };
+    }
+    return { kind: "reference", confidence: 0.4 };
+}
+function containsWords(haystack, needle) {
+    if (needle.length === 0 || (needle.length === 1 && needle[0].length <= 2))
+        return false;
+    for (let i = 0; i + needle.length <= haystack.length; i++)
+        if (needle.every((w, j) => haystack[i + j] === w))
+            return true;
+    return false;
+}
+/**
+ * One guideline per documentation page. The IR carries a page's title and headings, not its prose, so the
+ * statement is the title and the kind comes from keywords: a page that matches none stays a `reference`.
+ * `appliesTo` links a page to a component only when the file name or title names it.
+ */
+export function classifyDocuments(docs, components) {
+    const guidelines = [];
+    const evidence = new Map();
+    const skipped = [];
+    const used = new Set();
+    for (const doc of [...docs].sort((a, b) => cmp(a.source.id, b.source.id))) {
+        const byId = new Map(doc.evidence.map((e) => [e.id, e]));
+        const bySubject = new Map();
+        for (const f of doc.facts)
+            bySubject.set(f.subject, [...(bySubject.get(f.subject) ?? []), f]);
+        for (const entity of doc.entities
+            .filter((e) => e.kind === "doc-page")
+            .sort((a, b) => cmp(a.ref, b.ref))) {
+            const facts = bySubject.get(entity.ref) ?? [];
+            const find = (path) => facts.find((f) => f.path === path);
+            const titleFact = find("doc.title") ?? facts[0];
+            if (!titleFact) {
+                skipped.push({ ref: entity.ref, sourceId: doc.source.id, reason: "the page has no facts to cite" });
+                continue;
+            }
+            const title = typeof find("doc.title")?.value === "string" ? find("doc.title")?.value : entity.name;
+            const documentId = entity.ref.replace(/^doc:/, "");
+            const stem = (documentId.split("/").pop() ?? documentId).replace(/\.[^.]*$/, "");
+            const cite = (ids) => {
+                for (const id of ids) {
+                    const found = byId.get(id);
+                    if (found)
+                        evidence.set(id, found);
+                }
+            };
+            const text = [title, stem].join(" \n ").toLowerCase();
+            const kind = classify(text);
+            const segments = documentId
+                .replace(/\.[^./]*$/, "")
+                .split("/")
+                .map(slugSegment);
+            let id = `guideline:${segments.join("/")}`;
+            for (let n = 2; used.has(id); n++)
+                id = `guideline:${segments.join("/")}-${n}`;
+            used.add(id);
+            const facts_ = {};
+            const status = titleFact.origin === "extracted" ? "discovered" : "documented";
+            facts_.name = { status, evidenceIds: titleFact.evidenceIds };
+            facts_.statement = { status, evidenceIds: titleFact.evidenceIds };
+            facts_["references.0"] = { status: "discovered", evidenceIds: titleFact.evidenceIds };
+            cite(titleFact.evidenceIds);
+            const kindEvidence = [...titleFact.evidenceIds];
+            const kindInference = {
+                rule: kind.kind === "reference" ? "document.classify.fallback" : "document.classify.keyword",
+                confidence: kind.confidence,
+                reasoning: kind.kind === "reference"
+                    ? "No keyword in the title or file name identifies a more specific kind of page"
+                    : `The title or file name contains "${kind.matched}", which marks a ${kind.kind} page`,
+                inputs: ["doc.title"],
+                evidenceIds: kindEvidence
+            };
+            facts_.kind = inferredFact(kindInference);
+            cite(kindEvidence);
+            const stemWords = words(stem);
+            const titleWords = words(title);
+            const applies = [];
+            for (const c of [...components].sort((a, b) => cmp(a.id, b.id))) {
+                const cw = words(c.name);
+                if (stemWords.join(" ") === cw.join(" ") && cw.length > 0)
+                    applies.push({
+                        id: c.id,
+                        confidence: 0.8,
+                        reason: `The file name "${stem}" is the component name "${c.name}"`
+                    });
+                else if (containsWords(titleWords, cw))
+                    applies.push({
+                        id: c.id,
+                        confidence: 0.6,
+                        reason: `The title "${title}" names the component "${c.name}"`
+                    });
+            }
+            const exact = applies
+                .filter((a) => a.confidence === 0.8)
+                .map((a) => words(components.find((c) => c.id === a.id)?.name ?? ""));
+            const covered = (id) => {
+                const cw = words(components.find((c) => c.id === id)?.name ?? "");
+                return exact.some((e) => e.length > cw.length && containsWords(e, cw));
+            };
+            const kept = applies.filter((a) => a.confidence === 0.8 || !covered(a.id));
+            kept.forEach((a, index) => {
+                facts_[`appliesTo.${index}`] = inferredFact({
+                    rule: "document.names-component",
+                    confidence: a.confidence,
+                    reasoning: a.reason,
+                    inputs: ["doc.title"],
+                    evidenceIds: titleFact.evidenceIds
+                });
+            });
+            guidelines.push({
+                id: id,
+                name: title,
+                kind: kind.kind,
+                statement: title,
+                appliesTo: kept.map((a) => a.id),
+                examples: [],
+                references: [{ sourceId: doc.source.id, documentId, title }],
+                facts: Object.fromEntries(Object.entries(facts_).sort((a, b) => cmp(a[0], b[0])))
+            });
+        }
+    }
+    return {
+        guidelines: guidelines.sort((a, b) => cmp(a.id, b.id)),
+        evidence: [...evidence.values()].sort((a, b) => cmp(a.id, b.id)),
+        skipped
+    };
+}
+//# sourceMappingURL=documents.js.map

package/dist/semantic-engine/enrich.js

@@ -0,0 +1,42 @@
+import { DiagnosticCollector } from "../shared/index.js";
+import { assertAdditive } from "./additive.js";
+import { inferCompounds } from "./compounds.js";
+import { classifyDocuments } from "./documents.js";
+import { cmp } from "./infer.js";
+import { classifyTokens } from "./tokens.js";
+/**
+ * Adds inferred semantics to a reconciled contract: token categories, guidelines from documentation pages,
+ * and compound-component containment. Every output is an `inferred` fact with a rule, reasoning, confidence
+ * and existing evidence. The result is checked to be purely additive; if it is not, the input contract is
+ * returned unchanged with an error. Nothing here promotes a fact to `approved` or creates a policy.
+ */
+export function enrich(input) {
+    const diagnostics = new DiagnosticCollector();
+    const documents = classifyDocuments(input.docs, input.contract.components);
+    for (const s of documents.skipped)
+        diagnostics.info("semantic.page-skipped", `${s.ref} was not classified: ${s.reason}`, {
+            sourceId: s.sourceId,
+            entityId: s.ref
+        });
+    const candidate = {
+        ...input.contract,
+        components: inferCompounds(input.contract.components),
+        tokens: classifyTokens(input.contract.tokens),
+        guidelines: [...input.contract.guidelines, ...documents.guidelines].sort((a, b) => cmp(a.id, b.id))
+    };
+    const violations = assertAdditive(input.contract, candidate);
+    if (violations.length > 0) {
+        for (const v of violations)
+            diagnostics.error("semantic.not-additive", `Enrichment would alter existing data: ${v}`);
+        return { contract: input.contract, evidence: [...input.evidence], diagnostics: diagnostics.toArray() };
+    }
+    const evidence = new Map(input.evidence.map((e) => [e.id, e]));
+    for (const e of documents.evidence)
+        evidence.set(e.id, e);
+    return {
+        contract: candidate,
+        evidence: [...evidence.values()].sort((a, b) => cmp(a.id, b.id)),
+        diagnostics: diagnostics.toArray()
+    };
+}
+//# sourceMappingURL=enrich.js.map

package/dist/semantic-engine/index.js

@@ -0,0 +1,7 @@
+export { assertAdditive } from "./additive.js";
+export { inferCompounds } from "./compounds.js";
+export { classifyDocuments } from "./documents.js";
+export { enrich } from "./enrich.js";
+export { inferredFact } from "./infer.js";
+export { classifyTokens } from "./tokens.js";
+//# sourceMappingURL=index.js.map

package/dist/semantic-engine/infer.js

@@ -0,0 +1,38 @@
+/**
+ * The only way the engine writes a fact. An inference without evidence, reasoning or a usable confidence
+ * is a bug in a rule, not something to store: it throws, so a rule can never emit an unattributable claim.
+ */
+export function inferredFact(i) {
+    if (i.evidenceIds.length === 0)
+        throw new Error(`rule ${i.rule} produced an inference without evidence`);
+    if (i.reasoning.trim() === "")
+        throw new Error(`rule ${i.rule} produced an inference without reasoning`);
+    if (!(i.confidence > 0 && i.confidence < 1))
+        throw new Error(`rule ${i.rule} produced confidence ${i.confidence}; inferences are never certain`);
+    return {
+        status: "inferred",
+        evidenceIds: [...new Set(i.evidenceIds)].sort(),
+        confidence: i.confidence,
+        derivation: { rule: i.rule, reasoning: i.reasoning, inputs: [...new Set(i.inputs)].sort() }
+    };
+}
+export function words(text) {
+    return text
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+}
+export function cmp(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+export function slugSegment(text) {
+    const s = text
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^[^a-z0-9]+/, "")
+        .replace(/-{2,}/g, "-")
+        .replace(/[-.]+$/, "");
+    return s === "" ? "x" : s;
+}
+//# sourceMappingURL=infer.js.map

package/dist/semantic-engine/tokens.js

@@ -0,0 +1,120 @@
+import { cmp, inferredFact, words } from "./infer.js";
+const DTCG = {
+    color: "color",
+    shadow: "shadow",
+    typography: "typography",
+    fontFamily: "typography",
+    fontWeight: "typography",
+    fontSize: "typography",
+    lineHeight: "typography",
+    letterSpacing: "typography",
+    border: "border",
+    strokeStyle: "border",
+    duration: "motion",
+    cubicBezier: "motion",
+    transition: "motion"
+};
+const NAME_PREFIX = {
+    color: "color",
+    colour: "color",
+    space: "spacing",
+    spacing: "spacing",
+    gap: "spacing",
+    margin: "spacing",
+    padding: "spacing",
+    size: "sizing",
+    sizing: "sizing",
+    width: "sizing",
+    height: "sizing",
+    font: "typography",
+    typography: "typography",
+    line: "typography",
+    letter: "typography",
+    radius: "border",
+    border: "border",
+    stroke: "border",
+    shadow: "shadow",
+    elevation: "shadow",
+    breakpoint: "breakpoint",
+    screen: "breakpoint",
+    duration: "motion",
+    easing: "motion",
+    motion: "motion",
+    transition: "motion",
+    animation: "motion"
+};
+function classify(token) {
+    const evidence = (path) => token.facts[path]?.evidenceIds ?? [];
+    const named = evidence("name");
+    const dtcg = token.extensions?.dtcg?.type;
+    if (typeof dtcg === "string" && DTCG[dtcg] && evidence("extensions.dtcg.type").length > 0) {
+        return {
+            category: DTCG[dtcg],
+            inference: {
+                rule: "token-category.dtcg-type",
+                confidence: 0.95,
+                reasoning: `The token declares the DTCG type "${dtcg}", which is the ${DTCG[dtcg]} category`,
+                inputs: ["extensions.dtcg.type"],
+                evidenceIds: evidence("extensions.dtcg.type")
+            }
+        };
+    }
+    const css = token.extensions?.css;
+    if (css) {
+        const kinds = Object.entries(css)
+            .filter(([, v]) => typeof v === "object" && v !== null && v.valueKind === "color")
+            .map(([k]) => k);
+        const path = kinds.map((k) => `extensions.css.${k}.valueKind`).find((p) => evidence(p).length > 0);
+        if (path)
+            return {
+                category: "color",
+                inference: {
+                    rule: "token-category.value-kind",
+                    confidence: 0.9,
+                    reasoning: "The CSS value is a colour literal or colour function",
+                    inputs: [path],
+                    evidenceIds: evidence(path)
+                }
+            };
+    }
+    const first = words(token.name.replace(/^-+/, ""))[0];
+    if (first && NAME_PREFIX[first] && named.length > 0)
+        return {
+            category: NAME_PREFIX[first],
+            inference: {
+                rule: "token-category.name-prefix",
+                confidence: 0.7,
+                reasoning: `The token name starts with "${first}", which conventionally names the ${NAME_PREFIX[first]} category`,
+                inputs: ["name"],
+                evidenceIds: named
+            }
+        };
+    return named.length > 0
+        ? {
+            category: "other",
+            inference: {
+                rule: "token-category.fallback",
+                confidence: 0.2,
+                reasoning: "No declared type, value kind or conventional name prefix identifies a category",
+                inputs: ["name"],
+                evidenceIds: named
+            }
+        }
+        : undefined;
+}
+/** Sets `category` on tokens that have only the reconciliation placeholder, and records why. */
+export function classifyTokens(tokens) {
+    return tokens.map((token) => {
+        if (token.facts.category)
+            return token;
+        const result = classify(token);
+        if (!result)
+            return token;
+        return {
+            ...token,
+            category: result.category,
+            facts: Object.fromEntries(Object.entries({ ...token.facts, category: inferredFact(result.inference) }).sort((a, b) => cmp(a[0], b[0])))
+        };
+    });
+}
+//# sourceMappingURL=tokens.js.map

package/dist/shared/canonical.js

@@ -0,0 +1,65 @@
+import { createHash } from "node:crypto";
+/**
+ * Canonical JSON: object keys sorted by UTF-16 code unit, no insignificant whitespace
+ * (or fixed-width indentation when `indent > 0`). Properties whose value is `undefined`
+ * are omitted, matching JSON.stringify. Non-finite numbers and `undefined` array items throw.
+ * Array order is preserved: producers are responsible for sorting arrays.
+ */
+export function canonicalStringify(value, indent = 0) {
+    return write(value, indent, 0);
+}
+export function sha256Hex(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+export function hashJson(value) {
+    return sha256Hex(canonicalStringify(value));
+}
+function write(value, indent, depth) {
+    if (value === null)
+        return "null";
+    switch (typeof value) {
+        case "string":
+            return JSON.stringify(value);
+        case "boolean":
+            return value ? "true" : "false";
+        case "number":
+            if (!Number.isFinite(value))
+                throw new TypeError(`Cannot canonicalize non-finite number: ${value}`);
+            return JSON.stringify(value);
+        case "object":
+            return Array.isArray(value) ? writeArray(value, indent, depth) : writeObject(value, indent, depth);
+        default:
+            throw new TypeError(`Cannot canonicalize value of type ${typeof value}`);
+    }
+}
+function writeArray(items, indent, depth) {
+    if (items.length === 0)
+        return "[]";
+    const parts = items.map((item) => {
+        if (item === undefined)
+            throw new TypeError("Cannot canonicalize undefined array item");
+        return write(item, indent, depth + 1);
+    });
+    return wrap("[", "]", parts, indent, depth);
+}
+function writeObject(object, indent, depth) {
+    const record = object;
+    const parts = [];
+    for (const key of Object.keys(record).sort()) {
+        const member = record[key];
+        if (member === undefined)
+            continue;
+        parts.push(`${JSON.stringify(key)}:${indent > 0 ? " " : ""}${write(member, indent, depth + 1)}`);
+    }
+    if (parts.length === 0)
+        return "{}";
+    return wrap("{", "}", parts, indent, depth);
+}
+function wrap(open, close, parts, indent, depth) {
+    if (indent <= 0)
+        return `${open}${parts.join(",")}${close}`;
+    const inner = " ".repeat(indent * (depth + 1));
+    const outer = " ".repeat(indent * depth);
+    return `${open}\n${inner}${parts.join(`,\n${inner}`)}\n${outer}${close}`;
+}
+//# sourceMappingURL=canonical.js.map

package/dist/shared/diagnostic.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+export const severitySchema = z.enum(["error", "warning", "info"]);
+export const diagnosticLocationSchema = z.strictObject({
+    path: z.string().min(1),
+    line: z.number().int().positive().optional(),
+    column: z.number().int().positive().optional()
+});
+/** Codes are `area.kebab-name`, for example `contract.dangling-reference`. */
+export const diagnosticCodeSchema = z.string().regex(/^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/);
+export const diagnosticSchema = z.strictObject({
+    code: diagnosticCodeSchema,
+    severity: severitySchema,
+    message: z.string().min(1),
+    sourceId: z.string().min(1).optional(),
+    entityId: z.string().min(1).optional(),
+    location: diagnosticLocationSchema.optional(),
+    hint: z.string().min(1).optional()
+});
+const SEVERITY_RANK = { error: 0, warning: 1, info: 2 };
+export function diagnostic(input) {
+    return diagnosticSchema.parse(input);
+}
+export function hasErrors(diagnostics) {
+    return diagnostics.some((d) => d.severity === "error");
+}
+/** Total order so diagnostic output is identical regardless of discovery order. */
+export function sortDiagnostics(diagnostics) {
+    return [...diagnostics].sort(compareDiagnostics);
+}
+function compareDiagnostics(a, b) {
+    return (SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] ||
+        cmp(a.code, b.code) ||
+        cmp(a.sourceId ?? "", b.sourceId ?? "") ||
+        cmp(a.entityId ?? "", b.entityId ?? "") ||
+        cmp(a.location?.path ?? "", b.location?.path ?? "") ||
+        (a.location?.line ?? 0) - (b.location?.line ?? 0) ||
+        (a.location?.column ?? 0) - (b.location?.column ?? 0) ||
+        cmp(a.message, b.message));
+}
+function cmp(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+export const DIAGNOSTICS_FILE_VERSION = "1.0.0";
+export const diagnosticsFileSchema = z.strictObject({
+    diagnosticsVersion: z.literal(DIAGNOSTICS_FILE_VERSION),
+    diagnostics: z.array(diagnosticSchema)
+});
+/** Accumulates diagnostics during a run. Output is always sorted, so discovery order never leaks. */
+export class DiagnosticCollector {
+    items = [];
+    defaults;
+    constructor(defaults = {}) {
+        this.defaults = defaults;
+    }
+    add(input) {
+        this.items.push(diagnostic({ ...this.defaults, ...input }));
+    }
+    error(code, message, extra = {}) {
+        this.add({ ...extra, code, severity: "error", message });
+    }
+    warning(code, message, extra = {}) {
+        this.add({ ...extra, code, severity: "warning", message });
+    }
+    info(code, message, extra = {}) {
+        this.add({ ...extra, code, severity: "info", message });
+    }
+    addAll(inputs) {
+        for (const input of inputs)
+            this.add(input);
+    }
+    hasErrors() {
+        return hasErrors(this.items);
+    }
+    toArray() {
+        return sortDiagnostics(this.items);
+    }
+}
+//# sourceMappingURL=diagnostic.js.map