@invariant-ui/cli 0.0.0-stage → 0.2.0

package/dist/contract/sources.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { isoTimestampSchema, sourceIdSchema, sourceTypeSchema } from "./primitives.js";
+/**
+ * Authentication metadata only. `credentialRef` names where a credential lives (for example an
+ * environment variable name); the credential itself can never be represented here.
+ */
+export const authenticationSchema = z.strictObject({
+    method: z.enum(["none", "token", "oauth", "ssh"]),
+    credentialRef: z.string().min(1).optional()
+});
+export const sourceVersionSchema = z.strictObject({
+    kind: z.enum(["git-commit", "package-version", "tool-version", "file-version", "content-hash"]),
+    value: z.string().min(1)
+});
+export const sourceSchema = z.strictObject({
+    id: sourceIdSchema,
+    type: sourceTypeSchema,
+    location: z.string().min(1),
+    /** Absent when the source exposes no version. The compiler must not invent one. */
+    version: sourceVersionSchema.optional(),
+    authentication: authenticationSchema.optional(),
+    lastSyncedAt: isoTimestampSchema.optional(),
+    /** Fact-path patterns this source is able to supply, for example `props.*.required`. */
+    capabilities: z.array(z.string().min(1)),
+    health: z.strictObject({
+        status: z.enum(["ok", "degraded", "failed"]),
+        diagnosticCount: z.number().int().nonnegative()
+    })
+});
+//# sourceMappingURL=sources.js.map

package/dist/contract/tokens.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { deprecationSchema } from "./components.js";
+import { factsSchema } from "./facts.js";
+import { extensionsSchema, jsonValueSchema, themeIdSchema, tokenIdSchema } from "./primitives.js";
+export const TOKEN_CATEGORIES = [
+    "color",
+    "typography",
+    "spacing",
+    "sizing",
+    "border",
+    "shadow",
+    "breakpoint",
+    "motion",
+    "other"
+];
+export const tokenCategorySchema = z.enum(TOKEN_CATEGORIES);
+/** A token value is either a literal or a reference to another token (a semantic alias), never both. */
+export const tokenValueSchema = z
+    .strictObject({ value: jsonValueSchema.optional(), aliasOf: tokenIdSchema.optional() })
+    .refine((v) => (v.value === undefined) !== (v.aliasOf === undefined), {
+    message: "exactly one of 'value' or 'aliasOf' is required"
+});
+export const themeSchema = z.strictObject({
+    id: themeIdSchema,
+    name: z.string().min(1),
+    description: z.string().optional(),
+    default: z.boolean().optional()
+});
+export const tokenSchema = z.strictObject({
+    id: tokenIdSchema,
+    name: z.string().min(1),
+    category: tokenCategorySchema,
+    description: z.string().optional(),
+    value: tokenValueSchema,
+    /** Per-theme values keyed by theme id. */
+    modes: z.record(themeIdSchema, tokenValueSchema).optional(),
+    deprecated: deprecationSchema.optional(),
+    facts: factsSchema,
+    extensions: extensionsSchema.optional()
+});
+//# sourceMappingURL=tokens.js.map

package/dist/contract/validate.js

@@ -0,0 +1,253 @@
+import { sortDiagnostics } from "../shared/index.js";
+import { CONTRACT_VERSION, contractSchema, SUPPORTED_CONTRACT_VERSIONS } from "./contract.js";
+import { computeEvidenceId } from "./evidence.js";
+import { resolveFactPath } from "./fact-path.js";
+import { computeFactFingerprint } from "./facts.js";
+import { computeContentHash } from "./integrity.js";
+import { checkPatterns, constraintReferences, newInOnePointOne, patternReferences } from "./pattern-checks.js";
+/**
+ * Structural validation. Major-version mismatches are reported before schema errors. Minor versions
+ * are additive (1.1.0 only added optional fields), so older documents are read as they are and there is
+ * nothing to migrate; a migration registry is added with the first breaking schema change.
+ */
+export function parseContract(input) {
+    const version = declaredVersion(input);
+    if (version !== undefined && version.split(".")[0] !== CONTRACT_VERSION.split(".")[0]) {
+        return {
+            ok: false,
+            diagnostics: [
+                {
+                    code: "contract.unsupported-version",
+                    severity: "error",
+                    message: `Contract version ${version} is not supported; this build reads ${SUPPORTED_CONTRACT_VERSIONS.join(" and ")}`
+                }
+            ]
+        };
+    }
+    const result = contractSchema.safeParse(input);
+    return result.success
+        ? { ok: true, value: result.data }
+        : { ok: false, diagnostics: schemaDiagnostics(result.error) };
+}
+/** Semantic validation: cross-references, ordering, fact paths, approvals, hashes and evidence links. */
+export function verifyContract(contract, evidenceFile) {
+    const found = [];
+    const report = (code, message, entityId) => {
+        found.push({ code, severity: "error", message, ...(entityId ? { entityId } : {}) });
+    };
+    const sourceIds = new Set(contract.sources.map((s) => s.id));
+    const themeIds = new Set(contract.themes.map((t) => t.id));
+    const entityIds = new Set();
+    checkOrdering("source", contract.sources.map((s) => s.id), report);
+    for (const [kind, ids] of collectionIds(contract)) {
+        checkOrdering(kind, ids, report);
+        for (const id of ids)
+            entityIds.add(id);
+    }
+    for (const { from, to } of entityReferences(contract)) {
+        if (!entityIds.has(to))
+            report("contract.dangling-reference", `${from} references unknown entity ${to}`, from);
+    }
+    for (const { from, sourceId } of sourceReferences(contract)) {
+        if (!sourceIds.has(sourceId))
+            report("contract.unknown-source", `${from} references unknown source ${sourceId}`, from);
+    }
+    for (const token of contract.tokens) {
+        for (const theme of Object.keys(token.modes ?? {})) {
+            if (!themeIds.has(theme))
+                report("contract.dangling-reference", `${token.id} has a mode for unknown theme ${theme}`, token.id);
+        }
+    }
+    const frameworks = new Set(contract.metadata.frameworks);
+    for (const component of contract.components) {
+        for (const impl of component.implementations) {
+            if (!frameworks.has(impl.framework)) {
+                report("contract.framework-mismatch", `${component.id} uses framework ${impl.framework} missing from metadata.frameworks`, component.id);
+            }
+        }
+    }
+    checkPatterns(contract, report, found);
+    if (contract.contractVersion === "1.0.0")
+        for (const { entityId, reason } of newInOnePointOne(contract))
+            report("contract.field-newer-than-version", `${entityId} ${reason}, which contract 1.0.0 cannot contain; the document must declare 1.1.0`, entityId);
+    const evidenceIdsUsed = new Set();
+    for (const entity of factBearingEntities(contract)) {
+        for (const [path, fact] of Object.entries(entity.facts)) {
+            for (const id of fact.evidenceIds)
+                evidenceIdsUsed.add(id);
+            checkFact({ entity, path, fact, report });
+        }
+    }
+    for (const conflict of contract.conflicts)
+        for (const claim of conflict.claims)
+            for (const id of claim.evidenceIds)
+                evidenceIdsUsed.add(id);
+    for (const token of contract.tokens)
+        checkAliasCycles({ token, tokens: contract.tokens, themeIds: [...themeIds], report });
+    if (computeContentHash(contract) !== contract.integrity.contentHash) {
+        report("contract.hash-mismatch", "integrity.contentHash does not match the contract content");
+    }
+    if (evidenceFile)
+        checkEvidence({ contract, evidenceFile, evidenceIdsUsed, sourceIds, report });
+    return sortDiagnostics(found);
+}
+function checkFact(input) {
+    const { entity, path, fact, report } = input;
+    const resolved = resolveFactPath(entity, path);
+    if (!resolved.found) {
+        report("contract.unresolvable-fact-path", `${entity.id} has a fact for '${path}' but the path does not resolve`, entity.id);
+        return;
+    }
+    if (fact.status === "approved" && fact.approval) {
+        const fingerprint = computeFactFingerprint({ entityId: entity.id, path, value: resolved.value });
+        if (fingerprint !== fact.approval.fingerprint) {
+            report("contract.approval-stale", `Approval of ${entity.id} '${path}' no longer matches its current value`, entity.id);
+        }
+    }
+}
+function checkOrdering(kind, ids, report) {
+    for (let i = 1; i < ids.length; i++) {
+        const previous = ids[i - 1];
+        const current = ids[i];
+        if (current === previous)
+            report("contract.duplicate-id", `Duplicate ${kind} id ${current}`, current);
+        else if (current < previous)
+            report("contract.unsorted", `${kind} ids must be sorted: ${current} follows ${previous}`, current);
+    }
+}
+function checkAliasCycles(input) {
+    const { token, tokens, themeIds, report } = input;
+    const byId = new Map(tokens.map((t) => [t.id, t]));
+    for (const layer of [undefined, ...themeIds]) {
+        const seen = new Set([token.id]);
+        let current = token;
+        while (current) {
+            const modes = current.modes ?? {};
+            const value = (layer && modes[layer]) || current.value;
+            if (!value.aliasOf)
+                break;
+            if (seen.has(value.aliasOf)) {
+                report("contract.token-alias-cycle", `Token ${token.id} is part of an alias cycle${layer ? ` in ${layer}` : ""}`, token.id);
+                return;
+            }
+            seen.add(value.aliasOf);
+            current = byId.get(value.aliasOf);
+        }
+    }
+}
+function checkEvidence(input) {
+    const { contract, evidenceFile, evidenceIdsUsed, sourceIds, report } = input;
+    if (evidenceFile.contractContentHash !== contract.integrity.contentHash) {
+        report("contract.evidence-hash-mismatch", "Evidence file belongs to a different contract content hash");
+    }
+    const known = new Set();
+    checkOrdering("evidence", evidenceFile.evidence.map((e) => e.id), report);
+    for (const evidence of evidenceFile.evidence) {
+        known.add(evidence.id);
+        if (computeEvidenceId(evidence) !== evidence.id)
+            report("contract.evidence-id-mismatch", `Evidence ${evidence.id} id does not match its content`);
+        if (!sourceIds.has(evidence.sourceId))
+            report("contract.unknown-source", `Evidence ${evidence.id} references unknown source ${evidence.sourceId}`);
+    }
+    for (const id of [...evidenceIdsUsed].sort()) {
+        if (!known.has(id))
+            report("contract.unknown-evidence", `Evidence ${id} is referenced but missing from the evidence file`);
+    }
+}
+function collectionIds(contract) {
+    return [
+        ["component", contract.components.map((e) => e.id)],
+        ["token", contract.tokens.map((e) => e.id)],
+        ["theme", contract.themes.map((e) => e.id)],
+        ["pattern", contract.patterns.map((e) => e.id)],
+        ["guideline", contract.guidelines.map((e) => e.id)],
+        ["constraint", contract.constraints.map((e) => e.id)],
+        ["policy", contract.policies.map((e) => e.id)],
+        ["conflict", contract.conflicts.map((e) => e.id)]
+    ];
+}
+function factBearingEntities(contract) {
+    return [
+        ...contract.components,
+        ...contract.tokens,
+        ...contract.patterns,
+        ...contract.guidelines,
+        ...contract.constraints
+    ];
+}
+function entityReferences(contract) {
+    const refs = [];
+    const add = (from, to) => {
+        if (to)
+            refs.push({ from, to });
+    };
+    for (const c of contract.components) {
+        add(c.id, c.deprecated?.replacedBy);
+        for (const prop of c.props)
+            add(c.id, prop.deprecated?.replacedBy);
+        for (const event of c.events)
+            add(c.id, event.deprecated?.replacedBy);
+        for (const slot of c.slots)
+            for (const target of slot.accepts ?? [])
+                add(c.id, target);
+        for (const rel of c.composition)
+            add(c.id, rel.target);
+    }
+    for (const t of contract.tokens) {
+        add(t.id, t.deprecated?.replacedBy);
+        add(t.id, t.value.aliasOf);
+        for (const mode of Object.values(t.modes ?? {}))
+            add(t.id, mode.aliasOf);
+    }
+    for (const p of contract.patterns)
+        for (const to of [...p.components, ...p.guidelines])
+            add(p.id, to);
+    for (const g of contract.guidelines)
+        for (const to of g.appliesTo)
+            add(g.id, to);
+    for (const c of contract.constraints)
+        for (const to of c.subjects)
+            add(c.id, to);
+    for (const { from, to } of [...patternReferences(contract), ...constraintReferences(contract)])
+        add(from, to);
+    for (const p of contract.policies)
+        for (const to of [...(p.scope.entities ?? []), ...p.basedOn])
+            add(p.id, to);
+    for (const c of contract.conflicts)
+        add(c.id, c.subject);
+    return refs;
+}
+function sourceReferences(contract) {
+    const refs = [];
+    for (const c of contract.components) {
+        for (const impl of c.implementations)
+            refs.push({ from: c.id, sourceId: impl.sourceId });
+        for (const example of c.examples)
+            if (example.sourceId)
+                refs.push({ from: c.id, sourceId: example.sourceId });
+    }
+    for (const g of contract.guidelines)
+        for (const ref of g.references)
+            refs.push({ from: g.id, sourceId: ref.sourceId });
+    for (const c of contract.conflicts)
+        for (const claim of c.claims)
+            refs.push({ from: c.id, sourceId: claim.sourceId });
+    return refs;
+}
+function declaredVersion(input) {
+    if (typeof input !== "object" || input === null)
+        return undefined;
+    const version = input.contractVersion;
+    return typeof version === "string" ? version : undefined;
+}
+function schemaDiagnostics(error) {
+    return sortDiagnostics(error.issues.map((issue) => ({
+        code: "contract.invalid-schema",
+        severity: "error",
+        message: `${formatPath(issue.path)}: ${issue.message}`
+    })));
+}
+function formatPath(path) {
+    return path.reduce((acc, part) => (typeof part === "number" ? `${acc}[${part}]` : `${acc}.${String(part)}`), "$");
+}
+//# sourceMappingURL=validate.js.map

package/dist/contract-query/archetype.js

@@ -0,0 +1,188 @@
+import { effectiveParts, isPatternConstraintKind } from "../contract/index.js";
+import { patternStatus } from "./patterns.js";
+import { cmp } from "./system.js";
+const MAX_DEPTH = 6;
+const COMPOSING = new Set(["composes", "contains", "uses", "requires"]);
+const kindOf = (id) => id.slice(0, Math.max(0, id.indexOf(":")));
+function describe(ds, id) {
+    const name = ds.component(id)?.name ?? ds.pattern(id)?.name;
+    return { id, kind: kindOf(id), ...(name ? { name } : {}) };
+}
+function summary(p) {
+    const s = patternStatus(p);
+    return {
+        id: p.id,
+        name: p.name,
+        category: p.category,
+        status: s.overall,
+        approved: s.overall === "approved"
+    };
+}
+/**
+ * A pattern read as a page blueprint: what it is made of, followed through the patterns it composes to any depth,
+ * its regions, variations, required interaction states, responsive expectations and prohibited combinations, and
+ * how much of it is approved. A variation, when named, is applied to the pattern's own composition (patterns it
+ * composes contribute their base composition).
+ */
+export function archetypeView(ds, root, options = {}) {
+    const names = (root.variations ?? []).map((v) => v.name);
+    if (options.variation !== undefined && !names.includes(options.variation))
+        return {
+            ok: false,
+            message: `${root.id} has no variation "${options.variation}"${names.length > 0 ? `; its variations are ${names.join(", ")}` : " (it has none)"}`,
+            variations: names
+        };
+    const members = new Map();
+    const missing = new Set();
+    let truncated = false;
+    const node = (p, variation, trail, depth) => {
+        const parts = effectiveParts(p, variation);
+        const seen = new Set();
+        const expand = (ref, via) => {
+            if (!ref.startsWith("pattern:"))
+                return undefined;
+            const n = ds.pattern(ref);
+            if (!n) {
+                missing.add(ref);
+                return undefined;
+            }
+            if (trail.includes(ref) || ref === p.id)
+                return { cycle: true };
+            if (depth + 1 >= MAX_DEPTH) {
+                truncated = true;
+                return { truncated: true };
+            }
+            const known = members.get(ref);
+            if (!known || known.depth > depth + 1)
+                members.set(ref, { pattern: n, depth: depth + 1, via });
+            return node(n, undefined, [...trail, p.id], depth + 1);
+        };
+        const rendered = parts.map((x) => {
+            seen.add(x.ref);
+            const expanded = x.role === "prohibited" ? undefined : expand(x.ref, `${p.id} part ${x.name}`);
+            return {
+                name: x.name,
+                role: x.role,
+                ...(x.region ? { region: x.region } : {}),
+                ref: describe(ds, x.ref),
+                ...(expanded ? { expanded } : {})
+            };
+        });
+        const related = (p.relationships ?? [])
+            .filter((r) => COMPOSING.has(r.type))
+            .map((r) => {
+            const expanded = seen.has(r.target) ? undefined : expand(r.target, `${p.id} ${r.type}`);
+            return {
+                id: r.id,
+                type: r.type,
+                target: describe(ds, r.target),
+                ...(expanded ? { expanded } : {})
+            };
+        });
+        return { pattern: summary(p), parts: rendered, related };
+    };
+    members.set(root.id, { pattern: root, depth: 0, via: "the archetype itself" });
+    const tree = node(root, options.variation, [], 0);
+    const set = [...members.values()].sort((a, b) => a.depth - b.depth || cmp(a.pattern.id, b.pattern.id));
+    const constraints = set.flatMap(({ pattern }) => (pattern.constraints ?? []).flatMap((id) => {
+        const c = ds.contract.constraints.find((x) => x.id === id);
+        if (!c)
+            return [];
+        const enforcedBy = ds.contract.policies.filter((p) => p.basedOn.includes(c.id)).map((p) => p.id);
+        return [{ pattern, constraint: c, enforcedBy }];
+    }));
+    const requiredStates = constraints
+        .filter((x) => x.constraint.kind === "required-state")
+        .map(({ pattern, constraint, enforcedBy }) => {
+        const d = (constraint.details ?? {});
+        return {
+            pattern: pattern.id,
+            constraint: constraint.id,
+            workflow: d.workflow ?? null,
+            state: d.state ?? null,
+            minimum: d.minimum ?? "structural",
+            enforced: enforcedBy.length > 0,
+            enforcedBy
+        };
+    });
+    const structural = constraints
+        .filter((x) => x.constraint.kind !== "required-state" && isPatternConstraintKind(x.constraint.kind))
+        .map(({ pattern, constraint, enforcedBy }) => ({
+        pattern: pattern.id,
+        constraint: constraint.id,
+        kind: constraint.kind,
+        enforced: enforcedBy.length > 0,
+        enforcedBy
+    }));
+    const responsive = set.flatMap(({ pattern }) => (pattern.layout?.regions ?? []).flatMap((r) => (r.responsive ?? []).map((x) => ({
+        pattern: pattern.id,
+        region: r.name,
+        breakpoint: x.breakpoint,
+        behavior: x.behavior
+    }))));
+    const parts = effectiveParts(root, options.variation);
+    const regions = (root.layout?.regions ?? []).map((r) => ({
+        name: r.name,
+        required: r.required,
+        ...(r.parent ? { parent: r.parent } : {}),
+        parts: parts.filter((x) => x.region === r.name && x.role !== "prohibited").map((x) => x.name),
+        ...(r.responsive ? { responsive: r.responsive } : {})
+    }));
+    const variations = (root.variations ?? []).map((v) => ({
+        name: v.name,
+        ...(v.description ? { description: v.description } : {}),
+        ...(v.when ? { when: v.when } : {}),
+        roles: (v.roles ?? []),
+        addedParts: (v.parts ?? []).map((x) => ({ name: x.name, role: x.role, ref: describe(ds, x.ref) })),
+        fact: ds.factView(root.facts, `variations.${v.name}`) ?? null
+    }));
+    const inSet = new Set(set.map((x) => x.pattern.id));
+    const prohibitedTogether = set.flatMap(({ pattern }) => (pattern.relationships ?? [])
+        .filter((r) => r.type === "prohibited-with")
+        .map((r) => ({ pattern: pattern.id, with: r.target, composedHere: inSet.has(r.target) })));
+    const unapproved = set.filter((x) => !summary(x.pattern).approved);
+    const rootStatus = patternStatus(root);
+    const notes = [];
+    if (rootStatus.overall !== "approved")
+        notes.push(`This archetype is not fully approved (${rootStatus.overall}). Treat it as a proposal.`);
+    const nested = unapproved.filter((x) => x.pattern.id !== root.id);
+    if (rootStatus.overall === "approved" && nested.length > 0)
+        notes.push(`This archetype is approved, but ${nested.length} pattern(s) it builds on are not: ${nested.map((x) => x.pattern.id).join(", ")}. Approval of the archetype does not approve them.`);
+    if (missing.size > 0)
+        notes.push(`It refers to pattern(s) the contract does not have: ${[...missing].sort(cmp).join(", ")}.`);
+    if (truncated)
+        notes.push(`Composition was followed ${MAX_DEPTH} levels deep and then stopped.`);
+    const unenforced = requiredStates.filter((x) => x.enforced !== true).length + structural.filter((x) => !x.enforced).length;
+    if (constraints.length > 0 && unenforced > 0)
+        notes.push(`${unenforced} constraint(s) have no approved policy, so \`validate\` does not enforce them.`);
+    if (options.variation)
+        notes.push(`Showing the "${options.variation}" variation. Patterns it composes are shown as written.`);
+    return {
+        ok: true,
+        view: {
+            id: root.id,
+            name: root.name,
+            category: root.category,
+            ...(root.intent ? { intent: root.intent } : {}),
+            ...(options.variation ? { variation: options.variation } : {}),
+            status: { overall: rootStatus.overall, counts: rootStatus.counts, total: rootStatus.total },
+            approved: rootStatus.overall === "approved",
+            regions,
+            composition: tree,
+            patterns: set.map((x) => ({ ...summary(x.pattern), depth: x.depth, via: x.via })),
+            unapproved: unapproved.map((x) => x.pattern.id),
+            variations,
+            prohibited: {
+                parts: parts
+                    .filter((x) => x.role === "prohibited")
+                    .map((x) => ({ name: x.name, ref: describe(ds, x.ref) })),
+                patterns: prohibitedTogether
+            },
+            requiredStates,
+            constraints: structural,
+            responsive,
+            notes
+        }
+    };
+}
+//# sourceMappingURL=archetype.js.map

package/dist/contract-query/index.js

@@ -0,0 +1,6 @@
+export { archetypeView } from "./archetype.js";
+export { patternRelationships, patternStatus, patternsView, patternView } from "./patterns.js";
+export { search } from "./search.js";
+export { cmp, DesignSystem, normalize, sanitizeName } from "./system.js";
+export { catalog, componentView, compositionView, guidelinesView, overview, page, tokensView, tokenView, usageView } from "./views.js";
+//# sourceMappingURL=index.js.map