@vertekum/schema-builder 0.1.6 → 0.2.0

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,10 +57,27 @@ 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.
+  const file = scope.module.path;
   if (!ref.imported) {
     const production = scope.module.module.productions.get(ref.name);
     if (!production) {
@@ -42,6 +85,7 @@ function target(ref: Ref, scope: Scope): { node: Node; scope: Scope } {
         `unknown production '<${ref.name}>'`,
         ref.line,
         ref.column,
+        file,
       );
     }
     return { node: production, scope };
@@ -51,36 +95,76 @@ function target(ref: Ref, scope: Scope): { node: Node; scope: Scope } {
   if (ref.from) {
     const imported = scope.module.imports.get(ref.from);
     if (!imported) {
-      throw new DfnError(`no import named '${ref.from}'`, ref.line, ref.column);
+      throw new DfnError(
+        `no import named '${ref.from}'`,
+        ref.line,
+        ref.column,
+        file,
+      );
     }
     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}'`,
+        `'${ref.from}' has no production '${ref.name}' — it declares: ${productionsOf(ref.from, imported)}`,
         ref.line,
         ref.column,
+        file,
       );
     }
     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) {
+    // 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,
       ref.column,
+      file,
     );
   }
   if (hits.length > 1) {
@@ -88,6 +172,7 @@ function target(ref: Ref, scope: Scope): { node: Node; scope: Scope } {
       `'<@${ref.name}>' is ambiguous across imports — qualify it: <@module/${ref.name}>`,
       ref.line,
       ref.column,
+      file,
     );
   }
   return hits[0];
@@ -117,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',
@@ -125,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) {
@@ -132,6 +221,7 @@ function evaluate(node: Node, scope: Scope, tail: () => TreeNode): TreeNode {
           error instanceof Error ? error.message : String(error),
           node.line,
           node.column,
+          scope.module.path,
         );
       }
       if (scale.collisions.length > 0) {
@@ -139,6 +229,7 @@ function evaluate(node: Node, scope: Scope, tail: () => TreeNode): TreeNode {
           `scale steps ${scale.collisions.join(', ')} quantize onto earlier names — the quantum is too coarse for the factor`,
           node.line,
           node.column,
+          scope.module.path,
         );
       }
       const forest = leaf();
@@ -149,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': {
@@ -181,52 +289,110 @@ 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(
             `'<${node.name}>' expands through itself`,
             node.line,
             node.column,
+            scope.module.path,
           );
         }
         scope.expanding.add(node.name);
       }
       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`,
             node.line,
             node.column,
+            scope.module.path,
           );
         }
       }
       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`,
               node.line,
               node.column,
+              scope.module.path,
             );
           }
         }
-        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;
     }
@@ -241,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;
   }
@@ -251,12 +420,31 @@ 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(`${resolved.name}.dfn declares no root`, 1, 1);
+    throw new DfnError(
+      `${resolved.name}.dfn declares no root`,
+      1,
+      1,
+      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`
@@ -274,6 +462,7 @@ export function build(resolved: ResolvedModule): TreeNode {
             `top-level '${name}' comes from both '${owner}' and '${option.name}'`,
             option.line,
             option.column,
+            resolved.path,
           );
         }
         seen.set(name, option.name);
@@ -296,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);
 }
 
@@ -332,6 +526,7 @@ export function assertOpenSetsAreNameSets(
           '* opens a set of names, not sub-paths',
           node.line,
           node.column,
+          scope.module.path,
         );
       }
       assertOpenSetsAreNameSets(resolved, node.node, scope);
@@ -344,6 +539,7 @@ export function assertOpenSetsAreNameSets(
             `'<${node.name}*>' opens a set, but the production is not name-only`,
             node.line,
             node.column,
+            scope.module.path,
           );
         }
       }