@invariant-ui/cli 0.0.0-stage → 0.2.0

package/dist/contract/knowledge.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { approvalSchema, factsSchema } from "./facts.js";
+import { behaviorSchema, compositionSchema, layoutSchema, PATTERN_CATEGORIES, PATTERN_CONSTRAINT_KINDS, patternAccessibilitySchema, patternRelationshipSchema, patternVariationSchema } from "./patterns.js";
+import { componentIdSchema, constraintIdSchema, entityIdSchema, extensionsSchema, frameworkSchema, guidelineIdSchema, jsonObjectSchema, patternIdSchema, policyIdSchema, sourceIdSchema } from "./primitives.js";
+export const documentRefSchema = z.strictObject({
+    sourceId: sourceIdSchema,
+    documentId: z.string().min(1),
+    title: z.string().optional(),
+    url: z.url().optional()
+});
+export const patternSchema = z.strictObject({
+    id: patternIdSchema,
+    name: z.string().min(1),
+    category: z.enum(PATTERN_CATEGORIES),
+    description: z.string().min(1),
+    /** What the pattern is for, in one sentence (1.1.0). */
+    intent: z.string().min(1).optional(),
+    components: z.array(componentIdSchema),
+    guidelines: z.array(guidelineIdSchema),
+    /** The named parts a pattern is made of (1.1.0). */
+    composition: compositionSchema.optional(),
+    /** Named, approved ways the composition may differ (1.1.0). */
+    variations: z.array(patternVariationSchema).optional(),
+    /** Regions and their structure (1.1.0). */
+    layout: layoutSchema.optional(),
+    /** States and transitions (1.1.0). */
+    behavior: behaviorSchema.optional(),
+    accessibility: patternAccessibilitySchema.optional(),
+    /** Typed edges to other patterns and components (1.1.0). */
+    relationships: z.array(patternRelationshipSchema).optional(),
+    /** Constraints this pattern owns. Policies make them enforceable (1.1.0). */
+    constraints: z.array(constraintIdSchema).optional(),
+    /** Where the pattern applies: the files and frameworks that are instances of it (1.1.0). */
+    appliesTo: z
+        .strictObject({
+        paths: z.array(z.string().min(1)).min(1).optional(),
+        frameworks: z.array(frameworkSchema).min(1).optional()
+    })
+        .optional(),
+    /**
+     * Opt in: files in `appliesTo.paths` are also held to the constraints of every pattern this one composes (1.1.0).
+     * It has effect only while both this flag and `appliesTo` are approved.
+     */
+    inheritsConstraints: z.boolean().optional(),
+    facts: factsSchema,
+    extensions: extensionsSchema.optional()
+});
+export const guidelineSchema = z.strictObject({
+    id: guidelineIdSchema,
+    name: z.string().min(1),
+    kind: z.enum(["usage", "accessibility", "composition", "visual-principle", "do-dont", "reference"]),
+    statement: z.string().min(1),
+    appliesTo: z.array(entityIdSchema),
+    examples: z.array(z.strictObject({ kind: z.enum(["do", "dont"]), text: z.string().min(1) })),
+    references: z.array(documentRefSchema),
+    facts: factsSchema,
+    extensions: extensionsSchema.optional()
+});
+export const constraintSchema = z.strictObject({
+    id: constraintIdSchema,
+    name: z.string().min(1),
+    kind: z.enum([
+        "valid-combination",
+        "invalid-combination",
+        "required-prop",
+        "deprecated-api",
+        "approved-alternative",
+        "framework-restriction",
+        ...PATTERN_CONSTRAINT_KINDS
+    ]),
+    description: z.string().min(1),
+    subjects: z.array(entityIdSchema).min(1),
+    details: jsonObjectSchema.optional(),
+    facts: factsSchema,
+    extensions: extensionsSchema.optional()
+});
+/**
+ * Organization-approved rule. Policies are never produced by inference: approval metadata is
+ * mandatory in the schema, so an unapproved rule cannot be represented as a policy.
+ */
+export const policySchema = z.strictObject({
+    id: policyIdSchema,
+    name: z.string().min(1),
+    statement: z.string().min(1),
+    severity: z.enum(["error", "warning", "info"]),
+    enforcement: z.enum(["block", "warn", "report-only"]),
+    scope: z.strictObject({
+        entities: z.array(entityIdSchema).optional(),
+        frameworks: z.array(frameworkSchema).optional(),
+        paths: z.array(z.string().min(1)).optional()
+    }),
+    basedOn: z.array(z.union([guidelineIdSchema, constraintIdSchema])),
+    approval: approvalSchema.omit({ fingerprint: true, priorStatus: true })
+});
+//# sourceMappingURL=knowledge.js.map

package/dist/contract/pattern-checks.js

@@ -0,0 +1,254 @@
+import { checkArchetypes, checkVariations } from "./archetype-checks.js";
+import { ACYCLIC_RELATIONSHIPS, constraintDetailsSchemas, isPatternConstraintKind, PATTERN_CATEGORIES_1_1, PATTERN_CONSTRAINT_KINDS, PATTERN_ONLY_RELATIONSHIPS } from "./patterns.js";
+const duplicates = (names) => [
+    ...new Set(names.filter((n, i) => names.indexOf(n) !== i))
+];
+/** Where a constraint's `details` point at components and patterns, as entity ids (region refs are local). */
+export function constraintReferences(contract) {
+    const refs = [];
+    for (const c of contract.constraints) {
+        if (!isPatternConstraintKind(c.kind))
+            continue;
+        const parsed = constraintDetailsSchemas[c.kind].safeParse(c.details);
+        if (!parsed.success)
+            continue;
+        // Only component and pattern ids are references; other strings (a workflow name, a minimum) are not.
+        for (const value of stringsIn(parsed.data))
+            if (/^(?:component|pattern):/.test(value))
+                refs.push({ from: c.id, to: value });
+    }
+    return refs;
+}
+function stringsIn(value) {
+    if (typeof value === "string")
+        return [value];
+    if (Array.isArray(value))
+        return value.flatMap(stringsIn);
+    if (value && typeof value === "object")
+        return Object.values(value).flatMap(stringsIn);
+    return [];
+}
+/** Entity ids a pattern points at, with the fact path that holds the claim. */
+export function patternReferences(contract) {
+    const refs = [];
+    for (const p of contract.patterns) {
+        for (const part of p.composition?.parts ?? [])
+            refs.push({ from: p.id, to: part.ref });
+        for (const v of p.variations ?? [])
+            for (const part of v.parts ?? [])
+                refs.push({ from: p.id, to: part.ref });
+        for (const rel of p.relationships ?? [])
+            refs.push({ from: p.id, to: rel.target });
+        for (const id of p.constraints ?? [])
+            refs.push({ from: p.id, to: id });
+        for (const region of p.layout?.regions ?? []) {
+            for (const target of region.accepts ?? [])
+                refs.push({ from: p.id, to: target });
+            if (region.spacing)
+                refs.push({ from: p.id, to: region.spacing });
+            if (region.grid?.gap)
+                refs.push({ from: p.id, to: region.grid.gap });
+            for (const r of region.responsive ?? [])
+                refs.push({ from: p.id, to: r.breakpoint });
+        }
+    }
+    return refs;
+}
+/** Things a 1.0.0 document cannot contain. Returns one reason per offending entity. */
+export function newInOnePointOne(contract) {
+    const out = [];
+    const newCategories = PATTERN_CATEGORIES_1_1;
+    const newKinds = PATTERN_CONSTRAINT_KINDS;
+    for (const p of contract.patterns) {
+        const fields = [
+            "intent",
+            "composition",
+            "layout",
+            "behavior",
+            "accessibility",
+            "relationships",
+            "constraints",
+            "variations",
+            "appliesTo",
+            "inheritsConstraints"
+        ].filter((f) => p[f] !== undefined);
+        if (fields.length > 0)
+            out.push({ entityId: p.id, reason: `uses ${fields.join(", ")}` });
+        if (newCategories.includes(p.category))
+            out.push({ entityId: p.id, reason: `has category "${p.category}"` });
+    }
+    for (const c of contract.constraints)
+        if (newKinds.includes(c.kind))
+            out.push({ entityId: c.id, reason: `has kind "${c.kind}"` });
+    return out;
+}
+/**
+ * Semantic checks for pattern contracts: unique names, region and state-machine integrity, relationship rules,
+ * cycles, and the typed details of structural constraints. References to other entities are checked with the
+ * rest of the contract by `entityReferences`.
+ */
+export function checkPatterns(contract, error, found) {
+    const warn = (code, message, entityId) => {
+        found.push({ code, severity: "warning", message, entityId });
+    };
+    const ownedConstraints = new Map();
+    for (const p of contract.patterns)
+        for (const id of p.constraints ?? [])
+            ownedConstraints.set(id, p);
+    for (const p of contract.patterns) {
+        checkNames(p, error);
+        checkRegions(p, error);
+        checkBehavior(p, error, warn);
+        checkRelationships(p, error);
+        checkVariations(p, error);
+    }
+    checkConstraints(contract, ownedConstraints, error);
+    checkCycles(contract, error);
+    checkArchetypes(contract, error, warn);
+}
+function checkNames(p, error) {
+    const groups = [
+        ["region", (p.layout?.regions ?? []).map((r) => r.name)],
+        ["composition part", (p.composition?.parts ?? []).map((x) => x.name)],
+        ["state", (p.behavior?.states ?? []).map((s) => s.name)],
+        ["transition", (p.behavior?.transitions ?? []).map((t) => t.id)],
+        ["relationship", (p.relationships ?? []).map((r) => r.id)],
+        ["accessibility requirement", (p.accessibility?.requirements ?? []).map((r) => r.id)]
+    ];
+    for (const [what, names] of groups)
+        for (const name of duplicates(names))
+            error("contract.pattern-duplicate-name", `${p.id} has more than one ${what} named "${name}"`, p.id);
+}
+function checkRegions(p, error) {
+    const regions = p.layout?.regions ?? [];
+    const names = new Set(regions.map((r) => r.name));
+    for (const r of regions) {
+        if (r.parent !== undefined && !names.has(r.parent))
+            error("contract.pattern-region-unknown", `${p.id} region "${r.name}" has unknown parent "${r.parent}"`, p.id);
+    }
+    const parentOf = new Map(regions.map((r) => [r.name, r.parent]));
+    for (const r of regions) {
+        const seen = new Set([r.name]);
+        for (let at = r.parent; at !== undefined; at = parentOf.get(at)) {
+            if (seen.has(at)) {
+                error("contract.pattern-region-cycle", `${p.id} region "${r.name}" is its own ancestor`, p.id);
+                break;
+            }
+            seen.add(at);
+        }
+    }
+    for (const part of p.composition?.parts ?? []) {
+        if (part.region !== undefined && !names.has(part.region))
+            error("contract.pattern-region-unknown", `${p.id} part "${part.name}" is placed in unknown region "${part.region}"`, p.id);
+    }
+}
+function checkBehavior(p, error, warn) {
+    const b = p.behavior;
+    if (!b)
+        return;
+    const states = new Set(b.states.map((s) => s.name));
+    if (!states.has(b.initial))
+        error("contract.pattern-state-unknown", `${p.id} initial state "${b.initial}" is not a state`, p.id);
+    for (const t of b.transitions)
+        for (const end of [t.from, t.to])
+            if (!states.has(end))
+                error("contract.pattern-state-unknown", `${p.id} transition "${t.id}" uses unknown state "${end}"`, p.id);
+    const reached = new Set(states.has(b.initial) ? [b.initial] : []);
+    for (let grew = true; grew;) {
+        grew = false;
+        for (const t of b.transitions)
+            if (reached.has(t.from) && states.has(t.to) && !reached.has(t.to)) {
+                reached.add(t.to);
+                grew = true;
+            }
+    }
+    for (const name of states)
+        if (!reached.has(name) && states.has(b.initial))
+            warn("contract.pattern-unreachable-state", `${p.id} state "${name}" cannot be reached from "${b.initial}"`, p.id);
+}
+function checkRelationships(p, error) {
+    const seen = new Set();
+    for (const rel of p.relationships ?? []) {
+        if (rel.target === p.id)
+            error("contract.pattern-self-relationship", `${p.id} has a ${rel.type} relationship to itself`, p.id);
+        if (PATTERN_ONLY_RELATIONSHIPS.includes(rel.type) &&
+            !rel.target.startsWith("pattern:"))
+            error("contract.pattern-relationship-target", `${p.id} relationship "${rel.id}" (${rel.type}) must target a pattern, not ${rel.target}`, p.id);
+        const key = `${rel.type} ${rel.target}`;
+        if (seen.has(key))
+            error("contract.pattern-duplicate-relationship", `${p.id} repeats ${rel.type} ${rel.target}`, p.id);
+        seen.add(key);
+    }
+}
+function checkConstraints(contract, owned, error) {
+    for (const c of contract.constraints) {
+        if (!isPatternConstraintKind(c.kind))
+            continue;
+        const parsed = constraintDetailsSchemas[c.kind].safeParse(c.details);
+        if (!parsed.success) {
+            const issue = parsed.error.issues[0];
+            error("contract.constraint-details-invalid", `${c.id} (${c.kind}) has invalid details at ${issue?.path.join(".") || "(root)"}: ${issue?.message ?? "schema error"}`, c.id);
+            continue;
+        }
+        const regions = stringsIn(parsed.data).filter((v) => v.startsWith("region:"));
+        if (regions.length === 0)
+            continue;
+        const pattern = owned.get(c.id);
+        if (!pattern) {
+            error("contract.pattern-region-unknown", `${c.id} refers to ${regions.join(", ")}, but no pattern owns the constraint`, c.id);
+            continue;
+        }
+        const known = new Set((pattern.layout?.regions ?? []).map((r) => `region:${r.name}`));
+        for (const region of regions)
+            if (!known.has(region))
+                error("contract.pattern-region-unknown", `${c.id} refers to ${region}, which ${pattern.id} does not define`, c.id);
+    }
+}
+/** Patterns pointing at patterns through the relationship types that nest or depend, and through composition parts. */
+function edges(contract) {
+    const ids = new Set(contract.patterns.map((p) => p.id));
+    const graph = new Map();
+    for (const p of contract.patterns) {
+        const out = new Set();
+        for (const rel of p.relationships ?? [])
+            if (ACYCLIC_RELATIONSHIPS.includes(rel.type) && ids.has(rel.target))
+                out.add(rel.target);
+        for (const part of [
+            ...(p.composition?.parts ?? []),
+            ...(p.variations ?? []).flatMap((v) => v.parts ?? [])
+        ])
+            if (part.role !== "prohibited" && ids.has(part.ref))
+                out.add(part.ref);
+        graph.set(p.id, [...out].sort());
+    }
+    return graph;
+}
+function checkCycles(contract, error) {
+    const graph = edges(contract);
+    const state = new Map();
+    const reported = new Set();
+    const visit = (id, path) => {
+        state.set(id, "open");
+        for (const next of graph.get(id) ?? []) {
+            if (next === id)
+                continue; // reported as a self-relationship
+            if (state.get(next) === "open") {
+                const cycle = [...path.slice(path.indexOf(next)), id].filter((_, i, a) => i < a.length);
+                const start = cycle.indexOf([...cycle].sort()[0]);
+                const normal = [...cycle.slice(start), ...cycle.slice(0, start)];
+                const key = normal.join(" > ");
+                if (!reported.has(key)) {
+                    reported.add(key);
+                    error("contract.pattern-cycle", `Patterns form a cycle: ${[...normal, normal[0]].join(" -> ")}`, normal[0]);
+                }
+            }
+            else if (state.get(next) === undefined)
+                visit(next, [...path, id]);
+        }
+        state.set(id, "done");
+    };
+    for (const id of [...graph.keys()].sort())
+        if (state.get(id) === undefined)
+            visit(id, []);
+}
+//# sourceMappingURL=pattern-checks.js.map

package/dist/contract/patterns.js

@@ -0,0 +1,225 @@
+import { z } from "zod";
+import { componentIdSchema, patternIdSchema, tokenIdSchema } from "./primitives.js";
+/*
+ * Pattern contracts (contract 1.1.0). Every field here is optional on a pattern, so a 1.0.0 document is also a
+ * valid 1.1.0 document. Nothing in this file refers to a frontend framework or to how a rule is evaluated.
+ */
+/**
+ * Names of regions, parts, states, transitions and relationships inside one pattern. They are fact-path
+ * segments (`layout.regions.header.required`), so unlike entity names they cannot contain dots.
+ */
+export const partNameSchema = z
+    .string()
+    .max(64)
+    .regex(/^[a-z0-9][a-z0-9_-]*$/);
+/** How a requirement can be verified at best. A validator may never claim more than the method it used. */
+export const verifiableBySchema = z.enum(["static", "runtime", "manual"]);
+/** What a part or a relationship can point at. */
+export const patternTargetSchema = z.union([componentIdSchema, patternIdSchema]);
+/** A named region of the pattern that owns the constraint, written `region:<name>`. */
+export const regionRefSchema = z.string().regex(/^region:[a-z0-9][a-z0-9_-]*$/);
+/** What a structural constraint can talk about: a component, a pattern, or a region of the owning pattern. */
+export const elementRefSchema = z.union([componentIdSchema, patternIdSchema, regionRefSchema]);
+const lengthSchema = z.strictObject({
+    value: z.number().positive().finite(),
+    unit: z.enum(["px", "rem", "em", "%", "ch", "vw"])
+});
+export const layoutRegionSchema = z.strictObject({
+    name: partNameSchema,
+    description: z.string().min(1).optional(),
+    required: z.boolean(),
+    /** The enclosing region, which gives the layout its hierarchy. */
+    parent: partNameSchema.optional(),
+    /** Components and patterns that may fill the region. Absent means no restriction is stated. */
+    accepts: z.array(patternTargetSchema).optional(),
+    width: z.strictObject({ min: lengthSchema.optional(), max: lengthSchema.optional() }).optional(),
+    align: z.enum(["start", "center", "end", "stretch"]).optional(),
+    grid: z
+        .strictObject({ columns: z.number().int().min(1).max(24), gap: tokenIdSchema.optional() })
+        .optional(),
+    spacing: tokenIdSchema.optional(),
+    responsive: z
+        .array(z.strictObject({
+        breakpoint: tokenIdSchema,
+        behavior: z.enum(["unchanged", "stack", "collapse", "hide", "reflow"])
+    }))
+        .optional()
+});
+export const layoutSchema = z.strictObject({ regions: z.array(layoutRegionSchema).min(1) });
+export const compositionPartSchema = z.strictObject({
+    name: partNameSchema,
+    ref: patternTargetSchema,
+    role: z.enum(["required", "optional", "prohibited"]),
+    /** The layout region the part belongs in. */
+    region: partNameSchema.optional(),
+    description: z.string().min(1).optional()
+});
+export const compositionSchema = z.strictObject({ parts: z.array(compositionPartSchema).min(1) });
+/**
+ * A named, approved way a pattern may differ: some parts change role (a required part becomes optional or
+ * prohibited) and some parts exist only here. Everything else is the pattern's base composition. A variation
+ * is how an archetype says "this is allowed" without becoming a second pattern.
+ */
+export const patternVariationSchema = z
+    .strictObject({
+    /** Names the variation; evidence for it is addressed as `variations.<name>`. */
+    name: partNameSchema,
+    description: z.string().min(1).optional(),
+    /** When this variation is the right one, in words. */
+    when: z.string().min(1).optional(),
+    /** Parts of the base composition whose role differs in this variation. */
+    roles: z
+        .array(z.strictObject({ part: partNameSchema, role: z.enum(["required", "optional", "prohibited"]) }))
+        .optional(),
+    /** Parts that exist only in this variation. */
+    parts: z.array(compositionPartSchema).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"
+});
+export const behaviorStateSchema = z.strictObject({
+    name: partNameSchema,
+    description: z.string().min(1).optional(),
+    /** Feedback a user must be given while in this state. */
+    feedback: z.string().min(1).optional(),
+    terminal: z.boolean().optional(),
+    verifiableBy: verifiableBySchema.optional()
+});
+export const behaviorTransitionSchema = z.strictObject({
+    id: partNameSchema,
+    from: partNameSchema,
+    to: partNameSchema,
+    trigger: z.string().min(1).optional(),
+    verifiableBy: verifiableBySchema.optional()
+});
+/** An explicit state machine, enough to describe common interface interactions. It is data, not a workflow engine. */
+export const behaviorSchema = z.strictObject({
+    initial: partNameSchema,
+    states: z.array(behaviorStateSchema).min(1),
+    transitions: z.array(behaviorTransitionSchema)
+});
+export const patternAccessibilitySchema = z.strictObject({
+    requirements: z
+        .array(z.strictObject({
+        id: partNameSchema,
+        statement: z.string().min(1),
+        verifiableBy: verifiableBySchema.optional()
+    }))
+        .min(1)
+});
+export const PATTERN_RELATIONSHIP_TYPES = [
+    "contains",
+    "requires",
+    "uses",
+    "extends",
+    "composes",
+    "alternative-to",
+    "prohibited-with",
+    "supersedes"
+];
+/** Relationship types whose target must be another pattern. `contains` and `uses` may also name a component. */
+export const PATTERN_ONLY_RELATIONSHIPS = [
+    "requires",
+    "extends",
+    "composes",
+    "alternative-to",
+    "prohibited-with",
+    "supersedes"
+];
+/** Relationship types that must not form a cycle. `uses`, `alternative-to` and `prohibited-with` may. */
+export const ACYCLIC_RELATIONSHIPS = [
+    "contains",
+    "requires",
+    "extends",
+    "composes",
+    "supersedes"
+];
+export const patternRelationshipSchema = z.strictObject({
+    /** Stable within the pattern; evidence for the edge is addressed as `relationships.<id>`. */
+    id: partNameSchema,
+    type: z.enum(PATTERN_RELATIONSHIP_TYPES),
+    target: patternTargetSchema,
+    description: z.string().min(1).optional()
+});
+/** Constraint kinds added for patterns. They carry a typed `details` object, validated by `verifyContract`. */
+export const PATTERN_CONSTRAINT_KINDS = [
+    "required-child",
+    "forbidden-child",
+    "requires-parent",
+    "required-region",
+    "ordering",
+    "cardinality",
+    "required-state"
+];
+const count = z.number().int().min(0);
+/**
+ * The interactions Invariant knows how to look for in code, and the states each can be required to represent.
+ * A state here means "the code represents this", not "this works at runtime"; see `evidenceLevelSchema`.
+ */
+export const INTERACTION_STATES = {
+    "form-submission": ["submitting", "error", "success", "guarded"],
+    "destructive-confirmation": ["confirming", "cancellable"],
+    "search-results": ["connected", "loading", "empty", "error", "clearable"]
+};
+export const interactionWorkflowSchema = z.enum(Object.keys(INTERACTION_STATES));
+/**
+ * How much a check established. Static analysis reaches `structural` (the code has the piece and shows it in the
+ * interface) and `static-inferred` (a handler's code shows it happening, such as a pending flag set around an
+ * await). `runtime-verified` is reserved for results that come from running the code, which static analysis
+ * never produces.
+ */
+export const EVIDENCE_LEVELS = ["structural", "static-inferred", "runtime-verified"];
+export const evidenceLevelSchema = z.enum(EVIDENCE_LEVELS);
+export const constraintDetailsSchemas = {
+    "required-child": z.strictObject({
+        parent: elementRefSchema,
+        child: elementRefSchema,
+        min: z.number().int().min(1).optional()
+    }),
+    "forbidden-child": z.strictObject({ parent: elementRefSchema, child: elementRefSchema }),
+    "requires-parent": z.strictObject({ child: elementRefSchema, parents: z.array(elementRefSchema).min(1) }),
+    "required-region": z.strictObject({ region: regionRefSchema }),
+    ordering: z.strictObject({
+        before: elementRefSchema,
+        after: elementRefSchema,
+        within: elementRefSchema.optional()
+    }),
+    cardinality: z
+        .strictObject({
+        target: elementRefSchema,
+        within: elementRefSchema.optional(),
+        min: count.optional(),
+        max: count.optional()
+    })
+        .refine((d) => d.min !== undefined || d.max !== undefined, { message: "state min, max or both" })
+        .refine((d) => d.min === undefined || d.max === undefined || d.max >= d.min, {
+        message: "max must not be below min"
+    }),
+    "required-state": z
+        .strictObject({
+        workflow: interactionWorkflowSchema,
+        state: z.string().min(1).max(40),
+        /** The weakest evidence that satisfies the rule. Default `structural`. */
+        minimum: z.enum(["structural", "static-inferred"]).optional()
+    })
+        .refine((d) => INTERACTION_STATES[d.workflow].includes(d.state), {
+        message: "state is not one of the workflow's states",
+        path: ["state"]
+    })
+};
+export const isPatternConstraintKind = (kind) => PATTERN_CONSTRAINT_KINDS.includes(kind);
+/** Pattern categories introduced in 1.1.0. */
+export const PATTERN_CATEGORIES_1_1 = ["interaction", "page"];
+export const PATTERN_CATEGORIES = [
+    "layout",
+    "navigation",
+    "form",
+    "data-table",
+    "card",
+    "dialog",
+    "workflow",
+    "composition",
+    "other",
+    ...PATTERN_CATEGORIES_1_1
+];
+//# sourceMappingURL=patterns.js.map

package/dist/contract/primitives.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+export const SEGMENT = "[A-Za-z0-9_:-]+";
+/** Source ids are plain slugs: `ui-library`, `storybook`. */
+export const sourceIdSchema = z
+    .string()
+    .max(64)
+    .regex(/^[a-z0-9][a-z0-9._-]*$/);
+export const slugSchema = sourceIdSchema;
+export const ENTITY_KINDS = [
+    "component",
+    "token",
+    "theme",
+    "pattern",
+    "guideline",
+    "constraint",
+    "policy",
+    "conflict"
+];
+const NAME_BODY = "[a-z0-9][a-z0-9._-]*(?:/[a-z0-9][a-z0-9._-]*)*";
+// Theme ids carry no dots or slashes: they appear as keys inside dotted fact paths.
+const THEME_BODY = "[a-z0-9][a-z0-9_-]*";
+/** Stable entity ids are `<kind>:<canonical-name>`, for example `component:button`. */
+export function entityIdSchemaFor(kind) {
+    const body = kind === "theme" ? THEME_BODY : NAME_BODY;
+    return z.string().regex(new RegExp(`^${kind}:${body}$`));
+}
+export const entityIdSchema = z.string().regex(new RegExp(`^(?:${ENTITY_KINDS.join("|")}):${NAME_BODY}$`));
+export const componentIdSchema = entityIdSchemaFor("component");
+export const tokenIdSchema = entityIdSchemaFor("token");
+export const themeIdSchema = entityIdSchemaFor("theme");
+export const patternIdSchema = entityIdSchemaFor("pattern");
+export const guidelineIdSchema = entityIdSchemaFor("guideline");
+export const constraintIdSchema = entityIdSchemaFor("constraint");
+export const policyIdSchema = entityIdSchemaFor("policy");
+export const conflictIdSchema = entityIdSchemaFor("conflict");
+/**
+ * Dotted path to a field inside an entity, for example `props.size.allowedValues`.
+ * Items of keyed arrays (props, events, slots, ...) are addressed by name or id.
+ */
+export const factPathSchema = z.string().regex(new RegExp(`^${SEGMENT}(?:\\.${SEGMENT})*$`));
+export const isoTimestampSchema = z.iso.datetime();
+export const sha256HexSchema = z.string().regex(/^[0-9a-f]{64}$/);
+export const confidenceSchema = z.number().min(0).max(1);
+export const jsonValueSchema = z.lazy(() => z.union([
+    z.string(),
+    z.number().finite(),
+    z.boolean(),
+    z.null(),
+    z.array(jsonValueSchema),
+    z.record(z.string(), jsonValueSchema)
+]));
+export const jsonObjectSchema = z.record(z.string(), jsonValueSchema);
+/**
+ * Framework-specific data lives here, namespaced by framework or tool (`react`, `angular`, `vue`, ...).
+ * The core model never interprets it.
+ */
+export const extensionsSchema = z.record(slugSchema, jsonObjectSchema);
+export const FRAMEWORKS = ["react", "angular", "vue", "other"];
+export const frameworkSchema = z.enum(FRAMEWORKS);
+export const SOURCE_TYPES = [
+    "react",
+    "angular",
+    "vue",
+    "storybook",
+    "figma",
+    "zeroheight",
+    "tokens",
+    "markdown",
+    "git",
+    "npm",
+    /** A human-authored pattern definition file. Adapters never emit it, so it is not an IR source type. */
+    "patterns"
+];
+export const sourceTypeSchema = z.enum(SOURCE_TYPES);
+export const relativePathSchema = z
+    .string()
+    .min(1)
+    .refine((p) => !p.startsWith("/") && !/^[A-Za-z]:/.test(p) && !p.includes("\\") && !p.split("/").includes(".."), {
+    message: "must be a POSIX path relative to the source root, with no '..' segments"
+});
+//# sourceMappingURL=primitives.js.map