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

package/dist/conformance.js

@@ -0,0 +1,124 @@
+import { buildSpec } from "./build.js";
+import { CAPABILITIES } from "./catalog.js";
+import { checkSchemaDocument, isRecord, validateInstance } from "./dialect.js";
+import { validateBlueprint } from "./validate.js";
+/**
+ * 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 function checkConformance(normative, committed) {
+    const issues = [];
+    const json = (path) => JSON.parse(normative[path] ?? 'null');
+    const schemas = {};
+    for (const path of Object.keys(normative).filter((p) => p.startsWith('schemas/'))) {
+        const schema = json(path);
+        schemas[path] = schema;
+        for (const issue of checkSchemaDocument(schema)) {
+            issues.push({
+                check: 'dialect',
+                path,
+                message: `${issue.path} ${issue.code}: ${issue.message}`,
+            });
+        }
+    }
+    const catalogSchema = schemas['schemas/catalog.schema.json'];
+    const blueprintSchema = schemas['schemas/blueprint.schema.json'];
+    const catalog = json('catalog/components.json');
+    if (catalogSchema) {
+        for (const issue of validateInstance(catalogSchema, catalog)) {
+            issues.push({
+                check: 'catalog',
+                path: 'catalog/components.json',
+                message: `${issue.path} ${issue.code}`,
+            });
+        }
+    }
+    const ids = new Set((catalog?.components ?? []).map((c) => c.id));
+    const capabilities = json('catalog/capabilities.json');
+    if (!isRecord(capabilities)) {
+        issues.push({
+            check: 'capabilities',
+            path: 'catalog/capabilities.json',
+            message: 'must be an object',
+        });
+    }
+    else {
+        for (const [id, value] of Object.entries(capabilities)) {
+            if (!ids.has(id) || !CAPABILITIES.includes(value)) {
+                issues.push({
+                    check: 'capabilities',
+                    path: 'catalog/capabilities.json',
+                    message: `${id}: an audited capability needs a catalog id and a known tier`,
+                });
+            }
+        }
+    }
+    let build;
+    try {
+        build = buildSpec(normative);
+    }
+    catch (cause) {
+        issues.push({ check: 'generated', path: '', message: cause.message });
+    }
+    if (build) {
+        if (committed['manifest.json'] !== build.manifest) {
+            issues.push({
+                check: 'manifest',
+                path: 'manifest.json',
+                message: 'digests do not match the normative files',
+            });
+        }
+        if (committed['generated-manifest.json'] !== build.generatedManifest) {
+            issues.push({
+                check: 'generated',
+                path: 'generated-manifest.json',
+                message: 'does not match a fresh generation',
+            });
+        }
+        const expected = new Set(Object.keys(build.generated));
+        for (const [path, text] of Object.entries(build.generated)) {
+            if (committed[path] !== text) {
+                issues.push({
+                    check: 'generated',
+                    path,
+                    message: committed[path] === undefined ? 'missing' : 'differs from a fresh generation',
+                });
+            }
+        }
+        for (const path of Object.keys(committed)) {
+            if (path.startsWith('generated/') && !expected.has(path)) {
+                issues.push({ check: 'generated', path, message: 'no generator produces this file' });
+            }
+        }
+    }
+    if (blueprintSchema) {
+        const documents = { blueprintSchema, catalog };
+        for (const path of Object.keys(normative).filter((p) => p.startsWith('fixtures/golden/'))) {
+            const result = validateBlueprint(json(path), documents);
+            for (const d of result.diagnostics) {
+                issues.push({ check: 'golden', path, message: `${d.path} ${d.code}: ${d.message}` });
+            }
+        }
+        for (const path of Object.keys(normative).filter((p) => p.startsWith('fixtures/invalid/'))) {
+            const fixture = json(path);
+            const got = validateBlueprint(fixture.blueprint, documents, fixture.options).diagnostics.map((d) => d.code);
+            if (got.join(',') !== fixture.expect.join(',')) {
+                issues.push({
+                    check: 'invalid',
+                    path,
+                    message: `expected [${fixture.expect.join(', ')}], got [${got.join(', ')}]`,
+                });
+            }
+        }
+    }
+    return issues;
+}

package/dist/dialect.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The pinned, closed schema dialect: a small subset of JSON Schema 2020-12
+ * that both the TypeScript and Kotlin generators can project exactly. A
+ * schema that uses anything else fails `checkSchemaDocument`, and code
+ * generation refuses it (spec/Compose design §2.3: unsupported constructs
+ * fail generation). Schemas are read as data; nothing is evaluated.
+ */
+export declare const DIALECT_URI = "https://json-schema.org/draft/2020-12/schema";
+/** Every keyword the dialect understands. */
+export declare const DIALECT_KEYWORDS: readonly ["$schema", "$id", "$comment", "$defs", "$ref", "title", "description", "type", "properties", "required", "additionalProperties", "items", "enum", "const", "minLength", "maxLength", "pattern", "minimum", "maximum", "minItems", "maxItems"];
+export declare const DIALECT_TYPES: readonly ["object", "array", "string", "number", "integer", "boolean"];
+export type DialectType = (typeof DIALECT_TYPES)[number];
+/** A schema node in the dialect. `{}` (no keywords) accepts any JSON value. */
+export interface Schema {
+    $schema?: string;
+    $id?: string;
+    $comment?: string;
+    $defs?: Readonly<Record<string, Schema>>;
+    $ref?: string;
+    title?: string;
+    description?: string;
+    type?: DialectType;
+    properties?: Readonly<Record<string, Schema>>;
+    required?: readonly string[];
+    /** `false` for a closed object, or a schema for map values. */
+    additionalProperties?: false | Schema;
+    items?: Schema;
+    enum?: readonly (string | number | boolean)[];
+    const?: string | number | boolean;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minimum?: number;
+    maximum?: number;
+    minItems?: number;
+    maxItems?: number;
+}
+export interface SchemaIssue {
+    code: string;
+    path: string;
+    message: string;
+}
+/** The `$defs` name a `$ref` points at. */
+export declare function refName(ref: string): string | undefined;
+/**
+ * Check that a schema document stays inside the dialect: known keywords only,
+ * local `$ref`s that resolve, a single `type`, and every object either closed
+ * (`additionalProperties: false`) or an explicit map. Fails closed.
+ */
+export declare function checkSchemaDocument(document: unknown): SchemaIssue[];
+/**
+ * Validate a JSON value against a dialect schema. `root` resolves `$ref`s
+ * (defaults to `schema`). Returns every issue, with JSON paths from `$`.
+ */
+export declare function validateInstance(schema: Schema, value: unknown, root?: Schema): SchemaIssue[];
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/dialect.js

@@ -0,0 +1,264 @@
+/**
+ * The pinned, closed schema dialect: a small subset of JSON Schema 2020-12
+ * that both the TypeScript and Kotlin generators can project exactly. A
+ * schema that uses anything else fails `checkSchemaDocument`, and code
+ * generation refuses it (spec/Compose design §2.3: unsupported constructs
+ * fail generation). Schemas are read as data; nothing is evaluated.
+ */
+export const DIALECT_URI = 'https://json-schema.org/draft/2020-12/schema';
+/** Every keyword the dialect understands. */
+export const DIALECT_KEYWORDS = [
+    '$schema',
+    '$id',
+    '$comment',
+    '$defs',
+    '$ref',
+    'title',
+    'description',
+    'type',
+    'properties',
+    'required',
+    'additionalProperties',
+    'items',
+    'enum',
+    'const',
+    'minLength',
+    'maxLength',
+    'pattern',
+    'minimum',
+    'maximum',
+    'minItems',
+    'maxItems',
+];
+export const DIALECT_TYPES = ['object', 'array', 'string', 'number', 'integer', 'boolean'];
+const REF = /^#\/\$defs\/([A-Za-z][A-Za-z0-9]*)$/;
+const MAX_DEPTH = 64;
+/** The `$defs` name a `$ref` points at. */
+export function refName(ref) {
+    return REF.exec(ref)?.[1];
+}
+/**
+ * Check that a schema document stays inside the dialect: known keywords only,
+ * local `$ref`s that resolve, a single `type`, and every object either closed
+ * (`additionalProperties: false`) or an explicit map. Fails closed.
+ */
+export function checkSchemaDocument(document) {
+    const issues = [];
+    if (!isRecord(document)) {
+        return [{ code: 'not-a-schema', path: '$', message: 'A schema must be an object.' }];
+    }
+    if (document.$schema !== DIALECT_URI) {
+        issues.push({
+            code: 'dialect',
+            path: '$.$schema',
+            message: `"$schema" must be ${DIALECT_URI}.`,
+        });
+    }
+    const defs = isRecord(document.$defs) ? document.$defs : {};
+    const visit = (node, path, depth) => {
+        if (depth > MAX_DEPTH) {
+            issues.push({ code: 'too-deep', path, message: 'The schema nests too deeply.' });
+            return;
+        }
+        if (!isRecord(node)) {
+            issues.push({ code: 'not-a-schema', path, message: 'A schema node must be an object.' });
+            return;
+        }
+        for (const key of Object.keys(node)) {
+            if (!DIALECT_KEYWORDS.includes(key)) {
+                issues.push({
+                    code: 'unsupported-keyword',
+                    path: `${path}.${key}`,
+                    message: `"${key}" is not in the dialect.`,
+                });
+            }
+        }
+        if (node.$ref !== undefined) {
+            const name = typeof node.$ref === 'string' ? refName(node.$ref) : undefined;
+            if (name === undefined || !Object.hasOwn(defs, name)) {
+                issues.push({
+                    code: 'bad-ref',
+                    path: `${path}.$ref`,
+                    message: 'A $ref must name a local $defs entry.',
+                });
+            }
+        }
+        if (node.type !== undefined && !DIALECT_TYPES.includes(node.type)) {
+            issues.push({
+                code: 'bad-type',
+                path: `${path}.type`,
+                message: '"type" must be one dialect type.',
+            });
+        }
+        if (node.type === 'object') {
+            if (node.additionalProperties === undefined || node.additionalProperties === true) {
+                issues.push({
+                    code: 'open-object',
+                    path,
+                    message: 'Objects must set "additionalProperties": false or a map schema.',
+                });
+            }
+            if (Array.isArray(node.required) && isRecord(node.properties)) {
+                for (const name of node.required) {
+                    if (typeof name !== 'string' || !Object.hasOwn(node.properties, name)) {
+                        issues.push({
+                            code: 'bad-required',
+                            path: `${path}.required`,
+                            message: `Required "${String(name)}" is not a declared property.`,
+                        });
+                    }
+                }
+            }
+        }
+        if (node.enum !== undefined) {
+            const values = node.enum;
+            const valid = Array.isArray(values) &&
+                values.length > 0 &&
+                values.every((v) => typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean');
+            if (!valid) {
+                issues.push({
+                    code: 'bad-enum',
+                    path: `${path}.enum`,
+                    message: '"enum" must list scalars.',
+                });
+            }
+        }
+        if (isRecord(node.properties)) {
+            for (const [name, child] of Object.entries(node.properties)) {
+                visit(child, `${path}.properties.${name}`, depth + 1);
+            }
+        }
+        if (isRecord(node.additionalProperties)) {
+            visit(node.additionalProperties, `${path}.additionalProperties`, depth + 1);
+        }
+        if (node.items !== undefined)
+            visit(node.items, `${path}.items`, depth + 1);
+        if (isRecord(node.$defs)) {
+            for (const [name, child] of Object.entries(node.$defs)) {
+                if (!/^[A-Za-z][A-Za-z0-9]*$/.test(name)) {
+                    issues.push({
+                        code: 'bad-def-name',
+                        path: `${path}.$defs.${name}`,
+                        message: 'Def names are alphanumeric.',
+                    });
+                }
+                visit(child, `${path}.$defs.${name}`, depth + 1);
+            }
+        }
+    };
+    visit(document, '$', 0);
+    return issues;
+}
+/**
+ * Validate a JSON value against a dialect schema. `root` resolves `$ref`s
+ * (defaults to `schema`). Returns every issue, with JSON paths from `$`.
+ */
+export function validateInstance(schema, value, root = schema) {
+    const issues = [];
+    const fail = (code, path, message) => {
+        issues.push({ code, path, message });
+    };
+    const visit = (node, current, path, depth) => {
+        if (depth > MAX_DEPTH) {
+            fail('too-deep', path, 'The value nests too deeply.');
+            return;
+        }
+        if (node.$ref !== undefined) {
+            const name = refName(node.$ref);
+            const target = name === undefined ? undefined : root.$defs?.[name];
+            if (target === undefined)
+                fail('bad-ref', path, `Unresolved ${node.$ref}.`);
+            else
+                visit(target, current, path, depth + 1);
+            return;
+        }
+        if (node.const !== undefined && current !== node.const) {
+            fail('const', path, `Must be ${JSON.stringify(node.const)}.`);
+            return;
+        }
+        if (node.enum !== undefined && !node.enum.includes(current)) {
+            fail('enum', path, `Must be one of ${node.enum.map((v) => JSON.stringify(v)).join(', ')}.`);
+            return;
+        }
+        switch (node.type) {
+            case undefined:
+                return;
+            case 'string':
+                if (typeof current !== 'string') {
+                    fail('type', path, 'Must be a string.');
+                    return;
+                }
+                if (node.minLength !== undefined && [...current].length < node.minLength)
+                    fail('min-length', path, `At least ${node.minLength} characters.`);
+                if (node.maxLength !== undefined && [...current].length > node.maxLength)
+                    fail('max-length', path, `At most ${node.maxLength} characters.`);
+                if (node.pattern !== undefined && !new RegExp(node.pattern, 'u').test(current))
+                    fail('pattern', path, `Must match ${node.pattern}.`);
+                return;
+            case 'number':
+            case 'integer':
+                if (typeof current !== 'number' || !Number.isFinite(current)) {
+                    fail('type', path, 'Must be a finite number.');
+                    return;
+                }
+                if (node.type === 'integer' && !Number.isInteger(current)) {
+                    fail('type', path, 'Must be an integer.');
+                    return;
+                }
+                if (node.minimum !== undefined && current < node.minimum)
+                    fail('minimum', path, `At least ${node.minimum}.`);
+                if (node.maximum !== undefined && current > node.maximum)
+                    fail('maximum', path, `At most ${node.maximum}.`);
+                return;
+            case 'boolean':
+                if (typeof current !== 'boolean')
+                    fail('type', path, 'Must be a boolean.');
+                return;
+            case 'array':
+                if (!Array.isArray(current)) {
+                    fail('type', path, 'Must be an array.');
+                    return;
+                }
+                if (node.minItems !== undefined && current.length < node.minItems)
+                    fail('min-items', path, `At least ${node.minItems} items.`);
+                if (node.maxItems !== undefined && current.length > node.maxItems) {
+                    fail('max-items', path, `At most ${node.maxItems} items.`);
+                    return;
+                }
+                if (node.items) {
+                    const items = node.items;
+                    current.forEach((item, index) => {
+                        visit(items, item, `${path}[${index}]`, depth + 1);
+                    });
+                }
+                return;
+            case 'object': {
+                if (!isRecord(current)) {
+                    fail('type', path, 'Must be an object.');
+                    return;
+                }
+                const properties = node.properties ?? {};
+                for (const name of node.required ?? []) {
+                    if (!Object.hasOwn(current, name))
+                        fail('required', `${path}.${name}`, `"${name}" is required.`);
+                }
+                for (const [key, child] of Object.entries(current)) {
+                    const here = `${path}.${key}`;
+                    const declared = Object.hasOwn(properties, key) ? properties[key] : undefined;
+                    if (declared)
+                        visit(declared, child, here, depth + 1);
+                    else if (node.additionalProperties)
+                        visit(node.additionalProperties, child, here, depth + 1);
+                    else
+                        fail('additional-property', here, `"${key}" is not allowed.`);
+                }
+                return;
+            }
+        }
+    };
+    visit(schema, value, '$', 0);
+    return issues;
+}
+export function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/format.d.ts

@@ -0,0 +1,9 @@
+/** The repository formatter's line width (biome.json). */
+export declare const LINE_WIDTH = 100;
+/**
+ * Committed JSON in the repository formatter's style, so generated files
+ * stay byte-stable under `pnpm lint`: keys sorted, two-space indent, objects
+ * always expanded, and an array of scalars kept on one line when it fits the
+ * line width. Ends with a newline.
+ */
+export declare function formatJson(value: unknown): string;

package/dist/format.js

@@ -0,0 +1,48 @@
+import { canonicalJson } from "./canonical.js";
+/** The repository formatter's line width (biome.json). */
+export const LINE_WIDTH = 100;
+/**
+ * Committed JSON in the repository formatter's style, so generated files
+ * stay byte-stable under `pnpm lint`: keys sorted, two-space indent, objects
+ * always expanded, and an array of scalars kept on one line when it fits the
+ * line width. Ends with a newline.
+ */
+export function formatJson(value) {
+    // Round-trip through canonical JSON: sorted keys, undefined dropped.
+    return `${print(JSON.parse(canonicalJson(value)), 0, '', 0)}\n`;
+}
+function isScalar(value) {
+    return value === null || typeof value !== 'object';
+}
+/**
+ * `prefix` is what precedes the value on its line (indent and key) and
+ * `suffix` the length of what follows it (a comma, or nothing for the last
+ * entry), for the width check.
+ */
+function print(value, indent, prefix, suffix) {
+    if (isScalar(value))
+        return JSON.stringify(value);
+    const pad = '  '.repeat(indent + 1);
+    const close = '  '.repeat(indent);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return '[]';
+        if (value.every(isScalar)) {
+            const inline = `[${value.map((item) => JSON.stringify(item)).join(', ')}]`;
+            if (prefix.length + inline.length + suffix <= LINE_WIDTH)
+                return inline;
+        }
+        const last = value.length - 1;
+        const items = value.map((item, index) => `${pad}${print(item, indent + 1, pad, index < last ? 1 : 0)}`);
+        return `[\n${items.join(',\n')}\n${close}]`;
+    }
+    const entries = Object.entries(value);
+    if (entries.length === 0)
+        return '{}';
+    const last = entries.length - 1;
+    const lines = entries.map(([key, child], index) => {
+        const head = `${pad}${JSON.stringify(key)}: `;
+        return `${head}${print(child, indent + 1, head, index < last ? 1 : 0)}`;
+    });
+    return `{\n${lines.join(',\n')}\n${close}}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@texuli/spec` — the schema-first blueprint contract (spec/Compose design
+ * B1), runtime half: the generated types and vocabulary, the dialect
+ * validator, the target-neutral blueprint validator and deterministic
+ * hashing. Build-time generation and the conformance harness live in
+ * `@texuli/spec/codegen`. Framework-free: no DOM, no Svelte and no Node APIs.
+ */
+export type * from '../generated/typescript/blueprint.js';
+export type * from '../generated/typescript/catalog-schema.js';
+export type * from '../generated/typescript/diagnostics.js';
+export type * from '../generated/typescript/manifest.js';
+export { SPEC_CATALOG_HASH, SPEC_COMPONENT_IDS, type SpecComponentId, type SpecComponentProps, } from '../generated/typescript/vocabulary.js';
+export { canonicalJson, sha256 } from './canonical.js';
+export { CAPABILITIES, type Capability, type SpecPropKind, WEB_ONLY_KINDS, WEB_ONLY_PROP_NAMES, } from './catalog.js';
+export { checkSchemaDocument, DIALECT_KEYWORDS, DIALECT_TYPES, DIALECT_URI, type DialectType, type Schema, type SchemaIssue, validateInstance, } from './dialect.js';
+export { type SpecDocuments, validateBlueprint, validateTree, } from './validate.js';
+export { SPEC_VERSION } from './version.js';

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * `@texuli/spec` — the schema-first blueprint contract (spec/Compose design
+ * B1), runtime half: the generated types and vocabulary, the dialect
+ * validator, the target-neutral blueprint validator and deterministic
+ * hashing. Build-time generation and the conformance harness live in
+ * `@texuli/spec/codegen`. Framework-free: no DOM, no Svelte and no Node APIs.
+ */
+export { SPEC_CATALOG_HASH, SPEC_COMPONENT_IDS, } from "../generated/typescript/vocabulary.js";
+export { canonicalJson, sha256 } from "./canonical.js";
+export { CAPABILITIES, WEB_ONLY_KINDS, WEB_ONLY_PROP_NAMES, } from "./catalog.js";
+export { checkSchemaDocument, DIALECT_KEYWORDS, DIALECT_TYPES, DIALECT_URI, validateInstance, } from "./dialect.js";
+export { validateBlueprint, validateTree, } from "./validate.js";
+export { SPEC_VERSION } from "./version.js";

package/dist/validate.d.ts

@@ -0,0 +1,25 @@
+import type { SpecDiagnostic, SpecDiagnosticCode, SpecValidation } from '../generated/typescript/diagnostics.js';
+import type { SpecCatalog } from './catalog.js';
+import { type Schema } from './dialect.js';
+export type { SpecDiagnostic, SpecDiagnosticCode, SpecValidation };
+export interface SpecDocuments {
+    blueprintSchema: Schema;
+    catalog: SpecCatalog;
+}
+/**
+ * Validate a blueprint envelope against the spec alone: the envelope schema,
+ * then every node against the catalog vocabulary (closed ids, closed prop
+ * names, prop kinds and enum values, required props, no platform-extension
+ * props from data) and the declared profile. With `catalogHash`, an envelope
+ * bound to another catalog is refused. This is the shared, target-neutral
+ * contract; URL policy, limits, grammar and rendering stay in the runtime
+ * validators (`@texuli/catalog/validate`).
+ */
+export declare function validateBlueprint(input: unknown, documents: SpecDocuments, options?: {
+    catalogHash?: string;
+}): SpecValidation;
+/** Check one catalog tree against the vocabulary. See {@link validateBlueprint}. */
+export declare function validateTree(tree: unknown, catalog: SpecCatalog, options?: {
+    portable?: boolean;
+    path?: string;
+}): SpecDiagnostic[];