@vertekum/schema-builder 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @vertekum/schema-builder
 
+## 0.1.7
+
+### Patch Changes
+
+- [`880b288`](https://github.com/moros-oxus/vertekum/commit/880b288630455eaf629f0d458fb38b3eaf0222a6) Thanks [@tschemmer](https://github.com/tschemmer)! - Grammar errors are attributed to the module that contains them — a failure inside an imported module names that file, not the one being linted or built. Referencing a fragment by module name (`<@t-shirt>`) now explains that a fragment has no root and lists its productions to reference instead; a qualified miss lists what the import declares.
+
+## 0.1.6
+
+### Patch Changes
+
+- [`2e9a56f`](https://github.com/moros-oxus/vertekum/commit/2e9a56f5cc52de26ee8768ae0035178ebe4d847e) Thanks [@tschemmer](https://github.com/tschemmer)! - Names may start with digits when they contain a letter (`2xs`, `4k-display`) — everywhere a name works, including pick/omit lists. Pure numbers and scale expressions keep their numeric meaning; the syntax highlighting follows suit.
+
 ## 0.1.5
 
 ### Patch Changes

package/docs/language.md

@@ -29,9 +29,10 @@ root = color.[text | icon].<role>.<@emphasis>
   ```
 
 - **`#` starts a comment**, running to the end of the line.
-- **Identifiers** are `[A-Za-z][A-Za-z0-9-]*` — letters, digits, hyphens
-  (`color-role`). A term that starts with a digit is numeric: a bare number (`950`) or
-  a [scale expression](./scales.md) (`100-300/50`) — which is why hyphens inside names
+- **Identifiers** are letters, digits, and hyphens (`color-role`), and may start with
+  digits **when they contain a letter** (`2xs`, `4k-display`). A term that is purely
+  numeric keeps its numeric meaning: a bare number (`950`) or a
+  [scale expression](./scales.md) (`100-300/50`) — which is why hyphens inside names
   never collide with range syntax.
 - **Strings** (pragma and `use` arguments) are double-quoted.
 

package/grammar/dfn.tmLanguage.json

@@ -61,7 +61,7 @@
       }
     },
     "production": {
-      "match": "^([A-Za-z][A-Za-z0-9-]*)\\s*(=)",
+      "match": "^(\\d+[A-Za-z][A-Za-z0-9-]*|[A-Za-z][A-Za-z0-9-]*)\\s*(=)",
       "captures": {
         "1": {
           "name": "entity.name.function.production.dfn"
@@ -127,7 +127,7 @@
       },
       "patterns": [
         {
-          "match": "([A-Za-z][A-Za-z0-9-]*)(/)([A-Za-z][A-Za-z0-9-]*)",
+          "match": "(\\d+[A-Za-z][A-Za-z0-9-]*|[A-Za-z][A-Za-z0-9-]*)(/)(\\d+[A-Za-z][A-Za-z0-9-]*|[A-Za-z][A-Za-z0-9-]*)",
           "captures": {
             "1": {
               "name": "entity.name.namespace.module.dfn"
@@ -145,7 +145,7 @@
         },
         {
           "name": "variable.other.reference.imported.dfn",
-          "match": "[A-Za-z][A-Za-z0-9-]*"
+          "match": "\\d+[A-Za-z][A-Za-z0-9-]*|[A-Za-z][A-Za-z0-9-]*"
         }
       ]
     },
@@ -171,7 +171,7 @@
         },
         {
           "name": "variable.other.reference.dfn",
-          "match": "[A-Za-z][A-Za-z0-9-]*"
+          "match": "\\d+[A-Za-z][A-Za-z0-9-]*|[A-Za-z][A-Za-z0-9-]*"
         }
       ]
     },
@@ -197,7 +197,7 @@
           "patterns": [
             {
               "name": "variable.parameter.member.dfn",
-              "match": "[A-Za-z][A-Za-z0-9-]*|\\d+"
+              "match": "\\d+[A-Za-z][A-Za-z0-9-]*|[A-Za-z][A-Za-z0-9-]*|\\d+"
             },
             {
               "name": "punctuation.separator.comma.dfn",
@@ -245,7 +245,7 @@
     },
     "name": {
       "name": "constant.language.name.dfn",
-      "match": "[A-Za-z][A-Za-z0-9-]*"
+      "match": "\\d+[A-Za-z][A-Za-z0-9-]*|[A-Za-z][A-Za-z0-9-]*"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertekum/schema-builder",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Declare token vocabularies as grammar; build them into JSON Schema files",
   "license": "Apache-2.0",
   "keywords": [
@@ -43,7 +43,7 @@
     "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@vertekum/core": "0.1.2",
-    "@vertekum/schema-vocabulary": "0.1.0"
+    "@vertekum/schema-vocabulary": "0.1.0",
+    "@vertekum/core": "0.1.2"
   }
 }

package/src/build.ts

@@ -33,8 +33,19 @@ interface Scope {
   expanding: Set<string>;
 }
 
+/** The `<@key/name>, …` listing a miss suggests — an error should name the fix, not just the gap. */
+function productionsOf(key: string, imported: ResolvedModule): string {
+  return [...imported.module.productions.keys()]
+    .map((p) => `<@${key}/${p}>`)
+    .join(', ');
+}
+
 /** Find what `<name>` / `<@name>` means in this scope. Imported roots go by module name. */
 function target(ref: Ref, scope: Scope): { node: Node; scope: Scope } {
+  // Every error here names the module whose TEXT holds the ref — `scope.module` — so a
+  // failure inside an imported production's body is attributed to that file, not to
+  // whichever module the walk started from.
+  const file = scope.module.path;
   if (!ref.imported) {
     const production = scope.module.module.productions.get(ref.name);
     if (!production) {
@@ -42,6 +53,7 @@ function target(ref: Ref, scope: Scope): { node: Node; scope: Scope } {
         `unknown production '<${ref.name}>'`,
         ref.line,
         ref.column,
+        file,
       );
     }
     return { node: production, scope };
@@ -51,14 +63,20 @@ function target(ref: Ref, scope: Scope): { node: Node; scope: Scope } {
   if (ref.from) {
     const imported = scope.module.imports.get(ref.from);
     if (!imported) {
-      throw new DfnError(`no import named '${ref.from}'`, ref.line, ref.column);
+      throw new DfnError(
+        `no import named '${ref.from}'`,
+        ref.line,
+        ref.column,
+        file,
+      );
     }
     const production = imported.module.productions.get(ref.name);
     if (!production) {
       throw new DfnError(
-        `'${ref.from}' has no production '${ref.name}'`,
+        `'${ref.from}' has no production '${ref.name}' — it declares: ${productionsOf(ref.from, imported)}`,
         ref.line,
         ref.column,
+        file,
       );
     }
     return {
@@ -77,10 +95,22 @@ function target(ref: Ref, scope: Scope): { node: Node; scope: Scope } {
     }
   }
   if (hits.length === 0) {
+    // The near-miss that reads as a missing `use`: the import EXISTS under this key, but
+    // `<@key>` means its root and a fragment has none. Say so, and name the real forms.
+    const fragment = scope.module.imports.get(ref.name);
+    if (fragment) {
+      throw new DfnError(
+        `'${ref.name}' is imported, but it declares no root (a fragment) — reference one of its productions: ${productionsOf(ref.name, fragment)}`,
+        ref.line,
+        ref.column,
+        file,
+      );
+    }
     throw new DfnError(
       `no import provides '<@${ref.name}>'`,
       ref.line,
       ref.column,
+      file,
     );
   }
   if (hits.length > 1) {
@@ -88,6 +118,7 @@ function target(ref: Ref, scope: Scope): { node: Node; scope: Scope } {
       `'<@${ref.name}>' is ambiguous across imports — qualify it: <@module/${ref.name}>`,
       ref.line,
       ref.column,
+      file,
     );
   }
   return hits[0];
@@ -132,6 +163,7 @@ function evaluate(node: Node, scope: Scope, tail: () => TreeNode): TreeNode {
           error instanceof Error ? error.message : String(error),
           node.line,
           node.column,
+          scope.module.path,
         );
       }
       if (scale.collisions.length > 0) {
@@ -139,6 +171,7 @@ function evaluate(node: Node, scope: Scope, tail: () => TreeNode): TreeNode {
           `scale steps ${scale.collisions.join(', ')} quantize onto earlier names — the quantum is too coarse for the factor`,
           node.line,
           node.column,
+          scope.module.path,
         );
       }
       const forest = leaf();
@@ -188,6 +221,7 @@ function evaluate(node: Node, scope: Scope, tail: () => TreeNode): TreeNode {
             `'<${node.name}>' expands through itself`,
             node.line,
             node.column,
+            scope.module.path,
           );
         }
         scope.expanding.add(node.name);
@@ -200,6 +234,7 @@ function evaluate(node: Node, scope: Scope, tail: () => TreeNode): TreeNode {
             `'<${node.name}>' has no member '${omitted}' to omit`,
             node.line,
             node.column,
+            scope.module.path,
           );
         }
       }
@@ -210,6 +245,7 @@ function evaluate(node: Node, scope: Scope, tail: () => TreeNode): TreeNode {
               `'<${node.name}>' has no member '${picked}' to pick`,
               node.line,
               node.column,
+              scope.module.path,
             );
           }
         }
@@ -254,7 +290,12 @@ function isTerminal(node: TreeNode): boolean {
 export function build(resolved: ResolvedModule): TreeNode {
   const root = resolved.module.root;
   if (!root) {
-    throw new DfnError(`${resolved.name}.dfn declares no root`, 1, 1);
+    throw new DfnError(
+      `${resolved.name}.dfn declares no root`,
+      1,
+      1,
+      resolved.path,
+    );
   }
   const scope: Scope = { module: resolved, expanding: new Set() };
 
@@ -274,6 +315,7 @@ export function build(resolved: ResolvedModule): TreeNode {
             `top-level '${name}' comes from both '${owner}' and '${option.name}'`,
             option.line,
             option.column,
+            resolved.path,
           );
         }
         seen.set(name, option.name);
@@ -332,6 +374,7 @@ export function assertOpenSetsAreNameSets(
           '* opens a set of names, not sub-paths',
           node.line,
           node.column,
+          scope.module.path,
         );
       }
       assertOpenSetsAreNameSets(resolved, node.node, scope);
@@ -344,6 +387,7 @@ export function assertOpenSetsAreNameSets(
             `'<${node.name}*>' opens a set, but the production is not name-only`,
             node.line,
             node.column,
+            scope.module.path,
           );
         }
       }

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]);