@aestheticfunction/dspack-gen 0.1.0

package/dist/core/contract.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Minimal dspack v0.3/v0.4 contract types — exactly the fields the pipeline
+ * reads. Deliberately local: `core` (compiler + linter) is protocol-neutral
+ * and depends on no emitter and no network module (enforced by core-boundary
+ * tests). dspack documents may carry more; unknown properties are ignored per
+ * dspack conformance rules.
+ */
+export interface Contract {
+    dspack: string;
+    name: string;
+    description?: string;
+    tokens?: Record<string, {
+        values?: Record<string, {
+            value?: unknown;
+        }>;
+    }>;
+    components?: Record<string, ContractComponent>;
+    /** v0.4: contract-defined category registry (spec v0.4 §3). */
+    categories?: Record<string, {
+        name?: string;
+        description: string;
+    }>;
+    patterns?: ContractPattern[];
+    intents?: IntentEntry[];
+    rules?: RuleEntry[];
+    examples?: ExampleEntry[];
+    [k: string]: unknown;
+}
+export interface ContractComponent {
+    name: string;
+    description: string;
+    props?: Record<string, ContractProp>;
+    composition?: {
+        subComponents?: SubComponent[];
+        notes?: string;
+    };
+    /** v0.4: membership in registered categories. */
+    categories?: string[];
+    [k: string]: unknown;
+}
+export interface ContractProp {
+    type: string;
+    description?: string;
+    values?: Array<string | number | boolean | {
+        value: unknown;
+        description?: string;
+    }>;
+    default?: unknown;
+    [k: string]: unknown;
+}
+export interface SubComponent {
+    id: string;
+    name: string;
+    description?: string;
+    required?: boolean;
+    slot?: string;
+    acceptsChildren?: string;
+    /** v0.4: membership in registered categories. */
+    categories?: string[];
+}
+export interface ContractPattern {
+    id: string;
+    name?: string;
+    guidance?: string;
+    [k: string]: unknown;
+}
+export interface IntentEntry {
+    id: string;
+    name?: string;
+    description: string;
+    relatedPatterns?: string[];
+    tags?: string[];
+}
+export type RuleSeverity = "must" | "should";
+export type RuleType = "component-choice" | "required-composition" | "forbidden-composition" | "required-props";
+export interface RuleBase {
+    id: string;
+    type: string;
+    severity: RuleSeverity;
+    rationale: string;
+    appliesTo?: {
+        intents: string[];
+    };
+    examples?: string[];
+    tags?: string[];
+}
+export interface ComponentChoiceRule extends RuleBase {
+    type: "component-choice";
+    require?: string[];
+    forbid?: string[];
+}
+export interface RequiredCompositionRule extends RuleBase {
+    type: "required-composition";
+    component: string;
+    requiredSubComponents?: Array<{
+        id: string;
+        min?: number;
+    }>;
+    requiredProps?: Array<{
+        on?: string;
+        prop: string;
+        oneOf: unknown[];
+    }>;
+}
+export interface ForbiddenCompositionRule extends RuleBase {
+    type: "forbidden-composition";
+    component: string;
+    forbiddenDescendants?: string[];
+    forbiddenProps?: Array<{
+        on?: string;
+        prop: string;
+        values: unknown[];
+    }>;
+    /** v0.4: forbid descendants by registered category (spec v0.4 §4.2). */
+    forbiddenCategories?: string[];
+}
+/**
+ * v0.4 required-props (spec v0.4 §4.1): content every instance of `component`
+ * must carry DIRECTLY — its own `text` field and/or directly-present props.
+ * The one rule type whose `component` accepts a sub-component id.
+ */
+export interface RequiredPropsRule extends RuleBase {
+    type: "required-props";
+    component: string;
+    within?: string;
+    requiredText?: true;
+    /** v0.4 amendment (2026-07-04): where requiredText looks. Default "self". */
+    textScope?: "self" | "subtree";
+    requiredProps?: Array<{
+        prop: string;
+        oneOf?: unknown[];
+    }>;
+}
+export type RuleEntry = ComponentChoiceRule | RequiredCompositionRule | ForbiddenCompositionRule | RequiredPropsRule | RuleBase;
+export interface ExampleEntry {
+    id: string;
+    intent: string;
+    name?: string;
+    description?: string;
+    prompt?: string;
+    surface: Surface;
+}
+/** dspack surface v0.1 (schema: dspack repo, dspack.surface.v0_1.schema.json). */
+export interface Surface {
+    dspackSurface: string;
+    system: string;
+    intent: string;
+    root: SurfaceNode;
+}
+export interface SurfaceNode {
+    component: string;
+    id?: string;
+    props?: Record<string, unknown>;
+    text?: string;
+    children?: SurfaceNode[];
+    slots?: Record<string, SurfaceNode[]>;
+}
+/** Bare enum values from a prop descriptor (valueDescriptor objects unwrapped). */
+export declare function enumValues(prop: ContractProp): unknown[] | null;
+/** All sub-component ids of the contract, mapped to their parent component id. */
+export declare function subComponentIndex(contract: Contract): Map<string, string>;
+/**
+ * Sub-component ids declared by more than one component, with all declaring
+ * parents. Spec v0.3 §5 makes document-wide uniqueness normative for
+ * contracts using governance blocks: S2 and rule resolution work by id alone
+ * and must never depend on object iteration order.
+ */
+export declare function duplicateSubComponentIds(contract: Contract): Map<string, string[]>;
+/**
+ * Category memberships by component/sub-component id (v0.4). Ids without
+ * memberships are absent. Resolution is through the contract at lint time —
+ * categories never appear in surfaces (spec v0.4 §3).
+ */
+export declare function categoryIndex(contract: Contract): Map<string, string[]>;
+export declare function getIntent(contract: Contract, intentId: string): IntentEntry;

package/dist/core/contract.js

@@ -0,0 +1,62 @@
+/**
+ * Minimal dspack v0.3/v0.4 contract types — exactly the fields the pipeline
+ * reads. Deliberately local: `core` (compiler + linter) is protocol-neutral
+ * and depends on no emitter and no network module (enforced by core-boundary
+ * tests). dspack documents may carry more; unknown properties are ignored per
+ * dspack conformance rules.
+ */
+/** Bare enum values from a prop descriptor (valueDescriptor objects unwrapped). */
+export function enumValues(prop) {
+    if (prop.type !== "enum" || !Array.isArray(prop.values))
+        return null;
+    return prop.values.map((v) => (v && typeof v === "object" ? v.value : v));
+}
+/** All sub-component ids of the contract, mapped to their parent component id. */
+export function subComponentIndex(contract) {
+    const index = new Map();
+    for (const [id, component] of Object.entries(contract.components ?? {})) {
+        for (const sub of component.composition?.subComponents ?? [])
+            index.set(sub.id, id);
+    }
+    return index;
+}
+/**
+ * Sub-component ids declared by more than one component, with all declaring
+ * parents. Spec v0.3 §5 makes document-wide uniqueness normative for
+ * contracts using governance blocks: S2 and rule resolution work by id alone
+ * and must never depend on object iteration order.
+ */
+export function duplicateSubComponentIds(contract) {
+    const parents = new Map();
+    for (const [id, component] of Object.entries(contract.components ?? {})) {
+        for (const sub of component.composition?.subComponents ?? []) {
+            parents.set(sub.id, [...(parents.get(sub.id) ?? []), id]);
+        }
+    }
+    return new Map([...parents].filter(([, declaredBy]) => declaredBy.length > 1));
+}
+/**
+ * Category memberships by component/sub-component id (v0.4). Ids without
+ * memberships are absent. Resolution is through the contract at lint time —
+ * categories never appear in surfaces (spec v0.4 §3).
+ */
+export function categoryIndex(contract) {
+    const index = new Map();
+    for (const [id, component] of Object.entries(contract.components ?? {})) {
+        if (component.categories?.length)
+            index.set(id, component.categories);
+        for (const sub of component.composition?.subComponents ?? []) {
+            if (sub.categories?.length)
+                index.set(sub.id, sub.categories);
+        }
+    }
+    return index;
+}
+export function getIntent(contract, intentId) {
+    const intent = (contract.intents ?? []).find((i) => i.id === intentId);
+    if (!intent) {
+        const known = (contract.intents ?? []).map((i) => i.id).join(", ") || "(none)";
+        throw new Error(`intent '${intentId}' is not registered in the contract (known: ${known})`);
+    }
+    return intent;
+}

package/dist/core/generation-schema.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Per-contract generation schema: the JSON Schema handed to constrained
+ * decoding (Ollama `format`, hosted output schemas).
+ *
+ * Derivation from the contract: full component + sub-component vocabulary as
+ * anyOf branches, per-component prop enums, `intent`/`system`/`dspackSurface`
+ * as consts, and recursion depth-unrolled ($defs node_0..node_{D-1}; the last
+ * level is a leaf) so the schema is non-recursive by construction. Default
+ * depth 6 was confirmed by the S0 spike (docs/spike-structured-outputs.md):
+ * depths 3–8 compile and are enforced on grammar-backed engines.
+ *
+ * The three layers, deliberately: this schema encodes vocabulary and shape
+ * ONLY — never governance. Encoding rules here would make violations
+ * unobservable and the audit trail vacuous. Gate S2 is *defined* as a check on
+ * the produced surface; this schema may be reused to implement it, but S2 is
+ * always reported independently.
+ *
+ * Spike-inherited simplifications (documented): children accept the full
+ * vocabulary at every level (per-parent child constraints are S3 territory),
+ * `text` is allowed on every node, and `slots` are not generated (composition
+ * is expressed via children; the surface schema still accepts slots on
+ * hand-authored surfaces).
+ */
+import { type Contract } from "./contract.js";
+export declare const DEFAULT_UNROLL_DEPTH = 6;
+export interface GenerationSchemaOptions {
+    /** Levels of tree nesting the schema admits. S0-confirmed default: 6. */
+    depth?: number;
+}
+type Json = Record<string, unknown>;
+export declare function buildGenerationSchema(contract: Contract, intentId: string, options?: GenerationSchemaOptions): Json;
+export {};

package/dist/core/generation-schema.js

@@ -0,0 +1,85 @@
+/**
+ * Per-contract generation schema: the JSON Schema handed to constrained
+ * decoding (Ollama `format`, hosted output schemas).
+ *
+ * Derivation from the contract: full component + sub-component vocabulary as
+ * anyOf branches, per-component prop enums, `intent`/`system`/`dspackSurface`
+ * as consts, and recursion depth-unrolled ($defs node_0..node_{D-1}; the last
+ * level is a leaf) so the schema is non-recursive by construction. Default
+ * depth 6 was confirmed by the S0 spike (docs/spike-structured-outputs.md):
+ * depths 3–8 compile and are enforced on grammar-backed engines.
+ *
+ * The three layers, deliberately: this schema encodes vocabulary and shape
+ * ONLY — never governance. Encoding rules here would make violations
+ * unobservable and the audit trail vacuous. Gate S2 is *defined* as a check on
+ * the produced surface; this schema may be reused to implement it, but S2 is
+ * always reported independently.
+ *
+ * Spike-inherited simplifications (documented): children accept the full
+ * vocabulary at every level (per-parent child constraints are S3 territory),
+ * `text` is allowed on every node, and `slots` are not generated (composition
+ * is expressed via children; the surface schema still accepts slots on
+ * hand-authored surfaces).
+ */
+import { enumValues } from "./contract.js";
+export const DEFAULT_UNROLL_DEPTH = 6;
+export function buildGenerationSchema(contract, intentId, options = {}) {
+    const depth = options.depth ?? DEFAULT_UNROLL_DEPTH;
+    if (!Number.isInteger(depth) || depth < 1)
+        throw new Error(`invalid unroll depth ${depth}`);
+    const components = contract.components ?? {};
+    const $defs = {};
+    for (let level = 0; level < depth; level++) {
+        const branches = [];
+        for (const [id, component] of Object.entries(components)) {
+            branches.push(branch(id, componentProps(component), level, depth));
+            for (const sub of component.composition?.subComponents ?? []) {
+                branches.push(branch(sub.id, null, level, depth));
+            }
+        }
+        $defs[`node_${level}`] = { anyOf: branches };
+    }
+    return {
+        $schema: "https://json-schema.org/draft/2020-12/schema",
+        type: "object",
+        additionalProperties: false,
+        required: ["dspackSurface", "system", "intent", "root"],
+        properties: {
+            dspackSurface: { const: "0.1" },
+            system: { const: contract.name },
+            intent: { const: intentId },
+            root: { $ref: "#/$defs/node_0" },
+        },
+        $defs,
+    };
+}
+function componentProps(component) {
+    const entries = Object.entries(component.props ?? {});
+    if (entries.length === 0)
+        return null;
+    const properties = {};
+    for (const [name, descriptor] of entries) {
+        const values = enumValues(descriptor);
+        properties[name] = values
+            ? { enum: values }
+            : descriptor.type === "boolean"
+                ? { type: "boolean" }
+                : descriptor.type === "number"
+                    ? { type: "number" }
+                    : { type: "string" };
+    }
+    return { type: "object", additionalProperties: false, properties };
+}
+function branch(id, props, level, depth) {
+    const properties = {
+        component: { const: id },
+        id: { type: "string" },
+        text: { type: "string" },
+    };
+    if (props)
+        properties.props = props;
+    if (level < depth - 1) {
+        properties.children = { type: "array", items: { $ref: `#/$defs/node_${level + 1}` } };
+    }
+    return { type: "object", additionalProperties: false, required: ["component"], properties };
+}

package/dist/core/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @aestheticfunction/dspack-gen/core — the zero-network, emitter-free subset:
+ * prompt/context compiler (+ the governance linter, from PR-4 on).
+ *
+ * ds-mcp's `get-generation-context` / `validate-ui` tools import exactly this
+ * subpath; its no-network/read-only invariants depend on this boundary, which
+ * is enforced by src/core/core-boundary.test.ts.
+ */
+export * from "./contract.js";
+export * from "./generation-schema.js";
+export * from "./compiler.js";
+export * from "./lint/index.js";

package/dist/core/index.js

@@ -0,0 +1,12 @@
+/**
+ * @aestheticfunction/dspack-gen/core — the zero-network, emitter-free subset:
+ * prompt/context compiler (+ the governance linter, from PR-4 on).
+ *
+ * ds-mcp's `get-generation-context` / `validate-ui` tools import exactly this
+ * subpath; its no-network/read-only invariants depend on this boundary, which
+ * is enforced by src/core/core-boundary.test.ts.
+ */
+export * from "./contract.js";
+export * from "./generation-schema.js";
+export * from "./compiler.js";
+export * from "./lint/index.js";

package/dist/core/lint/findings.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Lint findings and the gate report — ONE object, two serializations (ADR-7):
+ * the JSON here is embedded verbatim in audit reports and rendered
+ * deterministically into repair feedback; `renderText` is the human CLI view.
+ *
+ * Severity carries both faces (ADR-11): `requirement` is the contract's
+ * RFC 2119 term (must|should), `level` the tool mapping (error|warn).
+ */
+import type { RuleSeverity } from "../contract.js";
+export type FindingLevel = "error" | "warn";
+export declare const LEVEL_OF: Record<RuleSeverity, FindingLevel>;
+export interface FindingLocation {
+    /** Path from the surface root, e.g. `$.root.children[0]`; `$.root` for surface-wide findings. */
+    path: string;
+    /** The component id at the location, or "surface" for surface-wide findings. */
+    component: string;
+    nodeId?: string;
+}
+export interface Finding {
+    ruleId: string;
+    type: string;
+    requirement: RuleSeverity;
+    level: FindingLevel;
+    message: string;
+    rationale: string;
+    location: FindingLocation;
+    exampleIds: string[];
+}
+export type GateName = "S1" | "S2" | "S3";
+export type GateStatus = "PASS" | "FAIL" | "SKIPPED";
+export interface GateReport {
+    gate: GateName;
+    name: string;
+    status: GateStatus;
+    /** S1/S2 error strings; S3 uses `findings` instead. */
+    errors?: string[];
+}
+export interface LintReport {
+    gates: GateReport[];
+    findings: Finding[];
+    /** Errors only (warn findings never fail the lint in v0.3). */
+    errorCount: number;
+    warnCount: number;
+    pass: boolean;
+}
+export declare function renderText(report: LintReport): string;

package/dist/core/lint/findings.js

@@ -0,0 +1,28 @@
+export const LEVEL_OF = {
+    must: "error",
+    should: "warn",
+};
+export function renderText(report) {
+    const lines = [];
+    for (const gate of report.gates) {
+        lines.push(`gate ${gate.gate} ${gate.name.padEnd(21)} ${gate.status}`);
+        for (const error of gate.errors ?? [])
+            lines.push(`  ✖ ${error}`);
+    }
+    for (const finding of report.findings) {
+        const mark = finding.level === "error" ? "✖" : "▲";
+        lines.push(`${mark} ${finding.level} [${finding.requirement}]  ${finding.ruleId}  [${finding.type}]`);
+        const where = finding.location.nodeId
+            ? `${finding.location.path}  (component: ${finding.location.component}, id: "${finding.location.nodeId}")`
+            : `${finding.location.path}  (component: ${finding.location.component})`;
+        lines.push(`   at ${where}`);
+        lines.push(`   ${finding.message}`);
+        lines.push(`   Rationale: ${finding.rationale}`);
+        if (finding.exampleIds.length)
+            lines.push(`   See example: ${finding.exampleIds.join(", ")}`);
+    }
+    lines.push(report.pass
+        ? `lint: PASS — 0 error(s), ${report.warnCount} warning(s)`
+        : `lint: FAIL — ${report.errorCount} error(s), ${report.warnCount} warning(s)`);
+    return lines.join("\n");
+}

package/dist/core/lint/index.d.ts

@@ -0,0 +1,7 @@
+import type { Contract } from "../contract.js";
+import { type LintReport } from "./findings.js";
+export { renderText, LEVEL_OF } from "./findings.js";
+export type { Finding, FindingLevel, FindingLocation, GateName, GateReport, GateStatus, LintReport } from "./findings.js";
+export { UnknownRuleTypeError } from "./rules.js";
+export { walkSurface } from "./walk.js";
+export declare function lintSurface(surface: unknown, contract: Contract): LintReport;

package/dist/core/lint/index.js

@@ -0,0 +1,67 @@
+/**
+ * The surface gates, run in order and independently reported (never implicit
+ * steps inside generation):
+ *   S1 — generic surface schema (vendored dspack.surface.v0_1)
+ *   S2 — contract vocabulary
+ *   S3 — governance rules (typed evaluators, registry in rules.ts)
+ *
+ * S1 failure skips S2/S3 (the tree shape is not trustworthy); S2 failure
+ * still evaluates S3 (the walk is safe and more findings help repair).
+ * `pass` is false iff any gate FAILs; warn-level findings never fail (v0.3).
+ */
+import Ajv2020 from "ajv/dist/2020.js";
+import { surfaceSchemaV0_1 } from "../surface-schema.js";
+import { checkVocabulary } from "./vocabulary.js";
+import { evaluateRules } from "./rules.js";
+export { renderText, LEVEL_OF } from "./findings.js";
+export { UnknownRuleTypeError } from "./rules.js";
+export { walkSurface } from "./walk.js";
+const ajv = new Ajv2020({ strict: false, allErrors: true });
+const validateSurfaceSchema = ajv.compile(surfaceSchemaV0_1);
+export function lintSurface(surface, contract) {
+    const gates = [];
+    let findings = [];
+    // S1 — generic surface schema.
+    const s1Ok = validateSurfaceSchema(surface);
+    gates.push({
+        gate: "S1",
+        name: "surface-schema",
+        status: s1Ok ? "PASS" : "FAIL",
+        errors: s1Ok
+            ? undefined
+            : (validateSurfaceSchema.errors ?? []).map((e) => `${e.instancePath || "(root)"} ${e.message ?? ""}`.trim()),
+    });
+    if (!s1Ok) {
+        gates.push({ gate: "S2", name: "contract-vocabulary", status: "SKIPPED" });
+        gates.push({ gate: "S3", name: "governance", status: "SKIPPED" });
+        return summarize(gates, findings);
+    }
+    const typed = surface;
+    // S2 — contract vocabulary (a check on the artifact, whatever produced it).
+    const s2Errors = checkVocabulary(typed, contract);
+    gates.push({
+        gate: "S2",
+        name: "contract-vocabulary",
+        status: s2Errors.length === 0 ? "PASS" : "FAIL",
+        errors: s2Errors.length ? s2Errors : undefined,
+    });
+    // S3 — governance. Unknown rule types throw (CLI exit 4), never skip.
+    findings = evaluateRules(typed, contract);
+    gates.push({
+        gate: "S3",
+        name: "governance",
+        status: findings.some((f) => f.level === "error") ? "FAIL" : "PASS",
+    });
+    return summarize(gates, findings);
+}
+function summarize(gates, findings) {
+    const errorCount = findings.filter((f) => f.level === "error").length;
+    const warnCount = findings.filter((f) => f.level === "warn").length;
+    return {
+        gates,
+        findings,
+        errorCount,
+        warnCount,
+        pass: gates.every((g) => g.status !== "FAIL"),
+    };
+}

package/dist/core/lint/rules.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Gate S3 — the rule-type registry and evaluators (normative semantics:
+ * spec/dspack-v0.3.md §5.3 and spec/dspack-v0.4.md §4).
+ *
+ * The registry is the thesis-bearing seam: new rule types land additively in
+ * v0.4 by adding an entry — never by touching existing evaluators. v0.4 kept
+ * that promise for `required-props` (a new entry); `forbiddenCategories` is
+ * the spec'd exception — a new OPTIONAL field on forbidden-composition
+ * (v0.4 §4.2; existing fields' semantics frozen). A rule whose type has no
+ * registry entry is a HARD error (UnknownRuleTypeError → CLI exit 4):
+ * silently skipping would misreport a surface as governed.
+ *
+ * All three v0.3 evaluators are implemented. (The M1 plan deferred
+ * `forbidden-composition` to M2, but the v0.3 shadcn contract carries a
+ * UNIVERSAL forbidden-composition rule and spec §5.4 forbids skipping — a
+ * two-evaluator linter would hard-error on every lint of the real contract.
+ * Deviation flagged for maintainer review in the PR; the evaluator is ~40
+ * lines and fixture F5 activates with it.)
+ */
+import type { Contract, Surface } from "../contract.js";
+import { type Finding } from "./findings.js";
+export declare class UnknownRuleTypeError extends Error {
+    readonly ruleId: string;
+    readonly ruleType: string;
+    constructor(ruleId: string, ruleType: string, detail: string);
+}
+export declare function evaluateRules(surface: Surface, contract: Contract): Finding[];