@vertekum/schema-builder 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @vertekum/schema-builder
 
+## 0.1.4
+
+### Patch Changes
+
+- [`6932b20`](https://github.com/moros-oxus/vertekum/commit/6932b20cd3c4e133de5c465bacea5dd1fada2d06) Thanks [@tschemmer](https://github.com/tschemmer)! - Imports can be aliased — `use "./palette/color.dfn" as palette` — making `<@palette>` the module's root and `<@palette/name>` a qualified reference, which resolves same-basename imports (the duplicate-import error now suggests it). Provenance stamps record a caller-supplied module label (the CLI passes the project-relative path), so nested same-named modules stamp distinguishably; `buildModule` accepts the label as its second argument.
+
+- [`9c0f093`](https://github.com/moros-oxus/vertekum/commit/9c0f093b5016c6c0ca9cb5b5fd48598718e698d9) Thanks [@tschemmer](https://github.com/tschemmer)! - Range terms grow into scale expressions: a leading zero on a written endpoint zero-pads every emitted name (`025-100/25` → `025 050 075 100`), `min-max*factor` declares a geometric scale (fractional factors allowed), and `~quantum` rounds each step to the nearest multiple (`16-64*1.25~4` → `16 20 24 32 40 48 60`). Steps that quantize onto an earlier name are a build error.
+- Updated dependencies [[`9c0f093`](https://github.com/moros-oxus/vertekum/commit/9c0f093b5016c6c0ca9cb5b5fd48598718e698d9)]:
+  - @vertekum/core@0.1.2
+
+## 0.1.3
+
+### Patch Changes
+
+- [`67ef6d9`](https://github.com/moros-oxus/vertekum/commit/67ef6d96ad209072df270adccaa7ee879edbc30e) Thanks [@tschemmer](https://github.com/tschemmer)! - The package now ships a TextMate grammar and language configuration for `.dfn` files under `grammar/` — the single source editor integrations and documentation highlighters (e.g. Shiki) consume.
+
 ## 0.1.2
 
 ### Patch Changes

package/README.md

@@ -57,6 +57,7 @@ indented line continues the statement above it.
 | `name = expression` | a **production**: a named fragment (a denotation, a branch, a whole subtree) |
 | `root = expression` | the reserved production `build` materializes; one per module |
 | `use "./other.dfn"` | import a module (relative path or package specifier) |
+| `use "./other.dfn" as x` | alias the import: `<@x>` is its root, `<@x/name>` qualifies into it — the resolver when two imports share a basename |
 | `id "…"` `title "…"` `description "…"` | pragmas: the built schema's `$id`, `title`, `description` |
 | `scope "branch"` | the schema governs only its named top-level branches — the document root stays unsealed so sibling vocabularies can bind over the same files (default: `"document"`, which seals it) |
 
@@ -74,7 +75,8 @@ indented line continues the statement above it.
 | `<name ![a, b]>` | **omit** — the set minus the listed members |
 | `<name*>` / `[a \| b *]` | **open set** — additions beyond the listed names are permitted, and every member (listed or added) takes the same tail |
 | `step?` | **optional slot** — the step may be skipped: `<role>.<emphasis>?.<state>?` grants `role`, `role.<emphasis>`, `role.<state>`, and the full path |
-| `100-900/100` | a numeric range with step, inclusive both ends, enumerated at build |
+| `100-900/100` | an additive scale, inclusive both ends, enumerated at build; a leading zero on a written endpoint (`025-100/25`) zero-pads every emitted name |
+| `16-64*1.25~4` | a geometric scale: `min-max*factor` (fractional ok), `~quantum` rounding each step to the nearest multiple; steps that collide onto an earlier name are a build error |
 
 Pick and omit validate every listed name against the set's members — a typo is a build
 error, and a modified set is a new set. Naming one derives a narrowed denotation:

package/grammar/dfn.language-configuration.json

@@ -0,0 +1,11 @@
+{
+  "comments": {
+    "lineComment": "#"
+  },
+  "brackets": [["[", "]"], ["<", ">"]],
+  "autoClosingPairs": [
+    { "open": "[", "close": "]" },
+    { "open": "\"", "close": "\"" }
+  ],
+  "surroundingPairs": [["[", "]"], ["<", ">"], ["\"", "\""]]
+}

package/grammar/dfn.tmLanguage.json

@@ -0,0 +1,251 @@
+{
+  "$schema": "https://raw.githubusercontent.com/martinring/tmlanguage/master/tmlanguage.json",
+  "name": "DFN",
+  "scopeName": "source.dfn",
+  "patterns": [
+    {
+      "include": "#comment"
+    },
+    {
+      "include": "#pragma"
+    },
+    {
+      "include": "#use"
+    },
+    {
+      "include": "#root"
+    },
+    {
+      "include": "#production"
+    },
+    {
+      "include": "#expression"
+    }
+  ],
+  "repository": {
+    "comment": {
+      "name": "comment.line.number-sign.dfn",
+      "match": "#.*$"
+    },
+    "string": {
+      "name": "string.quoted.double.dfn",
+      "begin": "\"",
+      "end": "\"",
+      "patterns": []
+    },
+    "pragma": {
+      "match": "^(id|title|description|scope)\\s+(?=\")",
+      "captures": {
+        "1": {
+          "name": "keyword.other.pragma.dfn"
+        }
+      }
+    },
+    "use": {
+      "match": "^(use)\\s+(?=\")",
+      "captures": {
+        "1": {
+          "name": "keyword.control.import.dfn"
+        }
+      }
+    },
+    "root": {
+      "match": "^(root)\\s*(=)",
+      "captures": {
+        "1": {
+          "name": "keyword.control.root.dfn"
+        },
+        "2": {
+          "name": "keyword.operator.assignment.dfn"
+        }
+      }
+    },
+    "production": {
+      "match": "^([A-Za-z][A-Za-z0-9-]*)\\s*(=)",
+      "captures": {
+        "1": {
+          "name": "entity.name.function.production.dfn"
+        },
+        "2": {
+          "name": "keyword.operator.assignment.dfn"
+        }
+      }
+    },
+    "expression": {
+      "patterns": [
+        {
+          "include": "#string"
+        },
+        {
+          "include": "#reference"
+        },
+        {
+          "include": "#range"
+        },
+        {
+          "include": "#number"
+        },
+        {
+          "include": "#operator"
+        },
+        {
+          "include": "#group"
+        },
+        {
+          "include": "#name"
+        }
+      ]
+    },
+    "reference": {
+      "patterns": [
+        {
+          "include": "#reference-imported"
+        },
+        {
+          "include": "#reference-local"
+        }
+      ]
+    },
+    "reference-imported": {
+      "begin": "(<)(@)",
+      "end": "(\\*)?(>)",
+      "beginCaptures": {
+        "1": {
+          "name": "punctuation.definition.reference.begin.dfn"
+        },
+        "2": {
+          "name": "punctuation.definition.imported.dfn"
+        }
+      },
+      "endCaptures": {
+        "1": {
+          "name": "keyword.operator.open-set.dfn"
+        },
+        "2": {
+          "name": "punctuation.definition.reference.end.dfn"
+        }
+      },
+      "patterns": [
+        {
+          "match": "([A-Za-z][A-Za-z0-9-]*)(/)([A-Za-z][A-Za-z0-9-]*)",
+          "captures": {
+            "1": {
+              "name": "entity.name.namespace.module.dfn"
+            },
+            "2": {
+              "name": "punctuation.separator.qualified.dfn"
+            },
+            "3": {
+              "name": "variable.other.reference.imported.dfn"
+            }
+          }
+        },
+        {
+          "include": "#reference-modifiers"
+        },
+        {
+          "name": "variable.other.reference.imported.dfn",
+          "match": "[A-Za-z][A-Za-z0-9-]*"
+        }
+      ]
+    },
+    "reference-local": {
+      "begin": "(<)",
+      "end": "(\\*)?(>)",
+      "beginCaptures": {
+        "1": {
+          "name": "punctuation.definition.reference.begin.dfn"
+        }
+      },
+      "endCaptures": {
+        "1": {
+          "name": "keyword.operator.open-set.dfn"
+        },
+        "2": {
+          "name": "punctuation.definition.reference.end.dfn"
+        }
+      },
+      "patterns": [
+        {
+          "include": "#reference-modifiers"
+        },
+        {
+          "name": "variable.other.reference.dfn",
+          "match": "[A-Za-z][A-Za-z0-9-]*"
+        }
+      ]
+    },
+    "reference-modifiers": {
+      "patterns": [
+        {
+          "name": "keyword.operator.omit.dfn",
+          "match": "!"
+        },
+        {
+          "begin": "\\[",
+          "end": "\\]",
+          "beginCaptures": {
+            "0": {
+              "name": "punctuation.definition.modifier.begin.dfn"
+            }
+          },
+          "endCaptures": {
+            "0": {
+              "name": "punctuation.definition.modifier.end.dfn"
+            }
+          },
+          "patterns": [
+            {
+              "name": "variable.parameter.member.dfn",
+              "match": "[A-Za-z][A-Za-z0-9-]*|\\d+"
+            },
+            {
+              "name": "punctuation.separator.comma.dfn",
+              "match": ","
+            }
+          ]
+        }
+      ]
+    },
+    "range": {
+      "name": "constant.numeric.range.dfn",
+      "match": "\\d+-\\d+[*/]\\d+(?:\\.\\d+)?(?:~\\d+)?"
+    },
+    "number": {
+      "name": "constant.numeric.dfn",
+      "match": "\\b\\d+\\b"
+    },
+    "operator": {
+      "patterns": [
+        {
+          "name": "keyword.operator.optional.dfn",
+          "match": "\\?"
+        },
+        {
+          "name": "keyword.operator.dfn",
+          "match": "[|.=]"
+        }
+      ]
+    },
+    "group": {
+      "patterns": [
+        {
+          "name": "punctuation.definition.group.begin.dfn",
+          "match": "\\["
+        },
+        {
+          "name": "keyword.operator.open-set.dfn",
+          "match": "\\*(?=\\s*\\])"
+        },
+        {
+          "name": "punctuation.definition.group.end.dfn",
+          "match": "\\]"
+        }
+      ]
+    },
+    "name": {
+      "name": "constant.language.name.dfn",
+      "match": "[A-Za-z][A-Za-z0-9-]*"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertekum/schema-builder",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Declare token vocabularies as grammar; build them into JSON Schema files",
   "license": "Apache-2.0",
   "keywords": [
@@ -19,6 +19,7 @@
   "bugs": "https://github.com/moros-oxus/vertekum/issues",
   "files": [
     "CHANGELOG.md",
+    "grammar",
     "src",
     "tsconfig.json",
     "!src/**/*.test.ts"
@@ -35,13 +36,13 @@
     "./cli": "./src/cli.ts"
   },
   "peerDependencies": {
-    "@vertekum/core": "0.1.1"
+    "@vertekum/core": "0.1.2"
   },
   "dependencies": {
     "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@vertekum/core": "0.1.1",
+    "@vertekum/core": "0.1.2",
     "@vertekum/schema-vocabulary": "0.1.0"
   }
 }

package/src/ast.ts

@@ -7,8 +7,8 @@
 
 /** A parsed module: imports, named productions, and the reserved `root` (absent in fragments). */
 export interface Module {
-  /** `use "<specifier>"` statements, in order: relative paths or package specifiers. */
-  uses: string[];
+  /** `use "<specifier>" [as <alias>]` statements, in order. */
+  uses: Array<{ spec: string; alias?: string }>;
   /** Productions by name. `root` is never stored here. */
   productions: Map<string, Node>;
   /** The reserved `root` production, when declared. */
@@ -56,12 +56,21 @@ export interface Name {
   value: string;
 }
 
-/** `min-max/step` — an inclusive numeric name set, enumerated at build time. */
+/**
+ * A numeric name scale, enumerated at build time. `min-max/step` is additive;
+ * `min-max*factor` is geometric (fractional factors allowed), optionally quantized to the
+ * nearest multiple of `quantum` (`~4`). A leading zero on a written endpoint (`025`)
+ * declares the zero-pad width for every emitted name.
+ */
 export interface Range {
   kind: 'range';
   min: number;
   max: number;
+  mode: 'stepped' | 'multiplied';
+  /** The additive step, or the geometric factor. */
   step: number;
+  quantum?: number;
+  pad?: number;
 }
 
 /**

package/src/build.ts

@@ -1,3 +1,4 @@
+import { evaluateScale } from '@vertekum/core';
 import type { Node, Ref } from './ast';
 import { DfnError } from './error';
 import type { ResolvedModule } from './resolve';
@@ -59,11 +60,11 @@ function target(ref: Ref, scope: Scope): { node: Node; scope: Scope } {
   }
 
   const hits: Array<{ node: Node; scope: Scope }> = [];
-  for (const imported of scope.module.imports.values()) {
+  for (const [key, imported] of scope.module.imports) {
     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) {
+    if (key === ref.name && imported.module.root) {
       hits.push({ node: imported.module.root, scope: importedScope });
     }
   }
@@ -93,9 +94,44 @@ function evaluate(node: Node, scope: Scope, tail: () => TreeNode): TreeNode {
       return forest;
     }
     case 'range': {
+      // One authority for scale names (and, later, token values): core's evaluateScale.
+      let scale: ReturnType<typeof evaluateScale>;
+      try {
+        scale = evaluateScale(
+          node.mode === 'stepped'
+            ? {
+                kind: 'stepped',
+                min: node.min,
+                max: node.max,
+                step: node.step,
+                pad: node.pad,
+              }
+            : {
+                kind: 'multiplied',
+                min: node.min,
+                max: node.max,
+                factor: node.step,
+                quantum: node.quantum,
+                pad: node.pad,
+              },
+        );
+      } catch (error) {
+        throw new DfnError(
+          error instanceof Error ? error.message : String(error),
+          1,
+          1,
+        );
+      }
+      if (scale.collisions.length > 0) {
+        throw new DfnError(
+          `scale steps ${scale.collisions.join(', ')} quantize onto earlier names — the quantum is too coarse for the factor`,
+          1,
+          1,
+        );
+      }
       const forest = leaf();
-      for (let n = node.min; n <= node.max; n += node.step) {
-        forest.children.set(String(n), tail());
+      for (const name of scale.names) {
+        forest.children.set(name, tail());
       }
       return forest;
     }

package/src/cli.ts

@@ -25,14 +25,19 @@ 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 }),
@@ -77,7 +82,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/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.
@@ -168,6 +174,19 @@ 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();
     switch (token.kind) {
@@ -175,19 +194,48 @@ class Parser {
       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) {
+        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 and a non-zero step',
+            'range needs max >= min',
             token.line,
             token.column,
           );
         }
-        return { kind: 'range', min, max, step };
+        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 };
+        }
+        if (step <= 1) {
+          throw new DfnError(
+            'a multiplied range needs a factor greater than one',
+            token.line,
+            token.column,
+          );
+        }
+        return {
+          kind: 'range',
+          min,
+          max,
+          mode: 'multiplied',
+          step,
+          quantum,
+          pad,
+        };
       }
       case 'langle': {
         const imported = this.peek().kind === 'at';
@@ -216,10 +264,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) {

package/src/resolve.ts

@@ -58,13 +58,18 @@ export function resolveModule(
   const module = parse(source);
 
   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,