@vertekum/schema-builder 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @vertekum/schema-builder
 
+## 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.3.1
+
 ## 0.3.0
 
 ### Minor Changes

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.3.0",
+  "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.3.0"
+    "@vertekum/core": "0.3.1"
   },
   "dependencies": {
     "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@vertekum/core": "0.3.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,