@chrisdudek/yg 5.2.3 → 5.2.5

package/README.md

@@ -1,8 +1,8 @@
 # @chrisdudek/yg
 
-**Your agent will ignore CLAUDE.md. Yggdrasil makes sure it doesn't.**
+**Stop babysitting your agent.**
 
-Architecture rules your agent can't ignore. Before it edits a file, your agent gets the few rules that apply — and writes to them. After, every change is checked before it moves on: by a script that runs locally for free, or by an LLM reviewer. A rule written as a script *runs* — your agent can't quietly optimize it away the way it drops a line in CLAUDE.md. Works with Claude Code, Cursor, Copilot, Codex, Cline, and more. Checks run against your code, not your diffs; the feedback is specific; the agent has to fix before it can move on.
+Your architecture rules become checks it can't skip, run on every change before it moves on. A script runs them locally for free, or an LLM reviews the call a script can't make. Checks run against your code, not your diffs. The feedback is specific, and the agent has to fix before it can move on. Works with Claude Code, Cursor, Copilot, Codex, Cline, and more.
 
 See the [main README](https://github.com/krzysztofdudek/Yggdrasil#readme) for documentation, or visit
 [krzysztofdudek.github.io/Yggdrasil](https://krzysztofdudek.github.io/Yggdrasil/).

package/dist/bin.js

@@ -10027,6 +10027,7 @@ var GRAMMAR_DIRS = [
 ];
 var initPromise = null;
 var langCache = /* @__PURE__ */ new Map();
+var parserCache = /* @__PURE__ */ new Map();
 function init() {
   if (initPromise === null) {
     initPromise = Parser.init();
@@ -10067,8 +10068,11 @@ async function getParser(extension) {
     });
   }
   const lang = await langP;
+  const existing = parserCache.get(cacheKey);
+  if (existing) return existing;
   const parser = new Parser();
   parser.setLanguage(lang);
+  parserCache.set(cacheKey, parser);
   return parser;
 }
 async function parseFile(filePath, content20) {
@@ -10404,6 +10408,14 @@ function validateCheckModuleExport(mod, opts) {
   return { ok: true };
 }
 
+// src/ast/parse-cache.ts
+function destroyParseCache(cache) {
+  for (const { ast } of cache.values()) {
+    ast.delete();
+  }
+  cache.clear();
+}
+
 // src/structure/hook-loader.ts
 import * as fs4 from "fs";
 import * as path29 from "path";
@@ -10787,143 +10799,149 @@ async function runCompanionHook(params) {
 // src/structure/runner.ts
 async function runStructureAspect(params) {
   const { aspectDir, aspectId, nodePath, graph, projectRoot, subjectScope } = params;
+  const ownCache = !params.parseCache;
   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);
-  } catch (err) {
-    if (err instanceof UndeclaredFsReadError) {
-      return {
-        violations: [{
-          message: `Aspect tried to read undeclared path '${err.path}'. Add a relation in yg-node.yaml to the node owning this path.`,
-          kind: "structure-aspect-undeclared-fs-read",
-          file: `.yggdrasil/aspects/${aspectId}/check.mjs`
-        }],
-        touchedFiles: [],
-        succeeded: false,
-        observations: recorder.snapshot(),
-        observationsTainted: recorder.tainted
-      };
+    let rangesFor2 = function(filePath) {
+      const existing = rangesByFile.get(filePath);
+      if (existing !== void 0) return existing;
+      const cached = astCache.get(filePath);
+      let ranges;
+      if (cached) {
+        ranges = collectSuppressions(cached.ast, filePath, cached.content.split("\n").length, cached.content);
+      } else {
+        const content20 = contentByPath.get(filePath);
+        ranges = content20 !== void 0 ? collectSuppressions(void 0, filePath, content20.split("\n").length, content20) : null;
+      }
+      rangesByFile.set(filePath, ranges);
+      return ranges;
+    };
+    var rangesFor = rangesFor2;
+    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);
     }
-    if (err instanceof UndeclaredGraphReadError) {
-      return {
-        violations: [{
-          message: `Aspect tried to read undeclared graph node '${err.nodePath}'. Add a relation in yg-node.yaml.`,
-          kind: "structure-aspect-undeclared-graph-read",
-          file: `.yggdrasil/aspects/${aspectId}/check.mjs`
-        }],
-        touchedFiles: [],
-        succeeded: false,
-        observations: recorder.snapshot(),
-        observationsTainted: recorder.tainted
-      };
+    const checkFn = mod.check;
+    const { ctx, recorder, ownFiles, astInputSet } = await buildUnitCtx({
+      aspectId,
+      nodePath,
+      graph,
+      projectRoot,
+      astCache,
+      touchedFiles,
+      subjectScope
+    });
+    let raw;
+    try {
+      raw = checkFn(ctx);
+    } catch (err) {
+      if (err instanceof UndeclaredFsReadError) {
+        return {
+          violations: [{
+            message: `Aspect tried to read undeclared path '${err.path}'. Add a relation in yg-node.yaml to the node owning this path.`,
+            kind: "structure-aspect-undeclared-fs-read",
+            file: `.yggdrasil/aspects/${aspectId}/check.mjs`
+          }],
+          touchedFiles: [],
+          succeeded: false,
+          observations: recorder.snapshot(),
+          observationsTainted: recorder.tainted
+        };
+      }
+      if (err instanceof UndeclaredGraphReadError) {
+        return {
+          violations: [{
+            message: `Aspect tried to read undeclared graph node '${err.nodePath}'. Add a relation in yg-node.yaml.`,
+            kind: "structure-aspect-undeclared-graph-read",
+            file: `.yggdrasil/aspects/${aspectId}/check.mjs`
+          }],
+          touchedFiles: [],
+          succeeded: false,
+          observations: recorder.snapshot(),
+          observationsTainted: recorder.tainted
+        };
+      }
+      if (err instanceof ParseAstNotPrewarmedError) {
+        return {
+          violations: [{
+            message: `Aspect called ctx.parseAst on '${err.filePath}', which was not pre-warmed by the dispatcher. Add a declared relation to the node owning this file, or use ctx.parseYaml/Json/Toml if AST is not required.`,
+            kind: "structure-aspect-parseast-not-prewarmed",
+            file: `.yggdrasil/model/${nodePath}/yg-node.yaml`
+          }],
+          touchedFiles: [],
+          succeeded: false,
+          observations: recorder.snapshot(),
+          observationsTainted: recorder.tainted
+        };
+      }
+      throw new StructureRunnerError("STRUCTURE_CHECK_THROWN", {
+        what: `check.mjs threw an exception while running (aspect '${aspectId}').`,
+        why: `${err.message}
+${err.stack ?? ""}`,
+        next: `Fix the bug in check.mjs, then re-run: yg check --approve`
+      });
     }
-    if (err instanceof ParseAstNotPrewarmedError) {
-      return {
-        violations: [{
-          message: `Aspect called ctx.parseAst on '${err.filePath}', which was not pre-warmed by the dispatcher. Add a declared relation to the node owning this file, or use ctx.parseYaml/Json/Toml if AST is not required.`,
-          kind: "structure-aspect-parseast-not-prewarmed",
-          file: `.yggdrasil/model/${nodePath}/yg-node.yaml`
-        }],
-        touchedFiles: [],
-        succeeded: false,
-        observations: recorder.snapshot(),
-        observationsTainted: recorder.tainted
-      };
+    if (raw !== null && typeof raw === "object" && typeof raw.then === "function") {
+      throw new StructureRunnerError("STRUCTURE_CHECK_ASYNC", {
+        what: `check.mjs returned a Promise; only synchronous returns are supported.`,
+        why: `The runner does not await check's return value.`,
+        next: `Refactor check to be synchronous.`
+      });
     }
-    throw new StructureRunnerError("STRUCTURE_CHECK_THROWN", {
-      what: `check.mjs threw an exception while running (aspect '${aspectId}').`,
-      why: `${err.message}
-${err.stack ?? ""}`,
-      next: `Fix the bug in check.mjs, then re-run: yg check --approve`
-    });
-  }
-  if (raw !== null && typeof raw === "object" && typeof raw.then === "function") {
-    throw new StructureRunnerError("STRUCTURE_CHECK_ASYNC", {
-      what: `check.mjs returned a Promise; only synchronous returns are supported.`,
-      why: `The runner does not await check's return value.`,
-      next: `Refactor check to be synchronous.`
-    });
-  }
-  if (!Array.isArray(raw)) {
-    throw new StructureRunnerError("STRUCTURE_CHECK_RETURN_SHAPE", {
-      what: `check.mjs returned ${typeof raw}, expected Violation[].`,
-      why: `The runner reports violations from the array returned by check.`,
-      next: `Return [] or Violation[] from check.`
-    });
-  }
-  const contextFiles = new Set(ownFiles.map((f) => f.path));
-  for (const t of touchedFiles) contextFiles.add(t);
-  const violations = [];
-  for (const v of raw) {
-    if (typeof v !== "object" || v === null || typeof v.message !== "string") {
+    if (!Array.isArray(raw)) {
       throw new StructureRunnerError("STRUCTURE_CHECK_RETURN_SHAPE", {
-        what: `Violation entry must be an object with a string 'message' field.`,
-        why: `The runner renders each violation from its message and optional file/line.`,
-        next: `Return objects shaped { message: string, file?: string, line?: number } from check.`
+        what: `check.mjs returned ${typeof raw}, expected Violation[].`,
+        why: `The runner reports violations from the array returned by check.`,
+        next: `Return [] or Violation[] from check.`
       });
     }
-    const vv = v;
-    if (typeof vv.file === "string" && !contextFiles.has(normalizeMappingPath(vv.file))) {
-      throw new StructureRunnerError("STRUCTURE_CHECK_FILE_NOT_IN_CONTEXT", {
-        what: `Violation references file '${vv.file}' not in ctx (own mapping or touched via ctx.fs/ctx.graph).`,
-        why: `Author cannot synthesize violations against files they were not given.`,
-        next: `Return only violations for files in ctx, or declare a relation to the node owning '${vv.file}'.`
-      });
+    const contextFiles = new Set(ownFiles.map((f) => f.path));
+    for (const t of touchedFiles) contextFiles.add(t);
+    const violations = [];
+    for (const v of raw) {
+      if (typeof v !== "object" || v === null || typeof v.message !== "string") {
+        throw new StructureRunnerError("STRUCTURE_CHECK_RETURN_SHAPE", {
+          what: `Violation entry must be an object with a string 'message' field.`,
+          why: `The runner renders each violation from its message and optional file/line.`,
+          next: `Return objects shaped { message: string, file?: string, line?: number } from check.`
+        });
+      }
+      const vv = v;
+      if (typeof vv.file === "string" && !contextFiles.has(normalizeMappingPath(vv.file))) {
+        throw new StructureRunnerError("STRUCTURE_CHECK_FILE_NOT_IN_CONTEXT", {
+          what: `Violation references file '${vv.file}' not in ctx (own mapping or touched via ctx.fs/ctx.graph).`,
+          why: `Author cannot synthesize violations against files they were not given.`,
+          next: `Return only violations for files in ctx, or declare a relation to the node owning '${vv.file}'.`
+        });
+      }
+      violations.push(vv);
     }
-    violations.push(vv);
-  }
-  const contentByPath = /* @__PURE__ */ new Map();
-  for (const f of [...ownFiles, ...astInputSet]) {
-    contentByPath.set(normalizeMappingPath(f.path), f.content);
-  }
-  const rangesByFile = /* @__PURE__ */ new Map();
-  function rangesFor(filePath) {
-    const existing = rangesByFile.get(filePath);
-    if (existing !== void 0) return existing;
-    const cached = astCache.get(filePath);
-    let ranges;
-    if (cached) {
-      ranges = collectSuppressions(cached.ast, filePath, cached.content.split("\n").length, cached.content);
-    } else {
-      const content20 = contentByPath.get(filePath);
-      ranges = content20 !== void 0 ? collectSuppressions(void 0, filePath, content20.split("\n").length, content20) : null;
+    const contentByPath = /* @__PURE__ */ new Map();
+    for (const f of [...ownFiles, ...astInputSet]) {
+      contentByPath.set(normalizeMappingPath(f.path), f.content);
     }
-    rangesByFile.set(filePath, ranges);
-    return ranges;
+    const rangesByFile = /* @__PURE__ */ new Map();
+    const visible = violations.filter((v) => {
+      if (typeof v.file !== "string" || typeof v.line !== "number") return true;
+      const ranges = rangesFor2(normalizeMappingPath(v.file));
+      if (!ranges) return true;
+      return !isLineSuppressed(ranges, aspectId, v.line);
+    });
+    return {
+      violations: visible,
+      touchedFiles,
+      succeeded: true,
+      observations: recorder.snapshot(),
+      observationsTainted: recorder.tainted
+    };
+  } finally {
+    if (ownCache) destroyParseCache(astCache);
   }
-  const visible = violations.filter((v) => {
-    if (typeof v.file !== "string" || typeof v.line !== "number") return true;
-    const ranges = rangesFor(normalizeMappingPath(v.file));
-    if (!ranges) return true;
-    return !isLineSuppressed(ranges, aspectId, v.line);
-  });
-  return {
-    violations: visible,
-    touchedFiles,
-    succeeded: true,
-    observations: recorder.snapshot(),
-    observationsTainted: recorder.tainted
-  };
 }
 
 // src/structure/suppress-ranges.ts
@@ -10939,6 +10957,7 @@ async function resolveSuppressedRangesForPrompt(subjects, aspectId) {
     }
     const totalLines = content20.split("\n").length;
     const all = collectSuppressions(tree, subject.path, totalLines, content20);
+    tree?.delete();
     const ranges = formatSuppressedRangesForAspect(all, aspectId);
     if (ranges.length > 0) {
       byFile.push({ path: subject.path, ranges });
@@ -12237,6 +12256,9 @@ async function runRelationPass(graph, projectRoot, deps) {
       violationsByNode.set(nodeId, { verdict: "approved", violations: [] });
     }
   }
+  for (const entry of parseCache.values()) {
+    if (entry) entry.tree.delete();
+  }
   return { violationsByNode };
 }
 
@@ -15821,20 +15843,20 @@ function registerCheckCommand(program2) {
       const gitFiles = collectGitFiles(projectRoot);
       const wantsTop = opts.top !== void 0;
       if (wantsTop && opts.summary) {
-        process.stdout.write(buildIssueMessage({
+        process.stderr.write(chalk8.red(buildIssueMessage({
           what: "--top and --summary cannot be combined.",
           why: "Both are read-only triage VIEWS of the same `yg check` result \u2014 --top renders the N highest-priority blocks, --summary renders per-node counts only. Asking for both at once is ambiguous; pick one lens.",
           next: "Run: yg check --top <n> (priority blocks), or yg check --summary (per-node counts)."
-        }) + "\n");
+        }) + "\n"));
         await exitAfterFlush(1);
         return;
       }
       if ((wantsTop || opts.summary) && opts.approve) {
-        process.stdout.write(buildIssueMessage({
+        process.stderr.write(chalk8.red(buildIssueMessage({
           what: `${wantsTop ? "--top" : "--summary"} cannot be combined with --approve.`,
           why: "--top and --summary triage the READ-ONLY check wall (they narrow the output of plain `yg check`, which writes nothing). --approve is the writer path; its own free cost preview is --dry-run. Mixing a read-only triage view with the writer is contradictory.",
           next: `Run: yg check ${wantsTop ? "--top <n>" : "--summary"} (read-only triage), or yg check --approve --dry-run (preview the writer's cost).`
-        }) + "\n");
+        }) + "\n"));
         await exitAfterFlush(1);
         return;
       }
@@ -15844,22 +15866,22 @@ function registerCheckCommand(program2) {
       } else if (wantsTop) {
         const n = resolveTopValue(opts.top);
         if (n === null) {
-          process.stdout.write(buildIssueMessage({
+          process.stderr.write(chalk8.red(buildIssueMessage({
             what: `--top expects a non-negative whole number; got "${String(opts.top)}".`,
             why: "--top N prints the N highest-priority issue blocks. A negative, fractional, or non-numeric value is meaningless, and printing the full wall instead would silently hide that the flag was ignored \u2014 masking the very output you tried to narrow.",
             next: "Run: yg check --top 5 (top 5 blocks), yg check --top (just the suggestedNext block), or yg check (full output)."
-          }) + "\n");
+          }) + "\n"));
           await exitAfterFlush(1);
           return;
         }
         view = { kind: "top", n };
       }
       if (opts.dryRun && !opts.approve) {
-        process.stdout.write(buildIssueMessage({
+        process.stderr.write(chalk8.red(buildIssueMessage({
           what: "--dry-run requires --approve.",
           why: "--dry-run previews what `yg check --approve` would fill (the reviewer-call budget and per-node breakdown) without writing or calling the reviewer; it is a mode of --approve, not a variant of the plain read. Plain `yg check` is already a free, no-write read.",
           next: "Run: yg check --approve --dry-run (cost preview), or yg check (plain read)."
-        }) + "\n");
+        }) + "\n"));
         await exitAfterFlush(1);
         return;
       }
@@ -15879,7 +15901,7 @@ function registerCheckCommand(program2) {
             return;
           }
           const hasErrors2 = fill.checkResult.issues.some((i) => i.severity === "error");
-          if (hasErrors2) await exitAfterFlush(1);
+          await exitAfterFlush(hasErrors2 ? 1 : 0);
           return;
         } catch (err) {
           if (err instanceof FillGatingError) {
@@ -15892,7 +15914,7 @@ function registerCheckCommand(program2) {
       const result = await runCheck(graph, gitFiles);
       process.stdout.write(formatOutput(result, view));
       const hasErrors = result.issues.some((i) => i.severity === "error");
-      if (hasErrors) await exitAfterFlush(1);
+      await exitAfterFlush(hasErrors ? 1 : 0);
     } catch (error) {
       debugWrite(`[check] error: ${error.message}`);
       abortOnUnexpectedError(error, "running check");
@@ -16212,86 +16234,95 @@ async function runAstAspect(params) {
     throw new AstRunnerError(exportCheck.code, exportCheck.message);
   }
   const checkFn = mod.check;
+  const localTrees = [];
   const sourceFiles = [];
-  for (const f of params.files) {
-    const cached = params.parseCache?.get(f.path);
-    if (cached !== void 0) {
-      sourceFiles.push({ path: f.path, content: cached.content, ast: cached.ast });
-      continue;
+  try {
+    for (const f of params.files) {
+      const cached = params.parseCache?.get(f.path);
+      if (cached !== void 0) {
+        sourceFiles.push({ path: f.path, content: cached.content, ast: cached.ast });
+        continue;
+      }
+      const content20 = await readFile16(path49.resolve(params.projectRoot, f.path), "utf-8");
+      if (getLanguageForExtension(path49.extname(f.path).toLowerCase()) === null) {
+        sourceFiles.push({ path: f.path, content: content20, ast: void 0 });
+        continue;
+      }
+      let ast;
+      try {
+        ast = await parseFile(f.path, content20);
+      } catch (e) {
+        const msg = e.message ?? String(e);
+        throw new AstRunnerError("AST_GRAMMAR_LOAD_FAILED", {
+          what: `Failed to load tree-sitter grammar for ${f.path}: ${msg}`,
+          why: `The bundled WASM grammar could not be loaded.`,
+          next: `Reinstall the CLI.`
+        });
+      }
+      if (ast.rootNode.hasError) {
+        const err = findFirstErrorNode(ast.rootNode);
+        throw new AstRunnerError("AST_SOURCE_PARSE_ERROR", {
+          what: `Source file ${f.path} has a syntax error at line ${(err?.startPosition.row ?? 0) + 1}.`,
+          why: `Tree-sitter could not parse the file cleanly.`,
+          next: `Fix the syntax error in ${f.path}.`
+        });
+      }
+      if (params.parseCache) {
+        params.parseCache.set(f.path, { content: content20, ast });
+      } else {
+        localTrees.push(ast);
+      }
+      sourceFiles.push({ path: f.path, content: content20, ast });
     }
-    const content20 = await readFile16(path49.resolve(params.projectRoot, f.path), "utf-8");
-    if (getLanguageForExtension(path49.extname(f.path).toLowerCase()) === null) {
-      sourceFiles.push({ path: f.path, content: content20, ast: void 0 });
-      continue;
+    const rangesPerFile = /* @__PURE__ */ new Map();
+    for (const f of sourceFiles) {
+      const totalLines = f.content.split("\n").length;
+      rangesPerFile.set(f.path, collectSuppressions(f.ast, f.path, totalLines, f.content));
     }
-    let ast;
+    const ctx = { files: sourceFiles };
+    let raw;
     try {
-      ast = await parseFile(f.path, content20);
+      raw = checkFn(ctx);
     } catch (e) {
-      const msg = e.message ?? String(e);
-      throw new AstRunnerError("AST_GRAMMAR_LOAD_FAILED", {
-        what: `Failed to load tree-sitter grammar for ${f.path}: ${msg}`,
-        why: `The bundled WASM grammar could not be loaded.`,
-        next: `Reinstall the CLI.`
+      throw new AstRunnerError("AST_CHECK_THROWN", {
+        what: `check.mjs threw an exception while running (aspect '${params.aspectId}').`,
+        why: (e instanceof Error ? e.stack : void 0) ?? String(e),
+        next: `Fix the bug in check.mjs, then re-run: yg check --approve`
       });
     }
-    if (ast.rootNode.hasError) {
-      const err = findFirstErrorNode(ast.rootNode);
-      throw new AstRunnerError("AST_SOURCE_PARSE_ERROR", {
-        what: `Source file ${f.path} has a syntax error at line ${(err?.startPosition.row ?? 0) + 1}.`,
-        why: `Tree-sitter could not parse the file cleanly.`,
-        next: `Fix the syntax error in ${f.path}.`
+    if (raw !== null && typeof raw === "object" && typeof raw.then === "function") {
+      throw new AstRunnerError("AST_CHECK_ASYNC", {
+        what: `check.mjs returned a Promise; only synchronous returns are supported in v1.`,
+        why: `The runner does not await check's return value.`,
+        next: `Refactor check to be synchronous.`
       });
     }
-    params.parseCache?.set(f.path, { content: content20, ast });
-    sourceFiles.push({ path: f.path, content: content20, ast });
-  }
-  const rangesPerFile = /* @__PURE__ */ new Map();
-  for (const f of sourceFiles) {
-    const totalLines = f.content.split("\n").length;
-    rangesPerFile.set(f.path, collectSuppressions(f.ast, f.path, totalLines, f.content));
-  }
-  const ctx = { files: sourceFiles };
-  let raw;
-  try {
-    raw = checkFn(ctx);
-  } catch (e) {
-    throw new AstRunnerError("AST_CHECK_THROWN", {
-      what: `check.mjs threw an exception while running (aspect '${params.aspectId}').`,
-      why: (e instanceof Error ? e.stack : void 0) ?? String(e),
-      next: `Fix the bug in check.mjs, then re-run: yg check --approve`
-    });
-  }
-  if (raw !== null && typeof raw === "object" && typeof raw.then === "function") {
-    throw new AstRunnerError("AST_CHECK_ASYNC", {
-      what: `check.mjs returned a Promise; only synchronous returns are supported in v1.`,
-      why: `The runner does not await check's return value.`,
-      next: `Refactor check to be synchronous.`
-    });
-  }
-  if (!Array.isArray(raw)) {
-    throw new AstRunnerError("AST_CHECK_RETURN_SHAPE", {
-      what: `check.mjs returned ${typeof raw}, expected Violation[].`,
-      why: `The runner reports violations from the array returned by check.`,
-      next: `Return [] or Violation[] from check.`
-    });
-  }
-  const contextPaths = new Set(sourceFiles.map((f) => f.path));
-  for (const v of raw) {
-    if (!contextPaths.has(v.file)) {
-      throw new AstRunnerError("AST_CHECK_FILE_NOT_IN_CONTEXT", {
-        what: `check.mjs returned a Violation referencing file '${v.file}' which is not in ctx.files (aspect '${params.aspectId}').`,
-        why: `Author cannot synthesize violations against files they were not given. Suppress markers cannot reach unknown files.`,
-        next: `Return only violations for files in ctx.files (the array passed to check).`
+    if (!Array.isArray(raw)) {
+      throw new AstRunnerError("AST_CHECK_RETURN_SHAPE", {
+        what: `check.mjs returned ${typeof raw}, expected Violation[].`,
+        why: `The runner reports violations from the array returned by check.`,
+        next: `Return [] or Violation[] from check.`
       });
     }
+    const contextPaths = new Set(sourceFiles.map((f) => f.path));
+    for (const v of raw) {
+      if (!contextPaths.has(v.file)) {
+        throw new AstRunnerError("AST_CHECK_FILE_NOT_IN_CONTEXT", {
+          what: `check.mjs returned a Violation referencing file '${v.file}' which is not in ctx.files (aspect '${params.aspectId}').`,
+          why: `Author cannot synthesize violations against files they were not given. Suppress markers cannot reach unknown files.`,
+          next: `Return only violations for files in ctx.files (the array passed to check).`
+        });
+      }
+    }
+    const filtered = raw.filter((v) => {
+      const ranges = rangesPerFile.get(v.file);
+      if (!ranges) return true;
+      return !isLineSuppressed(ranges, params.aspectId, v.line);
+    });
+    return { violations: filtered };
+  } finally {
+    for (const t of localTrees) t.delete();
   }
-  const filtered = raw.filter((v) => {
-    const ranges = rangesPerFile.get(v.file);
-    if (!ranges) return true;
-    return !isLineSuppressed(ranges, params.aspectId, v.line);
-  });
-  return { violations: filtered };
 }
 function findFirstErrorNode(node) {
   if (node.isError) return node;
@@ -21822,7 +21853,9 @@ async function scanMarkersForFile(relFile, text2) {
   }
   try {
     const tree = await parseFile(relFile, text2);
-    return scanSuppressionMarkersInComments(tree, relFile);
+    const result = scanSuppressionMarkersInComments(tree, relFile);
+    tree.delete();
+    return result;
   } catch (error) {
     debugWrite(`[suppressions] parse fallback (raw scan): ${relFile}: ${error instanceof Error ? error.message : String(error)}`);
     return scanSuppressionMarkers(text2);

package/dist/structure.js

@@ -549,6 +549,7 @@ var GRAMMAR_DIRS = [
 ];
 var initPromise = null;
 var langCache = /* @__PURE__ */ new Map();
+var parserCache = /* @__PURE__ */ new Map();
 function init() {
   if (initPromise === null) {
     initPromise = Parser.init();
@@ -589,8 +590,11 @@ async function getParser(extension) {
     });
   }
   const lang = await langP;
+  const existing = parserCache.get(cacheKey);
+  if (existing) return existing;
   const parser = new Parser();
   parser.setLanguage(lang);
+  parserCache.set(cacheKey, parser);
   return parser;
 }
 async function parseFile(filePath, content) {
@@ -876,6 +880,14 @@ function validateCheckModuleExport(mod, opts) {
   return { ok: true };
 }
 
+// src/ast/parse-cache.ts
+function destroyParseCache(cache) {
+  for (const { ast } of cache.values()) {
+    ast.delete();
+  }
+  cache.clear();
+}
+
 // src/structure/hook-loader.ts
 import * as fs4 from "fs";
 import * as path8 from "path";
@@ -1435,143 +1447,149 @@ async function buildUnitCtx(params) {
 // src/structure/runner.ts
 async function runStructureAspect(params) {
   const { aspectDir, aspectId, nodePath, graph, projectRoot, subjectScope } = params;
+  const ownCache = !params.parseCache;
   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);
-  } catch (err) {
-    if (err instanceof UndeclaredFsReadError) {
-      return {
-        violations: [{
-          message: `Aspect tried to read undeclared path '${err.path}'. Add a relation in yg-node.yaml to the node owning this path.`,
-          kind: "structure-aspect-undeclared-fs-read",
-          file: `.yggdrasil/aspects/${aspectId}/check.mjs`
-        }],
-        touchedFiles: [],
-        succeeded: false,
-        observations: recorder.snapshot(),
-        observationsTainted: recorder.tainted
-      };
+    let rangesFor2 = function(filePath) {
+      const existing = rangesByFile.get(filePath);
+      if (existing !== void 0) return existing;
+      const cached = astCache.get(filePath);
+      let ranges;
+      if (cached) {
+        ranges = collectSuppressions(cached.ast, filePath, cached.content.split("\n").length, cached.content);
+      } else {
+        const content = contentByPath.get(filePath);
+        ranges = content !== void 0 ? collectSuppressions(void 0, filePath, content.split("\n").length, content) : null;
+      }
+      rangesByFile.set(filePath, ranges);
+      return ranges;
+    };
+    var rangesFor = rangesFor2;
+    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);
     }
-    if (err instanceof UndeclaredGraphReadError) {
-      return {
-        violations: [{
-          message: `Aspect tried to read undeclared graph node '${err.nodePath}'. Add a relation in yg-node.yaml.`,
-          kind: "structure-aspect-undeclared-graph-read",
-          file: `.yggdrasil/aspects/${aspectId}/check.mjs`
-        }],
-        touchedFiles: [],
-        succeeded: false,
-        observations: recorder.snapshot(),
-        observationsTainted: recorder.tainted
-      };
+    const checkFn = mod.check;
+    const { ctx, recorder, ownFiles, astInputSet } = await buildUnitCtx({
+      aspectId,
+      nodePath,
+      graph,
+      projectRoot,
+      astCache,
+      touchedFiles,
+      subjectScope
+    });
+    let raw;
+    try {
+      raw = checkFn(ctx);
+    } catch (err) {
+      if (err instanceof UndeclaredFsReadError) {
+        return {
+          violations: [{
+            message: `Aspect tried to read undeclared path '${err.path}'. Add a relation in yg-node.yaml to the node owning this path.`,
+            kind: "structure-aspect-undeclared-fs-read",
+            file: `.yggdrasil/aspects/${aspectId}/check.mjs`
+          }],
+          touchedFiles: [],
+          succeeded: false,
+          observations: recorder.snapshot(),
+          observationsTainted: recorder.tainted
+        };
+      }
+      if (err instanceof UndeclaredGraphReadError) {
+        return {
+          violations: [{
+            message: `Aspect tried to read undeclared graph node '${err.nodePath}'. Add a relation in yg-node.yaml.`,
+            kind: "structure-aspect-undeclared-graph-read",
+            file: `.yggdrasil/aspects/${aspectId}/check.mjs`
+          }],
+          touchedFiles: [],
+          succeeded: false,
+          observations: recorder.snapshot(),
+          observationsTainted: recorder.tainted
+        };
+      }
+      if (err instanceof ParseAstNotPrewarmedError) {
+        return {
+          violations: [{
+            message: `Aspect called ctx.parseAst on '${err.filePath}', which was not pre-warmed by the dispatcher. Add a declared relation to the node owning this file, or use ctx.parseYaml/Json/Toml if AST is not required.`,
+            kind: "structure-aspect-parseast-not-prewarmed",
+            file: `.yggdrasil/model/${nodePath}/yg-node.yaml`
+          }],
+          touchedFiles: [],
+          succeeded: false,
+          observations: recorder.snapshot(),
+          observationsTainted: recorder.tainted
+        };
+      }
+      throw new StructureRunnerError("STRUCTURE_CHECK_THROWN", {
+        what: `check.mjs threw an exception while running (aspect '${aspectId}').`,
+        why: `${err.message}
+${err.stack ?? ""}`,
+        next: `Fix the bug in check.mjs, then re-run: yg check --approve`
+      });
     }
-    if (err instanceof ParseAstNotPrewarmedError) {
-      return {
-        violations: [{
-          message: `Aspect called ctx.parseAst on '${err.filePath}', which was not pre-warmed by the dispatcher. Add a declared relation to the node owning this file, or use ctx.parseYaml/Json/Toml if AST is not required.`,
-          kind: "structure-aspect-parseast-not-prewarmed",
-          file: `.yggdrasil/model/${nodePath}/yg-node.yaml`
-        }],
-        touchedFiles: [],
-        succeeded: false,
-        observations: recorder.snapshot(),
-        observationsTainted: recorder.tainted
-      };
+    if (raw !== null && typeof raw === "object" && typeof raw.then === "function") {
+      throw new StructureRunnerError("STRUCTURE_CHECK_ASYNC", {
+        what: `check.mjs returned a Promise; only synchronous returns are supported.`,
+        why: `The runner does not await check's return value.`,
+        next: `Refactor check to be synchronous.`
+      });
     }
-    throw new StructureRunnerError("STRUCTURE_CHECK_THROWN", {
-      what: `check.mjs threw an exception while running (aspect '${aspectId}').`,
-      why: `${err.message}
-${err.stack ?? ""}`,
-      next: `Fix the bug in check.mjs, then re-run: yg check --approve`
-    });
-  }
-  if (raw !== null && typeof raw === "object" && typeof raw.then === "function") {
-    throw new StructureRunnerError("STRUCTURE_CHECK_ASYNC", {
-      what: `check.mjs returned a Promise; only synchronous returns are supported.`,
-      why: `The runner does not await check's return value.`,
-      next: `Refactor check to be synchronous.`
-    });
-  }
-  if (!Array.isArray(raw)) {
-    throw new StructureRunnerError("STRUCTURE_CHECK_RETURN_SHAPE", {
-      what: `check.mjs returned ${typeof raw}, expected Violation[].`,
-      why: `The runner reports violations from the array returned by check.`,
-      next: `Return [] or Violation[] from check.`
-    });
-  }
-  const contextFiles = new Set(ownFiles.map((f) => f.path));
-  for (const t of touchedFiles) contextFiles.add(t);
-  const violations = [];
-  for (const v of raw) {
-    if (typeof v !== "object" || v === null || typeof v.message !== "string") {
+    if (!Array.isArray(raw)) {
       throw new StructureRunnerError("STRUCTURE_CHECK_RETURN_SHAPE", {
-        what: `Violation entry must be an object with a string 'message' field.`,
-        why: `The runner renders each violation from its message and optional file/line.`,
-        next: `Return objects shaped { message: string, file?: string, line?: number } from check.`
+        what: `check.mjs returned ${typeof raw}, expected Violation[].`,
+        why: `The runner reports violations from the array returned by check.`,
+        next: `Return [] or Violation[] from check.`
       });
     }
-    const vv = v;
-    if (typeof vv.file === "string" && !contextFiles.has(normalizeMappingPath(vv.file))) {
-      throw new StructureRunnerError("STRUCTURE_CHECK_FILE_NOT_IN_CONTEXT", {
-        what: `Violation references file '${vv.file}' not in ctx (own mapping or touched via ctx.fs/ctx.graph).`,
-        why: `Author cannot synthesize violations against files they were not given.`,
-        next: `Return only violations for files in ctx, or declare a relation to the node owning '${vv.file}'.`
-      });
+    const contextFiles = new Set(ownFiles.map((f) => f.path));
+    for (const t of touchedFiles) contextFiles.add(t);
+    const violations = [];
+    for (const v of raw) {
+      if (typeof v !== "object" || v === null || typeof v.message !== "string") {
+        throw new StructureRunnerError("STRUCTURE_CHECK_RETURN_SHAPE", {
+          what: `Violation entry must be an object with a string 'message' field.`,
+          why: `The runner renders each violation from its message and optional file/line.`,
+          next: `Return objects shaped { message: string, file?: string, line?: number } from check.`
+        });
+      }
+      const vv = v;
+      if (typeof vv.file === "string" && !contextFiles.has(normalizeMappingPath(vv.file))) {
+        throw new StructureRunnerError("STRUCTURE_CHECK_FILE_NOT_IN_CONTEXT", {
+          what: `Violation references file '${vv.file}' not in ctx (own mapping or touched via ctx.fs/ctx.graph).`,
+          why: `Author cannot synthesize violations against files they were not given.`,
+          next: `Return only violations for files in ctx, or declare a relation to the node owning '${vv.file}'.`
+        });
+      }
+      violations.push(vv);
     }
-    violations.push(vv);
-  }
-  const contentByPath = /* @__PURE__ */ new Map();
-  for (const f of [...ownFiles, ...astInputSet]) {
-    contentByPath.set(normalizeMappingPath(f.path), f.content);
-  }
-  const rangesByFile = /* @__PURE__ */ new Map();
-  function rangesFor(filePath) {
-    const existing = rangesByFile.get(filePath);
-    if (existing !== void 0) return existing;
-    const cached = astCache.get(filePath);
-    let ranges;
-    if (cached) {
-      ranges = collectSuppressions(cached.ast, filePath, cached.content.split("\n").length, cached.content);
-    } else {
-      const content = contentByPath.get(filePath);
-      ranges = content !== void 0 ? collectSuppressions(void 0, filePath, content.split("\n").length, content) : null;
+    const contentByPath = /* @__PURE__ */ new Map();
+    for (const f of [...ownFiles, ...astInputSet]) {
+      contentByPath.set(normalizeMappingPath(f.path), f.content);
     }
-    rangesByFile.set(filePath, ranges);
-    return ranges;
-  }
-  const visible = violations.filter((v) => {
-    if (typeof v.file !== "string" || typeof v.line !== "number") return true;
-    const ranges = rangesFor(normalizeMappingPath(v.file));
-    if (!ranges) return true;
-    return !isLineSuppressed(ranges, aspectId, v.line);
-  });
-  return {
-    violations: visible,
-    touchedFiles,
-    succeeded: true,
-    observations: recorder.snapshot(),
-    observationsTainted: recorder.tainted
-  };
+    const rangesByFile = /* @__PURE__ */ new Map();
+    const visible = violations.filter((v) => {
+      if (typeof v.file !== "string" || typeof v.line !== "number") return true;
+      const ranges = rangesFor2(normalizeMappingPath(v.file));
+      if (!ranges) return true;
+      return !isLineSuppressed(ranges, aspectId, v.line);
+    });
+    return {
+      violations: visible,
+      touchedFiles,
+      succeeded: true,
+      observations: recorder.snapshot(),
+      observationsTainted: recorder.tainted
+    };
+  } finally {
+    if (ownCache) destroyParseCache(astCache);
+  }
 }
 
 // src/structure/suppress-ranges.ts
@@ -1587,6 +1605,7 @@ async function resolveSuppressedRangesForPrompt(subjects, aspectId) {
     }
     const totalLines = content.split("\n").length;
     const all = collectSuppressions(tree, subject.path, totalLines, content);
+    tree?.delete();
     const ranges = formatSuppressedRangesForAspect(all, aspectId);
     if (ranges.length > 0) {
       byFile.push({ path: subject.path, ranges });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrisdudek/yg",
-  "version": "5.2.3",
+  "version": "5.2.5",
   "description": "Architecture rules your AI coding agent can't ignore. It gets the rules for a file before it edits, and every change is checked — by a free local script or an LLM reviewer — before it moves on. Works with Claude Code, Cursor, Copilot, Codex, Cline.",
   "type": "module",
   "bin": {
@@ -85,7 +85,7 @@
     "@tree-sitter-grammars/tree-sitter-kotlin": "^1.1.0",
     "@tree-sitter-grammars/tree-sitter-toml": "^0.7.0",
     "@tree-sitter-grammars/tree-sitter-yaml": "^0.7.1",
-    "@types/node": "^25.9.1",
+    "@types/node": "^26.0.0",
     "@types/semver": "^7.7.1",
     "@vitest/coverage-v8": "^4.1.8",
     "eslint": "^10.4.1",