@vertekum/schema-builder 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @vertekum/schema-builder
+
+## 0.1.2
+
+### Patch Changes
+
+- [`579276d`](https://github.com/moros-oxus/vertekum/commit/579276d8c1ab7215f291037cebcad0e03ae8d170) Thanks [@tschemmer](https://github.com/tschemmer)! - `schema build` with no argument now skips fragment modules (files declaring no `root` — imports, noted in the summary) instead of failing; naming one explicitly is still an error. References gain a qualified form, `<@module/production>`, addressing one import's production by module basename — the resolver for name collisions across imports, which the ambiguity error now suggests.
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [[`34b1157`](https://github.com/moros-oxus/vertekum/commit/34b1157546027442bf98437699ea3b9da45ebe86)]:
+  - @vertekum/core@0.1.1

package/README.md

@@ -41,7 +41,9 @@ npx vertekum check                 # the built schema now governs your token nam
 
 `schema build` accepts a single module argument, defaults to every `.dfn` under
 `./schemas`, and supports `--dry-run` (list without writing), `--json`, and `--check`
-(verify built files are current; exit 1 when stale — the CI guard).
+(verify built files are current; exit 1 when stale — the CI guard). Only modules with a
+`root` build: the sweep skips fragment modules (denotation files that exist to be `use`d),
+while naming one explicitly is an error.
 
 ## The definition language
 
@@ -67,6 +69,7 @@ indented line continues the statement above it.
 | `[ … ]` | grouping; groups may hold full sub-paths (branches) |
 | `<name>` | reference a local production |
 | `<@name>` | reference an imported production; an imported module's *root* goes by its basename |
+| `<@module/name>` | qualified: that import's production alone — the resolver when two imports share a name |
 | `<name [a, b]>` | **pick** — only the listed members of the set |
 | `<name ![a, b]>` | **omit** — the set minus the listed members |
 | `<name*>` / `[a \| b *]` | **open set** — additions beyond the listed names are permitted, and every member (listed or added) takes the same tail |

package/package.json

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

package/src/ast.ts

@@ -73,6 +73,8 @@ export interface Ref {
   kind: 'ref';
   name: string;
   imported: boolean;
+  /** `<@module/production>` — resolve `name` in this import alone (the collision resolver). */
+  from?: string;
   open: boolean;
   pick: string[];
   omit: string[];

package/src/build.ts

@@ -42,6 +42,22 @@ function target(ref: Ref, scope: Scope): { node: Node; scope: Scope } {
     return { node: production, scope };
   }
 
+  // Qualified: `<@module/production>` looks in that import alone — the collision resolver.
+  if (ref.from) {
+    const imported = scope.module.imports.get(ref.from);
+    if (!imported) {
+      throw new DfnError(`no import named '${ref.from}'`, 1, 1);
+    }
+    const production = imported.module.productions.get(ref.name);
+    if (!production) {
+      throw new DfnError(`'${ref.from}' has no production '${ref.name}'`, 1, 1);
+    }
+    return {
+      node: production,
+      scope: { module: imported, expanding: new Set() },
+    };
+  }
+
   const hits: Array<{ node: Node; scope: Scope }> = [];
   for (const imported of scope.module.imports.values()) {
     const importedScope: Scope = { module: imported, expanding: new Set() };
@@ -55,7 +71,11 @@ function target(ref: Ref, scope: Scope): { node: Node; scope: Scope } {
     throw new DfnError(`no import provides '<@${ref.name}>'`, 1, 1);
   }
   if (hits.length > 1) {
-    throw new DfnError(`'<@${ref.name}>' is ambiguous across imports`, 1, 1);
+    throw new DfnError(
+      `'<@${ref.name}>' is ambiguous across imports — qualify it: <@module/${ref.name}>`,
+      1,
+      1,
+    );
   }
   return hits[0];
 }

package/src/cli.ts

@@ -66,9 +66,17 @@ export const schemaBuildCommand: CommandDescriptor = {
 
     const files: Array<{ path: string; content: string }> = [];
     const skipped: string[] = [];
+    const fragments: string[] = [];
     const stale: string[] = [];
 
     for (const modulePath of modules) {
+      // A rootless module is a FRAGMENT — imports for other modules. The sweep skips it;
+      // naming one explicitly stays an error (buildModule throws), since silence there
+      // would hide a typo'd `root`.
+      if (!ctx.args.module && !resolveModule(modulePath).module.root) {
+        fragments.push(relative(projectDir, modulePath));
+        continue;
+      }
       const { target, content } = buildModule(modulePath);
       const existing = existsSync(target)
         ? readFileSync(target, 'utf8')
@@ -93,10 +101,11 @@ export const schemaBuildCommand: CommandDescriptor = {
     }
     const notes = [
       ctx.options.check === true
-        ? `${modules.length} module(s) current`
+        ? `${modules.length - fragments.length} module(s) current`
         : `built ${files.length} module(s)`,
+      ...fragments.map((f) => `${f} declares no root (a fragment) — skipped`),
       ...skipped.map((f) => `${f} has local edits (no stamp) — left as is`),
     ];
-    return { summary: notes.join('\n'), files, data: { skipped } };
+    return { summary: notes.join('\n'), files, data: { skipped, fragments } };
   },
 };

package/src/parser.ts

@@ -192,7 +192,22 @@ class Parser {
       case 'langle': {
         const imported = this.peek().kind === 'at';
         if (imported) this.next();
-        const name = this.expect('ident', 'a production name');
+        let name = this.expect('ident', 'a production name');
+        // `<@module/production>` — qualified access to one import's production.
+        let from: string | undefined;
+        if (this.peek().kind === 'slash') {
+          if (!imported) {
+            const bad = this.peek();
+            throw new DfnError(
+              'a qualified reference is an import — write <@module/name>',
+              bad.line,
+              bad.column,
+            );
+          }
+          this.next();
+          from = name.value;
+          name = this.expect('ident', 'a production name');
+        }
         // Set modifiers: `[a, b]` picks only the listed members; `![a, b]` omits them.
         const pick: string[] = [];
         const omit: string[] = [];
@@ -218,7 +233,15 @@ class Parser {
         const open = this.peek().kind === 'star';
         if (open) this.next();
         this.expect('rangle', "'>'");
-        return { kind: 'ref', name: name.value, imported, open, pick, omit };
+        return {
+          kind: 'ref',
+          name: name.value,
+          imported,
+          from,
+          open,
+          pick,
+          omit,
+        };
       }
       case 'lbracket': {
         const node = this.alternation();

package/src/tokenizer.ts

@@ -25,6 +25,7 @@ export type TokenKind =
   | 'question'
   | 'comma'
   | 'bang'
+  | 'slash'
   | 'newline'
   | 'eof';
 
@@ -126,6 +127,7 @@ export function tokenize(source: string): Token[] {
         '?': 'question',
         ',': 'comma',
         '!': 'bang',
+        '/': 'slash',
       };
       const kind = single[text[0]];
       if (!kind) throw new DfnError(`unexpected '${text[0]}'`, line, column);