@vertekum/schema-builder 0.1.4 → 0.1.6

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

@@ -133,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();
     }
@@ -189,10 +199,11 @@ class Parser {
 
   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 payload = token.range as NonNullable<Token['range']>;
         const { min, max, mode, step, quantum, pad } = payload;
@@ -218,7 +229,7 @@ class Parser {
               token.column,
             );
           }
-          return { kind: 'range', min, max, mode: 'stepped', step, pad };
+          return { kind: 'range', min, max, mode: 'stepped', step, pad, ...at };
         }
         if (step <= 1) {
           throw new DfnError(
@@ -235,6 +246,7 @@ class Parser {
           step,
           quantum,
           pad,
+          ...at,
         };
       }
       case 'langle': {
@@ -289,6 +301,7 @@ class Parser {
           open,
           pick,
           omit,
+          ...at,
         };
       }
       case 'lbracket': {
@@ -296,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,7 +55,17 @@ 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, alias } of module.uses) {

package/src/tokenizer.ts

@@ -49,6 +49,12 @@ export interface Token {
 
 const IDENT = /^[A-Za-z][A-Za-z0-9-]*/;
 const RANGE = /^(\d+)-(\d+)([*/])(\d+(?:\.\d+)?)(?:~(\d+))?/;
+/**
+ * A digit-leading NAME (`2xs`, `4k-display`): digits, then at least one letter. Tried after
+ * RANGE — so `100-300/50` stays numeric — and before NUMBER, so the whole word is one token
+ * rather than `2` + `xs`. Real design systems name t-shirt sizes this way.
+ */
+const WORD = /^\d+[A-Za-z][A-Za-z0-9-]*/;
 const NUMBER = /^\d+/;
 
 /** "Write the numbers as they appear": a leading zero declares the pad width. */
@@ -113,6 +119,11 @@ export function tokenize(source: string): Token[] {
         text = text.slice(range[0].length);
         continue;
       }
+      const word = text.match(WORD);
+      if (word) {
+        push('ident', word[0]);
+        continue;
+      }
       const number = text.match(NUMBER);
       if (number) {
         push('number', number[0]);