@vertekum/schema-builder 0.1.3 → 0.1.5

package/src/cli.ts

@@ -1,8 +1,9 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { basename, dirname, join, relative } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative } from 'node:path';
 import type { CommandDescriptor, CommandResult } from '@vertekum/core';
 import { assertOpenSetsAreNameSets, build } from './build';
 import { emit, isStamped } from './emit';
+import { lintModule } from './lint';
 import { resolveModule } from './resolve';
 
 /**
@@ -25,20 +26,74 @@ function modulesUnder(dir: string): string[] {
     .map((f) => join(dir, f));
 }
 
-export function buildModule(modulePath: string): {
+export function buildModule(
+  modulePath: string,
+  /** The module name the provenance stamp records; default: the basename. Pass a relative
+   *  path when modules nest, so same-named modules stamp distinguishably. */
+  moduleLabel?: string,
+): {
   target: string;
   content: string;
 } {
   const resolved = resolveModule(modulePath);
   assertOpenSetsAreNameSets(resolved);
   const tree = build(resolved);
-  const moduleFile = basename(modulePath);
+  const moduleFile = moduleLabel ?? basename(modulePath);
   return {
     target: join(dirname(modulePath), `${resolved.name}.json`),
     content: emit(tree, { moduleFile, ...resolved.module.meta }),
   };
 }
 
+/**
+ * `vertekum schema lint [module]`: validate the `.dfn` sources themselves. Where `build --check`
+ * asks "are the artifacts current?", lint asks "is the grammar sound?" — fragments included,
+ * every production evaluated, findings collected instead of aborting on the first. Findings exit
+ * `1` through a thrown error carrying the listing (the `build --check` staleness precedent).
+ */
+export const schemaLintCommand: CommandDescriptor = {
+  name: 'schema lint',
+  description:
+    'validate .dfn vocabulary modules — fragments included — without building',
+  args: [
+    {
+      name: 'module',
+      required: false,
+      description: "a .dfn file; default: every module under './schemas'",
+    },
+  ],
+  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' };
+    }
+
+    const project = (file: string) =>
+      isAbsolute(file) ? relative(projectDir, file) : file;
+    const diagnostics = modules.flatMap((modulePath) =>
+      lintModule(modulePath).map((d) => ({ ...d, file: project(d.file) })),
+    );
+
+    if (diagnostics.length > 0) {
+      throw new Error(
+        [
+          `${diagnostics.length} problem(s) in the .dfn modules:`,
+          ...diagnostics.map(
+            (d) => `  ${d.file}:${d.line}:${d.column} ${d.message}`,
+          ),
+        ].join('\n'),
+      );
+    }
+    return {
+      summary: `${modules.length} module(s) clean`,
+      data: { modules: modules.map(project) },
+    };
+  },
+};
+
 export const schemaBuildCommand: CommandDescriptor = {
   name: 'schema build',
   description: 'build .dfn vocabulary modules into JSON Schema files',
@@ -77,7 +132,10 @@ export const schemaBuildCommand: CommandDescriptor = {
         fragments.push(relative(projectDir, modulePath));
         continue;
       }
-      const { target, content } = buildModule(modulePath);
+      const { target, content } = buildModule(
+        modulePath,
+        relative(projectDir, modulePath),
+      );
       const existing = existsSync(target)
         ? readFileSync(target, 'utf8')
         : undefined;

package/src/error.ts

@@ -2,11 +2,17 @@
 export class DfnError extends Error {
   readonly line: number;
   readonly column: number;
+  /** The module the position refers to, when the thrower knows it (multi-file runs). */
+  readonly file?: string;
+  /** The bare message, without the position prefix — what a diagnostic report carries. */
+  readonly detail: string;
 
-  constructor(message: string, line: number, column: number) {
-    super(`${line}:${column} ${message}`);
+  constructor(message: string, line: number, column: number, file?: string) {
+    super(`${file ? `${file}:` : ''}${line}:${column} ${message}`);
     this.name = 'DfnError';
     this.line = line;
     this.column = column;
+    this.file = file;
+    this.detail = message;
   }
 }

package/src/lint.ts

@@ -0,0 +1,80 @@
+import { assertOpenSetsAreNameSets, build, evaluateProduction } from './build';
+import { DfnError } from './error';
+import { resolveModule } from './resolve';
+
+/**
+ * Grammar-only validation of a `.dfn` module — the whole module, not just what a root reaches.
+ *
+ * `build --dry-run` validates incidentally: it expands from `root`, so a fragment's productions
+ * and a rooted module's unused ones are parsed and nothing more. Lint's contract is the source
+ * itself — every production evaluates (cycle-detected, references resolved, pick/omit members and
+ * scales checked, open sets verified name-only), and diagnostics COLLECT: one broken production
+ * does not hide the next one.
+ */
+
+export interface DfnDiagnostic {
+  /** The module the position refers to — the linted file, unless the error names another. */
+  file: string;
+  line: number;
+  column: number;
+  message: string;
+}
+
+function toDiagnostic(file: string, error: unknown): DfnDiagnostic {
+  if (error instanceof DfnError) {
+    return {
+      file: error.file ?? file,
+      line: error.line,
+      column: error.column,
+      message: error.detail,
+    };
+  }
+  return {
+    file,
+    line: 1,
+    column: 1,
+    message: error instanceof Error ? error.message : String(error),
+  };
+}
+
+/** Lint one module. Returns every finding; an empty array means the grammar is sound. */
+export function lintModule(path: string): DfnDiagnostic[] {
+  let resolved: ReturnType<typeof resolveModule>;
+  try {
+    resolved = resolveModule(path);
+  } catch (error) {
+    return [toDiagnostic(path, error)];
+  }
+
+  const out: DfnDiagnostic[] = [];
+  const collect = (walk: () => void): void => {
+    try {
+      walk();
+    } catch (error) {
+      out.push(toDiagnostic(path, error));
+    }
+  };
+
+  for (const [name, node] of resolved.module.productions) {
+    collect(() => {
+      evaluateProduction(resolved, name);
+      assertOpenSetsAreNameSets(resolved, node);
+    });
+  }
+  if (resolved.module.root) {
+    // `build` re-expands referenced productions, so a production's error can surface twice —
+    // once from its own walk, once through the root. The dedupe below keeps one.
+    collect(() => {
+      build(resolved);
+      assertOpenSetsAreNameSets(resolved);
+    });
+  }
+
+  const seen = new Set<string>();
+  return out.filter((d) => {
+    const key = `${d.file}|${d.line}|${d.column}|${d.message}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}

package/src/parser.ts

@@ -49,7 +49,7 @@ class Parser {
   }
 
   module(): Module {
-    const uses: string[] = [];
+    const uses: Array<{ spec: string; alias?: string }> = [];
     const productions = new Map<string, Node>();
     const meta: ModuleMeta = {};
     let root: Node | undefined;
@@ -59,7 +59,13 @@ class Parser {
       const token = this.peek();
       if (token.kind === 'use') {
         this.next();
-        uses.push(this.expect('string', 'a quoted specifier').value);
+        const spec = this.expect('string', 'a quoted specifier').value;
+        let alias: string | undefined;
+        if (this.peek().kind === 'ident' && this.peek().value === 'as') {
+          this.next();
+          alias = this.expect('ident', 'an import alias').value;
+        }
+        uses.push({ spec, alias });
       } 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.
@@ -127,6 +133,16 @@ class Parser {
           token.column,
         );
       }
+      // `<scale>*` — the open-set mark after a closed `>`/`]` lands here as a stray
+      // statement tail; name the fix rather than complaining about the line ending.
+      if (this.peek().kind === 'star') {
+        const star = this.peek();
+        throw new DfnError(
+          "'*' marks a set open and sits inside the reference or group it opens — <name*> or [a | b *]",
+          star.line,
+          star.column,
+        );
+      }
       if (this.peek().kind !== 'eof') this.expect('newline', 'end of line');
       this.skipNewlines();
     }
@@ -168,26 +184,70 @@ class Parser {
     return { term, optional };
   }
 
+  /** A pick/omit list member: an identifier or a (possibly padded) number. */
+  private member(): string {
+    const token = this.next();
+    if (token.kind !== 'ident' && token.kind !== 'number') {
+      throw new DfnError(
+        `expected a member name, got '${token.value || token.kind}'`,
+        token.line,
+        token.column,
+      );
+    }
+    return token.value;
+  }
+
   private term(): Step['term'] {
     const token = this.next();
+    const at = { line: token.line, column: token.column };
     switch (token.kind) {
       case 'ident':
       case 'number':
-        return { kind: 'name', value: token.value };
+        return { kind: 'name', value: token.value, ...at };
       case 'range': {
-        const { min, max, step } = token.range as {
-          min: number;
-          max: number;
-          step: number;
-        };
-        if (step === 0 || max < min) {
+        const payload = token.range as NonNullable<Token['range']>;
+        const { min, max, mode, step, quantum, pad } = payload;
+        if (max < min) {
+          throw new DfnError(
+            'range needs max >= min',
+            token.line,
+            token.column,
+          );
+        }
+        if (mode === '/') {
+          if (quantum !== undefined) {
+            throw new DfnError(
+              '~quantum belongs to multiplied scales (min-max*factor~q)',
+              token.line,
+              token.column,
+            );
+          }
+          if (step === 0 || !Number.isInteger(step)) {
+            throw new DfnError(
+              'a stepped range needs a whole-number step greater than zero',
+              token.line,
+              token.column,
+            );
+          }
+          return { kind: 'range', min, max, mode: 'stepped', step, pad, ...at };
+        }
+        if (step <= 1) {
           throw new DfnError(
-            'range needs max >= min and a non-zero step',
+            'a multiplied range needs a factor greater than one',
             token.line,
             token.column,
           );
         }
-        return { kind: 'range', min, max, step };
+        return {
+          kind: 'range',
+          min,
+          max,
+          mode: 'multiplied',
+          step,
+          quantum,
+          pad,
+          ...at,
+        };
       }
       case 'langle': {
         const imported = this.peek().kind === 'at';
@@ -216,10 +276,10 @@ class Parser {
         if (this.peek().kind === 'lbracket') {
           const into = negated ? omit : pick;
           this.next();
-          into.push(this.expect('ident', 'a member name').value);
+          into.push(this.member());
           while (this.peek().kind === 'comma') {
             this.next();
-            into.push(this.expect('ident', 'a member name').value);
+            into.push(this.member());
           }
           this.expect('rbracket', "']'");
         } else if (negated) {
@@ -241,6 +301,7 @@ class Parser {
           open,
           pick,
           omit,
+          ...at,
         };
       }
       case 'lbracket': {
@@ -248,8 +309,16 @@ class Parser {
         const open = this.peek().kind === 'star';
         if (open) this.next();
         this.expect('rbracket', "']'");
-        return { kind: 'group', node, open };
+        return { kind: 'group', node, open, ...at };
       }
+      case 'star':
+        // The most common misplacement: `color.*` or `a | *`. The mark exists — it just
+        // sits inside the set it opens, so say that instead of a bare grammar complaint.
+        throw new DfnError(
+          "'*' marks a set open and sits inside the reference or group it opens — <name*> or [a | b *]",
+          token.line,
+          token.column,
+        );
       default:
         throw new DfnError(
           `expected a term, got '${token.value || token.kind}'`,

package/src/resolve.ts

@@ -55,16 +55,31 @@ export function resolveModule(
   } catch {
     throw new DfnError(`cannot read ${absolute}`, 1, 1);
   }
-  const module = parse(source);
+  let module: Module;
+  try {
+    module = parse(source);
+  } catch (error) {
+    // Stamp the file: a sweep parses many modules, and `13:10 …` without a file name is
+    // exactly the kind of message this pipeline should never emit.
+    if (error instanceof DfnError && !error.file) {
+      throw new DfnError(error.detail, error.line, error.column, absolute);
+    }
+    throw error;
+  }
 
   const imports = new Map<string, ResolvedModule>();
-  for (const spec of module.uses) {
+  for (const { spec, alias } 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);
+    const key = alias ?? resolved.name;
+    if (imports.has(key)) {
+      throw new DfnError(
+        `two imports share the name '${key}' — alias one: use "…" as other-name`,
+        1,
+        1,
+      );
     }
-    imports.set(resolved.name, resolved);
+    imports.set(key, resolved);
   }
 
   inProgress.delete(absolute);

package/src/tokenizer.ts

@@ -31,17 +31,33 @@ export type TokenKind =
 
 export interface Token {
   kind: TokenKind;
-  /** Source text (for ident/number/string); ranges carry min/max/step instead. */
+  /** Source text (for ident/number/string); ranges carry their parsed payload instead. */
   value: string;
-  range?: { min: number; max: number; step: number };
+  range?: {
+    min: number;
+    max: number;
+    /** `/` = stepped (additive), `*` = multiplied (geometric). */
+    mode: '/' | '*';
+    step: number;
+    quantum?: number;
+    /** Pad width inferred from a leading zero on a written endpoint (`025` → 3). */
+    pad?: number;
+  };
   line: number;
   column: number;
 }
 
 const IDENT = /^[A-Za-z][A-Za-z0-9-]*/;
-const RANGE = /^(\d+)-(\d+)\/(\d+)/;
+const RANGE = /^(\d+)-(\d+)([*/])(\d+(?:\.\d+)?)(?:~(\d+))?/;
 const NUMBER = /^\d+/;
 
+/** "Write the numbers as they appear": a leading zero declares the pad width. */
+function padWidth(...literals: string[]): number | undefined {
+  const declared = literals.filter((l) => l.length > 1 && l.startsWith('0'));
+  if (declared.length === 0) return undefined;
+  return Math.max(...declared.map((l) => l.length));
+}
+
 export function tokenize(source: string): Token[] {
   const tokens: Token[] = [];
   const lines = source.split('\n');
@@ -85,7 +101,10 @@ export function tokenize(source: string): Token[] {
           range: {
             min: Number(range[1]),
             max: Number(range[2]),
-            step: Number(range[3]),
+            mode: range[3] as '/' | '*',
+            step: Number(range[4]),
+            quantum: range[5] ? Number(range[5]) : undefined,
+            pad: padWidth(range[1], range[2]),
           },
           line,
           column,