@vertekum/schema-builder 0.1.6 → 0.2.0

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.6",
+  "version": "0.2.0",
   "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.0"
   },
   "dependencies": {
     "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@vertekum/core": "0.1.2",
+    "@vertekum/core": "0.2.0",
     "@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. */