@vertekum/schema-builder 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -1,13 +1,14 @@
 # @vertekum/schema-builder
 
-## 0.2.1
+## 0.3.1
 
 ### Patch Changes
 
+- [`7f9db48`](https://github.com/moros-oxus/vertekum/commit/7f9db48344c672b90a97f3f4608bf7de893799bf) Thanks [@tschemmer](https://github.com/tschemmer)! - `<@name>` resolution gains key precedence: an import keyed `name` wins outright — its root, else its own `name` production — so sibling imports' public productions can no longer shadow or collide with a keyed module. The cross-import production search remains as the fallback when no key matches.
 - Updated dependencies []:
-  - @vertekum/core@0.2.1
+  - @vertekum/core@0.3.1
 
-## 0.2.0
+## 0.3.0
 
 ### Minor Changes
 
@@ -26,8 +27,8 @@
 - [`ef1ca4a`](https://github.com/moros-oxus/vertekum/commit/ef1ca4a0b696b799275c0f0acf7fde9414793f8d) Thanks [@tschemmer](https://github.com/tschemmer)! - Pick/omit lists take references as members — set algebra with sets as operands: `<@fullcolors ![<@fullcolors/saturated>, white]>` omits every saturated name plus white. Operands resolve with normal scope and privacy rules, keep member-by-member validation, and an open member reference is refused.
 
 - [`1de5e76`](https://github.com/moros-oxus/vertekum/commit/1de5e76929f9a1e17e6625cb3bfd36a3fd86ceec) Thanks [@tschemmer](https://github.com/tschemmer)! - The input/output pair is configurable on the extension — `schemaBuilderExtension({ source: './src/dfn', out: './src/schemas' })`. `source` becomes the default sweep for `schema build`, `lint`, and `fmt`; `out` redirects built schemas, mirroring `source`'s directory structure. `schema build` also takes a positional `[out]` for one invocation: a directory argument mirrors into it, a file argument lands directly in it.
-- Updated dependencies [[`84172d2`](https://github.com/moros-oxus/vertekum/commit/84172d2ca90320b60ec4c42730a69c056631a81c), [`82b695e`](https://github.com/moros-oxus/vertekum/commit/82b695e32cf1b7ee37f9d2f2f753aeff8ae3d15f)]:
-  - @vertekum/core@0.2.0
+- Updated dependencies [[`84172d2`](https://github.com/moros-oxus/vertekum/commit/84172d2ca90320b60ec4c42730a69c056631a81c)]:
+  - @vertekum/core@0.3.0
 
 ## 0.1.7
 

package/docs/modules.md

@@ -38,8 +38,8 @@ use "./system/color.dfn" as system-color
 
 | 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>`             | an import KEYED `key` **wins outright**: its root — else its own `key` production (the fragment idiom) — sibling imports' productions can never shadow or collide with it. |
+| `<@name>`            | no key matches: 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertekum/schema-builder",
-  "version": "0.2.1",
+  "version": "0.3.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.2.1"
+    "@vertekum/core": "0.3.1"
   },
   "dependencies": {
     "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@vertekum/core": "0.2.1",
-    "@vertekum/schema-vocabulary": "0.1.0"
+    "@vertekum/core": "0.3.1",
+    "@vertekum/schema-vocabulary": "0.3.0"
   }
 }

package/src/build.ts

@@ -125,41 +125,51 @@ function target(
     };
   }
 
+  // 1. A module KEY match wins outright — a keyed module cannot be shadowed by (or
+  //    collide with) sibling imports' productions. Its root; else its OWN production of
+  //    the same name (the fragment-declares-its-own-name idiom); else the fragment hint.
+  const keyed = scope.module.imports.get(ref.name);
+  if (keyed) {
+    const keyedScope: Scope = {
+      module: keyed,
+      expanding: new Set(),
+      warn: scope.warn,
+    };
+    if (keyed.module.root) {
+      return {
+        node: keyed.module.root,
+        scope: keyedScope,
+        importedRoot: keyed,
+      };
+    }
+    const own = keyed.module.productions.get(ref.name);
+    if (own && !keyed.module.private.has(ref.name)) {
+      return { node: own, scope: keyedScope };
+    }
+    throw new DfnError(
+      `'${ref.name}' is imported, but it declares no root (a fragment) — reference one of its productions: ${productionsOf(ref.name, keyed)}`,
+      ref.line,
+      ref.column,
+      file,
+    );
+  }
+
+  // 2. No key match: the production searched across every import — unambiguous or say so.
   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(),
-      warn: scope.warn,
-    };
+  for (const imported of scope.module.imports.values()) {
     const production = imported.module.productions.get(ref.name);
     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,
-        importedRoot: imported,
+        node: production,
+        scope: { module: imported, expanding: new Set(), warn: scope.warn },
       });
     }
   }
   if (hits.length === 0) {
-    // The near-miss that reads as a missing `use`: the import EXISTS under this key, but
-    // `<@key>` means its root and a fragment has none. Say so, and name the real forms.
-    const fragment = scope.module.imports.get(ref.name);
-    if (fragment) {
-      throw new DfnError(
-        `'${ref.name}' is imported, but it declares no root (a fragment) — reference one of its productions: ${productionsOf(ref.name, fragment)}`,
-        ref.line,
-        ref.column,
-        file,
-      );
-    }
     throw new DfnError(
       `no import provides '<@${ref.name}>'`,
       ref.line,