@vertekum/schema-builder 0.1.0

package/src/build.ts

@@ -0,0 +1,261 @@
+import type { Node, Ref } from './ast';
+import { DfnError } from './error';
+import type { ResolvedModule } from './resolve';
+
+/**
+ * The expanded name tree a root permits. `open` marks a position whose child SET admits additions
+ * (every member, listed or added, takes the same tail). `denotation` names the terminal
+ * denotation this subtree came from — emission turns multi-use denotations into `$defs`.
+ */
+export interface TreeNode {
+  children: Map<string, TreeNode>;
+  open: boolean;
+  denotation?: string;
+}
+
+const leaf = (): TreeNode => ({ children: new Map(), open: false });
+
+function merge(into: TreeNode, from: TreeNode): void {
+  into.open = into.open || from.open;
+  if (into.denotation !== from.denotation) into.denotation = undefined;
+  for (const [name, child] of from.children) {
+    const existing = into.children.get(name);
+    if (existing) merge(existing, child);
+    else into.children.set(name, child);
+  }
+}
+
+/** Evaluation scope: the module whose productions and imports are in view. */
+interface Scope {
+  module: ResolvedModule;
+  /** Local productions currently expanding, for reference-cycle detection. */
+  expanding: Set<string>;
+}
+
+/** Find what `<name>` / `<@name>` means in this scope. Imported roots go by module name. */
+function target(ref: Ref, scope: Scope): { node: Node; scope: Scope } {
+  if (!ref.imported) {
+    const production = scope.module.module.productions.get(ref.name);
+    if (!production) {
+      throw new DfnError(`unknown production '<${ref.name}>'`, 1, 1);
+    }
+    return { node: production, scope };
+  }
+
+  const hits: Array<{ node: Node; scope: Scope }> = [];
+  for (const imported of scope.module.imports.values()) {
+    const importedScope: Scope = { module: imported, expanding: new Set() };
+    const production = imported.module.productions.get(ref.name);
+    if (production) hits.push({ node: production, scope: importedScope });
+    if (imported.name === ref.name && imported.module.root) {
+      hits.push({ node: imported.module.root, scope: importedScope });
+    }
+  }
+  if (hits.length === 0) {
+    throw new DfnError(`no import provides '<@${ref.name}>'`, 1, 1);
+  }
+  if (hits.length > 1) {
+    throw new DfnError(`'<@${ref.name}>' is ambiguous across imports`, 1, 1);
+  }
+  return hits[0];
+}
+
+/**
+ * Evaluate a node to the forest of names it permits, each with its subtree. `tail` is what hangs
+ * beneath every name this node produces — how `a.<set>.b` threads `b` under each member of the
+ * set, which is also what makes an open set's additions well-defined.
+ */
+function evaluate(node: Node, scope: Scope, tail: () => TreeNode): TreeNode {
+  switch (node.kind) {
+    case 'name': {
+      const forest = leaf();
+      forest.children.set(node.value, tail());
+      return forest;
+    }
+    case 'range': {
+      const forest = leaf();
+      for (let n = node.min; n <= node.max; n += node.step) {
+        forest.children.set(String(n), tail());
+      }
+      return forest;
+    }
+    case 'alt': {
+      const forest = leaf();
+      for (const option of node.options) {
+        merge(forest, evaluate(option, scope, tail));
+      }
+      return forest;
+    }
+    case 'path': {
+      // Steps expand right to left: each step becomes the tail of the one before it. An
+      // optional step (`?`) may be SKIPPED — its tail also attaches directly, so
+      // `<role>.<emphasis>?.<interaction>?` grants the whole slot-collapse lattice.
+      let next = tail;
+      for (let i = node.steps.length - 1; i > 0; i--) {
+        const step = node.steps[i];
+        const after = next;
+        next = step.optional
+          ? () => {
+              const forest = evaluate(step.term, scope, after);
+              merge(forest, after());
+              return forest;
+            }
+          : () => evaluate(step.term, scope, after);
+      }
+      const first = node.steps[0];
+      const forest = evaluate(first.term, scope, next);
+      if (first.optional) merge(forest, next());
+      return forest;
+    }
+    case 'group': {
+      const forest = evaluate(node.node, scope, tail);
+      if (node.open) forest.open = true;
+      return forest;
+    }
+    case 'ref': {
+      const { node: production, scope: refScope } = target(node, scope);
+      if (!node.imported) {
+        if (scope.expanding.has(node.name)) {
+          throw new DfnError(`'<${node.name}>' expands through itself`, 1, 1);
+        }
+        scope.expanding.add(node.name);
+      }
+      const forest = evaluate(production, refScope, tail);
+      if (!node.imported) scope.expanding.delete(node.name);
+      for (const omitted of node.omit) {
+        if (!forest.children.delete(omitted)) {
+          throw new DfnError(
+            `'<${node.name}>' has no member '${omitted}' to omit`,
+            1,
+            1,
+          );
+        }
+      }
+      if (node.pick.length > 0) {
+        for (const picked of node.pick) {
+          if (!forest.children.has(picked)) {
+            throw new DfnError(
+              `'<${node.name}>' has no member '${picked}' to pick`,
+              1,
+              1,
+            );
+          }
+        }
+        const keep = new Set(node.pick);
+        for (const name of [...forest.children.keys()]) {
+          if (!keep.has(name)) forest.children.delete(name);
+        }
+      }
+      if (node.open) forest.open = true;
+      // A modified set is a different set — it never shares the source denotation's $def.
+      if (
+        node.pick.length === 0 &&
+        node.omit.length === 0 &&
+        isNameSet(production) &&
+        isTerminal(tail())
+      ) {
+        forest.denotation = node.name;
+      }
+      return forest;
+    }
+  }
+}
+
+/** A production of names/ranges only — the sets `*` may open and `$defs` may name. */
+function isNameSet(node: Node): boolean {
+  switch (node.kind) {
+    case 'name':
+    case 'range':
+      return true;
+    case 'alt':
+      return node.options.every(isNameSet);
+    default:
+      return false;
+  }
+}
+
+function isTerminal(node: TreeNode): boolean {
+  return node.children.size === 0;
+}
+
+/** Expand a module's root into its name tree. Fragments-only modules cannot build. */
+export function build(resolved: ResolvedModule): TreeNode {
+  const root = resolved.module.root;
+  if (!root) {
+    throw new DfnError(`${resolved.name}.dfn declares no root`, 1, 1);
+  }
+  const scope: Scope = { module: resolved, expanding: new Set() };
+
+  // An aggregate root unions imported roots; the same top-level name arriving from two different
+  // module refs is a collision, not a merge — each module owns its top. `[a | b]` and `a | b`
+  // are the same aggregate, so a root-level group unwraps first.
+  const aggregate = root.kind === 'group' ? root.node : root;
+  if (aggregate.kind === 'alt') {
+    const seen = new Map<string, string>();
+    for (const option of aggregate.options) {
+      if (option.kind !== 'ref' || !option.imported) continue;
+      const forest = evaluate(option, scope, leaf);
+      for (const name of forest.children.keys()) {
+        const owner = seen.get(name);
+        if (owner && owner !== option.name) {
+          throw new DfnError(
+            `top-level '${name}' comes from both '${owner}' and '${option.name}'`,
+            1,
+            1,
+          );
+        }
+        seen.set(name, option.name);
+      }
+    }
+  }
+
+  const tree = evaluate(root, scope, leaf);
+  // Open markers on the root's own set have no parent position to attach to.
+  tree.open = false;
+  return tree;
+}
+
+/**
+ * Enforce that every `*` sat on a name-only set: evaluation flags are structural, so the check is
+ * on the AST — walk refs/groups marked open and verify their expansion source.
+ */
+export function assertOpenSetsAreNameSets(
+  resolved: ResolvedModule,
+  node: Node | undefined = resolved.module.root,
+  scope: Scope = { module: resolved, expanding: new Set() },
+): void {
+  if (!node) return;
+  switch (node.kind) {
+    case 'alt':
+      for (const option of node.options) {
+        assertOpenSetsAreNameSets(resolved, option, scope);
+      }
+      return;
+    case 'path':
+      for (const step of node.steps) {
+        assertOpenSetsAreNameSets(resolved, step.term, scope);
+      }
+      return;
+    case 'group':
+      if (node.open && !isNameSet(node.node)) {
+        throw new DfnError('* opens a set of names, not sub-paths', 1, 1);
+      }
+      assertOpenSetsAreNameSets(resolved, node.node, scope);
+      return;
+    case 'ref': {
+      if (node.open) {
+        const { node: production } = target(node, scope);
+        if (!isNameSet(production)) {
+          throw new DfnError(
+            `'<${node.name}*>' opens a set, but the production is not name-only`,
+            1,
+            1,
+          );
+        }
+      }
+      return;
+    }
+    default:
+      return;
+  }
+}

package/src/cli.ts

@@ -0,0 +1,102 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { basename, dirname, join, relative } from 'node:path';
+import type { CommandDescriptor, CommandResult } from '@vertekum/core';
+import { assertOpenSetsAreNameSets, build } from './build';
+import { emit, isStamped } from './emit';
+import { resolveModule } from './resolve';
+
+/**
+ * `vertekum schema build [module]` (ADR-0030): expand `.dfn` modules and DECLARE the built JSON
+ * Schema files on the result — the runner owns writing, `--dry-run`, and `--json`. With no
+ * module argument, every `.dfn` under the project's `schemas/` directory builds. `--check`
+ * verifies the built files on disk are current instead of writing; stale files are an error
+ * (exit 1), which is the CI staleness gate.
+ */
+
+/** The slice of the CLI's Project this command reads. */
+interface ProjectDir {
+  projectDir: string;
+}
+
+function modulesUnder(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { recursive: true, encoding: 'utf8' })
+    .filter((f) => f.endsWith('.dfn') && !f.includes('node_modules'))
+    .map((f) => join(dir, f));
+}
+
+export function buildModule(modulePath: string): {
+  target: string;
+  content: string;
+} {
+  const resolved = resolveModule(modulePath);
+  assertOpenSetsAreNameSets(resolved);
+  const tree = build(resolved);
+  const moduleFile = basename(modulePath);
+  return {
+    target: join(dirname(modulePath), `${resolved.name}.json`),
+    content: emit(tree, { moduleFile, ...resolved.module.meta }),
+  };
+}
+
+export const schemaBuildCommand: CommandDescriptor = {
+  name: 'schema build',
+  description: 'build .dfn vocabulary modules into JSON Schema files',
+  args: [
+    {
+      name: 'module',
+      required: false,
+      description: "a .dfn file; default: every module under './schemas'",
+    },
+  ],
+  options: [
+    {
+      flag: '--check',
+      description: 'verify built files are current; write nothing',
+    },
+  ],
+  run(ctx): CommandResult {
+    const { projectDir } = ctx.project as ProjectDir;
+    const modules = ctx.args.module
+      ? [join(projectDir, ctx.args.module)]
+      : modulesUnder(join(projectDir, 'schemas'));
+    if (modules.length === 0) {
+      return { summary: 'no .dfn modules found', files: [] };
+    }
+
+    const files: Array<{ path: string; content: string }> = [];
+    const skipped: string[] = [];
+    const stale: string[] = [];
+
+    for (const modulePath of modules) {
+      const { target, content } = buildModule(modulePath);
+      const existing = existsSync(target)
+        ? readFileSync(target, 'utf8')
+        : undefined;
+      const targetRelative = relative(projectDir, target);
+
+      if (ctx.options.check === true) {
+        if (existing !== content) stale.push(targetRelative);
+        continue;
+      }
+      if (existing !== undefined && !isStamped(existing)) {
+        skipped.push(targetRelative);
+        continue;
+      }
+      files.push({ path: targetRelative, content });
+    }
+
+    if (stale.length > 0) {
+      throw new Error(
+        `stale built schemas: ${stale.join(', ')} — run \`vertekum schema build\``,
+      );
+    }
+    const notes = [
+      ctx.options.check === true
+        ? `${modules.length} module(s) current`
+        : `built ${files.length} module(s)`,
+      ...skipped.map((f) => `${f} has local edits (no stamp) — left as is`),
+    ];
+    return { summary: notes.join('\n'), files, data: { skipped } };
+  },
+};

package/src/emit.ts

@@ -0,0 +1,115 @@
+import type { TreeNode } from './build';
+
+/**
+ * Emit a name tree as the names-and-order JSON Schema shape shipped schemas use: every position
+ * `type: object`, declared children under `properties`, `$`-members passing via
+ * `patternProperties`, and closure via `unevaluatedProperties: false` — except open positions,
+ * which route additions to the members' shared tail through `additionalProperties` instead.
+ * Terminal denotation refs used more than once become `$defs`, matching the hand-written style.
+ */
+
+export const STAMP_PREFIX = 'built by @vertekum/schema-builder from';
+
+export function stamp(moduleFile: string): string {
+  return `${STAMP_PREFIX} ${moduleFile} — do not hand-edit; remove this comment to take ownership`;
+}
+
+type Schema = Record<string, unknown>;
+
+function countDenotations(node: TreeNode, counts: Map<string, number>): void {
+  if (node.denotation) {
+    counts.set(node.denotation, (counts.get(node.denotation) ?? 0) + 1);
+  }
+  for (const child of node.children.values()) countDenotations(child, counts);
+}
+
+function position(node: TreeNode, defs: Set<string>): Schema {
+  if (node.denotation && defs.has(node.denotation)) {
+    return { $ref: `#/$defs/${node.denotation}` };
+  }
+  const properties: Schema = {};
+  for (const [name, child] of node.children) {
+    properties[name] = position(child, defs);
+  }
+  const schema: Schema = {
+    type: 'object',
+    properties,
+    patternProperties: { '^\\$': true },
+  };
+  if (node.open) {
+    // Additions join the set: they take the same tail every listed member has. All members share
+    // it by construction (`*` is restricted to name-only sets), so the first child is the shape.
+    const first = node.children.values().next().value as TreeNode | undefined;
+    schema.additionalProperties = first
+      ? position(first, defs)
+      : { type: 'object', patternProperties: { '^\\$': true } };
+  } else {
+    schema.unevaluatedProperties = false;
+  }
+  return schema;
+}
+
+/** The $def body for a denotation node: its own position schema, never self-referential. */
+function definition(node: TreeNode, defs: Set<string>): Schema {
+  const bare: TreeNode = { ...node, denotation: undefined };
+  return position(bare, defs);
+}
+
+export interface EmitOptions {
+  /** The module filename for the provenance stamp, e.g. `house.dfn`. */
+  moduleFile: string;
+  /** From the module's pragmas: `id "…"`, `title "…"`, `description "…"`, `scope "…"`. */
+  id?: string;
+  title?: string;
+  description?: string;
+  scope?: 'document' | 'branch';
+}
+
+export function emit(tree: TreeNode, options: EmitOptions): string {
+  const counts = new Map<string, number>();
+  countDenotations(tree, counts);
+  const shared = new Set(
+    [...counts.entries()].filter(([, n]) => n >= 2).map(([name]) => name),
+  );
+
+  const document: Schema = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+  };
+  if (options.id) document.$id = options.id;
+  document.$comment = stamp(options.moduleFile);
+  if (options.title) document.title = options.title;
+  if (options.description) document.description = options.description;
+
+  if (shared.size > 0) {
+    const defs: Schema = {};
+    const collect = (node: TreeNode): void => {
+      if (
+        node.denotation &&
+        shared.has(node.denotation) &&
+        !(node.denotation in defs)
+      ) {
+        defs[node.denotation] = definition(node, shared);
+      }
+      for (const child of node.children.values()) collect(child);
+    };
+    collect(tree);
+    document.$defs = defs;
+  }
+
+  const root = position(tree, shared);
+  document.type = root.type;
+  document.properties = root.properties;
+  document.patternProperties = root.patternProperties;
+  // `scope "branch"`: govern only the named top-level branches — the document root stays
+  // unsealed so sibling vocabularies can bind over the same files. Default seals.
+  if (options.scope !== 'branch') {
+    document.unevaluatedProperties = root.unevaluatedProperties;
+  }
+
+  return `${JSON.stringify(document, null, 2)}\n`;
+}
+
+/** True when `content` carries the generated stamp — the file is the builder's to overwrite. */
+export function isStamped(content: string): boolean {
+  return content.includes(STAMP_PREFIX);
+}

package/src/error.ts

@@ -0,0 +1,12 @@
+/** A syntax or semantic error in a `.dfn` module, positioned for the author. */
+export class DfnError extends Error {
+  readonly line: number;
+  readonly column: number;
+
+  constructor(message: string, line: number, column: number) {
+    super(`${line}:${column} ${message}`);
+    this.name = 'DfnError';
+    this.line = line;
+    this.column = column;
+  }
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+import { defineExtension, type ExtensionManifest } from '@vertekum/core';
+import { activate } from './api';
+
+export const schemaBuilderManifest = {
+  id: 'vtk.schema-builder',
+  name: 'Schema Builder',
+  description:
+    "Builds `.dfn` vocabulary modules — a grammar for declaring which token names may exist, and in what order — into the JSON Schema files the `schemas` config binds. Contributes the 'schema build' command. A non-view extension: no route, no ribbon entry.",
+  activation: ['onStartup'],
+} satisfies ExtensionManifest;
+
+/**
+ * Grammar in, schemas out: the vocabulary is DECLARED in `.dfn` modules and BUILT into ordinary
+ * schema files, which stay the only thing binding and validation ever see.
+ */
+export const schemaBuilderExtension = defineExtension<
+  typeof schemaBuilderManifest
+>({
+  manifest: schemaBuilderManifest,
+  activate,
+});