@vertekum/schema-builder 0.1.7 → 0.2.1

package/docs/scales.md

@@ -1,22 +1,25 @@
 # Scale expressions
 
 A scale expression enumerates a numeric name set at build time — `100-900/100` instead
-of nine names by hand. Two modes:
+of nine names by hand. Two modes, plus word affixes around either:
 
 | Syntax                 | Mode                                                                  |
 | ---------------------- | --------------------------------------------------------------------- |
 | [`min-max/step`](#additive-scales)    | **additive** — arithmetic steps                        |
 | [`min-max*factor~quantum`](#geometric-scales) | **geometric** — a ratio, optionally quantized  |
+| [`(formula)xs`, `xs(formula)`, `x(formula)s`](#affixed-scales) | **affixed** — word fragments wrapping the names |
 
 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`.
+`min-max/step`: from `min`, adding `step`, up to and including `max`. The step is
+optional — `2-4` means `2-4/1`.
 
 ```dfn
 scale = 100-900/100     # 100 200 300 400 500 600 700 800 900
+steps = 2-4             # 2 3 4
 ```
 
 Different regions of one scale are alternation:
@@ -59,6 +62,30 @@ type-scale = 16-64*1.25~4
 
 (The next raw step, 76.29…, exceeds 64 — the series ends.)
 
+## Affixed scales
+
+A parenthesized formula may carry word fragments on either or both ends, as **one
+term** — no whitespace between affix and parenthesis. The full formula grammar applies
+inside the parentheses:
+
+| Expression       | Names                          |
+| ---------------- | ------------------------------- |
+| `(2-4)xs`        | `2xs 3xs 4xs`                   |
+| `xs(2-4)`        | `xs2 xs3 xs4`                   |
+| `x(2-8/2)s`      | `x2s x4s x6s x8s`               |
+| `(02-08/2)xxl`   | `02xxl 04xxl 06xxl 08xxl`       |
+| `(16-64*1.25~4)` | `16 20 24 32 40 48 60` — bare parentheses are grouping only |
+
+An affix is a word fragment: letters first, then letters, digits, and hyphens. The
+affixes wrap the **name**; the numeric series underneath is unchanged — padding sits
+inside the affixes (`02xxl`, never `xxl02` from a suffix form), and every rule below
+(inclusive bounds, integrality, collisions) binds on the numbers exactly as if the
+affixes were not there. One formula per term — `(2-4)x(1-2)` is refused.
+
+```dfn
+t-shirt = (2-4)xs | xsmall | small | medium | large | x(2-8/2)l
+```
+
 ## The semantics, precisely
 
 These rules are fixed; the same evaluator (in `@vertekum/core`) generates the names

package/grammar/dfn.tmLanguage.json

@@ -34,7 +34,7 @@
       "patterns": []
     },
     "pragma": {
-      "match": "^(id|title|description|scope)\\s+(?=\")",
+      "match": "^(id|title|description|scope|sealed)\\s+(?=\")",
       "captures": {
         "1": {
           "name": "keyword.other.pragma.dfn"
@@ -61,12 +61,15 @@
       }
     },
     "production": {
-      "match": "^(\\d+[A-Za-z][A-Za-z0-9-]*|[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"
+          "name": "storage.modifier.private.dfn"
         },
         "2": {
+          "name": "entity.name.function.production.dfn"
+        },
+        "3": {
           "name": "keyword.operator.assignment.dfn"
         }
       }
@@ -79,6 +82,9 @@
         {
           "include": "#reference"
         },
+        {
+          "include": "#affixed-range"
+        },
         {
           "include": "#range"
         },
@@ -195,6 +201,9 @@
             }
           },
           "patterns": [
+            {
+              "include": "#reference"
+            },
             {
               "name": "variable.parameter.member.dfn",
               "match": "\\d+[A-Za-z][A-Za-z0-9-]*|[A-Za-z][A-Za-z0-9-]*|\\d+"
@@ -209,7 +218,7 @@
     },
     "range": {
       "name": "constant.numeric.range.dfn",
-      "match": "\\d+-\\d+[*/]\\d+(?:\\.\\d+)?(?:~\\d+)?"
+      "match": "\\d+-\\d+(?:[*/]\\d+(?:\\.\\d+)?)?(?:~\\d+)?"
     },
     "number": {
       "name": "constant.numeric.dfn",
@@ -246,6 +255,26 @@
     "name": {
       "name": "constant.language.name.dfn",
       "match": "\\d+[A-Za-z][A-Za-z0-9-]*|[A-Za-z][A-Za-z0-9-]*"
+    },
+    "affixed-range": {
+      "match": "([A-Za-z][A-Za-z0-9-]*)?(\\()(\\d+-\\d+(?:[*/]\\d+(?:\\.\\d+)?)?(?:~\\d+)?)(\\))([A-Za-z][A-Za-z0-9-]*)?",
+      "captures": {
+        "1": {
+          "name": "constant.language.name.dfn"
+        },
+        "2": {
+          "name": "punctuation.definition.scale.begin.dfn"
+        },
+        "3": {
+          "name": "constant.numeric.range.dfn"
+        },
+        "4": {
+          "name": "punctuation.definition.scale.end.dfn"
+        },
+        "5": {
+          "name": "constant.language.name.dfn"
+        }
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertekum/schema-builder",
-  "version": "0.1.7",
+  "version": "0.2.1",
   "description": "Declare token vocabularies as grammar; build them into JSON Schema files",
   "license": "Apache-2.0",
   "keywords": [
@@ -37,13 +37,13 @@
     "./cli": "./src/cli.ts"
   },
   "peerDependencies": {
-    "@vertekum/core": "0.1.2"
+    "@vertekum/core": "0.2.1"
   },
   "dependencies": {
     "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@vertekum/schema-vocabulary": "0.1.0",
-    "@vertekum/core": "0.1.2"
+    "@vertekum/core": "0.2.1",
+    "@vertekum/schema-vocabulary": "0.1.0"
   }
 }

package/src/api.ts

@@ -1,5 +1,5 @@
 import type { ActivateContext } from '@vertekum/core';
-import { schemaBuildCommand, schemaLintCommand } from './cli';
+import { schemaBuildCommand, schemaFmtCommand, schemaLintCommand } from './cli';
 import type { schemaBuilderManifest } from './index';
 
 export {
@@ -8,16 +8,29 @@ export {
   evaluateProduction,
   type TreeNode,
 } from './build';
-export { buildModule, schemaBuildCommand, schemaLintCommand } from './cli';
+export {
+  buildModule,
+  schemaBuildCommand,
+  schemaFmtCommand,
+  schemaLintCommand,
+} from './cli';
 export { emit, isStamped, STAMP_PREFIX, stamp } from './emit';
+export {
+  type DfnFix,
+  type FormatOptions,
+  fixSource,
+  formatSource,
+  resolveIndent,
+} from './format';
 export { type DfnDiagnostic, lintModule } from './lint';
 export { parse } from './parser';
 export { type ResolvedModule, resolveModule } from './resolve';
 
-/** Headless activation: contributes the `schema build` and `schema lint` commands. */
+/** Headless activation: contributes the `schema build`, `schema lint`, and `schema fmt` commands. */
 export function activate(
   ctx: ActivateContext<typeof schemaBuilderManifest>,
 ): void {
   ctx.commands.register(schemaBuildCommand);
   ctx.commands.register(schemaLintCommand);
+  ctx.commands.register(schemaFmtCommand);
 }

package/src/ast.ts

@@ -9,12 +9,16 @@
 export interface Module {
   /** `use "<specifier>" [as <alias>]` statements, in order. */
   uses: Array<{ spec: string; alias?: string }>;
-  /** Productions by name. `root` is never stored here. */
+  /** Productions by name, declaration order. `root` is never stored here. */
   productions: Map<string, Node>;
+  /** Productions declared `:name = …` — invisible to importers, always inlined. */
+  private: Set<string>;
   /** The reserved `root` production, when declared. */
   root: Node | undefined;
-  /** Pragmas (`id "…"`, `title "…"`, `description "…"`) — document metadata for emission. */
+  /** Pragmas — document metadata and the file's nature. */
   meta: ModuleMeta;
+  /** Lint-surfaced notes recorded while parsing (deprecated forms), with positions. */
+  notes: Array<{ line: number; column: number; message: string }>;
 }
 
 /** The pragma statements a module may carry, each at most once. */
@@ -23,11 +27,17 @@ export interface ModuleMeta {
   title?: string;
   description?: string;
   /**
-   * `scope "branch"`: the schema governs only the top-level branches it names — the document
-   * root stays unsealed, so sibling vocabularies can bind over the same files. The default,
-   * `document`, seals the root: nothing beyond the granted names may exist.
+   * The file's NATURE. `document`: emitted, root required — consumers reference its
+   * top-level names. `def`: emitted, root optional — a pattern source; its root also
+   * lands as `$defs.<filename>`. `inline`: never emitted — expansion only. Absent:
+   * root → document, rootless → def.
    */
-  scope?: 'document' | 'branch';
+  scope?: 'document' | 'def' | 'inline';
+  /**
+   * `sealed "false"` leaves the document top unsealed so sibling vocabularies can bind
+   * over the same files. Default true. (`scope "branch"` parses as a deprecated alias.)
+   */
+  sealed?: boolean;
 }
 
 export type Node = Alt | Path | Name | Range | Ref | Group;
@@ -80,12 +90,16 @@ export interface Range extends Position {
   step: number;
   quantum?: number;
   pad?: number;
+  /** Name affixes from the parenthesized form (`(2-4)xs`); values stay numeric. */
+  prefix?: string;
+  suffix?: string;
 }
 
 /**
  * `<name>` / `<@name>`; `open` records a trailing `*` (the set admits additions). Set
  * modifiers: `[a, b]` is PICK (only the listed members), `![a, b]` is OMIT (the set minus
- * them) — a modified reference is a new set.
+ * them) — a modified reference is a new set. A member may itself be a REFERENCE, denoting
+ * every name in the referenced set (set algebra with sets as operands).
  */
 export interface Ref extends Position {
   kind: 'ref';
@@ -94,8 +108,8 @@ export interface Ref extends Position {
   /** `<@module/production>` — resolve `name` in this import alone (the collision resolver). */
   from?: string;
   open: boolean;
-  pick: string[];
-  omit: string[];
+  pick: Array<string | Ref>;
+  omit: Array<string | Ref>;
 }
 
 /** `[ … ]`; `open` records a trailing `*` before the closing bracket. */

package/src/build.ts

@@ -1,3 +1,4 @@
+import { basename } from 'node:path';
 import { evaluateScale } from '@vertekum/core';
 import type { Node, Ref } from './ast';
 import { DfnError } from './error';
@@ -11,14 +12,39 @@ import type { ResolvedModule } from './resolve';
 export interface TreeNode {
   children: Map<string, TreeNode>;
   open: boolean;
-  denotation?: string;
+  /**
+   * PATTERNS whose full member sets landed at this position — unmodified terminal
+   * references to public productions (local or imported) or to an imported def-scope
+   * module's root. Emission deep-checks each against the position's children and, when
+   * intact, emits a `$ref` to the pattern's `$def` instead of expanding; a merge that
+   * grew a member drops the pattern back to expansion. Keyed collision-proof.
+   */
+  patterns?: Map<string, PatternRef>;
+  /**
+   * This subtree is verbatim one top-level branch of an imported DOCUMENT module's own
+   * artifact. Emission MAY replace it with a `$ref` into `…#/properties/<top>` (linked
+   * mode); inline mode ignores the tag.
+   */
+  link?: { module: ResolvedModule; top: string };
+}
+
+/** One pattern source: a production (local when `module` is absent) or a def-scope root. */
+export interface PatternRef {
+  name: string;
+  module?: ResolvedModule;
+  /** The pattern is the module's ROOT def (`$defs.<filename>`), not a production. */
+  root?: boolean;
 }
 
 const leaf = (): TreeNode => ({ children: new Map(), open: false });
 
 function merge(into: TreeNode, from: TreeNode): void {
   into.open = into.open || from.open;
-  if (into.denotation !== from.denotation) into.denotation = undefined;
+  into.link = undefined;
+  if (from.patterns) {
+    into.patterns = into.patterns ?? new Map();
+    for (const [key, ref] of from.patterns) into.patterns.set(key, ref);
+  }
   for (const [name, child] of from.children) {
     const existing = into.children.get(name);
     if (existing) merge(existing, child);
@@ -31,17 +57,23 @@ interface Scope {
   module: ResolvedModule;
   /** Local productions currently expanding, for reference-cycle detection. */
   expanding: Set<string>;
+  /** Lint's warning sink (open-merge, …); absent in plain builds. */
+  warn?: (file: string, line: number, column: number, message: string) => void;
 }
 
 /** The `<@key/name>, …` listing a miss suggests — an error should name the fix, not just the gap. */
 function productionsOf(key: string, imported: ResolvedModule): string {
   return [...imported.module.productions.keys()]
+    .filter((p) => !imported.module.private.has(p))
     .map((p) => `<@${key}/${p}>`)
     .join(', ');
 }
 
 /** Find what `<name>` / `<@name>` means in this scope. Imported roots go by module name. */
-function target(ref: Ref, scope: Scope): { node: Node; scope: Scope } {
+function target(
+  ref: Ref,
+  scope: Scope,
+): { node: Node; scope: Scope; importedRoot?: ResolvedModule } {
   // Every error here names the module whose TEXT holds the ref — `scope.module` — so a
   // failure inside an imported production's body is attributed to that file, not to
   // whichever module the walk started from.
@@ -71,6 +103,14 @@ function target(ref: Ref, scope: Scope): { node: Node; scope: Scope } {
       );
     }
     const production = imported.module.productions.get(ref.name);
+    if (production && imported.module.private.has(ref.name)) {
+      throw new DfnError(
+        `'${ref.name}' is private to ${basename(imported.path)} — its public productions: ${productionsOf(ref.from, imported)}`,
+        ref.line,
+        ref.column,
+        file,
+      );
+    }
     if (!production) {
       throw new DfnError(
         `'${ref.from}' has no production '${ref.name}' — it declares: ${productionsOf(ref.from, imported)}`,
@@ -81,17 +121,31 @@ function target(ref: Ref, scope: Scope): { node: Node; scope: Scope } {
     }
     return {
       node: production,
-      scope: { module: imported, expanding: new Set() },
+      scope: { module: imported, expanding: new Set(), warn: scope.warn },
     };
   }
 
-  const hits: Array<{ node: Node; scope: Scope }> = [];
+  const hits: Array<{
+    node: Node;
+    scope: Scope;
+    importedRoot?: ResolvedModule;
+  }> = [];
   for (const [key, imported] of scope.module.imports) {
-    const importedScope: Scope = { module: imported, expanding: new Set() };
+    const importedScope: Scope = {
+      module: imported,
+      expanding: new Set(),
+      warn: scope.warn,
+    };
     const production = imported.module.productions.get(ref.name);
-    if (production) hits.push({ node: production, scope: importedScope });
+    if (production && !imported.module.private.has(ref.name)) {
+      hits.push({ node: production, scope: importedScope });
+    }
     if (key === ref.name && imported.module.root) {
-      hits.push({ node: imported.module.root, scope: importedScope });
+      hits.push({
+        node: imported.module.root,
+        scope: importedScope,
+        importedRoot: imported,
+      });
     }
   }
   if (hits.length === 0) {
@@ -148,6 +202,8 @@ function evaluate(node: Node, scope: Scope, tail: () => TreeNode): TreeNode {
                 max: node.max,
                 step: node.step,
                 pad: node.pad,
+                prefix: node.prefix,
+                suffix: node.suffix,
               }
             : {
                 kind: 'multiplied',
@@ -156,6 +212,8 @@ function evaluate(node: Node, scope: Scope, tail: () => TreeNode): TreeNode {
                 factor: node.step,
                 quantum: node.quantum,
                 pad: node.pad,
+                prefix: node.prefix,
+                suffix: node.suffix,
               },
         );
       } catch (error) {
@@ -182,9 +240,26 @@ function evaluate(node: Node, scope: Scope, tail: () => TreeNode): TreeNode {
     }
     case 'alt': {
       const forest = leaf();
-      for (const option of node.options) {
-        merge(forest, evaluate(option, scope, tail));
+      const forests = node.options.map((option) => ({
+        option,
+        forest: evaluate(option, scope, tail),
+      }));
+      // Opening a subset of a position's set opens the WHOLE position — additions carry
+      // no mark of which family they claim. Legal, but never silent.
+      const open = forests.find((f) => f.forest.open);
+      const closed = forests.find(
+        (f) => !f.forest.open && f.forest.children.size > 0,
+      );
+      if (open && closed && scope.warn) {
+        const at = open.option as { line?: number; column?: number };
+        scope.warn(
+          scope.module.path,
+          at.line ?? 1,
+          at.column ?? 1,
+          'an open set merges with closed siblings here — the whole position becomes open (additions are permitted beside every member)',
+        );
       }
+      for (const f of forests) merge(forest, f.forest);
       return forest;
     }
     case 'path': {
@@ -214,7 +289,11 @@ function evaluate(node: Node, scope: Scope, tail: () => TreeNode): TreeNode {
       return forest;
     }
     case 'ref': {
-      const { node: production, scope: refScope } = target(node, scope);
+      const {
+        node: production,
+        scope: refScope,
+        importedRoot,
+      } = target(node, scope);
       if (!node.imported) {
         if (scope.expanding.has(node.name)) {
           throw new DfnError(
@@ -228,7 +307,21 @@ function evaluate(node: Node, scope: Scope, tail: () => TreeNode): TreeNode {
       }
       const forest = evaluate(production, refScope, tail);
       if (!node.imported) scope.expanding.delete(node.name);
-      for (const omitted of node.omit) {
+      // Set-valued operands: a member REFERENCE contributes every top-level name of the
+      // set it denotes (evaluated in this scope, privacy and all); strings pass through.
+      const expandOperands = (list: Ref['omit']): string[] => {
+        const out: string[] = [];
+        for (const member of list) {
+          if (typeof member === 'string') {
+            out.push(member);
+            continue;
+          }
+          const operand = evaluate(member, scope, leaf);
+          for (const name of operand.children.keys()) out.push(name);
+        }
+        return out;
+      };
+      for (const omitted of expandOperands(node.omit)) {
         if (!forest.children.delete(omitted)) {
           throw new DfnError(
             `'<${node.name}>' has no member '${omitted}' to omit`,
@@ -239,7 +332,8 @@ function evaluate(node: Node, scope: Scope, tail: () => TreeNode): TreeNode {
         }
       }
       if (node.pick.length > 0) {
-        for (const picked of node.pick) {
+        const picks = expandOperands(node.pick);
+        for (const picked of picks) {
           if (!forest.children.has(picked)) {
             throw new DfnError(
               `'<${node.name}>' has no member '${picked}' to pick`,
@@ -249,20 +343,56 @@ function evaluate(node: Node, scope: Scope, tail: () => TreeNode): TreeNode {
             );
           }
         }
-        const keep = new Set(node.pick);
+        const keep = new Set(picks);
         for (const name of [...forest.children.keys()]) {
           if (!keep.has(name)) forest.children.delete(name);
         }
       }
       if (node.open) forest.open = true;
-      // A modified set is a different set — it never shares the source denotation's $def.
-      if (
-        node.pick.length === 0 &&
-        node.omit.length === 0 &&
-        isNameSet(production) &&
-        isTerminal(tail())
-      ) {
-        forest.denotation = node.name;
+      const unmodified =
+        node.pick.length === 0 && node.omit.length === 0 && !node.open;
+      // A modified set is a different set — it never shares a pattern's $def; a tail
+      // forces expansion (a $ref cannot be parameterized). Tags are inert unless
+      // emission chooses to reference them.
+      if (unmodified && isTerminal(tail())) {
+        if (importedRoot) {
+          const nature =
+            importedRoot.module.meta.scope ??
+            (importedRoot.module.root ? 'document' : 'def');
+          if (nature === 'document') {
+            // Verbatim top-level branches of the child DOCUMENT's artifact.
+            for (const [top, child] of forest.children) {
+              child.link = { module: importedRoot, top };
+            }
+          } else if (nature === 'def') {
+            forest.patterns = forest.patterns ?? new Map();
+            forest.patterns.set(`@${importedRoot.path}//root`, {
+              name: importedRoot.name,
+              module: importedRoot,
+              root: true,
+            });
+          }
+          // inline nature: pure expansion, no tag.
+        } else if (!node.imported) {
+          if (!scope.module.module.private.has(node.name)) {
+            forest.patterns = forest.patterns ?? new Map();
+            forest.patterns.set(node.name, { name: node.name });
+          }
+        } else {
+          // An imported PRODUCTION (qualified or search-resolved): public by
+          // construction (target refuses privates). Pattern in the child's artifact
+          // unless the child is inline-natured.
+          const child = refScope.module;
+          const nature =
+            child.module.meta.scope ?? (child.module.root ? 'document' : 'def');
+          if (nature !== 'inline') {
+            forest.patterns = forest.patterns ?? new Map();
+            forest.patterns.set(`@${child.path}/${node.name}`, {
+              name: node.name,
+              module: child,
+            });
+          }
+        }
       }
       return forest;
     }
@@ -277,6 +407,9 @@ function isNameSet(node: Node): boolean {
       return true;
     case 'alt':
       return node.options.every(isNameSet);
+    case 'group':
+      // Decorative brackets do not change a set's nature.
+      return isNameSet(node.node);
     default:
       return false;
   }
@@ -287,7 +420,17 @@ function isTerminal(node: TreeNode): boolean {
 }
 
 /** Expand a module's root into its name tree. Fragments-only modules cannot build. */
-export function build(resolved: ResolvedModule): TreeNode {
+export function build(
+  resolved: ResolvedModule,
+  options: {
+    warn?: (
+      file: string,
+      line: number,
+      column: number,
+      message: string,
+    ) => void;
+  } = {},
+): TreeNode {
   const root = resolved.module.root;
   if (!root) {
     throw new DfnError(
@@ -297,7 +440,11 @@ export function build(resolved: ResolvedModule): TreeNode {
       resolved.path,
     );
   }
-  const scope: Scope = { module: resolved, expanding: new Set() };
+  const scope: Scope = {
+    module: resolved,
+    expanding: new Set(),
+    warn: options.warn,
+  };
 
   // An aggregate root unions imported roots; the same top-level name arriving from two different
   // module refs is a collision, not a merge — each module owns its top. `[a | b]` and `a | b`
@@ -338,12 +485,17 @@ export function build(resolved: ResolvedModule): TreeNode {
 export function evaluateProduction(
   resolved: ResolvedModule,
   name: string,
+  warn?: (file: string, line: number, column: number, message: string) => void,
 ): 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]) };
+  const scope: Scope = {
+    module: resolved,
+    expanding: new Set([name]),
+    warn,
+  };
   return evaluate(production, scope, leaf);
 }