@texuli/spec 0.0.0-stage → 0.1.0-next.0

package/dist/codegen/kotlin.js

@@ -0,0 +1,328 @@
+import { assertSupported, defName, isRecordType, isStringEnum, pascal, refType, rootName, upperSnake, wrap, } from "./shared.js";
+/**
+ * Deterministic Kotlin projections of the spec, written as committed text
+ * (no Kotlin toolchain here): data classes, closed enums and static
+ * decoders over a small `JsonValue` model, with no library dependency.
+ * Decoders check JSON types, required and unknown fields, enums and
+ * constants; patterns and limits stay with the shared validator.
+ */
+export const KOTLIN_PACKAGE = 'com.texuli.spec';
+const INDENT = '    ';
+function header(source, stamp) {
+    return [
+        `// Generated by @texuli/spec from ${source}. Do not edit: run the spec generator.`,
+        `// Spec ${stamp.specVersion}, digest ${stamp.specDigest}`,
+        '',
+        `package ${KOTLIN_PACKAGE}`,
+        '',
+    ];
+}
+/** A Kotlin string literal (escapes backslash, quote, dollar and controls). */
+export function kotlinString(value) {
+    let out = '';
+    for (const char of value) {
+        const code = char.codePointAt(0) ?? 0;
+        if (char === '\\')
+            out += '\\\\';
+        else if (char === '"')
+            out += '\\"';
+        else if (char === '$')
+            out += '\\$';
+        else if (char === '\n')
+            out += '\\n';
+        else if (code < 0x20)
+            out += `\\u${code.toString(16).padStart(4, '0')}`;
+        else
+            out += char;
+    }
+    return `"${out}"`;
+}
+function kdoc(text, indent) {
+    if (!text)
+        return [];
+    // A line starting with `@` would read as a KDoc tag: quote package names.
+    const quoted = text.replace(/(^|\s)(@[\w/.-]+)/g, '$1`$2`');
+    return [
+        `${indent}/**`,
+        ...wrap(quoted, 96 - indent.length).map((line) => `${indent} * ${line}`),
+        `${indent} */`,
+    ];
+}
+const KEYWORDS = new Set([
+    'as',
+    'class',
+    'fun',
+    'in',
+    'is',
+    'object',
+    'package',
+    'typealias',
+    'val',
+    'var',
+    'when',
+]);
+function field(name) {
+    return KEYWORDS.has(name) ? `\`${name}\`` : name;
+}
+function kotlinType(node, ctx, inlineName) {
+    if (node.$ref !== undefined)
+        return refType(ctx.unit, node.$ref);
+    if (node.const !== undefined)
+        return typeof node.const === 'string' ? 'String' : 'Long';
+    if (isStringEnum(node)) {
+        ctx.inlineEnums.set(inlineName, node);
+        return inlineName;
+    }
+    switch (node.type) {
+        case undefined:
+            return 'JsonValue';
+        case 'string':
+            return 'String';
+        case 'integer':
+            return 'Long';
+        case 'number':
+            return 'Double';
+        case 'boolean':
+            return 'Boolean';
+        case 'array':
+            return `List<${node.items ? kotlinType(node.items, ctx, inlineName) : 'JsonValue'}>`;
+        case 'object':
+            if (node.properties !== undefined) {
+                throw new Error(`${ctx.unit.source}: inline object types are not supported; use $defs`);
+            }
+            return `Map<String, ${node.additionalProperties ? kotlinType(node.additionalProperties, ctx, inlineName) : 'JsonValue'}>`;
+    }
+}
+/** A decode expression for `value` (a `JsonValue`) at path expression `path`. */
+function decodeExpr(node, value, path, ctx, inlineName) {
+    if (node.$ref !== undefined) {
+        const name = refType(ctx.unit, node.$ref);
+        const target = ctx.unit.schema.$defs?.[node.$ref.slice('#/$defs/'.length)];
+        // Records and enums decode through their companion; aliases through a function.
+        return target && (isRecordType(target) || isStringEnum(target))
+            ? `${name}.decode(${value}, ${path})`
+            : `decode${name}(${value}, ${path})`;
+    }
+    if (node.const !== undefined) {
+        return typeof node.const === 'string'
+            ? `${value}.constant(${kotlinString(node.const)}, ${path})`
+            : `${value}.constant(${node.const}L, ${path})`;
+    }
+    if (isStringEnum(node))
+        return `${inlineName}.decode(${value}, ${path})`;
+    switch (node.type) {
+        case undefined:
+            return value;
+        case 'string':
+            return `${value}.str(${path})`;
+        case 'integer':
+            return `${value}.long(${path})`;
+        case 'number':
+            return `${value}.double(${path})`;
+        case 'boolean':
+            return `${value}.bool(${path})`;
+        case 'array': {
+            const item = node.items
+                ? decodeExpr(node.items, 'item', '"$p[$i]"', ctx, inlineName)
+                : 'item';
+            return `(${path}).let { p -> ${value}.arrValues(p).mapIndexed { i, item -> ${item} } }`;
+        }
+        case 'object': {
+            const inner = node.additionalProperties
+                ? decodeExpr(node.additionalProperties, 'item', '"$p.$k"', ctx, inlineName)
+                : 'item';
+            return `(${path}).let { p -> ${value}.obj(p).mapValues { (k, item) -> ${inner} } }`;
+        }
+    }
+}
+function enumClass(name, values, description) {
+    const names = values.map(upperSnake);
+    if (new Set(names).size !== names.length)
+        throw new Error(`${name}: enum entries collide`);
+    return [
+        ...kdoc(description, ''),
+        `enum class ${name}(val wire: String) {`,
+        ...values.map((value, i) => `${INDENT}${names[i]}(${kotlinString(value)}),`),
+        `${INDENT};`,
+        '',
+        `${INDENT}companion object {`,
+        `${INDENT}${INDENT}fun decode(json: JsonValue, path: String): ${name} {`,
+        `${INDENT}${INDENT}${INDENT}val wire = json.str(path)`,
+        `${INDENT}${INDENT}${INDENT}return entries.firstOrNull { it.wire == wire }`,
+        `${INDENT}${INDENT}${INDENT}${INDENT}?: throw SpecDecodeException(path, "unknown value \\"$wire\\"")`,
+        `${INDENT}${INDENT}}`,
+        `${INDENT}}`,
+        '}',
+    ];
+}
+function dataClass(name, node, ctx) {
+    const required = new Set(node.required ?? []);
+    const props = Object.entries(node.properties ?? {});
+    const params = [];
+    const args = [];
+    for (const [prop, child] of props) {
+        const inlineName = `${name}${pascal(prop)}`;
+        const type = kotlinType(child, ctx, inlineName);
+        const path = `"$path.${prop}"`;
+        if (required.has(prop)) {
+            const defaultValue = typeof child.const === 'string'
+                ? ` = ${kotlinString(child.const)}`
+                : child.const !== undefined
+                    ? ` = ${child.const}L`
+                    : '';
+            params.push(`${INDENT}val ${field(prop)}: ${type}${defaultValue},`);
+            args.push(`${INDENT}${INDENT}${INDENT}${INDENT}${field(prop)} = ${decodeExpr(child, `fields.required("${prop}", path)`, path, ctx, inlineName)},`);
+        }
+        else {
+            params.push(`${INDENT}val ${field(prop)}: ${type}? = null,`);
+            args.push(`${INDENT}${INDENT}${INDENT}${INDENT}${field(prop)} = fields["${prop}"]?.let { ${decodeExpr(child, 'it', path, ctx, inlineName)} },`);
+        }
+    }
+    const allowed = props.map(([prop]) => kotlinString(prop)).join(', ');
+    return [
+        ...kdoc(node.description, ''),
+        `data class ${name}(`,
+        ...params,
+        ') {',
+        `${INDENT}companion object {`,
+        `${INDENT}${INDENT}private val FIELDS = setOf(${allowed})`,
+        '',
+        `${INDENT}${INDENT}fun decode(json: JsonValue, path: String = "\\$"): ${name} {`,
+        `${INDENT}${INDENT}${INDENT}val fields = json.obj(path)`,
+        `${INDENT}${INDENT}${INDENT}fields.requireOnly(FIELDS, path)`,
+        `${INDENT}${INDENT}${INDENT}return ${name}(`,
+        ...args,
+        `${INDENT}${INDENT}${INDENT})`,
+        `${INDENT}${INDENT}}`,
+        `${INDENT}}`,
+        '}',
+    ];
+}
+function aliasBlock(name, node, ctx) {
+    const type = kotlinType(node, ctx, `${name}Value`);
+    return [
+        ...kdoc(node.description, ''),
+        `typealias ${name} = ${type}`,
+        '',
+        `fun decode${name}(json: JsonValue, path: String): ${name} =`,
+        `${INDENT}${decodeExpr(node, 'json', 'path', ctx, `${name}Value`)}`,
+    ];
+}
+/** One schema document as a Kotlin file of data classes, enums and decoders. */
+export function schemaToKotlin(unit, stamp) {
+    assertSupported(unit);
+    const ctx = { unit, inlineEnums: new Map() };
+    const blocks = [];
+    const entries = [
+        ...Object.entries(unit.schema.$defs ?? {}).map(([def, node]) => [
+            defName(unit, def),
+            node,
+        ]),
+        [rootName(unit), unit.schema],
+    ];
+    for (const [name, node] of entries) {
+        if (isRecordType(node))
+            blocks.push(dataClass(name, node, ctx));
+        else if (isStringEnum(node))
+            blocks.push(enumClass(name, node.enum, node.description));
+        else
+            blocks.push(aliasBlock(name, node, ctx));
+    }
+    for (const [name, node] of [...ctx.inlineEnums.entries()].sort(([a], [b]) => (a < b ? -1 : 1))) {
+        blocks.push(enumClass(name, node.enum, node.description));
+    }
+    return `${[...header(unit.source, stamp), blocks.map((b) => b.join('\n')).join('\n\n')].join('\n')}\n`;
+}
+/** The JSON model and decode helpers every generated decoder uses. */
+export function kotlinJsonRuntime(stamp) {
+    const lines = [
+        ...header('the spec generator (JSON runtime)', stamp),
+        '/** A parsed JSON value. Hosts convert their parser output into it. */',
+        'sealed interface JsonValue {',
+        `${INDENT}data class Str(val value: String) : JsonValue`,
+        `${INDENT}data class Num(val value: Double) : JsonValue`,
+        `${INDENT}data class Bool(val value: Boolean) : JsonValue`,
+        `${INDENT}data class Arr(val items: List<JsonValue>) : JsonValue`,
+        `${INDENT}data class Obj(val fields: Map<String, JsonValue>) : JsonValue`,
+        `${INDENT}data object Null : JsonValue`,
+        '}',
+        '',
+        '/** A value that does not match the spec, with its JSON path. */',
+        'class SpecDecodeException(val path: String, message: String) :',
+        `${INDENT}IllegalArgumentException("$path: $message")`,
+        '',
+        'internal fun JsonValue.obj(path: String): Map<String, JsonValue> =',
+        `${INDENT}(this as? JsonValue.Obj)?.fields ?: throw SpecDecodeException(path, "expected an object")`,
+        '',
+        'internal fun JsonValue.arrValues(path: String): List<JsonValue> =',
+        `${INDENT}(this as? JsonValue.Arr)?.items ?: throw SpecDecodeException(path, "expected an array")`,
+        '',
+        'internal fun JsonValue.str(path: String): String =',
+        `${INDENT}(this as? JsonValue.Str)?.value ?: throw SpecDecodeException(path, "expected a string")`,
+        '',
+        'internal fun JsonValue.double(path: String): Double {',
+        `${INDENT}val number = (this as? JsonValue.Num)?.value`,
+        `${INDENT}if (number == null || !number.isFinite()) throw SpecDecodeException(path, "expected a number")`,
+        `${INDENT}return number`,
+        '}',
+        '',
+        'internal fun JsonValue.long(path: String): Long {',
+        `${INDENT}val number = double(path)`,
+        `${INDENT}if (number % 1.0 != 0.0) throw SpecDecodeException(path, "expected an integer")`,
+        `${INDENT}return number.toLong()`,
+        '}',
+        '',
+        'internal fun JsonValue.bool(path: String): Boolean =',
+        `${INDENT}(this as? JsonValue.Bool)?.value ?: throw SpecDecodeException(path, "expected a boolean")`,
+        '',
+        'internal fun JsonValue.constant(expected: String, path: String): String {',
+        `${INDENT}val value = str(path)`,
+        `${INDENT}if (value != expected) throw SpecDecodeException(path, "expected \\"$expected\\"")`,
+        `${INDENT}return value`,
+        '}',
+        '',
+        'internal fun JsonValue.constant(expected: Long, path: String): Long {',
+        `${INDENT}val value = long(path)`,
+        `${INDENT}if (value != expected) throw SpecDecodeException(path, "expected $expected")`,
+        `${INDENT}return value`,
+        '}',
+        '',
+        'internal fun Map<String, JsonValue>.required(name: String, path: String): JsonValue =',
+        `${INDENT}this[name] ?: throw SpecDecodeException("$path.$name", "is required")`,
+        '',
+        '/** Unknown fields fail closed. */',
+        'internal fun Map<String, JsonValue>.requireOnly(allowed: Set<String>, path: String) {',
+        `${INDENT}val unknown = keys.firstOrNull { it !in allowed }`,
+        `${INDENT}if (unknown != null) throw SpecDecodeException("$path.$unknown", "is not allowed")`,
+        '}',
+        '',
+    ];
+    return lines.join('\n');
+}
+/** The catalog vocabulary as a Kotlin registry of `SpecComponent` values. */
+export function vocabularyToKotlin(catalog, stamp) {
+    const ids = catalog.components.map((c) => c.id);
+    const optional = (value) => (value === undefined ? 'null' : value);
+    const lines = [
+        ...header('catalog/components.json', stamp),
+        ...enumClass('SpecComponentId', ids, 'Every closed component id, sorted.'),
+        '',
+        '/** The catalog vocabulary: one entry per component id. */',
+        'object SpecVocabulary {',
+        `${INDENT}const val CATALOG_HASH: String = ${kotlinString(catalog.catalogHash)}`,
+        '',
+        `${INDENT}val components: List<SpecComponent> = listOf(`,
+    ];
+    for (const c of catalog.components) {
+        lines.push(`${INDENT}${INDENT}SpecComponent(`, `${INDENT}${INDENT}${INDENT}id = ${kotlinString(c.id)},`, `${INDENT}${INDENT}${INDENT}label = ${kotlinString(c.label)},`, `${INDENT}${INDENT}${INDENT}summary = ${kotlinString(c.summary)},`, `${INDENT}${INDENT}${INDENT}group = ${kotlinString(c.group)},`, `${INDENT}${INDENT}${INDENT}placement = SpecComponentPlacement.${upperSnake(c.placement)},`, `${INDENT}${INDENT}${INDENT}emit = listOf(${c.emit.map((e) => `SpecComponentEmit.${upperSnake(e)}`).join(', ')}),`, `${INDENT}${INDENT}${INDENT}capability = SpecComponentCapability.${upperSnake(c.capability)},`, `${INDENT}${INDENT}${INDENT}props = listOf(`);
+        for (const p of c.props) {
+            const enumValues = p.enumValues
+                ? `listOf(${p.enumValues.map(kotlinString).join(', ')})`
+                : undefined;
+            lines.push(`${INDENT}${INDENT}${INDENT}${INDENT}SpecProp(`, `${INDENT}${INDENT}${INDENT}${INDENT}${INDENT}name = ${kotlinString(p.name)},`, `${INDENT}${INDENT}${INDENT}${INDENT}${INDENT}kind = SpecPropKind.${upperSnake(p.kind)},`, `${INDENT}${INDENT}${INDENT}${INDENT}${INDENT}required = ${optional(p.required === undefined ? undefined : String(p.required))},`, `${INDENT}${INDENT}${INDENT}${INDENT}${INDENT}enumValues = ${optional(enumValues)},`, `${INDENT}${INDENT}${INDENT}${INDENT}${INDENT}extension = ${optional(p.extension ? `SpecPropExtension.${upperSnake(p.extension)}` : undefined)},`, `${INDENT}${INDENT}${INDENT}${INDENT}),`);
+        }
+        lines.push(`${INDENT}${INDENT}${INDENT}),`, `${INDENT}${INDENT}),`);
+    }
+    lines.push(`${INDENT})`, '', `${INDENT}fun component(id: String): SpecComponent? = components.firstOrNull { it.id == id }`, '}', '');
+    return lines.join('\n');
+}

package/dist/codegen/shared.d.ts

@@ -0,0 +1,35 @@
+import { type Schema } from '../dialect.js';
+/** What every generated file is stamped with. */
+export interface Stamp {
+    specVersion: string;
+    /** SHA-256 over the normative files' digests (`manifest.json`). */
+    specDigest: string;
+}
+/** One schema document the generators project. */
+export interface SchemaUnit {
+    /** Path inside the package, e.g. `schemas/blueprint.schema.json`. */
+    source: string;
+    schema: Schema;
+    /** Prefix for `$defs` type names (`Blueprint` + `node` = `BlueprintNode`). */
+    prefix: string;
+}
+/** `meetingRef` → `MeetingRef`, `stacked-bar` → `StackedBar`. */
+export declare function pascal(name: string): string;
+/** `portable-core` → `PORTABLE_CORE`, `setProp` → `SET_PROP`. */
+export declare function upperSnake(value: string): string;
+/** The generated type name of a `$defs` entry. */
+export declare function defName(unit: SchemaUnit, def: string): string;
+/** The generated type name a `$ref` points at. */
+export declare function refType(unit: SchemaUnit, ref: string): string;
+/** The root type name: the schema's `title`. */
+export declare function rootName(unit: SchemaUnit): string;
+/** Refuse a schema outside the dialect: generation never guesses. */
+export declare function assertSupported(unit: SchemaUnit): void;
+/** Whether a schema node is a closed object with declared properties. */
+export declare function isRecordType(node: Schema): boolean;
+/** Whether a schema node is a string enum. */
+export declare function isStringEnum(node: Schema): node is Schema & {
+    enum: readonly string[];
+};
+/** Words of `text` wrapped to `width` columns. */
+export declare function wrap(text: string, width: number): string[];

package/dist/codegen/shared.js

@@ -0,0 +1,69 @@
+import { checkSchemaDocument, refName } from "../dialect.js";
+/** `meetingRef` → `MeetingRef`, `stacked-bar` → `StackedBar`. */
+export function pascal(name) {
+    return name
+        .split(/[-_\s]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('');
+}
+/** `portable-core` → `PORTABLE_CORE`, `setProp` → `SET_PROP`. */
+export function upperSnake(value) {
+    const snake = value
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/[^A-Za-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .toUpperCase();
+    return /^[0-9]/.test(snake) ? `V_${snake}` : snake;
+}
+/** The generated type name of a `$defs` entry. */
+export function defName(unit, def) {
+    return `${unit.prefix}${pascal(def)}`;
+}
+/** The generated type name a `$ref` points at. */
+export function refType(unit, ref) {
+    const name = refName(ref);
+    if (name === undefined)
+        throw new Error(`${unit.source}: unsupported $ref ${ref}`);
+    return defName(unit, name);
+}
+/** The root type name: the schema's `title`. */
+export function rootName(unit) {
+    if (!unit.schema.title || !/^[A-Z][A-Za-z0-9]*$/.test(unit.schema.title)) {
+        throw new Error(`${unit.source}: the root schema needs a PascalCase "title"`);
+    }
+    return unit.schema.title;
+}
+/** Refuse a schema outside the dialect: generation never guesses. */
+export function assertSupported(unit) {
+    const issues = checkSchemaDocument(unit.schema);
+    if (issues.length > 0) {
+        const detail = issues.map((i) => `${i.path} ${i.code}`).join('; ');
+        throw new Error(`${unit.source}: not in the spec dialect: ${detail}`);
+    }
+}
+/** Whether a schema node is a closed object with declared properties. */
+export function isRecordType(node) {
+    return node.type === 'object' && node.properties !== undefined;
+}
+/** Whether a schema node is a string enum. */
+export function isStringEnum(node) {
+    return Array.isArray(node.enum) && node.enum.every((value) => typeof value === 'string');
+}
+/** Words of `text` wrapped to `width` columns. */
+export function wrap(text, width) {
+    const lines = [];
+    let line = '';
+    for (const word of text.split(/\s+/).filter(Boolean)) {
+        if (line && line.length + 1 + word.length > width) {
+            lines.push(line);
+            line = word;
+        }
+        else {
+            line = line ? `${line} ${word}` : word;
+        }
+    }
+    if (line)
+        lines.push(line);
+    return lines;
+}

package/dist/codegen/typescript.d.ts

@@ -0,0 +1,10 @@
+import type { SpecCatalog } from '../catalog.js';
+import { type SchemaUnit, type Stamp } from './shared.js';
+/** One schema document as a TypeScript module of types. */
+export declare function schemaToTypeScript(unit: SchemaUnit, stamp: Stamp): string;
+/**
+ * The catalog vocabulary as TypeScript: the closed component ids and the
+ * portable props of each component. Platform-extension props are left out:
+ * they never come from blueprint data.
+ */
+export declare function vocabularyToTypeScript(catalog: SpecCatalog, stamp: Stamp): string;

package/dist/codegen/typescript.js

@@ -0,0 +1,167 @@
+import { LINE_WIDTH } from "../format.js";
+import { assertSupported, defName, isRecordType, refType, rootName, wrap, } from "./shared.js";
+/**
+ * Deterministic TypeScript projections of the spec: strict, erasable types
+ * (interfaces, unions, `as const` arrays). The output is already in the
+ * repository formatter's style, so it is byte-stable under `pnpm lint`.
+ */
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function header(source, stamp) {
+    return [
+        `// Generated by @texuli/spec from ${source}. Do not edit: run the spec generator.`,
+        `// Spec ${stamp.specVersion}, digest ${stamp.specDigest}`,
+        '',
+    ].join('\n');
+}
+function literal(value) {
+    return typeof value === 'string'
+        ? `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`
+        : String(value);
+}
+function key(name) {
+    return IDENTIFIER.test(name) ? name : literal(name);
+}
+function doc(text, indent) {
+    if (!text)
+        return [];
+    const one = `${indent}/** ${text} */`;
+    if (one.length <= LINE_WIDTH)
+        return [one];
+    return [
+        `${indent}/**`,
+        ...wrap(text, LINE_WIDTH - indent.length - 3).map((line) => `${indent} * ${line}`),
+        `${indent} */`,
+    ];
+}
+/** The union members of a type, when it is a union of literals. */
+function unionMembers(node) {
+    if (node.enum !== undefined)
+        return node.enum.map(literal);
+    return null;
+}
+function typeOf(node, unit) {
+    if (node.$ref !== undefined)
+        return refType(unit, node.$ref);
+    if (node.const !== undefined)
+        return literal(node.const);
+    const members = unionMembers(node);
+    if (members)
+        return members.join(' | ');
+    switch (node.type) {
+        case undefined:
+            return 'unknown';
+        case 'string':
+            return 'string';
+        case 'number':
+        case 'integer':
+            return 'number';
+        case 'boolean':
+            return 'boolean';
+        case 'array': {
+            const item = node.items ? typeOf(node.items, unit) : 'unknown';
+            return item.includes(' | ') ? `readonly (${item})[]` : `readonly ${item}[]`;
+        }
+        case 'object':
+            if (node.properties !== undefined) {
+                throw new Error(`${unit.source}: inline object types are not supported; use $defs`);
+            }
+            return `Readonly<Record<string, ${node.additionalProperties ? typeOf(node.additionalProperties, unit) : 'never'}>>`;
+    }
+}
+/** `head` followed by a type, breaking a long union one member per line. */
+function typed(head, node, unit, indent) {
+    const type = typeOf(node, unit);
+    const one = `${head} ${type};`;
+    const members = unionMembers(node);
+    if (one.length <= LINE_WIDTH || !members)
+        return [one];
+    const last = members.length - 1;
+    return [head, ...members.map((m, i) => `${indent}  | ${m}${i === last ? ';' : ''}`)];
+}
+function declaration(name, node, unit) {
+    const lines = doc(node.description, '');
+    if (isRecordType(node)) {
+        lines.push(`export interface ${name} {`);
+        const required = new Set(node.required ?? []);
+        for (const [prop, child] of Object.entries(node.properties ?? {})) {
+            lines.push(...doc(child.description, '  '));
+            const head = `  ${key(prop)}${required.has(prop) ? '' : '?'}:`;
+            lines.push(...typed(head, child, unit, '  '));
+        }
+        lines.push('}');
+        return lines;
+    }
+    lines.push(...typed(`export type ${name} =`, node, unit, ''));
+    return lines;
+}
+/** One schema document as a TypeScript module of types. */
+export function schemaToTypeScript(unit, stamp) {
+    assertSupported(unit);
+    const blocks = [];
+    for (const [def, node] of Object.entries(unit.schema.$defs ?? {})) {
+        blocks.push(declaration(defName(unit, def), node, unit));
+    }
+    blocks.push(declaration(rootName(unit), unit.schema, unit));
+    return `${header(unit.source, stamp)}\n${blocks.map((b) => b.join('\n')).join('\n\n')}\n`;
+}
+function propType(prop) {
+    switch (prop.kind) {
+        case 'string':
+            return 'string';
+        case 'number':
+            return 'number';
+        case 'boolean':
+            return 'boolean';
+        case 'enum':
+            return (prop.enumValues ?? []).map(literal).join(' | ') || 'string';
+        case 'array':
+            return 'readonly unknown[]';
+        default:
+            return 'Readonly<Record<string, unknown>>';
+    }
+}
+/**
+ * The catalog vocabulary as TypeScript: the closed component ids and the
+ * portable props of each component. Platform-extension props are left out:
+ * they never come from blueprint data.
+ */
+export function vocabularyToTypeScript(catalog, stamp) {
+    const lines = [
+        header('catalog/components.json', stamp),
+        '/** The built catalog this vocabulary was projected from. */',
+        `export const SPEC_CATALOG_HASH = ${literal(catalog.catalogHash)};`,
+        '',
+        '/** Every closed component id, sorted. */',
+        'export const SPEC_COMPONENT_IDS = [',
+        ...catalog.components.map((c) => `  ${literal(c.id)},`),
+        '] as const;',
+        '',
+        'export type SpecComponentId = (typeof SPEC_COMPONENT_IDS)[number];',
+        '',
+        '/** The props a blueprint may set on each component (platform extensions left out). */',
+        'export interface SpecComponentProps {',
+    ];
+    for (const component of catalog.components) {
+        const props = component.props.filter((p) => !p.extension);
+        if (props.length === 0) {
+            lines.push(`  ${key(component.id)}: Record<string, never>;`);
+            continue;
+        }
+        lines.push(`  ${key(component.id)}: {`);
+        for (const prop of props) {
+            const head = `    ${key(prop.name)}${prop.required ? '' : '?'}:`;
+            const type = propType(prop);
+            const one = `${head} ${type};`;
+            if (one.length <= LINE_WIDTH || prop.kind !== 'enum') {
+                lines.push(one);
+            }
+            else {
+                const members = (prop.enumValues ?? []).map(literal);
+                lines.push(head, ...members.map((m, i) => `      | ${m}${i === members.length - 1 ? ';' : ''}`));
+            }
+        }
+        lines.push('  };');
+    }
+    lines.push('}', '');
+    return lines.join('\n');
+}

package/dist/conformance.d.ts

@@ -0,0 +1,20 @@
+/** One conformance failure: drift is a failed gate, never a warning. */
+export interface ConformanceIssue {
+    check: 'dialect' | 'catalog' | 'capabilities' | 'manifest' | 'generated' | 'golden' | 'invalid';
+    path: string;
+    message: string;
+}
+/**
+ * Run the spec's conformance harness (spec/Compose design §7.1 and §7.3)
+ * over the normative files and the committed outputs (`manifest.json`,
+ * `generated-manifest.json` and every generated file):
+ * - every schema stays in the dialect;
+ * - `catalog/components.json` and `catalog/capabilities.json` are valid;
+ * - the manifest digests match the normative files;
+ * - regenerating gives byte-identical TypeScript and Kotlin, with no file
+ *   missing or extra;
+ * - every golden blueprint validates, and every invalid fixture fails with
+ *   exactly its expected diagnostic codes.
+ * Runtime-neutral: the caller reads the files.
+ */
+export declare function checkConformance(normative: Readonly<Record<string, string>>, committed: Readonly<Record<string, string>>): ConformanceIssue[];