@invariant-ui/cli 0.0.0-stage → 0.1.0

package/dist/contract-query/views.js

@@ -0,0 +1,288 @@
+import { cmp } from "./system.js";
+const clamp = (n, fallback, max) => Math.max(1, Math.min(n ?? fallback, max));
+const statusOf = (f) => (f ? f : null);
+export function page(all, offset = 0, limit) {
+    const l = clamp(limit, 50, 200);
+    const o = Math.max(0, offset);
+    return { total: all.length, offset: o, limit: l, truncated: o + l < all.length, items: all.slice(o, o + l) };
+}
+export function overview(ds) {
+    const c = ds.contract;
+    const inferred = [...c.components, ...c.tokens, ...c.guidelines, ...c.patterns].reduce((n, e) => n + Object.values(e.facts).filter((f) => f.status === "inferred").length, 0);
+    const open = c.conflicts.filter((x) => x.resolution.state === "open");
+    const by = (key) => {
+        const out = {};
+        for (const x of open)
+            out[key(x)] = (out[key(x)] ?? 0) + 1;
+        return out;
+    };
+    const perFramework = {};
+    for (const comp of c.components)
+        for (const fw of new Set(comp.implementations.map((i) => i.framework)))
+            perFramework[fw] = (perFramework[fw] ?? 0) + 1;
+    const categories = {};
+    for (const t of c.tokens)
+        categories[t.category] = (categories[t.category] ?? 0) + 1;
+    const incomplete = c.components.filter((x) => !ds.propsComplete(x)).length;
+    const notes = [];
+    if (c.patterns.length === 0)
+        notes.push("No patterns are defined: none are inferred from code and no source documents one.");
+    if (c.policies.length === 0)
+        notes.push("No approved policies exist. Validation reports facts from the contract, not organizational rules.");
+    if (incomplete > 0)
+        notes.push(`${incomplete} component(s) have an incomplete API listing (inherited or generic props); a missing prop there is not proof it does not exist.`);
+    if (inferred > 0)
+        notes.push(`${inferred} fact(s) are inferred, not discovered; each carries a confidence and needs human approval.`);
+    if (open.length > 0)
+        notes.push(`${open.length} open conflict(s) between sources; the contract keeps one value and records every claim.`);
+    return {
+        name: c.metadata.name,
+        contractId: c.metadata.contractId,
+        contractVersion: c.contractVersion,
+        contentHash: c.integrity.contentHash,
+        compilerVersion: c.metadata.compilerVersion,
+        frameworks: c.metadata.frameworks,
+        sources: c.sources.map((s) => ({ id: s.id, type: s.type, health: s.health.status })),
+        counts: {
+            components: c.components.length,
+            tokens: c.tokens.length,
+            themes: c.themes.length,
+            guidelines: c.guidelines.length,
+            patterns: c.patterns.length,
+            policies: c.policies.length,
+            inferredFacts: inferred,
+            componentsWithIncompleteApi: incomplete
+        },
+        componentsByFramework: perFramework,
+        tokenCategories: categories,
+        openConflicts: { total: open.length, bySeverity: by((x) => x.severity), byType: by((x) => x.type) },
+        notes
+    };
+}
+export function catalog(ds) {
+    return ds.contract.components.map((c) => ({
+        id: c.id,
+        name: c.name,
+        frameworks: [...new Set(c.implementations.map((i) => i.framework))].sort(),
+        ...(c.lifecycle ? { lifecycle: c.lifecycle } : {}),
+        props: c.props.length,
+        events: c.events.length,
+        slots: c.slots.length,
+        variants: c.variants.map((v) => v.name)
+    }));
+}
+function roleOf(c, prop) {
+    for (const ext of Object.values(c.props.find((p) => p.name === prop)?.extensions ?? {}))
+        if (typeof ext.role === "string")
+            return ext.role;
+    return undefined;
+}
+export function componentView(ds, c) {
+    const conflicts = ds.conflictsFor(c.id);
+    const notes = [];
+    if (!ds.propsComplete(c))
+        notes.push("The prop list is incomplete for at least one implementation: do not conclude a prop is absent from this list alone; read the source.");
+    if (c.lifecycle === "deprecated")
+        notes.push("This component is deprecated.");
+    const identity = c.implementations.find((i) => c.facts[`implementations.${i.id}`]?.status === "inferred");
+    if (identity)
+        notes.push("Implementations in different frameworks were linked by name, which is inferred (see each implementation's status).");
+    return {
+        id: c.id,
+        name: c.name,
+        ...(c.description ? { description: c.description } : {}),
+        ...(c.lifecycle ? { lifecycle: c.lifecycle } : {}),
+        implementations: c.implementations.map((i) => ({
+            id: i.id,
+            framework: i.framework,
+            ...(i.packageName ? { package: i.packageName } : {}),
+            ...(i.exportName ? { export: i.exportName } : {}),
+            ...(i.importPath ? { importPath: i.importPath } : {}),
+            apiComplete: ds.propsComplete(c, i.framework),
+            status: statusOf(ds.factView(c.facts, `implementations.${i.id}`))
+        })),
+        props: c.props.map((p) => ({
+            name: p.name,
+            type: p.type.text,
+            ...(p.type.kind ? { kind: p.type.kind } : {}),
+            required: p.required,
+            ...(p.default !== undefined ? { default: p.default } : {}),
+            ...(p.allowedValues ? { allowedValues: p.allowedValues } : {}),
+            ...(p.description ? { description: p.description } : {}),
+            ...(p.deprecated ? { deprecated: p.deprecated } : {}),
+            ...(roleOf(c, p.name) ? { role: roleOf(c, p.name) } : {}),
+            status: statusOf(ds.factView(c.facts, `props.${p.name}.type.text`))
+        })),
+        events: c.events.map((e) => ({ name: e.name, ...(e.payload ? { payload: e.payload.text } : {}) })),
+        slots: c.slots.map((s) => ({
+            name: s.name,
+            ...(s.required !== undefined ? { required: s.required } : {})
+        })),
+        variants: c.variants.map((v) => ({
+            name: v.name,
+            values: v.values,
+            ...(v.default ? { default: v.default } : {})
+        })),
+        ...(c.accessibility ? { accessibility: c.accessibility } : {}),
+        conflicts: conflicts.map((x) => ({
+            type: x.type,
+            severity: x.severity,
+            ...(x.path ? { path: x.path } : {}),
+            claims: x.claims.map((cl) => ({
+                source: cl.sourceId,
+                ...(cl.value === undefined ? {} : { value: cl.value }),
+                status: cl.status
+            }))
+        })),
+        guidelines: ds.contract.guidelines.filter((g) => g.appliesTo.includes(c.id)).map((g) => g.id),
+        notes
+    };
+}
+export function usageView(ds, c) {
+    const required = c.props.filter((p) => p.required).map((p) => p.name);
+    const deprecatedProps = c.props
+        .filter((p) => p.deprecated)
+        .map((p) => ({ name: p.name, ...(p.deprecated?.reason ? { reason: p.deprecated.reason } : {}) }));
+    const usage = c.extensions?.invariant?.usage;
+    const notes = [];
+    if (!ds.propsComplete(c))
+        notes.push("API listing is incomplete; confirm unlisted props in the source.");
+    if (usage === undefined)
+        notes.push("No observed usage statistics for this component (only React usage is observed).");
+    return {
+        id: c.id,
+        name: c.name,
+        lifecycle: c.lifecycle ?? "unspecified",
+        howToImport: c.implementations.map((i) => ({
+            framework: i.framework,
+            ...(i.packageName ? { package: i.packageName } : {}),
+            ...(i.exportName ? { export: i.exportName } : {}),
+            ...(i.importPath ? { from: i.importPath } : {})
+        })),
+        requiredProps: required,
+        variants: c.variants.map((v) => ({
+            name: v.name,
+            values: v.values,
+            ...(v.default ? { default: v.default } : {})
+        })),
+        defaults: Object.fromEntries(c.props.filter((p) => p.default !== undefined).map((p) => [p.name, p.default])),
+        events: c.events.map((e) => e.name),
+        slots: c.slots.map((s) => s.name),
+        deprecatedProps,
+        examples: c.examples.map((e) => ({
+            id: e.id,
+            language: e.language,
+            code: e.code,
+            status: statusOf(ds.factView(c.facts, `examples.${e.id}.code`))
+        })),
+        ...(usage === undefined ? {} : { observedUsage: usage }),
+        guidelines: ds.contract.guidelines
+            .filter((g) => g.appliesTo.includes(c.id))
+            .map((g) => ({ id: g.id, kind: g.kind, title: g.name })),
+        notes
+    };
+}
+export function compositionView(ds, c) {
+    const staticRefs = c.extensions?.invariant?.composition;
+    const name = (id) => ds.component(id)?.name ?? id;
+    const notes = [];
+    const contains = c.composition.map((r, i) => ({
+        relation: r.type,
+        id: r.target,
+        name: name(r.target),
+        status: statusOf(ds.factView(c.facts, `composition.${i}`))
+    }));
+    if (contains.some((x) => x.status?.status === "inferred"))
+        notes.push("Some containment links are inferred from names and are low confidence; verify against the source.");
+    if (contains.length === 0)
+        notes.push("No composition relationships were found; that does not mean the component cannot be composed.");
+    return {
+        id: c.id,
+        name: c.name,
+        contains,
+        containedBy: ds.containedBy(c.id).map((x) => ({
+            id: x.id,
+            name: name(x.id),
+            status: x.fact
+                ? {
+                    status: x.fact.status,
+                    ...(x.fact.confidence === undefined ? {} : { confidence: x.fact.confidence })
+                }
+                : null
+        })),
+        slots: c.slots.map((s) => ({ name: s.name, ...(s.accepts ? { accepts: s.accepts } : {}) })),
+        ...(staticRefs === undefined ? {} : { staticReferences: staticRefs }),
+        notes
+    };
+}
+export function tokenView(ds, t, theme) {
+    const resolved = ds.resolveToken(t, theme);
+    return {
+        id: t.id,
+        name: t.name,
+        category: t.category,
+        categoryStatus: statusOf(ds.factView(t.facts, "category")),
+        ...(t.description ? { description: t.description } : {}),
+        ...(t.value.aliasOf ? { aliasOf: t.value.aliasOf } : { value: t.value.value }),
+        ...(resolved.value !== undefined ? { resolvedValue: resolved.value } : {}),
+        ...(resolved.chain.length > 1 ? { aliasChain: resolved.chain } : {}),
+        ...(resolved.note ? { note: resolved.note } : {}),
+        modes: Object.fromEntries(Object.entries(t.modes ?? {}).map(([k, v]) => [
+            k,
+            (v.aliasOf ? { aliasOf: v.aliasOf } : { value: v.value })
+        ])),
+        ...(t.deprecated ? { deprecated: t.deprecated } : {})
+    };
+}
+export function tokensView(ds, f) {
+    const q = f.query?.toLowerCase();
+    const theme = f.theme ? (f.theme.startsWith("theme:") ? f.theme : `theme:${f.theme}`) : undefined;
+    const all = ds.contract.tokens
+        .filter((t) => !f.category || t.category === f.category)
+        .filter((t) => !q ||
+        t.id.includes(q) ||
+        t.name.toLowerCase().includes(q) ||
+        JSON.stringify(t.value).toLowerCase().includes(q))
+        .sort((a, b) => cmp(a.id, b.id));
+    const p = page(all, f.offset, f.limit);
+    return {
+        total: p.total,
+        offset: p.offset,
+        truncated: p.truncated,
+        themes: ds.contract.themes.map((t) => t.id),
+        tokens: p.items.map((t) => tokenView(ds, t, theme)),
+        notes: all.some((t) => ds.factView(t.facts, "category")?.status === "inferred")
+            ? ["Token categories marked inferred are guesses from names and value kinds, not declarations."]
+            : []
+    };
+}
+export function guidelinesView(ds, f) {
+    const target = f.component ? ds.findComponent(f.component).match?.id : undefined;
+    const q = f.query?.toLowerCase();
+    const all = ds.contract.guidelines
+        .filter((g) => !f.kind || g.kind === f.kind)
+        .filter((g) => !f.component || (target !== undefined && g.appliesTo.includes(target)))
+        .filter((g) => !q || g.name.toLowerCase().includes(q) || g.id.includes(q));
+    const p = page(all, f.offset, f.limit);
+    return {
+        total: p.total,
+        offset: p.offset,
+        truncated: p.truncated,
+        guidelines: p.items.map((g) => ({
+            id: g.id,
+            title: g.name,
+            kind: g.kind,
+            kindStatus: statusOf(ds.factView(g.facts, "kind")),
+            appliesTo: g.appliesTo,
+            references: g.references.map((r) => ({ source: r.sourceId, document: r.documentId }))
+        })),
+        notes: [
+            "Guideline text is the page title: Invariant does not read page bodies, so open the referenced document for the actual guidance.",
+            ...(f.component && !target ? [`No component matches "${f.component}".`] : [])
+        ]
+    };
+}
+export function factsOf(c) {
+    return Object.keys(c.facts).length;
+}
+//# sourceMappingURL=views.js.map

package/dist/governance/decisions.js

@@ -0,0 +1,229 @@
+import { computeFactFingerprint, resolveFactPath } from "../contract/index.js";
+import { canonicalStringify, DiagnosticCollector, hashJson } from "../shared/index.js";
+import { z } from "zod";
+export const DECISIONS_FILE = "invariant.decisions.json";
+const who = {
+    by: z.string().min(1).max(200),
+    at: z.iso.datetime(),
+    note: z.string().min(1).max(2000).optional()
+};
+export const decisionSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("fact"),
+        action: z.enum(["approve", "reject"]),
+        subject: z.string().min(1).max(300),
+        path: z.string().min(1).max(300),
+        /** The value at `path` when the decision was made. If it has changed since, the decision is stale. */
+        value: z.custom((v) => v !== undefined),
+        role: z.string().min(1).max(200).optional(),
+        reference: z.string().min(1).max(500).optional(),
+        ...who
+    }),
+    z.strictObject({
+        kind: z.literal("conflict"),
+        action: z.enum(["resolve", "accept", "dismiss"]),
+        id: z.string().min(1).max(300),
+        /** Hash of the conflict's claims when the decision was made. */
+        claimsHash: z.string().regex(/^[0-9a-f]{64}$/),
+        chosenSourceId: z.string().min(1).max(100).optional(),
+        ...who
+    })
+]);
+export const decisionsFileSchema = z.strictObject({
+    version: z.literal(1),
+    decisions: z.array(decisionSchema)
+});
+export function parseDecisions(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        return { ok: false, message: `${DECISIONS_FILE} is not valid JSON: ${error.message}` };
+    }
+    const parsed = decisionsFileSchema.safeParse(raw);
+    if (!parsed.success) {
+        const i = parsed.error.issues[0];
+        return {
+            ok: false,
+            message: `${DECISIONS_FILE} is invalid at ${i?.path.join(".") || "(root)"}: ${i?.message ?? "schema error"}`
+        };
+    }
+    return { ok: true, value: parsed.data };
+}
+export const serializeDecisions = (file) => `${canonicalStringify(file, 2)}\n`;
+export const claimsHash = (conflict) => hashJson(conflict.claims);
+const targetKey = (d) => d.kind === "conflict"
+    ? `conflict\u0000${d.id}`
+    : `fact\u0000${d.subject}\u0000${canonicalStringify(d.value)}\u0000${d.path.replace(/\.\d+$/, "")}`;
+/** Adds a decision, replacing an earlier one about the same target so the last word stands. */
+export function addDecision(file, decision) {
+    const kept = (file?.decisions ?? []).filter((d) => targetKey(d) !== targetKey(decision));
+    return { version: 1, decisions: [...kept, decision] };
+}
+const COLLECTIONS = ["components", "tokens", "guidelines", "patterns", "constraints"];
+const same = (a, b) => canonicalStringify(a ?? null) === canonicalStringify(b ?? null);
+const INDEXED = /^(composition|appliesTo)\.(\d+)$/;
+function find(draft, id) {
+    for (const collection of COLLECTIONS) {
+        const entity = draft[collection].find((e) => e.id === id);
+        if (entity)
+            return { collection, entity };
+    }
+    return undefined;
+}
+/** Removes array item `index` from an entity and renumbers its facts for that collection. */
+function removeIndexed(entity, collection, index) {
+    const e = entity;
+    const items = [...e[collection]];
+    items.splice(index, 1);
+    const facts = {};
+    for (const [path, fact] of Object.entries(e.facts)) {
+        const m = new RegExp(`^${collection}\\.(\\d+)$`).exec(path);
+        if (!m)
+            facts[path] = fact;
+        else {
+            const n = Number(m[1]);
+            if (n < index)
+                facts[path] = fact;
+            else if (n > index)
+                facts[`${collection}.${n - 1}`] = fact;
+        }
+    }
+    return {
+        ...e,
+        [collection]: items,
+        facts: Object.fromEntries(Object.entries(facts).sort((a, b) => (a[0] < b[0] ? -1 : 1)))
+    };
+}
+/**
+ * Applies people's decisions to a contract draft, in file order. Approving layers `approved` over the
+ * fact's prior status with the contract's own fingerprint; rejecting removes an inferred fact where removal
+ * is well defined; resolving a conflict records the decision and leaves the kept value alone (the fix
+ * belongs in the source). A decision about a value or claims that have since changed is stale and ignored.
+ */
+export function applyDecisions(draft, file, options = {}) {
+    const collector = new DiagnosticCollector();
+    const applied = [];
+    const stale = [];
+    let contract = draft;
+    const approvers = options.approvers && options.approvers.length > 0 ? new Set(options.approvers) : undefined;
+    const replace = (collection, entity) => {
+        contract = {
+            ...contract,
+            [collection]: contract[collection].map((e) => (e.id === entity.id ? entity : e))
+        };
+    };
+    for (const d of file?.decisions ?? []) {
+        const label = d.kind === "conflict" ? d.id : `${d.subject} ${d.path}`;
+        if (approvers && !approvers.has(d.by)) {
+            collector.error("governance.unauthorized", `${label}: "${d.by}" is not listed in governance.approvers, so the decision was not applied`);
+            continue;
+        }
+        if (d.kind === "conflict") {
+            const conflict = contract.conflicts.find((c) => c.id === d.id);
+            if (!conflict) {
+                collector.warning("governance.decision-target-missing", `${d.id}: the conflict no longer exists (it may have been fixed at the source); remove the decision`);
+                continue;
+            }
+            if (claimsHash(conflict) !== d.claimsHash) {
+                collector.warning("governance.decision-stale", `${d.id}: the claims changed since ${d.by} decided, so the decision was not applied`);
+                stale.push(d);
+                continue;
+            }
+            if (d.chosenSourceId && !conflict.claims.some((c) => c.sourceId === d.chosenSourceId)) {
+                collector.error("governance.decision-invalid", `${d.id}: "${d.chosenSourceId}" is not one of the conflict's sources`);
+                continue;
+            }
+            const state = d.action === "resolve" ? "resolved" : d.action === "accept" ? "accepted" : "dismissed";
+            const next = {
+                ...conflict,
+                resolution: {
+                    state,
+                    ...(d.chosenSourceId ? { chosenSourceId: d.chosenSourceId } : {}),
+                    decidedBy: d.by,
+                    decidedAt: d.at,
+                    ...(d.note ? { note: d.note } : {})
+                }
+            };
+            contract = { ...contract, conflicts: contract.conflicts.map((c) => (c.id === conflict.id ? next : c)) };
+            applied.push({ action: d.action, target: d.id });
+            continue;
+        }
+        const hit = find(contract, d.subject);
+        if (!hit) {
+            collector.warning("governance.decision-target-missing", `${label}: ${d.subject} is no longer in the contract; remove the decision`);
+            continue;
+        }
+        let path = d.path;
+        const indexed = INDEXED.exec(d.path);
+        const entity = hit.entity;
+        if (indexed) {
+            const items = entity[indexed[1]] ?? [];
+            const at = items.findIndex((item) => same(item, d.value));
+            if (at < 0) {
+                collector.warning("governance.decision-stale", `${label}: the value it was about is gone, so the decision was not applied`);
+                stale.push(d);
+                continue;
+            }
+            path = `${indexed[1]}.${at}`;
+        }
+        else {
+            const current = resolveFactPath(entity, path);
+            if (!current.found || !same(current.value, d.value)) {
+                collector.warning("governance.decision-stale", `${label}: the value changed since ${d.by} decided, so the decision was not applied`);
+                stale.push(d);
+                continue;
+            }
+        }
+        const record = entity.facts[path];
+        if (!record) {
+            collector.warning("governance.decision-target-missing", `${label}: there is no fact at ${path}`);
+            continue;
+        }
+        if (d.action === "approve") {
+            if (record.status === "approved")
+                continue;
+            const value = resolveFactPath(entity, path);
+            if (!value.found)
+                continue;
+            const next = {
+                ...record,
+                status: "approved",
+                approval: {
+                    approvedBy: d.by,
+                    approvedAt: d.at,
+                    ...(d.role ? { role: d.role } : {}),
+                    ...(d.reference ? { reference: d.reference } : {}),
+                    fingerprint: computeFactFingerprint({ entityId: entity.id, path, value: value.value }),
+                    priorStatus: record.status
+                }
+            };
+            replace(hit.collection, { ...entity, facts: { ...entity.facts, [path]: next } });
+            applied.push({ action: "approve", target: label });
+            continue;
+        }
+        if (record.status === "approved") {
+            collector.error("governance.reject-approved", `${label}: the fact is approved; remove its approval decision before rejecting it`);
+            continue;
+        }
+        if (record.status !== "inferred") {
+            collector.error("governance.reject-unsupported", `${label}: only inferred facts can be rejected; a ${record.status} fact is stated by a source, so fix the source`);
+            continue;
+        }
+        if (indexed) {
+            replace(hit.collection, removeIndexed(hit.entity, indexed[1], Number(path.split(".")[1])));
+        }
+        else if (hit.collection === "tokens" && path === "category") {
+            const { category: _gone, ...facts } = entity.facts;
+            replace("tokens", { ...entity, category: "other", facts });
+        }
+        else {
+            collector.error("governance.reject-unsupported", `${label}: rejecting this kind of inference is not supported (for an inferred identity between implementations, fix the names or split the component at the source)`);
+            continue;
+        }
+        applied.push({ action: "reject", target: label });
+    }
+    return { contract, diagnostics: collector.toArray(), applied, stale };
+}
+//# sourceMappingURL=decisions.js.map

package/dist/governance/index.js

@@ -0,0 +1,5 @@
+export { addDecision, applyDecisions, claimsHash, DECISIONS_FILE, decisionSchema, decisionsFileSchema, parseDecisions, serializeDecisions } from "./decisions.js";
+export { compilePatterns, PATTERN_SOURCE_ID } from "./patterns.js";
+export { PATTERNS_FILE, PATTERNS_FILE_VERSION, parsePatterns, patternDefinitionSchema, patternsFileJsonSchema, patternsFileSchema } from "./patterns-file.js";
+export { compilePolicies, POLICIES_FILE, parsePolicies, policiesFileSchema } from "./policies.js";
+//# sourceMappingURL=index.js.map

package/dist/governance/patterns-file.js

@@ -0,0 +1,156 @@
+import { behaviorSchema, compositionPartSchema, frameworkSchema, layoutRegionSchema, PATTERN_CATEGORIES, PATTERN_CONSTRAINT_KINDS, PATTERN_RELATIONSHIP_TYPES, partNameSchema, patternAccessibilitySchema } from "../contract/index.js";
+import { z } from "zod";
+export const PATTERNS_FILE = "invariant.patterns.json";
+export const PATTERNS_FILE_VERSION = 1;
+/**
+ * What a person writes. References to components, patterns, tokens and guidelines are names or ids here
+ * (`DataTable`, `component:data-table`, `page.data-management`); compiling resolves them to ids or says why
+ * it cannot. Everything else has the same shape as in the contract, so a definition reads like the entity it
+ * becomes.
+ */
+const reference = z.string().min(1).max(200);
+const part = compositionPartSchema.extend({ ref: reference });
+const region = layoutRegionSchema
+    .omit({ accepts: true, grid: true, spacing: true, responsive: true })
+    .extend({
+    accepts: z.array(reference).optional(),
+    grid: z
+        .strictObject({
+        columns: layoutRegionSchema.shape.grid.unwrap().shape.columns,
+        gap: reference.optional()
+    })
+        .optional(),
+    spacing: reference.optional(),
+    responsive: z
+        .array(z.strictObject({
+        breakpoint: reference,
+        behavior: layoutRegionSchema.shape.responsive.unwrap().element.shape.behavior
+    }))
+        .optional()
+});
+const constraintName = z
+    .string()
+    .max(64)
+    .regex(/^[a-z0-9][a-z0-9_-]*$/);
+const constraint = z.strictObject({
+    /** Local to the pattern. The contract id is `constraint:<pattern>.<id>`. */
+    id: constraintName,
+    name: z.string().min(1).max(200).optional(),
+    kind: z.enum(PATTERN_CONSTRAINT_KINDS),
+    description: z.string().min(1).max(2000),
+    /** Checked against the kind's schema after references are resolved. */
+    details: z.record(z.string().max(100), z.unknown()),
+    /** Makes the constraint enforceable. It becomes a policy, which needs the pattern's approval. */
+    enforce: z
+        .strictObject({
+        severity: z.enum(["error", "warning", "info"]),
+        enforcement: z.enum(["block", "warn", "report-only"]).default("block")
+    })
+        .optional()
+});
+/** A named way the composition may differ. Its added parts are written with the same references as any part. */
+const variation = z
+    .strictObject({
+    name: partNameSchema,
+    description: z.string().min(1).max(500).optional(),
+    when: z.string().min(1).max(500).optional(),
+    roles: z
+        .array(z.strictObject({ part: partNameSchema, role: z.enum(["required", "optional", "prohibited"]) }))
+        .optional(),
+    parts: z.array(part).optional()
+})
+    .refine((v) => (v.roles?.length ?? 0) + (v.parts?.length ?? 0) > 0, {
+    message: "a variation changes at least one part's role or adds a part"
+});
+const relationship = z.strictObject({
+    id: partNameSchema,
+    type: z.enum(PATTERN_RELATIONSHIP_TYPES),
+    target: reference,
+    description: z.string().min(1).max(500).optional()
+});
+export const patternDefinitionSchema = z.strictObject({
+    id: z
+        .string()
+        .max(120)
+        .regex(/^(?:pattern:)?[a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._-]*)*$/),
+    name: z.string().min(1).max(200),
+    category: z.enum(PATTERN_CATEGORIES),
+    description: z.string().min(1).max(2000),
+    intent: z.string().min(1).max(500).optional(),
+    composition: z.strictObject({ parts: z.array(part).min(1) }).optional(),
+    layout: z.strictObject({ regions: z.array(region).min(1) }).optional(),
+    behavior: behaviorSchema.optional(),
+    accessibility: patternAccessibilitySchema.optional(),
+    variations: z.array(variation).optional(),
+    relationships: z.array(relationship).optional(),
+    constraints: z.array(constraint).optional(),
+    guidelines: z.array(reference).optional(),
+    /** Where the pattern applies. Carried into the policies it generates; enforcement scoping arrives with validation. */
+    appliesTo: z
+        .strictObject({
+        paths: z.array(z.string().min(1).max(300)).min(1).max(50).optional(),
+        frameworks: z.array(frameworkSchema).min(1).optional()
+    })
+        .optional(),
+    /**
+     * Where a definition came from when `invariant candidates promote` wrote it: the discovered candidate, how it was
+     * found, and who accepted it. Provenance only. It is kept on the pattern as `extensions.discovery` and grants nothing.
+     */
+    origin: z
+        .strictObject({
+        candidate: z.string().min(1).max(100),
+        method: z.string().min(1).max(100),
+        support: z.number().int().positive(),
+        files: z.number().int().positive(),
+        acceptedBy: z.string().min(1).max(200).optional(),
+        acceptedAt: z.iso.datetime().optional(),
+        reference: z.string().min(1).max(500).optional()
+    })
+        .optional(),
+    /**
+     * Opt in: files matching `appliesTo.paths` are also held to the constraints of every pattern this one composes.
+     * Needs `appliesTo.paths` and an approval; without them nothing is inherited.
+     */
+    inheritsConstraints: z.boolean().optional(),
+    /**
+     * Who approved this definition. With it, the pattern's facts are `approved`; without it they stay `documented`
+     * until someone approves them with `invariant review`. A file in the repository is not an approval by itself.
+     */
+    approval: z
+        .strictObject({
+        approvedBy: z.string().min(1).max(200),
+        approvedAt: z.iso.datetime(),
+        role: z.string().min(1).max(200).optional(),
+        reference: z.string().min(1).max(500).optional()
+    })
+        .optional()
+});
+export const patternsFileSchema = z.strictObject({
+    /** Lets an editor validate the file against the exported JSON Schema. Ignored by the compiler. */
+    $schema: z.string().max(500).optional(),
+    version: z.literal(PATTERNS_FILE_VERSION),
+    patterns: z.array(patternDefinitionSchema)
+});
+export function parsePatterns(text, name = PATTERNS_FILE) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        return { ok: false, message: `${name} is not valid JSON: ${error.message}` };
+    }
+    const parsed = patternsFileSchema.safeParse(raw);
+    if (!parsed.success) {
+        const i = parsed.error.issues[0];
+        return {
+            ok: false,
+            message: `${name} is invalid at ${i?.path.join(".") || "(root)"}: ${i?.message ?? "schema error"}`
+        };
+    }
+    return { ok: true, value: parsed.data };
+}
+/** JSON Schema for editors and CI, generated from the same definition. Refinements are not representable. */
+export function patternsFileJsonSchema() {
+    return { title: "Invariant pattern definitions v1", ...z.toJSONSchema(patternsFileSchema) };
+}
+//# sourceMappingURL=patterns-file.js.map