@vertekum/schema-builder 0.1.3 → 0.1.5

package/docs/lint.md

@@ -0,0 +1,59 @@
+# `vertekum schema lint`
+
+Validate the `.dfn` sources themselves — fragments included, every production evaluated —
+without building anything.
+
+```bash
+# vertekum schema lint [module] [--json] [--cwd <dir>]
+vertekum schema lint                        # every module under ./schemas
+vertekum schema lint schemas/color.dfn      # one module — fragment or rooted
+```
+
+| Argument / flag | What it does                                                                 |
+| --------------- | ----------------------------------------------------------------------------- |
+| `[module]`      | A `.dfn` file, relative to the working directory. Default: every module under `./schemas`, recursively — **fragments included**. |
+| `--json`        | Machine-readable result.                                                       |
+| `--cwd <dir>`   | Project discovery starts here.                                                 |
+
+Exit `0` when the grammar is sound, `1` with findings — one per line, positioned:
+
+```
+2 problem(s) in the .dfn modules:
+  schemas/emphasis.dfn:1:21 unknown production '<missing>'
+  schemas/scale.dfn:1:14 '*' marks a set open and sits inside the reference or group it opens — <name*> or [a | b *]
+```
+
+## What lint checks that a build does not
+
+A build expands from `root`, so its validation reaches exactly what a root reaches.
+Lint's contract is the source:
+
+- **Fragments** — a module with no `root` never builds, but lint evaluates its
+  productions, so a broken denotation is caught in the file that declares it, not
+  months later in the first module that imports it.
+- **Unused productions** — a rooted module's production that nothing references yet is
+  still checked.
+- **Everything a build would refuse** — unknown or ambiguous references, pick/omit
+  members that don't exist, scale collisions, `*` on a non-name set, reference cycles —
+  reported the same way, at the same positions.
+
+Findings **collect**: one broken production does not hide the next, so a module with
+three mistakes is one lint run, not three.
+
+## Sound vs. current
+
+`lint` and [`build --check`](./build.md#--check-the-staleness-gate) answer different
+questions:
+
+| Verb            | Question                    | Covers                                    |
+| --------------- | --------------------------- | ------------------------------------------ |
+| `schema lint`   | Is the grammar sound?       | Every `.dfn`, fragments and all; no artifacts touched. |
+| `schema build --check` | Are the artifacts current? | Rooted modules' built `.json` vs. disk.  |
+
+CI wants both — lint fails a broken fragment the staleness gate cannot see, and the
+staleness gate fails a sound grammar whose rebuild was forgotten.
+
+## Programmatic use
+
+`lintModule(path)` (from `@vertekum/schema-builder/api`) returns the findings as
+`{ file, line, column, message }` records — an empty array means sound.

package/docs/modules.md

@@ -0,0 +1,105 @@
+# Modules and composition
+
+A vocabulary rarely fits one file: denotations shared across aspects live in fragment
+modules, aspects live in their own modules, and one aggregate root unions them. `use`
+is the composition mechanism.
+
+```dfn
+# schema.dfn — the aggregate
+use "./color.dfn"
+use "./space.dfn"
+
+root = [<@color> | <@space>]
+```
+
+## `use`
+
+`use "<specifier>"` imports a module; everything it declares becomes referenceable.
+
+| Specifier form       | Example                              | Resolution                                                 |
+| -------------------- | ------------------------------------ | ----------------------------------------------------------- |
+| Relative path        | `use "./denotations/colors.dfn"`     | Relative to the importing module's own location.            |
+| Package specifier    | `use "@acme/vocabulary/color.dfn"`   | The package's `exports` map first; else the path joined to the package root — so a content package need not map every `.dfn` individually. |
+
+An import cycle is an authoring error, reported with the module that closes the loop.
+
+### Import keys and `as`
+
+Each import gets a **key**: its basename without `.dfn`, or the alias given with
+`as`. The key is how references address the import. Two imports landing on the same
+key — two `color.dfn` files from different directories — is an error naming the fix:
+
+```dfn
+use "./brand/color.dfn"
+use "./system/color.dfn" as system-color
+```
+
+### Accessing an import
+
+| Reference            | Means                                                                       |
+| -------------------- | ---------------------------------------------------------------------------- |
+| `<@key>`             | the imported module's **root** — the whole subtree it grants.                |
+| `<@name>`            | the production `name`, searched across every import; unambiguous or an error. |
+| `<@key/name>`        | qualified: that import's production alone — the collision resolver.           |
+
+When two imports both declare `<accent>`, the unqualified `<@accent>` refuses with the
+qualified form to use. Local productions (`<name>`, no `@`) never collide with imports.
+
+## Fragments
+
+A module without a `root` is a **fragment** — a library of denotations meant to be
+imported, never built:
+
+```dfn
+# denotations/emphasis.dfn
+emphasis = subtle | bold
+```
+
+The build sweep skips fragments with a notice (`… declares no root (a fragment) —
+skipped`); naming one explicitly as the build argument is an error, so a module whose
+`root` was mistyped cannot be silently skipped.
+
+## Aggregate roots
+
+A root that unions imported roots — `root = [<@color> | <@space>]` — composes a whole
+vocabulary from aspect modules. Each module owns its top-level names: the same
+top-level name arriving from two different imports is a **collision**, not a merge
+(`top-level 'color' comes from both 'color' and 'palette'`). To co-validate aspects as
+*separate* schemas over the same files instead, give each module
+[`scope "branch"`](./language.md#pragmas) and bind them side by side.
+
+## Nested directories
+
+Modules may nest — `schemas/color.dfn` beside `schemas/palette/color.dfn` — and the
+build preserves the structure: each built `.json` lands beside its own module. The
+provenance stamp records the module's project-relative path, so same-named modules in
+different directories stay distinguishable.
+
+## Shipping and ejecting grammar
+
+A package can ship its `.dfn` sources alongside the built schemas. An `exports` pattern
+keeps flat specifiers working over a nested layout:
+
+```json
+{
+  "exports": {
+    "./*.json": "./lib/*.json",
+    "./*.dfn": "./dfn/*.dfn"
+  }
+}
+```
+
+Consumers then eject the grammar rather than the generated JSON:
+
+```bash
+vertekum schema eject @acme/vocabulary/color.dfn ./schemas/color.dfn
+vertekum schema build
+```
+
+Editing an ejected module keeps changes one-line grammar edits with a rebuild, instead
+of surgery on generated schema. Two things to know:
+
+- An ejected module that `use`s **relative** imports needs them ejected alongside it
+  (package-specifier imports keep resolving).
+- What the `schemas` config binds is the **built `.json`**, never the `.dfn` — the
+  grammar is authoring source; core and `check` only ever see schema files.

package/docs/scales.md

@@ -0,0 +1,88 @@
+# Scale expressions
+
+A scale expression enumerates a numeric name set at build time — `100-900/100` instead
+of nine names by hand. Two modes:
+
+| Syntax                 | Mode                                                                  |
+| ---------------------- | --------------------------------------------------------------------- |
+| [`min-max/step`](#additive-scales)    | **additive** — arithmetic steps                        |
+| [`min-max*factor~quantum`](#geometric-scales) | **geometric** — a ratio, optionally quantized  |
+
+Both are inclusive at both ends, and both enumerate **names** — every step must land on
+a whole number, because a token name cannot be `31.25`.
+
+## Additive scales
+
+`min-max/step`: from `min`, adding `step`, up to and including `max`.
+
+```dfn
+scale = 100-900/100     # 100 200 300 400 500 600 700 800 900
+```
+
+Different regions of one scale are alternation:
+
+```dfn
+scale = 0 | 025-100/25 | 150-300/50 | 400-600/100 | 800 | 1000
+```
+
+### Zero-padding
+
+Write the numbers as they appear: a leading zero on a written endpoint declares the pad
+width for **every** emitted name of that range.
+
+```dfn
+scale = 025-100/25      # 025 050 075 100
+```
+
+## Geometric scales
+
+`min-max*factor`: from `min`, multiplying by `factor` (fractional ratios allowed), up
+to and including `max`. Raw geometric steps rarely land on whole numbers, so the mode
+pairs with quantization: `~quantum` rounds each step to the nearest multiple of
+`quantum`.
+
+The canonical case — a type scale, ratio 1.25, rounded to the nearest 4:
+
+```dfn
+type-scale = 16-64*1.25~4
+```
+
+| Raw step  | ×1.25 from | Quantized (~4) |
+| --------- | ---------- | -------------- |
+| 16        | —          | **16**         |
+| 20        | 16         | **20**         |
+| 25        | 20         | **24**         |
+| 31.25     | 25         | **32**         |
+| 39.0625   | 31.25      | **40**         |
+| 48.828125 | 39.0625    | **48**         |
+| 61.035…   | 48.828125  | **60**         |
+
+(The next raw step, 76.29…, exceeds 64 — the series ends.)
+
+## The semantics, precisely
+
+These rules are fixed; the same evaluator (in `@vertekum/core`) generates the names
+here and, in time, the values a token-side scale materializes — so a name can never
+drift from the value it mirrors.
+
+- **Bounds are inclusive and apply to the raw series.** A step enters while
+  `raw ≤ max`; the *quantized* value may stand just past a bound (a raw 62.5 with `~25`
+  emits 75 even when `max` is 70).
+- **Compounding is raw-basis.** The ratio always applies to the exact previous raw
+  value, never to a rounded one — rounding influences names, not the progression.
+- **Quantization is to the nearest multiple** of the quantum.
+- **Every emitted step must be a whole number.** A fractional step with no quantum is a
+  build error (`step 22.5 is not a whole number — names are names; quantize (~) or
+  adjust the scale`).
+- **Collisions are an error.** When two raw steps quantize onto the same name, the
+  build refuses, naming the colliding steps — the quantum is too coarse for the factor.
+  A silent dedupe would emit fewer names than the expression reads.
+
+## Constraints
+
+| Rule                    | Error otherwise                                    |
+| ----------------------- | -------------------------------------------------- |
+| `step > 0`, whole (additive) | a stepped scale needs a positive whole-number step |
+| `factor > 1` (geometric)| a multiplied scale needs a factor greater than one  |
+| `max ≥ min`             | a scale needs max >= min                            |
+| `~` only with `*`       | quantization belongs to the geometric mode          |

package/grammar/dfn.tmLanguage.json

@@ -209,7 +209,7 @@
     },
     "range": {
       "name": "constant.numeric.range.dfn",
-      "match": "\\d+-\\d+/\\d+"
+      "match": "\\d+-\\d+[*/]\\d+(?:\\.\\d+)?(?:~\\d+)?"
     },
     "number": {
       "name": "constant.numeric.dfn",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertekum/schema-builder",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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",
+    "docs",
     "grammar",
     "src",
     "tsconfig.json",
@@ -36,13 +37,13 @@
     "./cli": "./src/cli.ts"
   },
   "peerDependencies": {
-    "@vertekum/core": "0.1.1"
+    "@vertekum/core": "0.1.2"
   },
   "dependencies": {
     "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@vertekum/schema-vocabulary": "0.1.0",
-    "@vertekum/core": "0.1.1"
+    "@vertekum/core": "0.1.2",
+    "@vertekum/schema-vocabulary": "0.1.0"
   }
 }

package/src/api.ts

@@ -1,16 +1,23 @@
 import type { ActivateContext } from '@vertekum/core';
-import { schemaBuildCommand } from './cli';
+import { schemaBuildCommand, schemaLintCommand } from './cli';
 import type { schemaBuilderManifest } from './index';
 
-export { assertOpenSetsAreNameSets, build, type TreeNode } from './build';
-export { buildModule, schemaBuildCommand } from './cli';
+export {
+  assertOpenSetsAreNameSets,
+  build,
+  evaluateProduction,
+  type TreeNode,
+} from './build';
+export { buildModule, schemaBuildCommand, schemaLintCommand } from './cli';
 export { emit, isStamped, STAMP_PREFIX, stamp } from './emit';
+export { type DfnDiagnostic, lintModule } from './lint';
 export { parse } from './parser';
 export { type ResolvedModule, resolveModule } from './resolve';
 
-/** Headless activation: contributes the `schema build` command and nothing else. */
+/** Headless activation: contributes the `schema build` and `schema lint` commands. */
 export function activate(
   ctx: ActivateContext<typeof schemaBuilderManifest>,
 ): void {
   ctx.commands.register(schemaBuildCommand);
+  ctx.commands.register(schemaLintCommand);
 }

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. */
@@ -32,6 +32,15 @@ export interface ModuleMeta {
 
 export type Node = Alt | Path | Name | Range | Ref | Group;
 
+/**
+ * Where a node's source text begins. Carried on every node a later phase can fail on, so a build
+ * or lint error names the offending line rather than a placeholder.
+ */
+export interface Position {
+  line: number;
+  column: number;
+}
+
 /** `a | b | c` — set union of the options' name trees. */
 export interface Alt {
   kind: 'alt';
@@ -51,17 +60,26 @@ export interface Step {
 }
 
 /** A literal name segment — an identifier or a bare number. */
-export interface Name {
+export interface Name extends Position {
   kind: 'name';
   value: string;
 }
 
-/** `min-max/step` — an inclusive numeric name set, enumerated at build time. */
-export interface Range {
+/**
+ * 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 extends Position {
   kind: 'range';
   min: number;
   max: number;
+  mode: 'stepped' | 'multiplied';
+  /** The additive step, or the geometric factor. */
   step: number;
+  quantum?: number;
+  pad?: number;
 }
 
 /**
@@ -69,7 +87,7 @@ export interface Range {
  * modifiers: `[a, b]` is PICK (only the listed members), `![a, b]` is OMIT (the set minus
  * them) — a modified reference is a new set.
  */
-export interface Ref {
+export interface Ref extends Position {
   kind: 'ref';
   name: string;
   imported: boolean;
@@ -81,7 +99,7 @@ export interface Ref {
 }
 
 /** `[ … ]`; `open` records a trailing `*` before the closing bracket. */
-export interface Group {
+export interface Group extends Position {
   kind: 'group';
   node: Node;
   open: boolean;

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';
@@ -37,7 +38,11 @@ function target(ref: Ref, scope: Scope): { node: Node; scope: Scope } {
   if (!ref.imported) {
     const production = scope.module.module.productions.get(ref.name);
     if (!production) {
-      throw new DfnError(`unknown production '<${ref.name}>'`, 1, 1);
+      throw new DfnError(
+        `unknown production '<${ref.name}>'`,
+        ref.line,
+        ref.column,
+      );
     }
     return { node: production, scope };
   }
@@ -46,11 +51,15 @@ 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}'`, 1, 1);
+      throw new DfnError(`no import named '${ref.from}'`, ref.line, ref.column);
     }
     const production = imported.module.productions.get(ref.name);
     if (!production) {
-      throw new DfnError(`'${ref.from}' has no production '${ref.name}'`, 1, 1);
+      throw new DfnError(
+        `'${ref.from}' has no production '${ref.name}'`,
+        ref.line,
+        ref.column,
+      );
     }
     return {
       node: production,
@@ -59,22 +68,26 @@ 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 });
     }
   }
   if (hits.length === 0) {
-    throw new DfnError(`no import provides '<@${ref.name}>'`, 1, 1);
+    throw new DfnError(
+      `no import provides '<@${ref.name}>'`,
+      ref.line,
+      ref.column,
+    );
   }
   if (hits.length > 1) {
     throw new DfnError(
       `'<@${ref.name}>' is ambiguous across imports — qualify it: <@module/${ref.name}>`,
-      1,
-      1,
+      ref.line,
+      ref.column,
     );
   }
   return hits[0];
@@ -93,9 +106,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),
+          node.line,
+          node.column,
+        );
+      }
+      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`,
+          node.line,
+          node.column,
+        );
+      }
       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;
     }
@@ -136,7 +184,11 @@ function evaluate(node: Node, scope: Scope, tail: () => TreeNode): TreeNode {
       const { node: production, scope: refScope } = target(node, scope);
       if (!node.imported) {
         if (scope.expanding.has(node.name)) {
-          throw new DfnError(`'<${node.name}>' expands through itself`, 1, 1);
+          throw new DfnError(
+            `'<${node.name}>' expands through itself`,
+            node.line,
+            node.column,
+          );
         }
         scope.expanding.add(node.name);
       }
@@ -146,8 +198,8 @@ function evaluate(node: Node, scope: Scope, tail: () => TreeNode): TreeNode {
         if (!forest.children.delete(omitted)) {
           throw new DfnError(
             `'<${node.name}>' has no member '${omitted}' to omit`,
-            1,
-            1,
+            node.line,
+            node.column,
           );
         }
       }
@@ -156,8 +208,8 @@ function evaluate(node: Node, scope: Scope, tail: () => TreeNode): TreeNode {
           if (!forest.children.has(picked)) {
             throw new DfnError(
               `'<${node.name}>' has no member '${picked}' to pick`,
-              1,
-              1,
+              node.line,
+              node.column,
             );
           }
         }
@@ -220,8 +272,8 @@ export function build(resolved: ResolvedModule): TreeNode {
         if (owner && owner !== option.name) {
           throw new DfnError(
             `top-level '${name}' comes from both '${owner}' and '${option.name}'`,
-            1,
-            1,
+            option.line,
+            option.column,
           );
         }
         seen.set(name, option.name);
@@ -235,6 +287,24 @@ export function build(resolved: ResolvedModule): TreeNode {
   return tree;
 }
 
+/**
+ * Expand ONE production in isolation — the lint walk's unit. `build` stays root-only; this is what
+ * lets a fragment's productions (and a rooted module's unused ones) be validated at all. Seeding
+ * `expanding` with the production's own name makes direct self-reference a cycle, same as it is
+ * when reached from a root.
+ */
+export function evaluateProduction(
+  resolved: ResolvedModule,
+  name: string,
+): TreeNode {
+  const production = resolved.module.productions.get(name);
+  if (!production) {
+    throw new DfnError(`no production '${name}'`, 1, 1);
+  }
+  const scope: Scope = { module: resolved, expanding: new Set([name]) };
+  return evaluate(production, scope, leaf);
+}
+
 /**
  * Enforce that every `*` sat on a name-only set: evaluation flags are structural, so the check is
  * on the AST — walk refs/groups marked open and verify their expansion source.
@@ -258,7 +328,11 @@ export function assertOpenSetsAreNameSets(
       return;
     case 'group':
       if (node.open && !isNameSet(node.node)) {
-        throw new DfnError('* opens a set of names, not sub-paths', 1, 1);
+        throw new DfnError(
+          '* opens a set of names, not sub-paths',
+          node.line,
+          node.column,
+        );
       }
       assertOpenSetsAreNameSets(resolved, node.node, scope);
       return;
@@ -268,8 +342,8 @@ export function assertOpenSetsAreNameSets(
         if (!isNameSet(production)) {
           throw new DfnError(
             `'<${node.name}*>' opens a set, but the production is not name-only`,
-            1,
-            1,
+            node.line,
+            node.column,
           );
         }
       }