@vertekum/schema-builder 0.1.4 → 0.1.5

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertekum/schema-builder",
-  "version": "0.1.4",
+  "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",

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

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