@invariant-ui/cli 0.0.0-stage → 0.1.0

package/dist/cli/config.js

@@ -0,0 +1,197 @@
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { discoverProject, nodeFs } from "../compiler-core/index.js";
+import { nearest, RULES } from "../validation/index.js";
+import { z } from "zod";
+import { CliError } from "./errors.js";
+export const CONFIG_FILE = "invariant.config.json";
+export const DEFAULT_OUTPUT = "invariant";
+const CODE_CONFIGS = [
+    "invariant.config.ts",
+    "invariant.config.mts",
+    "invariant.config.mjs",
+    "invariant.config.js"
+];
+/** Source types the compiler can read today. zeroheight and Figma are planned but not implemented. */
+export const SOURCE_TYPES = ["react", "vue", "angular", "storybook", "tokens"];
+const PLANNED_TYPES = ["zeroheight", "figma"];
+const slugRe = /^[a-z0-9][a-z0-9._-]*$/;
+/** A project-relative path: no absolute paths, no drive letters, no backslashes, no `..`. */
+export function isSafeRelativePath(p) {
+    return (p !== "" &&
+        !p.startsWith("/") &&
+        !/^[A-Za-z]:/.test(p) &&
+        !p.includes("\\") &&
+        !p.split("/").includes(".."));
+}
+const relPath = z.string().refine(isSafeRelativePath, "must be a relative path inside the project (no '..')");
+export const configSchema = z.strictObject({
+    name: z.string().min(1),
+    contractId: z.string().regex(slugRe).max(64).optional(),
+    description: z.string().min(1).optional(),
+    sources: z.array(z.strictObject({
+        /** A label for this entry. Compiled source ids come from the adapters; `analyze` shows the mapping. */
+        id: z.string().regex(slugRe).max(64),
+        type: z.enum(SOURCE_TYPES),
+        /** Limits the entry to sources found at or below this directory. Omitted means the whole project. */
+        path: relPath.optional(),
+        /**
+         * Read the installed package at `path` (for example `node_modules/@acme/ui`) as a source, although it
+         * sits under node_modules. Needs `path`.
+         */
+        declarations: z.boolean().optional()
+    })),
+    output: z.strictObject({ directory: relPath }).optional(),
+    /**
+     * For an application that uses a design system it does not contain: the folder holding the contract the library
+     * ships (for example `node_modules/@acme/ui/invariant`). `compile` then starts from that contract instead of reading
+     * sources, and adds this project's own patterns, policies and decisions on top.
+     */
+    extends: z.strictObject({ contract: relPath }).optional(),
+    validation: z
+        .strictObject({
+        /** Severity per rule code, or `off`. See `invariant rules`. */
+        rules: z.record(z.string(), z.enum(["off", "info", "warning", "error"])).optional(),
+        /** Globs of files `validate` skips when walking directories. */
+        ignore: z.array(z.string().min(1).max(300)).max(100).optional(),
+        failOn: z.enum(["error", "warning", "never"]).optional()
+    })
+        .optional(),
+    governance: z
+        .strictObject({
+        /** If present, only these names may record decisions. Names are asserted, not authenticated. */
+        approvers: z.array(z.string().min(1).max(200)).max(200).optional(),
+        policiesFile: relPath.optional(),
+        patternsFile: relPath.optional(),
+        decisionsFile: relPath.optional(),
+        candidateReviewsFile: relPath.optional()
+    })
+        .optional(),
+    enforcement: z
+        .strictObject({
+        /**
+         * What `invariant hook` does when an AI agent writes code that breaks the contract. `gate-errors` blocks
+         * the write when error-severity findings remain after the baseline and rule overrides; `warn` never blocks
+         * and reports everything after the write; `off` checks nothing. Warnings never block.
+         */
+        hooks: z.enum(["gate-errors", "warn", "off"]).optional()
+    })
+        .optional()
+});
+export function outputDirectory(config) {
+    return config?.output?.directory ?? DEFAULT_OUTPUT;
+}
+export function validateConfig(raw) {
+    const sources = raw?.sources;
+    if (Array.isArray(sources)) {
+        for (const s of sources) {
+            const type = s?.type;
+            if (typeof type === "string" && PLANNED_TYPES.includes(type))
+                throw new CliError(`source type "${type}" is not supported yet. Supported: ${SOURCE_TYPES.join(", ")}. Remove the entry, or wait for the ${type} compiler.`);
+        }
+    }
+    const parsed = configSchema.safeParse(raw);
+    if (!parsed.success) {
+        const lines = parsed.error.issues.map((i) => `  ${i.path.join(".") || "(root)"}: ${i.message}`);
+        throw new CliError(`invalid configuration:\n${lines.join("\n")}`);
+    }
+    for (const code of Object.keys(parsed.data.validation?.rules ?? {})) {
+        if (RULES.some((r) => r.code === code))
+            continue;
+        const close = nearest(code, RULES.map((r) => r.code));
+        throw new CliError(`invalid configuration: validation.rules has unknown rule "${code}"${close.length > 0 ? `. Did you mean ${close.join(" or ")}?` : ""} (see \`invariant rules\`)`);
+    }
+    const ids = new Set();
+    for (const s of parsed.data.sources) {
+        if (s.declarations && s.path === undefined)
+            throw new CliError(`invalid configuration: source "${s.id}" sets declarations but has no path`);
+        if (ids.has(s.id))
+            throw new CliError(`invalid configuration: duplicate source id "${s.id}"`);
+        ids.add(s.id);
+    }
+    return parsed.data;
+}
+/**
+ * Finds and loads the configuration. JSON is read as data. A TypeScript or JavaScript config is code, and
+ * loading it runs it, so it is only loaded when the user passes `--trust-config`.
+ */
+export async function loadConfig(input) {
+    const candidates = input.file
+        ? [path.resolve(input.cwd, input.file)]
+        : [CONFIG_FILE, ...CODE_CONFIGS].map((f) => path.join(input.cwd, f));
+    const file = candidates.find((f) => existsSync(f));
+    if (!file) {
+        if (input.file)
+            throw new CliError(`configuration file not found: ${input.file}`);
+        return undefined;
+    }
+    if (file.endsWith(".json")) {
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch (error) {
+            throw new CliError(`${path.relative(input.cwd, file)} is not valid JSON: ${error.message}`);
+        }
+        return { config: validateConfig(raw), file, editable: true };
+    }
+    if (!input.trustConfig)
+        throw new CliError(`${path.relative(input.cwd, file)} is code, and loading it runs it. Re-run with --trust-config if you trust it, or use ${CONFIG_FILE}.`);
+    const module = (await import(pathToFileURL(file).href));
+    if (module.default === undefined)
+        throw new CliError(`${path.relative(input.cwd, file)} has no default export`);
+    return { config: validateConfig(module.default), file, editable: false };
+}
+export function writeConfig(file, config) {
+    writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+export const slug = (text) => {
+    const s = text
+        .toLowerCase()
+        .replace(/^@/, "")
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^[^a-z0-9]+/, "")
+        .replace(/-{2,}/g, "-")
+        .replace(/[-.]+$/, "");
+    return s === "" ? "source" : s;
+};
+export function isDirectory(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Proposes a configuration from what discovery finds: one entry per framework package, Storybook, tokens. */
+export async function detectConfig(cwd) {
+    const project = await discoverProject({ fs: nodeFs(cwd) });
+    const sources = [];
+    const taken = new Set();
+    const add = (base, type, dir) => {
+        let id = slug(base);
+        for (let n = 2; taken.has(id); n++)
+            id = `${slug(base)}-${n}`;
+        taken.add(id);
+        sources.push({ id, type, ...(dir === "." ? {} : { path: dir }) });
+    };
+    const MANY = 5;
+    const packages = [...project.packages].sort((a, b) => (a.dir < b.dir ? -1 : 1));
+    for (const type of ["react", "vue", "angular"]) {
+        const using = packages.filter((p) => p.frameworks.some((f) => f.name === type));
+        // A repository with many packages of one framework gets one whole-project entry rather than a long list.
+        if (using.length > MANY)
+            add(type, type, ".");
+        else
+            for (const pkg of using)
+                add(`${pkg.name}-${type}`, type, pkg.dir);
+    }
+    for (const sb of project.storybooks)
+        add(`storybook-${sb.directory}`, "storybook", sb.directory);
+    if (project.tokenFiles.length > 0)
+        add("tokens", "tokens", ".");
+    const rootName = project.packages.find((p) => p.dir === ".")?.name;
+    return { name: rootName ?? (path.basename(cwd) || "design-system"), sources };
+}
+//# sourceMappingURL=config.js.map

package/dist/cli/diff.js

@@ -0,0 +1,66 @@
+import { canonicalStringify } from "../shared/index.js";
+/** Collections of the contract that are keyed by `id` and compared entity by entity. */
+const COLLECTIONS = [
+    "sources",
+    "themes",
+    "components",
+    "tokens",
+    "patterns",
+    "guidelines",
+    "constraints",
+    "policies",
+    "conflicts"
+];
+/** Fields that change on every compile or sync and never mean the sources changed. */
+const VOLATILE = new Set(["lastSyncedAt"]);
+const same = (a, b) => a === undefined || b === undefined ? a === b : canonicalStringify(a) === canonicalStringify(b);
+function changedFields(a, b) {
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    return [...keys].filter((k) => !VOLATILE.has(k) && !same(a[k], b[k])).sort();
+}
+/**
+ * What differs between two compiled contracts, by collection and entity id. `metadata.compiledAt` and
+ * `sources[].lastSyncedAt` are ignored: they are carried but never part of the content hash.
+ */
+export function diffContracts(previous, next) {
+    const out = [];
+    for (const collection of COLLECTIONS) {
+        const before = new Map(previous[collection].map((e) => [e.id, e]));
+        const after = new Map(next[collection].map((e) => [e.id, e]));
+        const added = [...after.keys()].filter((id) => !before.has(id)).sort();
+        const removed = [...before.keys()].filter((id) => !after.has(id)).sort();
+        const changed = [];
+        for (const [id, a] of before) {
+            const b = after.get(id);
+            if (!b)
+                continue;
+            const fields = changedFields(a, b);
+            if (fields.length > 0)
+                changed.push({ id, fields });
+        }
+        changed.sort((x, y) => x.id.localeCompare(y.id));
+        if (added.length + removed.length + changed.length > 0)
+            out.push({ collection, added, removed, changed });
+    }
+    const meta = changedFields({ id: "metadata", ...previous.metadata, compiledAt: undefined }, { id: "metadata", ...next.metadata, compiledAt: undefined }).filter((k) => k !== "compiledAt" && k !== "id");
+    if (meta.length > 0)
+        out.push({ collection: "metadata", added: [], removed: [], changed: [{ id: "metadata", fields: meta }] });
+    return out;
+}
+/** Human-readable lines, at most `limit` entity lines per collection. */
+export function formatDiff(diff, limit = 10) {
+    const lines = [];
+    for (const d of diff) {
+        lines.push(`${d.collection}: +${d.added.length} -${d.removed.length} ~${d.changed.length}`);
+        const entries = [
+            ...d.added.map((id) => `  + ${id}`),
+            ...d.removed.map((id) => `  - ${id}`),
+            ...d.changed.map((c) => `  ~ ${c.id} (${c.fields.join(", ")})`)
+        ];
+        lines.push(...entries.slice(0, limit));
+        if (entries.length > limit)
+            lines.push(`  ... ${entries.length - limit} more`);
+    }
+    return lines;
+}
+//# sourceMappingURL=diff.js.map

package/dist/cli/enforcement-log.js

@@ -0,0 +1,83 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+/**
+ * The enforcement log: what `invariant hook` checked, one JSON object per line, under `.invariant/` in the
+ * project. Only the user-installed hook writes it; the MCP server stays read-only (ADR 0003).
+ *
+ * Appends use a single O_APPEND write of one short line, which POSIX keeps whole when hooks run concurrently
+ * (lines stay under 4 KB: findings are capped and their text truncated). The log holds findings and file
+ * paths, never file contents.
+ */
+export const LOG_DIR = ".invariant";
+export const LOG_FILE = `${LOG_DIR}/enforcement.jsonl`;
+const MAX_FINDINGS = 10;
+const MAX_TEXT = 200;
+export const findingSchema = z.object({
+    code: z.string(),
+    severity: z.enum(["error", "warning", "info"]),
+    message: z.string(),
+    line: z.number().optional(),
+    fix: z.string().optional()
+});
+export const eventSchema = z.object({
+    v: z.literal(1),
+    time: z.string(),
+    session: z.string(),
+    file: z.string(),
+    /** `blocked`: the write was denied. `warned`: it landed with findings. `passed`: it landed clean. */
+    outcome: z.enum(["blocked", "warned", "passed"]),
+    findings: z.array(findingSchema),
+    /** Findings beyond the cap, so the count stays honest. */
+    omitted: z.number().int().nonnegative(),
+    /** Component uses checked, for clean passes. */
+    checked: z.number().int().nonnegative()
+});
+const clip = (s) => (s.length > MAX_TEXT ? `${s.slice(0, MAX_TEXT - 1)}…` : s);
+/** Appends one event. The caller decides what a failure means; the hook notes it and carries on. */
+export function appendEvent(root, input) {
+    const dir = path.join(root, LOG_DIR);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+        // Local state: ignore the whole directory without touching the project's own .gitignore.
+        writeFileSync(path.join(dir, ".gitignore"), "*\n");
+    }
+    const event = {
+        v: 1,
+        time: input.time,
+        session: input.session,
+        file: input.file,
+        outcome: input.outcome,
+        findings: input.findings.slice(0, MAX_FINDINGS).map((f) => ({
+            code: f.code,
+            severity: f.severity,
+            message: clip(f.message),
+            ...(f.line !== undefined ? { line: f.line } : {}),
+            ...(f.suggestion ? { fix: clip(f.suggestion) } : {})
+        })),
+        omitted: Math.max(0, input.findings.length - MAX_FINDINGS),
+        checked: input.checked
+    };
+    appendFileSync(path.join(root, LOG_FILE), `${JSON.stringify(event)}\n`);
+}
+/** Reads every well-formed event; a torn or foreign line is skipped, never fatal. */
+export function readEvents(root) {
+    const file = path.join(root, LOG_FILE);
+    if (!existsSync(file))
+        return [];
+    const events = [];
+    for (const line of readFileSync(file, "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = eventSchema.safeParse(JSON.parse(line));
+            if (parsed.success)
+                events.push(parsed.data);
+        }
+        catch {
+            // a torn line is skipped
+        }
+    }
+    return events;
+}
+//# sourceMappingURL=enforcement-log.js.map

package/dist/cli/enforcement-report.js

@@ -0,0 +1,96 @@
+import { esc, STYLE } from "./report.js";
+/**
+ * Turns one session's events (in log order) into the timeline and its headline numbers. A catch is a blocked
+ * or warned write; it is fixed when a later write to the same file passes clean, outstanding otherwise.
+ */
+export function summarize(session, events) {
+    const open = new Map();
+    let caught = 0;
+    let fixed = 0;
+    const steps = [];
+    for (const e of events) {
+        const step = {
+            time: e.time,
+            file: e.file,
+            findings: e.findings,
+            omitted: e.omitted,
+            checked: e.checked,
+            resolves: []
+        };
+        if (e.outcome === "passed") {
+            const pending = open.get(e.file);
+            if (pending) {
+                fixed += pending.catches;
+                open.delete(e.file);
+                steps.push({ ...step, outcome: "fixed", resolves: [...new Set(pending.codes)] });
+            }
+            else
+                steps.push({ ...step, outcome: "passed" });
+            continue;
+        }
+        caught++;
+        const pending = open.get(e.file) ?? { catches: 0, codes: [] };
+        pending.catches++;
+        pending.codes.push(...e.findings.map((f) => f.code));
+        open.set(e.file, pending);
+        steps.push({ ...step, outcome: e.outcome });
+    }
+    return { session, steps, writes: events.length, caught, fixed, outstanding: caught - fixed };
+}
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+export function headline(s) {
+    return `${plural(s.writes, "write")} checked · ${plural(s.caught, "violation")} caught · ${s.fixed} fixed · ${s.outstanding} outstanding`;
+}
+const MARK = { error: "✗", warning: "⚠", info: "ℹ" };
+export function renderText(s) {
+    const lines = [`Invariant enforcement: ${headline(s)}`, `session ${s.session}`, ""];
+    for (const step of s.steps) {
+        const uses = plural(step.checked, "component use");
+        const state = step.outcome === "fixed"
+            ? `fixed (caught ${step.resolves.join(", ")}; now clean, ${uses} checked)`
+            : step.outcome === "passed"
+                ? `passed (${uses} checked)`
+                : `${step.outcome} (${plural(step.findings.length + step.omitted, "finding")})`;
+        lines.push(`${step.time}  ${step.file}  ${state}`);
+        for (const f of step.findings) {
+            lines.push(`    ${MARK[f.severity]} ${f.code}: ${f.message}${f.line !== undefined ? ` (line ${f.line})` : ""}`);
+            if (f.fix)
+                lines.push(`        fix: ${f.fix}`);
+        }
+        if (step.omitted > 0)
+            lines.push(`    …and ${step.omitted} more`);
+    }
+    if (s.steps.length === 0)
+        lines.push("No writes were checked in this session.");
+    return `${lines.join("\n")}\n`;
+}
+export function renderHtml(s) {
+    const rows = s.steps
+        .map((step) => {
+        const found = step.findings
+            .map((f) => `<div><span class="${esc(f.severity)}">${MARK[f.severity]}</span> <code>${esc(f.code)}</code> ${esc(f.message)}${f.line !== undefined ? ` (line ${esc(f.line)})` : ""}${f.fix ? `<br><small>fix: ${esc(f.fix)}</small>` : ""}</div>`)
+            .join("");
+        const detail = step.outcome === "fixed"
+            ? `Caught ${step.resolves.map((c) => `<code>${esc(c)}</code>`).join(", ")}; now clean.`
+            : step.outcome === "passed"
+                ? `Clean (${esc(plural(step.checked, "component use"))} checked).`
+                : found + (step.omitted > 0 ? `<div>…and ${esc(step.omitted)} more</div>` : "");
+        return `<tr><td>${esc(step.time)}</td><td><code>${esc(step.file)}</code></td><td>${esc(step.outcome)}</td><td>${detail}</td></tr>`;
+    })
+        .join("\n");
+    const table = s.steps.length === 0
+        ? "<p>No writes were checked in this session.</p>"
+        : `<table><thead><tr><th>Time</th><th>File</th><th>Outcome</th><th>Detail</th></tr></thead><tbody>\n${rows}\n</tbody></table>`;
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'">
+<title>Invariant enforcement report</title>
+<style>${STYLE}</style></head><body>
+<h1>Invariant enforcement</h1>
+<p><strong>${esc(headline(s))}</strong></p>
+<p>Session <code>${esc(s.session)}</code></p>
+${table}
+</body></html>
+`;
+}
+//# sourceMappingURL=enforcement-report.js.map

package/dist/cli/errors.js

@@ -0,0 +1,10 @@
+/** A failure to report to the user, with the exit code to use: 1 for findings, 2 for bad usage or input. */
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = 2) {
+        super(message);
+        this.name = "CliError";
+        this.exitCode = exitCode;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/cli/format.js

@@ -0,0 +1,22 @@
+export function table(head, rows) {
+    const all = [head, ...rows.map((r) => r.map(String))];
+    const widths = head.map((_, i) => Math.max(...all.map((r) => (r[i] ?? "").length)));
+    const line = (r) => r
+        .map((c, i) => c.padEnd(widths[i] ?? 0))
+        .join("  ")
+        .trimEnd();
+    return [line(head), line(widths.map((w) => "-".repeat(w))), ...all.slice(1).map(line)].join("\n");
+}
+export function formatDiagnostic(d) {
+    const where = d.location ? ` (${d.location.path}${d.location.line ? `:${d.location.line}` : ""})` : "";
+    return `${d.severity.padEnd(7)} ${d.code}: ${d.message}${where}`;
+}
+export function countBySeverity(diagnostics) {
+    const n = (s) => diagnostics.filter((d) => d.severity === s).length;
+    return `${n("error")} errors, ${n("warning")} warnings, ${n("info")} info`;
+}
+export function shortValue(value, max = 40) {
+    const text = value === undefined ? "" : typeof value === "string" ? value : JSON.stringify(value);
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+//# sourceMappingURL=format.js.map

package/dist/cli/index.js

@@ -0,0 +1,5 @@
+export { run } from "./cli.js";
+export { loadConfig, validateConfig } from "./config.js";
+export { runPipeline } from "./pipeline.js";
+export { renderReport } from "./report.js";
+//# sourceMappingURL=index.js.map

package/dist/cli/io.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=io.js.map

package/dist/cli/main.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { createInterface } from "node:readline/promises";
+import { run } from "./cli.js";
+const stop = new AbortController();
+for (const sig of ["SIGINT", "SIGTERM"])
+    process.once(sig, () => stop.abort());
+const code = await run(process.argv.slice(2), {
+    cwd: process.cwd(),
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+    clock: () => new Date().toISOString(),
+    env: process.env,
+    input: process.stdin,
+    output: process.stdout,
+    signal: stop.signal,
+    ...(process.stdin.isTTY && process.stdout.isTTY
+        ? {
+            prompt: async (question) => {
+                const rl = createInterface({ input: process.stdin, output: process.stdout });
+                try {
+                    return await rl.question(question);
+                }
+                finally {
+                    rl.close();
+                }
+            }
+        }
+        : {})
+});
+process.exitCode = code;
+//# sourceMappingURL=main.js.map