@vertekum/schema-builder 0.1.4 → 0.1.6

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

@@ -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.4",
+  "version": "0.1.6",
   "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",

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

@@ -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,7 +60,7 @@ 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;
 }
@@ -62,7 +71,7 @@ export interface Name {
  * 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 {
+export interface Range extends Position {
   kind: 'range';
   min: number;
   max: number;
@@ -78,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;
@@ -90,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

@@ -38,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 };
   }
@@ -47,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,
@@ -69,13 +77,17 @@ function target(ref: Ref, scope: Scope): { node: Node; scope: Scope } {
     }
   }
   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];
@@ -118,15 +130,15 @@ function evaluate(node: Node, scope: Scope, tail: () => TreeNode): TreeNode {
       } catch (error) {
         throw new DfnError(
           error instanceof Error ? error.message : String(error),
-          1,
-          1,
+          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`,
-          1,
-          1,
+          node.line,
+          node.column,
         );
       }
       const forest = leaf();
@@ -172,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);
       }
@@ -182,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,
           );
         }
       }
@@ -192,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,
             );
           }
         }
@@ -256,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);
@@ -271,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.
@@ -294,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;
@@ -304,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,
           );
         }
       }

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';
 
 /**
@@ -44,6 +45,55 @@ export function buildModule(
   };
 }
 
+/**
+ * `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',

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;
   }
 }