@vertekum/schema-builder 0.1.0

package/src/parser.ts

@@ -0,0 +1,238 @@
+import type { Alt, Module, ModuleMeta, Node, Path, Step } from './ast';
+import { DfnError } from './error';
+import { type Token, tokenize } from './tokenizer';
+
+/**
+ * Recursive-descent parser for `.dfn` modules. Statements are line-oriented: `use "<spec>"` or
+ * `name = expression`. Precedence: `.` binds tighter than `|`; `?` is postfix on the preceding
+ * step; `*` sits before a closing `>` or `]` and marks the set open. `root` is the reserved
+ * production `build` materializes — stored apart so fragments-only modules stay valid.
+ */
+export function parse(source: string): Module {
+  return new Parser(tokenize(source)).module();
+}
+
+class Parser {
+  private readonly tokens: Token[];
+  private index = 0;
+
+  constructor(tokens: Token[]) {
+    this.tokens = tokens;
+  }
+
+  private peek(): Token {
+    return this.tokens[this.index];
+  }
+
+  private at(offset: number): Token | undefined {
+    return this.tokens[this.index + offset];
+  }
+
+  private next(): Token {
+    return this.tokens[this.index++];
+  }
+
+  private expect(kind: Token['kind'], what: string): Token {
+    const token = this.next();
+    if (token.kind !== kind) {
+      throw new DfnError(
+        `expected ${what}, got '${token.value || token.kind}'`,
+        token.line,
+        token.column,
+      );
+    }
+    return token;
+  }
+
+  private skipNewlines(): void {
+    while (this.peek().kind === 'newline') this.next();
+  }
+
+  module(): Module {
+    const uses: string[] = [];
+    const productions = new Map<string, Node>();
+    const meta: ModuleMeta = {};
+    let root: Node | undefined;
+
+    this.skipNewlines();
+    while (this.peek().kind !== 'eof') {
+      const token = this.peek();
+      if (token.kind === 'use') {
+        this.next();
+        uses.push(this.expect('string', 'a quoted specifier').value);
+      } else if (token.kind === 'ident' && this.at(1)?.kind === 'string') {
+        // `<ident> "<string>"` (no `=`) is a PRAGMA — document metadata, not a production, so
+        // nothing is reserved: `title = a | b` still declares a production named title.
+        const name = this.next();
+        const value = this.next().value;
+        if (
+          name.value !== 'id' &&
+          name.value !== 'title' &&
+          name.value !== 'description' &&
+          name.value !== 'scope'
+        ) {
+          throw new DfnError(
+            `unknown pragma '${name.value}' — id, title, description, and scope exist`,
+            name.line,
+            name.column,
+          );
+        }
+        const key = name.value as keyof ModuleMeta;
+        if (meta[key] !== undefined) {
+          throw new DfnError(
+            `duplicate pragma '${name.value}'`,
+            name.line,
+            name.column,
+          );
+        }
+        if (key === 'scope') {
+          if (value !== 'document' && value !== 'branch') {
+            throw new DfnError(
+              `scope is "document" or "branch", not "${value}"`,
+              name.line,
+              name.column,
+            );
+          }
+          meta.scope = value;
+        } else {
+          meta[key] = value;
+        }
+      } else if (token.kind === 'ident') {
+        const name = this.next();
+        this.expect('equals', "'='");
+        const expression = this.alternation();
+        if (name.value === 'root') {
+          if (root) {
+            throw new DfnError(
+              'a module declares one root',
+              name.line,
+              name.column,
+            );
+          }
+          root = expression;
+        } else {
+          if (productions.has(name.value)) {
+            throw new DfnError(
+              `duplicate production '${name.value}'`,
+              name.line,
+              name.column,
+            );
+          }
+          productions.set(name.value, expression);
+        }
+      } else {
+        throw new DfnError(
+          `expected a statement, got '${token.value || token.kind}'`,
+          token.line,
+          token.column,
+        );
+      }
+      if (this.peek().kind !== 'eof') this.expect('newline', 'end of line');
+      this.skipNewlines();
+    }
+
+    return { uses, productions, root, meta };
+  }
+
+  /** `a | b | c` — a single option collapses to itself. */
+  private alternation(): Node {
+    const options: Node[] = [this.path()];
+    while (this.peek().kind === 'pipe') {
+      this.next();
+      options.push(this.path());
+    }
+    if (options.length === 1) return options[0];
+    const alt: Alt = { kind: 'alt', options };
+    return alt;
+  }
+
+  /** `a.b.c` — a single step with no `?` collapses to its term. */
+  private path(): Node {
+    const steps: Step[] = [this.step()];
+    while (this.peek().kind === 'dot') {
+      this.next();
+      steps.push(this.step());
+    }
+    if (steps.length === 1 && !steps[0].optional) return steps[0].term;
+    const path: Path = { kind: 'path', steps };
+    return path;
+  }
+
+  private step(): Step {
+    const term = this.term();
+    let optional = false;
+    if (this.peek().kind === 'question') {
+      this.next();
+      optional = true;
+    }
+    return { term, optional };
+  }
+
+  private term(): Step['term'] {
+    const token = this.next();
+    switch (token.kind) {
+      case 'ident':
+      case 'number':
+        return { kind: 'name', value: token.value };
+      case 'range': {
+        const { min, max, step } = token.range as {
+          min: number;
+          max: number;
+          step: number;
+        };
+        if (step === 0 || max < min) {
+          throw new DfnError(
+            'range needs max >= min and a non-zero step',
+            token.line,
+            token.column,
+          );
+        }
+        return { kind: 'range', min, max, step };
+      }
+      case 'langle': {
+        const imported = this.peek().kind === 'at';
+        if (imported) this.next();
+        const name = this.expect('ident', 'a production name');
+        // Set modifiers: `[a, b]` picks only the listed members; `![a, b]` omits them.
+        const pick: string[] = [];
+        const omit: string[] = [];
+        const negated = this.peek().kind === 'bang';
+        if (negated) this.next();
+        if (this.peek().kind === 'lbracket') {
+          const into = negated ? omit : pick;
+          this.next();
+          into.push(this.expect('ident', 'a member name').value);
+          while (this.peek().kind === 'comma') {
+            this.next();
+            into.push(this.expect('ident', 'a member name').value);
+          }
+          this.expect('rbracket', "']'");
+        } else if (negated) {
+          const bad = this.peek();
+          throw new DfnError(
+            "'!' must be followed by a [list]",
+            bad.line,
+            bad.column,
+          );
+        }
+        const open = this.peek().kind === 'star';
+        if (open) this.next();
+        this.expect('rangle', "'>'");
+        return { kind: 'ref', name: name.value, imported, open, pick, omit };
+      }
+      case 'lbracket': {
+        const node = this.alternation();
+        const open = this.peek().kind === 'star';
+        if (open) this.next();
+        this.expect('rbracket', "']'");
+        return { kind: 'group', node, open };
+      }
+      default:
+        throw new DfnError(
+          `expected a term, got '${token.value || token.kind}'`,
+          token.line,
+          token.column,
+        );
+    }
+  }
+}

package/src/resolve.ts

@@ -0,0 +1,77 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { basename, dirname, join, resolve } from 'node:path';
+import type { Module } from './ast';
+import { DfnError } from './error';
+import { parse } from './parser';
+
+/** A parsed module plus its imports, keyed by module name (basename without `.dfn`). */
+export interface ResolvedModule {
+  /** Absolute path of the module file. */
+  path: string;
+  /** Module name: basename without extension — how `<@name>` finds an imported root. */
+  name: string;
+  module: Module;
+  imports: Map<string, ResolvedModule>;
+}
+
+/**
+ * Resolve a `use` specifier from the importing module's location. Relative specifiers walk the
+ * filesystem; package specifiers (`@scope/pkg/file.dfn`) resolve the package root via its
+ * `package.json` and join the rest — `require.resolve` on the file itself would demand an exports
+ * entry per `.dfn`, which content packages should not need.
+ */
+function resolveSpecifier(spec: string, fromDir: string): string {
+  if (spec.startsWith('.')) return resolve(fromDir, spec);
+  const require = createRequire(join(fromDir, 'noop.js'));
+  // Exports-aware first: a package may remap flat specifiers into folders
+  // (`"./*.dfn": "./dfn/*.dfn"`). Root-join second, for content packages with no map.
+  try {
+    return require.resolve(spec);
+  } catch {
+    const segments = spec.split('/');
+    const packageEnd = spec.startsWith('@') ? 2 : 1;
+    const packageName = segments.slice(0, packageEnd).join('/');
+    const rest = segments.slice(packageEnd).join('/');
+    const packageJson = require.resolve(`${packageName}/package.json`);
+    return join(dirname(packageJson), rest);
+  }
+}
+
+/** Parse a module file and, recursively, everything it `use`s. A cycle is an authoring error. */
+export function resolveModule(
+  path: string,
+  inProgress: Set<string> = new Set(),
+): ResolvedModule {
+  const absolute = resolve(path);
+  if (inProgress.has(absolute)) {
+    throw new DfnError(`import cycle through ${basename(absolute)}`, 1, 1);
+  }
+  inProgress.add(absolute);
+
+  let source: string;
+  try {
+    source = readFileSync(absolute, 'utf8');
+  } catch {
+    throw new DfnError(`cannot read ${absolute}`, 1, 1);
+  }
+  const module = parse(source);
+
+  const imports = new Map<string, ResolvedModule>();
+  for (const spec of module.uses) {
+    const target = resolveSpecifier(spec, dirname(absolute));
+    const resolved = resolveModule(target, inProgress);
+    if (imports.has(resolved.name)) {
+      throw new DfnError(`two imports share the name '${resolved.name}'`, 1, 1);
+    }
+    imports.set(resolved.name, resolved);
+  }
+
+  inProgress.delete(absolute);
+  return {
+    path: absolute,
+    name: basename(absolute).replace(/\.dfn$/, ''),
+    module,
+    imports,
+  };
+}

package/src/tokenizer.ts

@@ -0,0 +1,140 @@
+import { DfnError } from './error';
+
+/**
+ * The `.dfn` lexer. Line-aware (statements are line-oriented), producing a flat token stream the
+ * parser walks. `#` comments run to end of line. A term starting with a digit is numeric — a
+ * NUMBER (`950`) or a RANGE (`100-300/50`) — so hyphens inside identifiers (`color-role`) never
+ * collide with range syntax.
+ */
+
+export type TokenKind =
+  | 'ident'
+  | 'number'
+  | 'range'
+  | 'string'
+  | 'use'
+  | 'equals'
+  | 'dot'
+  | 'pipe'
+  | 'lbracket'
+  | 'rbracket'
+  | 'langle'
+  | 'rangle'
+  | 'at'
+  | 'star'
+  | 'question'
+  | 'comma'
+  | 'bang'
+  | 'newline'
+  | 'eof';
+
+export interface Token {
+  kind: TokenKind;
+  /** Source text (for ident/number/string); ranges carry min/max/step instead. */
+  value: string;
+  range?: { min: number; max: number; step: number };
+  line: number;
+  column: number;
+}
+
+const IDENT = /^[A-Za-z][A-Za-z0-9-]*/;
+const RANGE = /^(\d+)-(\d+)\/(\d+)/;
+const NUMBER = /^\d+/;
+
+export function tokenize(source: string): Token[] {
+  const tokens: Token[] = [];
+  const lines = source.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = i + 1;
+    let text = lines[i];
+    const commentAt = text.indexOf('#');
+    if (commentAt !== -1) text = text.slice(0, commentAt);
+
+    // Continuation by indentation: a line that starts with whitespace continues the statement
+    // above it, so a long expression can wrap without any continuation character.
+    if (
+      /^\s/.test(text) &&
+      text.trim().length > 0 &&
+      tokens[tokens.length - 1]?.kind === 'newline'
+    ) {
+      tokens.pop();
+    }
+
+    let column = 1;
+    while (text.length > 0) {
+      const ws = text.match(/^\s+/);
+      if (ws) {
+        column += ws[0].length;
+        text = text.slice(ws[0].length);
+        continue;
+      }
+
+      const push = (kind: TokenKind, value: string): void => {
+        tokens.push({ kind, value, line, column });
+        column += value.length;
+        text = text.slice(value.length);
+      };
+
+      const range = text.match(RANGE);
+      if (range) {
+        tokens.push({
+          kind: 'range',
+          value: range[0],
+          range: {
+            min: Number(range[1]),
+            max: Number(range[2]),
+            step: Number(range[3]),
+          },
+          line,
+          column,
+        });
+        column += range[0].length;
+        text = text.slice(range[0].length);
+        continue;
+      }
+      const number = text.match(NUMBER);
+      if (number) {
+        push('number', number[0]);
+        continue;
+      }
+      const ident = text.match(IDENT);
+      if (ident) {
+        push(ident[0] === 'use' ? 'use' : 'ident', ident[0]);
+        continue;
+      }
+      if (text.startsWith('"')) {
+        const end = text.indexOf('"', 1);
+        if (end === -1) throw new DfnError('unterminated string', line, column);
+        const raw = text.slice(0, end + 1);
+        tokens.push({ kind: 'string', value: raw.slice(1, -1), line, column });
+        column += raw.length;
+        text = text.slice(raw.length);
+        continue;
+      }
+
+      const single: Record<string, TokenKind> = {
+        '=': 'equals',
+        '.': 'dot',
+        '|': 'pipe',
+        '[': 'lbracket',
+        ']': 'rbracket',
+        '<': 'langle',
+        '>': 'rangle',
+        '@': 'at',
+        '*': 'star',
+        '?': 'question',
+        ',': 'comma',
+        '!': 'bang',
+      };
+      const kind = single[text[0]];
+      if (!kind) throw new DfnError(`unexpected '${text[0]}'`, line, column);
+      push(kind, text[0]);
+    }
+
+    tokens.push({ kind: 'newline', value: '\n', line, column });
+  }
+
+  tokens.push({ kind: 'eof', value: '', line: lines.length + 1, column: 1 });
+  return tokens;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "resolveJsonModule": true
+  },
+  "include": ["src"]
+}