@invariant-ui/cli 0.0.0-stage → 0.1.0

package/dist/validation/policy.js

@@ -0,0 +1,241 @@
+import { isPatternConstraintKind } from "../contract/index.js";
+import { normalize } from "../contract-query/index.js";
+import { z } from "zod";
+import { isDynamic } from "./validate-usage.js";
+const names = z.array(z.string().min(1).max(200)).min(1).max(200);
+const scalar = z.union([z.string(), z.number(), z.boolean()]);
+/**
+ * What an approved policy enforces, in a form the validator can evaluate. Written by people in
+ * `invariant.policies.json`, normalized by governance into a constraint's `extensions.invariant.rule`.
+ */
+export const policyRuleSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("require-attribute"),
+        components: names,
+        anyOf: names,
+        unlessChildren: z.boolean().optional(),
+        category: z.enum(["accessibility", "general"]).optional()
+    }),
+    z.strictObject({
+        kind: z.literal("forbid-prop"),
+        component: z.string().min(1).max(200),
+        prop: z.string().min(1).max(200),
+        replacedBy: z.string().min(1).max(200).optional()
+    }),
+    z.strictObject({
+        kind: z.literal("forbid-prop-value"),
+        component: z.string().min(1).max(200),
+        prop: z.string().min(1).max(200),
+        values: z.array(scalar).min(1).max(100)
+    }),
+    z.strictObject({
+        kind: z.literal("forbid-component"),
+        component: z.string().min(1).max(200),
+        use: z.string().min(1).max(200).optional()
+    }),
+    z.strictObject({
+        kind: z.literal("forbid-token"),
+        tokens: names,
+        replacedBy: z.string().min(1).max(200).optional()
+    }),
+    z.strictObject({
+        kind: z.literal("allowed-children"),
+        container: z.string().min(1).max(200),
+        children: names,
+        category: z.enum(["layout", "composition"]).optional()
+    }),
+    z.strictObject({
+        kind: z.literal("required-parent"),
+        component: z.string().min(1).max(200),
+        parents: names
+    })
+]);
+const capped = (severity, enforcement) => enforcement === "report-only"
+    ? "info"
+    : enforcement === "warn" && severity === "error"
+        ? "warning"
+        : severity;
+/** Approved policies and the rules they carry. A policy whose rule cannot be read is reported, not enforced. */
+export function activePolicies(contract) {
+    const active = [];
+    const problems = [];
+    for (const policy of contract.policies) {
+        for (const id of policy.basedOn) {
+            const constraint = contract.constraints.find((c) => c.id === id);
+            // Structural pattern constraints are evaluated by `pattern-rules.ts`, not as component-level rules.
+            if (constraint && isPatternConstraintKind(constraint.kind))
+                continue;
+            const raw = constraint?.extensions?.invariant ?? {};
+            const parsed = policyRuleSchema.safeParse(raw.rule);
+            if (!constraint || !parsed.success) {
+                problems.push(`policy ${policy.id}: ${id} has no readable rule`);
+                continue;
+            }
+            active.push({
+                policyId: policy.id,
+                name: policy.name,
+                severity: capped(policy.severity, policy.enforcement),
+                rule: parsed.data,
+                ...(typeof raw.source === "string" ? { source: raw.source } : {})
+            });
+        }
+    }
+    return { active, problems };
+}
+/** `requires-parent` relationships the contract itself records, as rules (inferred ones are not enforced). */
+export function relationshipRules(ds) {
+    const out = [];
+    for (const c of ds.contract.components)
+        c.composition.forEach((r, i) => {
+            if (r.type !== "requires-parent")
+                return;
+            const status = c.facts[`composition.${i}`]?.status;
+            if (status === "inferred")
+                return;
+            out.push({
+                policyId: "",
+                name: `${c.name} requires a parent`,
+                severity: "error",
+                rule: { kind: "required-parent", component: c.id, parents: [r.target] }
+            });
+        });
+    return out;
+}
+const same = (a, b) => normalize(a.replace(/^component:/, "")) === normalize(b.replace(/^component:/, ""));
+const matches = (c, ref) => c.id === ref || same(c.name, ref) || same(c.id, ref);
+const ref = (p) => ({
+    ...(p.policyId ? { policy: p.policyId } : {}),
+    ...(p.source ? { source: p.source } : {}),
+    basis: p.policyId ? "approved" : "discovered"
+});
+const why = (p) => (p.policyId ? ` (policy ${p.policyId})` : "");
+function ancestors(ctx, index) {
+    const out = [];
+    for (let p = ctx.uses[index]?.parent; p !== undefined; p = ctx.uses[p]?.parent)
+        out.push(p);
+    return out;
+}
+/** Evaluates component-level rules against one scanned element. */
+export function evaluateUse(policies, ctx, index) {
+    const use = ctx.uses[index];
+    const comp = ctx.resolved[index];
+    if (!comp)
+        return [];
+    const findings = [];
+    const attrNames = new Set(Object.keys(use.attrs).map((n) => normalize(n)));
+    for (const p of policies) {
+        const r = p.rule;
+        switch (r.kind) {
+            case "require-attribute": {
+                if (!r.components.some((x) => matches(comp, x)) || use.hasSpread)
+                    break;
+                if (r.anyOf.some((a) => attrNames.has(normalize(a))))
+                    break;
+                if (r.unlessChildren) {
+                    if (use.hasChildren === true)
+                        break;
+                    if (use.hasChildren === undefined)
+                        break;
+                }
+                const accessibility = r.category === "accessibility";
+                findings.push({
+                    code: accessibility ? "accessibility-requirement-missing" : "policy-attribute-required",
+                    severity: p.severity,
+                    subject: comp.id,
+                    message: `${comp.name} needs one of ${r.anyOf.join(", ")}${r.unlessChildren ? " when it has no children" : ""}${why(p)}`,
+                    ...ref(p),
+                    suggestion: `Add ${r.anyOf[0]}="...".`
+                });
+                break;
+            }
+            case "forbid-prop": {
+                if (!matches(comp, r.component) ||
+                    !(normalize(r.prop) in Object.fromEntries([...attrNames].map((n) => [n, 1]))))
+                    break;
+                findings.push({
+                    code: "prop-forbidden",
+                    severity: p.severity,
+                    subject: comp.id,
+                    message: `${comp.name} must not use "${r.prop}"${why(p)}`,
+                    path: `props.${r.prop}`,
+                    ...ref(p),
+                    suggestion: r.replacedBy ? `Use ${r.replacedBy} instead.` : `Remove "${r.prop}".`
+                });
+                break;
+            }
+            case "forbid-prop-value": {
+                if (!matches(comp, r.component))
+                    break;
+                const key = Object.keys(use.attrs).find((n) => normalize(n) === normalize(r.prop));
+                const value = key === undefined ? undefined : use.attrs[key];
+                if (value === undefined || isDynamic(value))
+                    break;
+                if (!r.values.some((v) => v === value || String(v) === String(value)))
+                    break;
+                findings.push({
+                    code: "prop-value-forbidden",
+                    severity: p.severity,
+                    subject: comp.id,
+                    message: `${comp.name}.${r.prop} must not be ${JSON.stringify(value)}${why(p)}`,
+                    path: `props.${r.prop}`,
+                    ...ref(p),
+                    suggestion: "Choose a different value."
+                });
+                break;
+            }
+            case "forbid-component": {
+                if (!matches(comp, r.component))
+                    break;
+                findings.push({
+                    code: "component-forbidden",
+                    severity: p.severity,
+                    subject: comp.id,
+                    message: `${comp.name} must not be used${why(p)}`,
+                    ...ref(p),
+                    suggestion: r.use ? `Use ${r.use} instead.` : "Use an approved component."
+                });
+                break;
+            }
+            case "allowed-children": {
+                const parent = ctx.uses[index]?.parent;
+                const container = parent === undefined ? undefined : ctx.resolved[parent];
+                if (!container || !matches(container, r.container))
+                    break;
+                if (r.children.some((x) => matches(comp, x)))
+                    break;
+                findings.push({
+                    code: r.category === "layout" ? "layout-pattern-invalid" : "composition-not-allowed",
+                    severity: p.severity,
+                    subject: comp.id,
+                    message: `${comp.name} is not allowed directly inside ${container.name}; allowed: ${r.children.join(", ")}${why(p)}`,
+                    ...ref(p),
+                    suggestion: `Put ${comp.name} inside an allowed component, or use one of ${r.children.join(", ")} here.`
+                });
+                break;
+            }
+            case "required-parent": {
+                if (!matches(comp, r.component))
+                    break;
+                const chain = ancestors(ctx, index);
+                const dsAncestors = chain.map((a) => ctx.resolved[a]).filter((c) => c !== undefined);
+                // Only a violation when it sits inside other design-system components but none is an allowed parent: at the
+                // top of a file the real parent may be in another file.
+                if (dsAncestors.length === 0 || dsAncestors.some((a) => r.parents.some((x) => matches(a, x))))
+                    break;
+                findings.push({
+                    code: p.policyId ? "composition-not-allowed" : "composition-parent-required",
+                    severity: p.severity,
+                    subject: comp.id,
+                    message: `${comp.name} must be inside ${r.parents.join(" or ")}${why(p)}`,
+                    ...ref(p),
+                    suggestion: `Wrap it in ${r.parents[0]}.`
+                });
+                break;
+            }
+            case "forbid-token":
+                break;
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=policy.js.map

package/dist/validation/report.js

@@ -0,0 +1,163 @@
+import { RULES, ruleFor } from "./rules.js";
+export function summarize(violations, files, componentsChecked, evaluations = []) {
+    const n = (s) => violations.filter((v) => v.severity === s).length;
+    const patternRules = { pass: 0, fail: 0, warning: 0, notVerifiable: 0, skipped: 0 };
+    for (const e of evaluations)
+        patternRules[e.status === "not-verifiable" ? "notVerifiable" : e.status]++;
+    const leveled = evaluations.filter((e) => e.level !== undefined);
+    const interactionEvidence = leveled.length === 0
+        ? undefined
+        : {
+            structural: leveled.filter((e) => e.level === "structural").length,
+            staticInferred: leveled.filter((e) => e.level === "static-inferred").length,
+            runtimeVerified: leveled.filter((e) => e.level === "runtime-verified").length
+        };
+    return {
+        files,
+        errors: n("error"),
+        warnings: n("warning"),
+        info: n("info"),
+        componentsChecked,
+        patternRules,
+        ...(interactionEvidence ? { interactionEvidence } : {})
+    };
+}
+const evidenceLine = (s) => {
+    const e = s.interactionEvidence;
+    if (!e)
+        return undefined;
+    return `interaction evidence: ${e.structural + e.staticInferred + e.runtimeVerified} structural or better (${e.staticInferred} statically inferred, ${e.structural} structural only, ${e.runtimeVerified} runtime verified; static analysis does not run the code)`;
+};
+const patternLine = (s) => `${s.pass} passed, ${s.fail} failed, ${s.warning} warnings, ${s.notVerifiable} not verifiable, ${s.skipped} skipped`;
+const hasPatternRules = (s) => Object.values(s).some((n) => n > 0);
+export function sortEvaluations(evaluations) {
+    return [...evaluations].sort((a, b) => ((a.file ?? "") < (b.file ?? "") ? -1 : (a.file ?? "") > (b.file ?? "") ? 1 : 0) ||
+        (a.line ?? 0) - (b.line ?? 0) ||
+        (a.column ?? 0) - (b.column ?? 0) ||
+        (a.constraint < b.constraint ? -1 : a.constraint > b.constraint ? 1 : 0));
+}
+const RANK = { error: 0, warning: 1, info: 2 };
+/** Sorts worst-first: file, then position in it, then severity, then rule. `file` is optional for snippet checks. */
+export function sortViolations(violations) {
+    const fileOf = (f) => f.file ?? "";
+    return [...violations].sort((a, b) => (fileOf(a) < fileOf(b) ? -1 : fileOf(a) > fileOf(b) ? 1 : 0) ||
+        (a.line ?? 0) - (b.line ?? 0) ||
+        (a.column ?? 0) - (b.column ?? 0) ||
+        RANK[a.severity] - RANK[b.severity] ||
+        (a.code < b.code ? -1 : a.code > b.code ? 1 : 0));
+}
+/** True when the run should fail the build. */
+export function shouldFail(summary, failOn) {
+    return failOn === "never"
+        ? false
+        : failOn === "warning"
+            ? summary.errors + summary.warnings > 0
+            : summary.errors > 0;
+}
+export function formatText(violations, summary, evaluations = []) {
+    const lines = [];
+    for (const v of sortViolations(violations)) {
+        lines.push(`${v.file}:${v.line ?? 1}:${v.column ?? 1} ${v.severity} ${v.code}`);
+        lines.push(`  ${v.message}`);
+        if (v.suggestion)
+            lines.push(`  fix: ${v.suggestion}`);
+        const refs = [
+            v.source ? `evidence ${v.source} (${v.basis})` : `basis ${v.basis}`,
+            v.policy ? `policy ${v.policy}` : undefined,
+            v.subject ? `subject ${v.subject}` : undefined
+        ].filter(Boolean);
+        lines.push(`  ${refs.join("; ")}`);
+        lines.push("");
+    }
+    const unestablished = sortEvaluations(evaluations).filter((e) => e.status === "not-verifiable" || e.status === "skipped");
+    if (hasPatternRules(summary.patternRules)) {
+        lines.push(`pattern rules: ${patternLine(summary.patternRules)}`);
+        const evidence = evidenceLine(summary);
+        if (evidence)
+            lines.push(evidence);
+        for (const e of unestablished.slice(0, 50))
+            lines.push(`  ${e.status === "skipped" ? "skipped" : "not verifiable"} ${e.file ?? "(snippet)"}:${e.line ?? 1} ${e.rule}: ${e.reason}`);
+        if (unestablished.length > 50)
+            lines.push(`  ... ${unestablished.length - 50} more (see --format json)`);
+        lines.push("");
+    }
+    lines.push(`${summary.errors} errors, ${summary.warnings} warnings, ${summary.info} info in ${summary.files} files (${summary.componentsChecked} components checked)`);
+    return lines.join("\n");
+}
+export function toJson(violations, summary, contractHash, evaluations = []) {
+    return {
+        contractHash,
+        summary,
+        violations: sortViolations(violations),
+        evaluations: sortEvaluations(evaluations)
+    };
+}
+/** The pattern-rule tally for a one-line summary, or an empty string when no pattern rule applied. */
+export const patternSummaryText = (s) => {
+    if (!hasPatternRules(s.patternRules))
+        return "";
+    const evidence = evidenceLine(s);
+    return `pattern rules: ${patternLine(s.patternRules)}${evidence ? `\n${evidence}` : ""}`;
+};
+const escData = (s) => s.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+const escProp = (s) => escData(s).replace(/:/g, "%3A").replace(/,/g, "%2C");
+/** GitHub Actions workflow commands: one annotation per violation. */
+export function formatGithub(violations) {
+    return sortViolations(violations)
+        .map((v) => {
+        const level = v.severity === "error" ? "error" : v.severity === "warning" ? "warning" : "notice";
+        const props = `file=${escProp(v.file)},line=${v.line ?? 1},col=${v.column ?? 1},title=${escProp(v.code)}`;
+        return `::${level} ${props}::${escData(v.suggestion ? `${v.message}. Fix: ${v.suggestion}` : v.message)}`;
+    })
+        .join("\n");
+}
+/** SARIF 2.1.0, accepted by GitHub code scanning and most CI viewers. */
+export function toSarif(violations, tool, summary) {
+    const level = (s) => (s === "info" ? "note" : s);
+    const used = new Set(violations.map((v) => v.code));
+    return {
+        $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+        version: "2.1.0",
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: tool.name,
+                        version: tool.version,
+                        rules: RULES.filter((r) => used.has(r.code)).map((r) => ({
+                            id: r.code,
+                            name: r.title,
+                            shortDescription: { text: r.title },
+                            properties: { planRule: r.plan, origin: r.origin },
+                            defaultConfiguration: { level: level(r.severity) }
+                        }))
+                    }
+                },
+                ...(summary && hasPatternRules(summary.patternRules)
+                    ? { properties: { patternRules: summary.patternRules } }
+                    : {}),
+                results: sortViolations(violations).map((v) => ({
+                    ruleId: v.code,
+                    level: level(v.severity),
+                    message: { text: v.suggestion ? `${v.message}. Fix: ${v.suggestion}` : v.message },
+                    locations: [
+                        {
+                            physicalLocation: {
+                                artifactLocation: { uri: v.file },
+                                region: { startLine: v.line ?? 1, startColumn: v.column ?? 1 }
+                            }
+                        }
+                    ],
+                    properties: {
+                        basis: v.basis,
+                        ...(v.source ? { evidence: v.source } : {}),
+                        ...(v.policy ? { policy: v.policy } : {}),
+                        ...(v.subject ? { subject: v.subject } : {}),
+                        ...(ruleFor(v.code) ? {} : {})
+                    }
+                }))
+            }
+        ]
+    };
+}
+//# sourceMappingURL=report.js.map

package/dist/validation/rules.js

@@ -0,0 +1,269 @@
+export const RULES = [
+    {
+        code: "component-unknown",
+        title: "Component is not in the design system",
+        plan: "Unknown component",
+        severity: "error",
+        origin: "contract"
+    },
+    {
+        code: "component-ambiguous",
+        title: "Name matches several components",
+        plan: "support",
+        severity: "info",
+        origin: "contract"
+    },
+    {
+        code: "framework-not-implemented",
+        title: "Component has no implementation in this framework",
+        plan: "Unknown component",
+        severity: "error",
+        origin: "contract"
+    },
+    {
+        code: "unknown-prop",
+        title: "Property is not declared by the component",
+        plan: "Unknown property",
+        severity: "warning",
+        origin: "contract"
+    },
+    {
+        code: "unverifiable-prop",
+        title: "Property could not be verified (incomplete API listing)",
+        plan: "support",
+        severity: "info",
+        origin: "contract"
+    },
+    {
+        code: "prop-value-not-allowed",
+        title: "Property value is not one of the declared values",
+        plan: "Invalid property value",
+        severity: "error",
+        origin: "contract"
+    },
+    {
+        code: "prop-type-mismatch",
+        title: "Property value has the wrong type",
+        plan: "Invalid property value",
+        severity: "warning",
+        origin: "contract"
+    },
+    {
+        code: "component-deprecated",
+        title: "Component is deprecated",
+        plan: "Deprecated component",
+        severity: "warning",
+        origin: "contract"
+    },
+    {
+        code: "prop-deprecated",
+        title: "Property is deprecated",
+        plan: "Deprecated property",
+        severity: "warning",
+        origin: "contract"
+    },
+    {
+        code: "required-prop-missing",
+        title: "Required property is missing",
+        plan: "Missing required property",
+        severity: "error",
+        origin: "contract"
+    },
+    {
+        code: "color-not-in-tokens",
+        title: "Literal color is not a design token",
+        plan: "Hardcoded color",
+        severity: "warning",
+        origin: "contract"
+    },
+    {
+        code: "color-matches-token",
+        title: "Literal color equals a design token",
+        plan: "Hardcoded color",
+        severity: "info",
+        origin: "contract"
+    },
+    {
+        code: "spacing-not-in-tokens",
+        title: "Literal spacing value is not a design token",
+        plan: "Hardcoded value",
+        severity: "warning",
+        origin: "contract"
+    },
+    {
+        code: "spacing-matches-token",
+        title: "Literal spacing value equals a design token",
+        plan: "Hardcoded value",
+        severity: "info",
+        origin: "contract"
+    },
+    {
+        code: "typography-not-in-tokens",
+        title: "Literal typography value is not a design token",
+        plan: "Hardcoded value",
+        severity: "warning",
+        origin: "contract"
+    },
+    {
+        code: "typography-matches-token",
+        title: "Literal typography value equals a design token",
+        plan: "Hardcoded value",
+        severity: "info",
+        origin: "contract"
+    },
+    {
+        code: "pattern-required-child-missing",
+        title: "Pattern requires a child that is missing",
+        plan: "Pattern composition",
+        severity: "error",
+        origin: "policy"
+    },
+    {
+        code: "pattern-child-forbidden",
+        title: "Pattern forbids a child that is present",
+        plan: "Pattern composition",
+        severity: "error",
+        origin: "policy"
+    },
+    {
+        code: "pattern-parent-required",
+        title: "Component is used outside the parent its pattern requires",
+        plan: "Pattern composition",
+        severity: "error",
+        origin: "policy"
+    },
+    {
+        code: "pattern-region-missing",
+        title: "Pattern region is missing",
+        plan: "Pattern composition",
+        severity: "error",
+        origin: "policy"
+    },
+    {
+        code: "pattern-order-violated",
+        title: "Elements are in the wrong order for the pattern",
+        plan: "Pattern composition",
+        severity: "error",
+        origin: "policy"
+    },
+    {
+        code: "pattern-cardinality-violated",
+        title: "Number of elements breaks the pattern",
+        plan: "Pattern composition",
+        severity: "error",
+        origin: "policy"
+    },
+    {
+        code: "pattern-state-missing",
+        title: "Interaction state the pattern requires is not represented",
+        plan: "Pattern composition",
+        severity: "error",
+        origin: "policy"
+    },
+    {
+        code: "unknown-css-variable",
+        title: "CSS variable is not a design token",
+        plan: "Unapproved token",
+        severity: "warning",
+        origin: "contract"
+    },
+    {
+        code: "token-deprecated",
+        title: "Token is deprecated",
+        plan: "Unapproved token",
+        severity: "warning",
+        origin: "contract"
+    },
+    {
+        code: "token-forbidden",
+        title: "Token is forbidden by policy",
+        plan: "Unapproved token",
+        severity: "error",
+        origin: "policy"
+    },
+    {
+        code: "composition-parent-required",
+        title: "Component is used outside the parent it requires",
+        plan: "Unsupported composition",
+        severity: "error",
+        origin: "contract"
+    },
+    {
+        code: "composition-not-allowed",
+        title: "Component is not allowed inside this container",
+        plan: "Unsupported composition",
+        severity: "error",
+        origin: "policy"
+    },
+    {
+        code: "layout-pattern-invalid",
+        title: "Layout structure is not allowed",
+        plan: "Invalid layout pattern",
+        severity: "error",
+        origin: "policy"
+    },
+    {
+        code: "accessibility-requirement-missing",
+        title: "Accessibility requirement is not met",
+        plan: "Missing accessibility requirement",
+        severity: "error",
+        origin: "policy"
+    },
+    {
+        code: "policy-attribute-required",
+        title: "Policy requires an attribute",
+        plan: "support",
+        severity: "error",
+        origin: "policy"
+    },
+    {
+        code: "prop-forbidden",
+        title: "Property is forbidden by policy",
+        plan: "support",
+        severity: "error",
+        origin: "policy"
+    },
+    {
+        code: "prop-value-forbidden",
+        title: "Property value is forbidden by policy",
+        plan: "support",
+        severity: "error",
+        origin: "policy"
+    },
+    {
+        code: "component-forbidden",
+        title: "Component is forbidden by policy",
+        plan: "support",
+        severity: "error",
+        origin: "policy"
+    },
+    {
+        code: "native-element-has-equivalent",
+        title: "Native element has a similarly named component",
+        plan: "support",
+        severity: "info",
+        origin: "heuristic"
+    },
+    {
+        code: "input-too-large",
+        title: "Input exceeds the size limit",
+        plan: "support",
+        severity: "error",
+        origin: "contract"
+    }
+];
+export const ruleFor = (code) => RULES.find((r) => r.code === code);
+export const PLAN_RULES = [
+    "Unknown component",
+    "Unknown property",
+    "Invalid property value",
+    "Deprecated component",
+    "Deprecated property",
+    "Unsupported composition",
+    "Missing required property",
+    "Hardcoded color",
+    "Unapproved token",
+    "Missing accessibility requirement",
+    "Invalid layout pattern"
+];
+//# sourceMappingURL=rules.js.map