@invariant-ui/cli 0.0.0-stage → 0.1.0

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

package/dist/contract-query/validate-code.js

@@ -0,0 +1,239 @@
+import { scanJsx, scanMarkup } from "./scan.js";
+import { normalize } from "./system.js";
+import { validateUsage } from "./validate-usage.js";
+export const MAX_CODE_CHARS = 200_000;
+export const MAX_FINDINGS = 200;
+const NATIVE_EQUIVALENTS = {
+    button: ["button"],
+    input: ["input", "textfield", "textinput"],
+    select: ["select", "dropdown"],
+    textarea: ["textarea", "textfield"],
+    dialog: ["dialog", "modal"],
+    table: ["table", "datatable"],
+    a: ["link"],
+    img: ["image", "img"],
+    label: ["label"],
+    progress: ["progress", "progressbar"]
+};
+const HEX = /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})(?![0-9A-Za-z_-])/g;
+const CSS_VAR = /var\(\s*(--[A-Za-z0-9_-]+)/g;
+function expandHex(hex) {
+    const h = hex.slice(1).toLowerCase();
+    return `#${h.length <= 4 ? [...h].map((c) => c + c).join("") : h}`;
+}
+function tagIndex(ds) {
+    const map = new Map();
+    const add = (key, c) => {
+        if (key === "")
+            return;
+        const list = map.get(key) ?? [];
+        if (!list.includes(c))
+            list.push(c);
+        map.set(key, list);
+    };
+    for (const c of ds.contract.components) {
+        add(normalize(c.name), c);
+        for (const i of c.implementations) {
+            if (i.exportName)
+                add(normalize(i.exportName), c);
+            const sel = i.extensions?.[i.framework]?.selector;
+            if (typeof sel === "string")
+                add(normalize(/^[a-z][a-z0-9-]*/.exec(sel)?.[0] ?? ""), c);
+        }
+    }
+    return map;
+}
+function tokenColors(ds) {
+    const colors = new Map();
+    for (const t of ds.contract.tokens) {
+        const values = [
+            ds.resolveToken(t).value,
+            ...Object.keys(t.modes ?? {}).map((m) => ds.resolveToken(t, m).value)
+        ];
+        for (const v of values)
+            if (typeof v === "string" && /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(v.trim())) {
+                const key = expandHex(v.trim());
+                if (!colors.has(key))
+                    colors.set(key, t.id);
+            }
+    }
+    return colors;
+}
+function cssVariableNames(ds) {
+    const names = new Set();
+    for (const t of ds.contract.tokens) {
+        const css = t.extensions?.css;
+        if (typeof css?.name === "string")
+            names.add(css.name);
+        names.add(t.name.startsWith("--") ? t.name : `--${t.name.replace(/\./g, "-")}`);
+    }
+    return names;
+}
+/** From the file name, else the contract's only framework, else React. */
+export function defaultFramework(ds, filename) {
+    if (filename) {
+        if (/\.vue$/i.test(filename))
+            return "vue";
+        if (/\.component\.html$/i.test(filename))
+            return "angular";
+        if (/\.html?$/i.test(filename))
+            return "html";
+        if (/\.[cm]?[jt]sx?$/i.test(filename))
+            return "react";
+    }
+    const known = ds.contract.metadata.frameworks.filter((f) => f === "react" || f === "vue" || f === "angular");
+    return known.length === 1 ? known[0] : "react";
+}
+/**
+ * Checks a code snippet against the contract without running it: uses of known components are validated
+ * with their literal props, literal colors and CSS variables are compared with the tokens. Dynamic values
+ * are counted, not guessed.
+ */
+export function validateCode(ds, input) {
+    const framework = input.framework ?? defaultFramework(ds, input.filename);
+    const findings = [];
+    const limitations = [
+        "Static check of the given snippet only: nothing is executed or imported.",
+        "Only literal prop values are verified; expressions and bindings are counted as unverified.",
+        "A component is recognized by name or selector. Components from other libraries are not checked."
+    ];
+    const checked = new Set();
+    const unknown = new Set();
+    let unverified = 0;
+    if (input.code.length > MAX_CODE_CHARS) {
+        return {
+            valid: false,
+            framework,
+            summary: {
+                errors: 1,
+                warnings: 0,
+                info: 0,
+                componentsChecked: [],
+                elementsNotInContract: [],
+                unverifiedValues: 0
+            },
+            findings: [
+                {
+                    code: "input-too-large",
+                    severity: "error",
+                    message: `The snippet is ${input.code.length} characters; the limit is ${MAX_CODE_CHARS}`,
+                    basis: "discovered"
+                }
+            ],
+            truncated: false,
+            limitations
+        };
+    }
+    const index = tagIndex(ds);
+    const uses = framework === "react" ? scanJsx(input.code, input.filename) : scanMarkup(input.code);
+    for (const use of uses) {
+        const key = normalize(use.tag.replace(/^.*:/, ""));
+        // A lowercase tag without a hyphen is a native element in every framework (custom elements need a hyphen).
+        const nativeTag = /^[a-z][a-z0-9]*$/.test(use.tag);
+        const matches = nativeTag ? [] : (index.get(key) ?? []);
+        if (matches.length === 1) {
+            const result = validateUsage(ds, {
+                component: matches[0].id,
+                framework: framework === "html" ? undefined : framework,
+                props: use.attrs,
+                hasChildren: use.hasChildren,
+                hasSpread: use.hasSpread
+            });
+            checked.add(matches[0].id);
+            unverified += result.unverifiedValues;
+            for (const f of result.findings)
+                findings.push({ ...f, line: use.line });
+            continue;
+        }
+        if (matches.length > 1) {
+            findings.push({
+                code: "component-ambiguous",
+                severity: "info",
+                message: `<${use.tag}> matches ${matches.map((m) => m.id).join(", ")}; it was not checked`,
+                line: use.line,
+                basis: "discovered"
+            });
+            continue;
+        }
+        const native = NATIVE_EQUIVALENTS[use.tag.toLowerCase()];
+        const equivalent = native
+            ? ds.contract.components.find((c) => native.includes(normalize(c.name)))
+            : undefined;
+        if (equivalent)
+            findings.push({
+                code: "native-element-has-equivalent",
+                severity: "info",
+                message: `<${use.tag}> is a native element and the design system has ${equivalent.name}. This is a name match, not a rule`,
+                line: use.line,
+                basis: "heuristic",
+                confidence: 0.5
+            });
+        else if (/^[A-Z]/.test(use.tag) || use.tag.includes("-"))
+            unknown.add(use.tag);
+    }
+    const colors = tokenColors(ds);
+    if (colors.size > 0) {
+        const lines = input.code.split("\n");
+        lines.forEach((text, idx) => {
+            for (const m of text.matchAll(HEX)) {
+                const before = text.slice(Math.max(0, (m.index ?? 0) - 14), m.index ?? 0);
+                if (/(href|to|id|name)\s*=\s*["']?$/i.test(before) || /&$/.test(before))
+                    continue;
+                const token = colors.get(expandHex(m[0]));
+                findings.push(token
+                    ? {
+                        code: "color-matches-token",
+                        severity: "info",
+                        message: `${m[0]} equals the value of ${token}; reference the token instead`,
+                        line: idx + 1,
+                        basis: "discovered"
+                    }
+                    : {
+                        code: "color-not-in-tokens",
+                        severity: "warning",
+                        message: `${m[0]} is a literal color that is not the value of any token`,
+                        line: idx + 1,
+                        basis: "discovered"
+                    });
+            }
+        });
+    }
+    else
+        limitations.push("No token has a literal color value, so literal colors were not checked.");
+    if (ds.contract.tokens.length > 0) {
+        const known = cssVariableNames(ds);
+        input.code.split("\n").forEach((text, idx) => {
+            for (const m of text.matchAll(CSS_VAR)) {
+                const name = m[1];
+                if (!known.has(name))
+                    findings.push({
+                        code: "unknown-css-variable",
+                        severity: "warning",
+                        message: `${name} is not a token in the contract`,
+                        line: idx + 1,
+                        basis: "discovered"
+                    });
+            }
+        });
+    }
+    else
+        limitations.push("The contract has no tokens, so CSS variables were not checked.");
+    findings.sort((a, b) => (a.line ?? 0) - (b.line ?? 0) || (a.code < b.code ? -1 : a.code > b.code ? 1 : 0));
+    const count = (s) => findings.filter((f) => f.severity === s).length;
+    return {
+        valid: count("error") === 0,
+        framework,
+        summary: {
+            errors: count("error"),
+            warnings: count("warning"),
+            info: count("info"),
+            componentsChecked: [...checked].sort(),
+            elementsNotInContract: [...unknown].sort().slice(0, 50),
+            unverifiedValues: unverified
+        },
+        findings: findings.slice(0, MAX_FINDINGS),
+        truncated: findings.length > MAX_FINDINGS,
+        limitations
+    };
+}
+//# sourceMappingURL=validate-code.js.map

package/dist/contract-query/validate-usage.js

@@ -0,0 +1,150 @@
+import { normalize } from "./system.js";
+export const isDynamic = (v) => typeof v === "object" &&
+    v !== null &&
+    !Array.isArray(v) &&
+    Object.keys(v).length === 1 &&
+    typeof v.expression === "string";
+const PASSTHROUGH = /^(data-|aria-)|^(key|ref|class|className|style|id|slot|role|tabindex|title|hidden)$/i;
+function sameValue(allowed, v) {
+    if (allowed === v)
+        return true;
+    return typeof v === "string" && typeof allowed !== "string" && String(allowed) === v;
+}
+export function validateUsage(ds, input) {
+    const findings = [];
+    const found = ds.findComponent(input.component);
+    if (!found.match) {
+        const names = found.candidates.map((c) => c.name);
+        findings.push({
+            code: found.candidates.length > 1 && names.some((n) => normalize(n) === normalize(input.component))
+                ? "component-ambiguous"
+                : "component-unknown",
+            severity: "error",
+            message: `No single component "${input.component}" in the contract${names.length > 0 ? `. Candidates: ${names.join(", ")}` : ""}`,
+            basis: "discovered"
+        });
+        return { findings, unverifiedValues: 0 };
+    }
+    const c = found.match;
+    const framework = input.framework;
+    if (framework && !c.implementations.some((i) => i.framework === framework))
+        findings.push({
+            code: "framework-not-implemented",
+            severity: "error",
+            message: `${c.name} has no ${framework} implementation (it has: ${c.implementations.map((i) => i.framework).join(", ")})`,
+            basis: "discovered"
+        });
+    if (c.lifecycle === "deprecated")
+        findings.push({
+            code: "component-deprecated",
+            severity: "warning",
+            message: `${c.name} is deprecated`,
+            basis: ds.factView(c.facts, "lifecycle")?.status === "documented" ? "documented" : "discovered"
+        });
+    const complete = ds.propsComplete(c, framework);
+    const props = input.props ?? {};
+    let unverified = 0;
+    const basisOf = (path) => {
+        const s = ds.factView(c.facts, path)?.status;
+        return s === "documented" || s === "inferred" ? s : "discovered";
+    };
+    const where = (path) => {
+        const s = ds.factView(c.facts, path)?.source;
+        return s ? { source: s } : {};
+    };
+    const eventNames = new Set(c.events.map((e) => normalize(e.name)));
+    const slotNames = new Set(c.slots.map((s) => normalize(s.name)));
+    for (const [name, value] of Object.entries(props)) {
+        const prop = c.props.find((p) => p.name === name);
+        if (!prop) {
+            if (PASSTHROUGH.test(name) ||
+                eventNames.has(normalize(name.replace(/^on(?=[A-Z])/, ""))) ||
+                slotNames.has(normalize(name)))
+                continue;
+            findings.push(complete
+                ? {
+                    code: "unknown-prop",
+                    severity: "warning",
+                    message: `${c.name} does not declare a prop "${name}"`,
+                    path: `props.${name}`,
+                    basis: "discovered"
+                }
+                : {
+                    code: "unverifiable-prop",
+                    severity: "info",
+                    message: `${c.name}'s prop list is incomplete, so "${name}" could not be verified`,
+                    path: `props.${name}`,
+                    basis: "discovered"
+                });
+            continue;
+        }
+        const base = `props.${name}`;
+        if (prop.deprecated)
+            findings.push({
+                code: "prop-deprecated",
+                severity: "warning",
+                message: `${c.name}.${name} is deprecated${prop.deprecated.reason ? `: ${prop.deprecated.reason}` : ""}`,
+                path: base,
+                basis: basisOf(`${base}.deprecated`),
+                ...where(`${base}.deprecated`)
+            });
+        if (isDynamic(value)) {
+            unverified++;
+            continue;
+        }
+        if (prop.allowedValues &&
+            (typeof value === "string" || typeof value === "number" || typeof value === "boolean")) {
+            if (!prop.allowedValues.some((a) => sameValue(a, value)))
+                findings.push({
+                    code: "prop-value-not-allowed",
+                    severity: "error",
+                    message: `${c.name}.${name} is ${JSON.stringify(value)}, which is not one of ${prop.allowedValues.map((a) => JSON.stringify(a)).join(", ")}`,
+                    path: `${base}.allowedValues`,
+                    basis: basisOf(`${base}.allowedValues`),
+                    ...where(`${base}.allowedValues`)
+                });
+        }
+        else {
+            const kind = prop.type.kind;
+            const bad = (kind === "boolean" && typeof value !== "boolean") ||
+                (kind === "number" && typeof value !== "number") ||
+                (kind === "string" && typeof value !== "string");
+            if (bad)
+                findings.push({
+                    code: "prop-type-mismatch",
+                    severity: "warning",
+                    message: `${c.name}.${name} expects ${kind} (${prop.type.text}) but got ${JSON.stringify(value)}`,
+                    path: `${base}.type`,
+                    basis: basisOf(`${base}.type.text`),
+                    ...where(`${base}.type.text`)
+                });
+        }
+    }
+    if (!input.hasSpread)
+        for (const p of c.props) {
+            if (!p.required || p.name in props)
+                continue;
+            if (p.name === "children") {
+                if (input.hasChildren === false)
+                    findings.push({
+                        code: "required-prop-missing",
+                        severity: "error",
+                        message: `${c.name} requires children`,
+                        path: "props.children",
+                        basis: basisOf("props.children.required"),
+                        ...where("props.children.required")
+                    });
+                continue;
+            }
+            findings.push({
+                code: "required-prop-missing",
+                severity: "error",
+                message: `${c.name} requires the prop "${p.name}"`,
+                path: `props.${p.name}`,
+                basis: basisOf(`props.${p.name}.required`),
+                ...where(`props.${p.name}.required`)
+            });
+        }
+    return { component: c.id, findings, unverifiedValues: unverified };
+}
+//# sourceMappingURL=validate-usage.js.map