@chrisdudek/yg 5.0.3 → 5.1.0

package/dist/structure.js

@@ -1,31 +1,6 @@
-// src/structure/runner.ts
-import * as fs4 from "fs";
-import * as path8 from "path";
-import { pathToFileURL as pathToFileURL2 } from "url";
-
-// src/ast/loader-hook.ts
-import { register } from "module";
-import { pathToFileURL } from "url";
-import path from "path";
-import { fileURLToPath } from "url";
-import { existsSync } from "fs";
-var __filename = fileURLToPath(import.meta.url);
-var __dirname = path.dirname(__filename);
-var registered = false;
-function ensureLoaderRegistered() {
-  if (registered) return;
-  let implPath = path.resolve(__dirname, "./loader-hook-impl.js");
-  if (!existsSync(implPath)) {
-    const pkgRoot = path.resolve(__dirname, "../../");
-    implPath = path.resolve(pkgRoot, "dist/loader-hook-impl.js");
-  }
-  register(pathToFileURL(implPath));
-  registered = true;
-}
-
 // src/structure/ctx-fs.ts
 import * as fs from "fs";
-import * as path2 from "path";
+import * as path from "path";
 
 // src/utils/mapping-path.ts
 import { minimatch } from "minimatch";
@@ -81,7 +56,7 @@ function assertRealpathContained(abs, projectRoot, rel) {
   }
   let probe = abs;
   while (!fs.existsSync(probe)) {
-    const parent = path2.dirname(probe);
+    const parent = path.dirname(probe);
     if (parent === probe) return;
     probe = parent;
   }
@@ -91,15 +66,15 @@ function assertRealpathContained(abs, projectRoot, rel) {
   } catch {
     return;
   }
-  const relReal = toPosix(path2.relative(realRoot, realProbe));
-  if (relReal === ".." || relReal.startsWith("../") || path2.isAbsolute(relReal)) {
+  const relReal = toPosix(path.relative(realRoot, realProbe));
+  if (relReal === ".." || relReal.startsWith("../") || path.isAbsolute(relReal)) {
     throw new UndeclaredFsReadError(rel);
   }
 }
 function resolveAllowedReadPath(raw, allowedSet, projectRoot) {
-  const abs = path2.resolve(projectRoot, normalizeMappingPath(raw));
-  const rel = toPosix(path2.relative(projectRoot, abs));
-  if (rel === "" || rel.startsWith("..") || path2.isAbsolute(rel)) {
+  const abs = path.resolve(projectRoot, normalizeMappingPath(raw));
+  const rel = toPosix(path.relative(projectRoot, abs));
+  if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) {
     throw new UndeclaredFsReadError(normalizeMappingPath(raw));
   }
   if (!isAllowed(rel, allowedSet)) throw new UndeclaredFsReadError(rel);
@@ -119,7 +94,7 @@ function createCtxFs(params) {
   return {
     exists(raw) {
       const p = assertAllowed(raw);
-      const abs = path2.resolve(projectRoot, p);
+      const abs = path.resolve(projectRoot, p);
       let result;
       try {
         const stat2 = fs.statSync(abs);
@@ -134,7 +109,7 @@ function createCtxFs(params) {
     },
     read(raw) {
       const p = assertAllowed(raw);
-      const abs = path2.resolve(projectRoot, p);
+      const abs = path.resolve(projectRoot, p);
       let bytes;
       try {
         bytes = fs.readFileSync(abs);
@@ -149,7 +124,7 @@ function createCtxFs(params) {
     },
     list(raw) {
       const p = assertAllowed(raw);
-      const abs = path2.resolve(projectRoot, p);
+      const abs = path.resolve(projectRoot, p);
       let dirents;
       try {
         dirents = fs.readdirSync(abs, { withFileTypes: true });
@@ -171,7 +146,7 @@ function createCtxFs(params) {
 
 // src/structure/ctx-graph.ts
 import * as fs2 from "fs";
-import * as path3 from "path";
+import * as path2 from "path";
 
 // src/structure/expand-mapping-sync.ts
 function isPathInMapping(candidate, mapping) {
@@ -225,7 +200,7 @@ function createCtxGraph(params) {
   }
   function recordGraphNode(m) {
     if (!recorder) return;
-    const ygNodePath = path3.join(projectRoot, ".yggdrasil", "model", m.path, "yg-node.yaml");
+    const ygNodePath = path2.join(projectRoot, ".yggdrasil", "model", m.path, "yg-node.yaml");
     let yamlBytes;
     try {
       yamlBytes = fs2.readFileSync(ygNodePath);
@@ -244,7 +219,7 @@ function createCtxGraph(params) {
     const candidatePaths = preExpanded ?? (m.meta.mapping ?? []).map(normalizeMappingPath);
     for (const p of candidatePaths) {
       if (!p) continue;
-      const abs = path3.resolve(projectRoot, p);
+      const abs = path2.resolve(projectRoot, p);
       try {
         const stat2 = fs2.statSync(abs);
         if (stat2.isFile()) {
@@ -342,16 +317,16 @@ function createCtxGraph(params) {
 
 // src/structure/ctx-parsers.ts
 import * as fs3 from "fs";
-import * as path5 from "path";
+import * as path4 from "path";
 import { extname } from "path";
 import { parse as parseYaml } from "yaml";
 import { parse as parseTomlSmol } from "smol-toml";
 
 // src/ast/parser.ts
 import { Parser, Language } from "web-tree-sitter";
-import path4 from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
-import { existsSync as existsSync3 } from "fs";
+import path3 from "path";
+import { fileURLToPath } from "url";
+import { existsSync as existsSync2 } from "fs";
 import { createRequire } from "module";
 
 // src/core/graph/language-registry.ts
@@ -566,11 +541,11 @@ function getGrammarForExtension(ext) {
 
 // src/ast/parser.ts
 var _require = createRequire(import.meta.url);
-var __filename2 = fileURLToPath2(import.meta.url);
-var __dirname2 = path4.dirname(__filename2);
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path3.dirname(__filename);
 var GRAMMAR_DIRS = [
-  path4.resolve(__dirname2, "grammars"),
-  path4.resolve(__dirname2, "..", "grammars")
+  path3.resolve(__dirname, "grammars"),
+  path3.resolve(__dirname, "..", "grammars")
 ];
 var initPromise = null;
 var langCache = /* @__PURE__ */ new Map();
@@ -585,13 +560,13 @@ function init() {
 }
 function resolveWasm(filename, pkg) {
   for (const dir of GRAMMAR_DIRS) {
-    const p = path4.join(dir, filename);
-    if (existsSync3(p)) return p;
+    const p = path3.join(dir, filename);
+    if (existsSync2(p)) return p;
   }
   try {
-    const pkgDir = path4.dirname(_require.resolve(`${pkg}/package.json`));
-    for (const candidate of [path4.join(pkgDir, filename), path4.join(pkgDir, "bindings/node", filename)]) {
-      if (existsSync3(candidate)) return candidate;
+    const pkgDir = path3.dirname(_require.resolve(`${pkg}/package.json`));
+    for (const candidate of [path3.join(pkgDir, filename), path3.join(pkgDir, "bindings/node", filename)]) {
+      if (existsSync2(candidate)) return candidate;
     }
   } catch {
   }
@@ -619,7 +594,7 @@ async function getParser(extension) {
   return parser;
 }
 async function parseFile(filePath, content) {
-  const ext = path4.extname(filePath);
+  const ext = path3.extname(filePath);
   const parser = await getParser(ext);
   const tree = parser.parse(content);
   if (tree === null) {
@@ -647,7 +622,7 @@ function createCtxParsers(params) {
       return input;
     }
     const p = resolveAllowedReadPath(input, allowedSet, projectRoot);
-    const abs = path5.resolve(projectRoot, p);
+    const abs = path4.resolve(projectRoot, p);
     let bytes;
     try {
       bytes = fs3.readFileSync(abs);
@@ -703,6 +678,226 @@ function enrichFilesWithAst(files, astCache) {
   });
 }
 
+// src/ast/suppress.ts
+import { extname as extname3 } from "path";
+
+// src/ast/find-comments.ts
+import { extname as extname2 } from "path";
+function findComments(target) {
+  const hasAst = "ast" in target;
+  const hasRootNode = "rootNode" in target;
+  if (hasAst && hasRootNode) {
+    throw new Error("AST_FINDCOMMENTS_AMBIGUOUS_TARGET: pass either ast or rootNode, not both");
+  }
+  let language = "language" in target ? target.language : void 0;
+  if (language === void 0 && "path" in target) {
+    language = getLanguageForExtension(extname2(target.path)) ?? void 0;
+  }
+  if (language === void 0) {
+    throw new Error(
+      "AST_FINDCOMMENTS_NO_LANGUAGE: pass a SourceFile whose path has a known extension, or an explicit { language }"
+    );
+  }
+  const def = LANGUAGES[language];
+  if (def === void 0) {
+    throw new Error(`AST_FINDCOMMENTS_UNKNOWN_LANGUAGE: '${language}' not in registry`);
+  }
+  const root = hasAst ? target.ast.rootNode : target.rootNode;
+  const out = [];
+  for (const type of def.commentTypes) {
+    out.push(...root.descendantsOfType(type));
+  }
+  return out;
+}
+
+// src/ast/suppress.ts
+var SuppressMarkerError = class extends Error {
+  constructor(message, file, line) {
+    super(message);
+    this.file = file;
+    this.line = line;
+    this.name = "SuppressMarkerError";
+  }
+  file;
+  line;
+  code = "SUPPRESS_MARKER_MISSING_REASON";
+};
+var RE_SINGLE = /\byg-suppress\(\s*([^)]+?)\s*\)\s*(.+)?$/m;
+var RE_DISABLE = /\byg-suppress-disable\(\s*([^)]+?)\s*\)\s*(.+)?$/m;
+var RE_ENABLE = /\byg-suppress-enable\(\s*([^)]+?)\s*\)/;
+function commentBody(text) {
+  if (text.startsWith("//")) return text.slice(2).trim();
+  if (text.startsWith("/*")) return text.replace(/^\/\*+/, "").replace(/\*+\/$/, "").trim();
+  return text.trim();
+}
+function splitAspectList(raw) {
+  return raw.split(",").map((s) => s.trim()).filter(Boolean);
+}
+function makeMarker(kind, match, line, file) {
+  const aspectIds = splitAspectList(match[1]);
+  const reason = (match[2] ?? "").trim();
+  if (reason === "") {
+    throw new SuppressMarkerError(
+      `yg-suppress${kind === "disable" ? "-disable" : ""}(${match[1]}) missing reason at ${file}:${line}`,
+      file,
+      line
+    );
+  }
+  return { kind, aspectIds, reason, line };
+}
+function parseMarker(commentText, line, file) {
+  const body = commentBody(commentText);
+  let m = body.match(RE_DISABLE);
+  if (m) return makeMarker("disable", m, line, file);
+  m = body.match(RE_ENABLE);
+  if (m) {
+    return { kind: "enable", aspectIds: splitAspectList(m[1]), reason: "", line };
+  }
+  m = body.match(RE_SINGLE);
+  if (m) return makeMarker("single", m, line, file);
+  return null;
+}
+function collectSuppressions(tree, file, totalLines, content) {
+  const hasGrammar = getLanguageForExtension(extname3(file)) !== null;
+  const markers = [];
+  if (hasGrammar && tree) {
+    const comments = findComments({ path: file, ast: tree });
+    for (const c of comments) {
+      const m = parseMarker(c.text, c.startPosition.row + 1, file);
+      if (m) markers.push(m);
+    }
+  } else if (content !== void 0) {
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const m = parseMarker(lines[i], i + 1, file);
+      if (m) markers.push(m);
+    }
+  } else {
+    return [];
+  }
+  markers.sort((a, b) => a.line - b.line);
+  const ranges = [];
+  const openSpecific = /* @__PURE__ */ new Map();
+  let openWildcard = null;
+  for (const m of markers) {
+    if (m.kind === "single") {
+      const isWildcard = m.aspectIds.includes("*");
+      ranges.push({ aspectIds: new Set(m.aspectIds), startLine: m.line + 1, endLine: m.line + 1, isWildcard });
+    } else if (m.kind === "disable") {
+      for (const id of m.aspectIds) {
+        if (id === "*") {
+          if (openWildcard === null) openWildcard = m.line + 1;
+        } else {
+          if (!openSpecific.has(id)) openSpecific.set(id, m.line + 1);
+        }
+      }
+    } else {
+      for (const id of m.aspectIds) {
+        if (id === "*") {
+          if (openWildcard !== null) {
+            ranges.push({ aspectIds: /* @__PURE__ */ new Set(["*"]), startLine: openWildcard, endLine: m.line - 1, isWildcard: true });
+            openWildcard = null;
+          }
+        } else {
+          const start = openSpecific.get(id);
+          if (start !== void 0) {
+            ranges.push({ aspectIds: /* @__PURE__ */ new Set([id]), startLine: start, endLine: m.line - 1, isWildcard: false });
+            openSpecific.delete(id);
+          }
+        }
+      }
+    }
+  }
+  if (openWildcard !== null) ranges.push({ aspectIds: /* @__PURE__ */ new Set(["*"]), startLine: openWildcard, endLine: totalLines, isWildcard: true });
+  for (const [id, start] of openSpecific) {
+    ranges.push({ aspectIds: /* @__PURE__ */ new Set([id]), startLine: start, endLine: totalLines, isWildcard: false });
+  }
+  return ranges;
+}
+function isLineSuppressed(ranges, aspectId, line) {
+  return ranges.some((r) => {
+    if (line < r.startLine || line > r.endLine) return false;
+    return r.isWildcard || r.aspectIds.has(aspectId);
+  });
+}
+
+// src/utils/validate-check-module.ts
+function validateCheckModuleExport(mod, opts) {
+  const { codePrefix, runnerLabel } = opts;
+  if (mod.check === void 0) {
+    const defaultExport = mod.default;
+    if (typeof defaultExport === "function" && defaultExport.name === "check") {
+      return {
+        ok: false,
+        code: `${codePrefix}_CHECK_DEFAULT_EXPORT`,
+        message: {
+          what: `check.mjs exports 'check' as default, but a NAMED export is required (${runnerLabel}).`,
+          why: `The runner imports the named export. A default export is invisible to it.`,
+          next: `Change 'export default function check(...)' to 'export function check(...)'.`
+        }
+      };
+    }
+    return {
+      ok: false,
+      code: `${codePrefix}_CHECK_NOT_EXPORTED`,
+      message: {
+        what: `check.mjs does not export a function named 'check' (${runnerLabel}).`,
+        why: `The runner expects 'export function check(ctx) { ... }'.`,
+        next: `Add a named export 'check' in check.mjs.`
+      }
+    };
+  }
+  if (typeof mod.check !== "function") {
+    return {
+      ok: false,
+      code: `${codePrefix}_CHECK_NOT_FUNCTION`,
+      message: {
+        what: `'check' is exported but is not a function (got ${typeof mod.check}).`,
+        why: `The runner calls check(ctx).`,
+        next: `Re-export check as a function.`
+      }
+    };
+  }
+  const checkFn = mod.check;
+  if (checkFn.length !== 1) {
+    return {
+      ok: false,
+      code: `${codePrefix}_CHECK_WRONG_ARITY`,
+      message: {
+        what: `'check' must accept exactly 1 parameter (ctx); declared arity is ${checkFn.length}.`,
+        why: `The runner invokes check(ctx).`,
+        next: `Change the signature to function check(ctx).`
+      }
+    };
+  }
+  return { ok: true };
+}
+
+// src/structure/hook-loader.ts
+import * as fs4 from "fs";
+import * as path8 from "path";
+import { pathToFileURL as pathToFileURL2 } from "url";
+
+// src/ast/loader-hook.ts
+import { register } from "module";
+import { pathToFileURL } from "url";
+import path5 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { existsSync as existsSync3 } from "fs";
+var __filename2 = fileURLToPath2(import.meta.url);
+var __dirname2 = path5.dirname(__filename2);
+var registered = false;
+function ensureLoaderRegistered() {
+  if (registered) return;
+  let implPath = path5.resolve(__dirname2, "./loader-hook-impl.js");
+  if (!existsSync3(implPath)) {
+    const pkgRoot = path5.resolve(__dirname2, "../../");
+    implPath = path5.resolve(pkgRoot, "dist/loader-hook-impl.js");
+  }
+  register(pathToFileURL(implPath));
+  registered = true;
+}
+
 // src/structure/allowed-reads.ts
 function collectAllowedReadsForAspect(nodePath, graph) {
   const allowed = /* @__PURE__ */ new Set();
@@ -922,201 +1117,6 @@ async function expandMappingPaths(projectRoot, mappingPaths) {
   return result;
 }
 
-// src/ast/suppress.ts
-import { extname as extname3 } from "path";
-
-// src/ast/find-comments.ts
-import { extname as extname2 } from "path";
-function findComments(target) {
-  const hasAst = "ast" in target;
-  const hasRootNode = "rootNode" in target;
-  if (hasAst && hasRootNode) {
-    throw new Error("AST_FINDCOMMENTS_AMBIGUOUS_TARGET: pass either ast or rootNode, not both");
-  }
-  let language = "language" in target ? target.language : void 0;
-  if (language === void 0 && "path" in target) {
-    language = getLanguageForExtension(extname2(target.path)) ?? void 0;
-  }
-  if (language === void 0) {
-    throw new Error(
-      "AST_FINDCOMMENTS_NO_LANGUAGE: pass a SourceFile whose path has a known extension, or an explicit { language }"
-    );
-  }
-  const def = LANGUAGES[language];
-  if (def === void 0) {
-    throw new Error(`AST_FINDCOMMENTS_UNKNOWN_LANGUAGE: '${language}' not in registry`);
-  }
-  const root = hasAst ? target.ast.rootNode : target.rootNode;
-  const out = [];
-  for (const type of def.commentTypes) {
-    out.push(...root.descendantsOfType(type));
-  }
-  return out;
-}
-
-// src/ast/suppress.ts
-var SuppressMarkerError = class extends Error {
-  constructor(message, file, line) {
-    super(message);
-    this.file = file;
-    this.line = line;
-    this.name = "SuppressMarkerError";
-  }
-  file;
-  line;
-  code = "SUPPRESS_MARKER_MISSING_REASON";
-};
-var RE_SINGLE = /\byg-suppress\(\s*([^)]+?)\s*\)\s*(.+)?$/m;
-var RE_DISABLE = /\byg-suppress-disable\(\s*([^)]+?)\s*\)\s*(.+)?$/m;
-var RE_ENABLE = /\byg-suppress-enable\(\s*([^)]+?)\s*\)/;
-function commentBody(text) {
-  if (text.startsWith("//")) return text.slice(2).trim();
-  if (text.startsWith("/*")) return text.replace(/^\/\*+/, "").replace(/\*+\/$/, "").trim();
-  return text.trim();
-}
-function splitAspectList(raw) {
-  return raw.split(",").map((s) => s.trim()).filter(Boolean);
-}
-function makeMarker(kind, match, line, file) {
-  const aspectIds = splitAspectList(match[1]);
-  const reason = (match[2] ?? "").trim();
-  if (reason === "") {
-    throw new SuppressMarkerError(
-      `yg-suppress${kind === "disable" ? "-disable" : ""}(${match[1]}) missing reason at ${file}:${line}`,
-      file,
-      line
-    );
-  }
-  return { kind, aspectIds, reason, line };
-}
-function parseMarker(commentText, line, file) {
-  const body = commentBody(commentText);
-  let m = body.match(RE_DISABLE);
-  if (m) return makeMarker("disable", m, line, file);
-  m = body.match(RE_ENABLE);
-  if (m) {
-    return { kind: "enable", aspectIds: splitAspectList(m[1]), reason: "", line };
-  }
-  m = body.match(RE_SINGLE);
-  if (m) return makeMarker("single", m, line, file);
-  return null;
-}
-function collectSuppressions(tree, file, totalLines, content) {
-  const hasGrammar = getLanguageForExtension(extname3(file)) !== null;
-  const markers = [];
-  if (hasGrammar && tree) {
-    const comments = findComments({ path: file, ast: tree });
-    for (const c of comments) {
-      const m = parseMarker(c.text, c.startPosition.row + 1, file);
-      if (m) markers.push(m);
-    }
-  } else if (content !== void 0) {
-    const lines = content.split("\n");
-    for (let i = 0; i < lines.length; i++) {
-      const m = parseMarker(lines[i], i + 1, file);
-      if (m) markers.push(m);
-    }
-  } else {
-    return [];
-  }
-  markers.sort((a, b) => a.line - b.line);
-  const ranges = [];
-  const openSpecific = /* @__PURE__ */ new Map();
-  let openWildcard = null;
-  for (const m of markers) {
-    if (m.kind === "single") {
-      const isWildcard = m.aspectIds.includes("*");
-      ranges.push({ aspectIds: new Set(m.aspectIds), startLine: m.line + 1, endLine: m.line + 1, isWildcard });
-    } else if (m.kind === "disable") {
-      for (const id of m.aspectIds) {
-        if (id === "*") {
-          if (openWildcard === null) openWildcard = m.line + 1;
-        } else {
-          if (!openSpecific.has(id)) openSpecific.set(id, m.line + 1);
-        }
-      }
-    } else {
-      for (const id of m.aspectIds) {
-        if (id === "*") {
-          if (openWildcard !== null) {
-            ranges.push({ aspectIds: /* @__PURE__ */ new Set(["*"]), startLine: openWildcard, endLine: m.line - 1, isWildcard: true });
-            openWildcard = null;
-          }
-        } else {
-          const start = openSpecific.get(id);
-          if (start !== void 0) {
-            ranges.push({ aspectIds: /* @__PURE__ */ new Set([id]), startLine: start, endLine: m.line - 1, isWildcard: false });
-            openSpecific.delete(id);
-          }
-        }
-      }
-    }
-  }
-  if (openWildcard !== null) ranges.push({ aspectIds: /* @__PURE__ */ new Set(["*"]), startLine: openWildcard, endLine: totalLines, isWildcard: true });
-  for (const [id, start] of openSpecific) {
-    ranges.push({ aspectIds: /* @__PURE__ */ new Set([id]), startLine: start, endLine: totalLines, isWildcard: false });
-  }
-  return ranges;
-}
-function isLineSuppressed(ranges, aspectId, line) {
-  return ranges.some((r) => {
-    if (line < r.startLine || line > r.endLine) return false;
-    return r.isWildcard || r.aspectIds.has(aspectId);
-  });
-}
-
-// src/utils/validate-check-module.ts
-function validateCheckModuleExport(mod, opts) {
-  const { codePrefix, runnerLabel } = opts;
-  if (mod.check === void 0) {
-    const defaultExport = mod.default;
-    if (typeof defaultExport === "function" && defaultExport.name === "check") {
-      return {
-        ok: false,
-        code: `${codePrefix}_CHECK_DEFAULT_EXPORT`,
-        message: {
-          what: `check.mjs exports 'check' as default, but a NAMED export is required (${runnerLabel}).`,
-          why: `The runner imports the named export. A default export is invisible to it.`,
-          next: `Change 'export default function check(...)' to 'export function check(...)'.`
-        }
-      };
-    }
-    return {
-      ok: false,
-      code: `${codePrefix}_CHECK_NOT_EXPORTED`,
-      message: {
-        what: `check.mjs does not export a function named 'check' (${runnerLabel}).`,
-        why: `The runner expects 'export function check(ctx) { ... }'.`,
-        next: `Add a named export 'check' in check.mjs.`
-      }
-    };
-  }
-  if (typeof mod.check !== "function") {
-    return {
-      ok: false,
-      code: `${codePrefix}_CHECK_NOT_FUNCTION`,
-      message: {
-        what: `'check' is exported but is not a function (got ${typeof mod.check}).`,
-        why: `The runner calls check(ctx).`,
-        next: `Re-export check as a function.`
-      }
-    };
-  }
-  const checkFn = mod.check;
-  if (checkFn.length !== 1) {
-    return {
-      ok: false,
-      code: `${codePrefix}_CHECK_WRONG_ARITY`,
-      message: {
-        what: `'check' must accept exactly 1 parameter (ctx); declared arity is ${checkFn.length}.`,
-        why: `The runner invokes check(ctx).`,
-        next: `Change the signature to function check(ctx).`
-      }
-    };
-  }
-  return { ok: true };
-}
-
 // src/utils/binary-extensions.ts
 var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
   ".gif",
@@ -1270,7 +1270,7 @@ var ObservationRecorder = class {
   }
 };
 
-// src/structure/runner.ts
+// src/structure/hook-loader.ts
 var StructureRunnerError = class extends Error {
   constructor(code, data) {
     super(`${code}: ${data.what}
@@ -1332,11 +1332,24 @@ async function enumerateMappedFilesAsync(mappingPaths, projectRoot) {
   const normalized = mappingPaths.map(normalizeMappingPath).filter((p) => p !== "");
   return expandMappingPaths(projectRoot, normalized);
 }
-async function runStructureAspect(params) {
+async function loadHookModule(params) {
   ensureLoaderRegistered();
-  const { aspectDir, aspectId, nodePath, graph, projectRoot, subjectScope } = params;
-  const astCache = params.parseCache ?? /* @__PURE__ */ new Map();
-  const touchedFiles = [];
+  const { aspectDir, projectRoot, filename } = params;
+  const resolveFailedCode = params.resolveFailedCode ?? "STRUCTURE_LOADER_RESOLVE_FAILED";
+  const aspectDirAbs = path8.isAbsolute(aspectDir) ? aspectDir : path8.resolve(projectRoot, aspectDir);
+  const modulePath = path8.join(aspectDirAbs, filename);
+  try {
+    return await import(pathToFileURL2(modulePath).href);
+  } catch (err) {
+    throw new StructureRunnerError(resolveFailedCode, {
+      what: `Failed to load ${filename} at ${modulePath}: ${err.message}`,
+      why: `The runner dynamically imports the aspect's ${filename} before invoking it.`,
+      next: `Ensure ${filename} exists at the aspect directory and has no unresolved imports.`
+    });
+  }
+}
+async function buildUnitCtx(params) {
+  const { aspectId, nodePath, graph, projectRoot, astCache, touchedFiles, subjectScope } = params;
   const node = graph.nodes.get(nodePath);
   if (!node) {
     throw new StructureRunnerError("STRUCTURE_NODE_MISSING", {
@@ -1345,26 +1358,7 @@ async function runStructureAspect(params) {
       next: `Pass an existing node path, or add the node to the graph.`
     });
   }
-  const aspectDirAbs = path8.isAbsolute(aspectDir) ? aspectDir : path8.resolve(projectRoot, aspectDir);
-  const checkPath = path8.join(aspectDirAbs, "check.mjs");
-  let mod;
-  try {
-    mod = await import(pathToFileURL2(checkPath).href);
-  } catch (err) {
-    throw new StructureRunnerError("STRUCTURE_LOADER_RESOLVE_FAILED", {
-      what: `Failed to load check.mjs at ${checkPath}: ${err.message}`,
-      why: `The runner dynamically imports the aspect's check.mjs before invoking it.`,
-      next: `Ensure check.mjs exists at the aspect directory and has no unresolved imports.`
-    });
-  }
-  const exportCheck = validateCheckModuleExport(mod, {
-    codePrefix: "STRUCTURE",
-    runnerLabel: `aspect '${aspectId}'`
-  });
-  if (!exportCheck.ok) {
-    throw new StructureRunnerError(exportCheck.code, exportCheck.message);
-  }
-  const checkFn = mod.check;
+  void aspectId;
   const allowedSet = collectAllowedReadsForAspect(nodePath, graph);
   const recorder = new ObservationRecorder();
   const ownFilesRaw = (node.meta.mapping ?? []).map(normalizeMappingPath).filter((p) => p !== "");
@@ -1406,6 +1400,11 @@ async function runStructureAspect(params) {
       ports: node.meta.ports ?? {}
     },
     files: ctxFilesEnriched,
+    // ctx.subject is the unit's subject file(s): for the deterministic whole-node
+    // case it is the SAME array reference as ctx.files; for a per:file unit it is
+    // exactly the narrowed subject view (also ctx.files here). Identical reference
+    // in both branches keeps the alias contract.
+    subject: ctxFilesEnriched,
     fs: ctxFs,
     graph: ctxGraph,
     parseAst: parsers.parseAst,
@@ -1427,6 +1426,32 @@ async function runStructureAspect(params) {
     }
   }
   await prewarmupAstCache({ astCache, projectRoot, files: astInputSet });
+  return { ctx, recorder, node, subjectFiles, ownFiles, astInputSet };
+}
+
+// src/structure/runner.ts
+async function runStructureAspect(params) {
+  const { aspectDir, aspectId, nodePath, graph, projectRoot, subjectScope } = params;
+  const astCache = params.parseCache ?? /* @__PURE__ */ new Map();
+  const touchedFiles = [];
+  const mod = await loadHookModule({ aspectDir, projectRoot, filename: "check.mjs" });
+  const exportCheck = validateCheckModuleExport(mod, {
+    codePrefix: "STRUCTURE",
+    runnerLabel: `aspect '${aspectId}'`
+  });
+  if (!exportCheck.ok) {
+    throw new StructureRunnerError(exportCheck.code, exportCheck.message);
+  }
+  const checkFn = mod.check;
+  const { ctx, recorder, ownFiles, astInputSet } = await buildUnitCtx({
+    aspectId,
+    nodePath,
+    graph,
+    projectRoot,
+    astCache,
+    touchedFiles,
+    subjectScope
+  });
   let raw;
   try {
     raw = checkFn(ctx);