@chrisdudek/yg 2.4.1 → 2.5.1

package/dist/bin.js

@@ -45,6 +45,7 @@ quality:
   context_budget:
     warning: 10000
     error: 20000
+    own_warning: 5000
 `;
 
 // src/templates/platform.ts
@@ -348,8 +349,8 @@ When reviewing graph quality (triggered by user or quality improvement):
 
 - **\`yg\` not found** \u2192 inform user: "yg CLI is not installed or not in PATH." Stop.
 - **Unfixable validate errors** \u2192 if not resolved after 3 attempts, stop and report to user. Do not loop.
-- **Budget exceeded** \u2192 if \`yg build-context\` exits with error (context package exceeds budget), warn user: "This node should be split." Do not proceed with implementation.
-- **Budget warning (W005)** \u2192 if \`yg validate\` shows W005 (context near budget), the node needs splitting. NEVER delete knowledge from artifacts to reduce token count \u2014 knowledge destroyed is irrecoverable. Instead: identify a cohesive subset of the node's responsibilities, propose a split to the user, create child nodes, and redistribute artifacts. The total knowledge must be preserved or increased, never reduced.
+- **Budget warning (W005/W006)** \u2192 informational. \`yg validate\` shows a breakdown (own/hierarchy/aspects/flows/dependencies). Large inherited context means the system is complex \u2014 this is not a problem to fix, it is reality to acknowledge. Do not delete knowledge from artifacts. Do not attempt to "reduce" inherited context.
+- **Own budget warning (W015)** \u2192 own artifacts are large. Consider splitting this node's responsibilities into child nodes. Redistribute knowledge across children so total knowledge is preserved or increased, never reduced.
 - **Corrupted \`.yggdrasil/\` files** \u2192 report to user. Do not attempt repair.
 - **Incremental sync** \u2192 run \`yg drift-sync\` every 3-5 source files during multi-file tasks. Do not defer to end.`;
 var KNOWLEDGE_BASE = `## KNOWLEDGE BASE
@@ -439,7 +440,7 @@ When code anchors (\`anchors\` in an aspect entry in \`yg-node.yaml\`) are prese
 
 - [ ] 1. Read \`schemas/yg-flow.yaml\`
 - [ ] 2. Create \`flows/<name>/\` directory
-- [ ] 3. Write \`yg-flow.yaml\` \u2014 declare participants and flow-level aspects
+- [ ] 3. Write \`yg-flow.yaml\` \u2014 declare nodes (participant list) and flow-level aspects
 - [ ] 4. Write \`description.md\` with required sections: Business context, Trigger, Goal, Participants, Paths (at least Happy path), Invariants across all paths
 - [ ] 5. \`yg validate\`
 
@@ -492,7 +493,7 @@ yg drift-sync --node <path> [--recursive] | --all
 | Information specific to this node | Local node artifact (check \`yg-config.yaml artifacts\` for types) |
 | Rule that applies to many nodes | Aspect (content \`.md\` files in \`aspects/<id>/\`) |
 | Architectural invariant for a node type | Required aspect in \`yg-config.yaml node_types\` |
-| Business process participation | Flow (\`yg-flow.yaml participants\`) |
+| Business process participation | Flow (\`yg-flow.yaml nodes\`) |
 | Process-level requirement | Flow \`aspects\` + aspect directory |
 | Context shared across a domain | Parent node artifact |
 | Technology stack | Node artifact at appropriate hierarchy level |
@@ -1185,7 +1186,7 @@ import { parse as parseYaml3 } from "yaml";
 var DEFAULT_QUALITY = {
   min_artifact_length: 50,
   max_direct_relations: 10,
-  context_budget: { warning: 1e4, error: 2e4 }
+  context_budget: { warning: 1e4, error: 2e4, own_warning: void 0 }
 };
 async function parseConfig(filePath) {
   const content = await readFile5(filePath, "utf-8");
@@ -1250,7 +1251,8 @@ async function parseConfig(filePath) {
     max_direct_relations: qualityRaw.max_direct_relations ?? DEFAULT_QUALITY.max_direct_relations,
     context_budget: {
       warning: qualityRaw.context_budget?.warning ?? DEFAULT_QUALITY.context_budget.warning,
-      error: qualityRaw.context_budget?.error ?? DEFAULT_QUALITY.context_budget.error
+      error: qualityRaw.context_budget?.error ?? DEFAULT_QUALITY.context_budget.error,
+      own_warning: qualityRaw.context_budget?.own_warning
     }
   } : DEFAULT_QUALITY;
   if (quality.context_budget.error < quality.context_budget.warning) {
@@ -1258,6 +1260,9 @@ async function parseConfig(filePath) {
       `yg-config.yaml: quality.context_budget.error (${quality.context_budget.error}) must be >= warning (${quality.context_budget.warning})`
     );
   }
+  if (quality.context_budget.own_warning !== void 0 && quality.context_budget.own_warning <= 0) {
+    throw new Error("quality.context_budget.own_warning must be a positive number");
+  }
   return {
     version,
     name: raw.name.trim(),
@@ -1504,13 +1509,17 @@ async function parseFlow(flowDir, flowYamlPath) {
   if (!raw.name || typeof raw.name !== "string" || raw.name.trim() === "") {
     throw new Error(`yg-flow.yaml at ${flowYamlPath}: missing or empty 'name'`);
   }
-  const nodes = raw.nodes;
+  const nodes = raw.nodes ?? raw.participants;
   if (!Array.isArray(nodes) || nodes.length === 0) {
-    throw new Error(`yg-flow.yaml at ${flowYamlPath}: 'nodes' must be a non-empty array`);
+    throw new Error(
+      `yg-flow.yaml at ${flowYamlPath}: 'nodes' (or 'participants') must be a non-empty array`
+    );
   }
   const nodePaths = nodes.filter((n) => typeof n === "string");
   if (nodePaths.length === 0) {
-    throw new Error(`yg-flow.yaml at ${flowYamlPath}: 'nodes' must contain string node paths`);
+    throw new Error(
+      `yg-flow.yaml at ${flowYamlPath}: 'nodes' (or 'participants') must contain string node paths`
+    );
   }
   let aspects;
   if (raw.aspects !== void 0) {
@@ -1727,19 +1736,20 @@ async function scanAspectsDirectory(dirPath, aspectsRoot, aspects) {
   }
 }
 async function loadFlows(flowsDir) {
+  let entries;
   try {
-    const entries = await readdir4(flowsDir, { withFileTypes: true });
-    const flows = [];
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      const flowYamlPath = path9.join(flowsDir, entry.name, "yg-flow.yaml");
-      const flow = await parseFlow(path9.join(flowsDir, entry.name), flowYamlPath);
-      flows.push(flow);
-    }
-    return flows;
+    entries = await readdir4(flowsDir, { withFileTypes: true });
   } catch {
     return [];
   }
+  const flows = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const flowYamlPath = path9.join(flowsDir, entry.name, "yg-flow.yaml");
+    const flow = await parseFlow(path9.join(flowsDir, entry.name), flowYamlPath);
+    flows.push(flow);
+  }
+  return flows;
 }
 async function loadSchemas(schemasDir) {
   try {
@@ -2045,6 +2055,77 @@ function collectAncestors(node) {
   }
   return ancestors;
 }
+function collectDependencyAncestors(target, config, graph) {
+  const ancestors = collectAncestors(target);
+  const structuralFilenames = Object.entries(config.artifacts ?? {}).filter(([, c]) => c.included_in_relations).map(([filename]) => filename);
+  const configArtifactKeys = [...Object.keys(config.artifacts ?? {})];
+  return ancestors.map((ancestor) => {
+    const nodeAspects = (ancestor.meta.aspects ?? []).map((a) => a.aspect);
+    const expanded = expandAspects(nodeAspects, graph.aspects);
+    const filterFilenames = structuralFilenames.length > 0 ? structuralFilenames : configArtifactKeys;
+    const availableFiles = filterFilenames.filter(
+      (f) => ancestor.artifacts.some((a) => a.filename === f)
+    );
+    return {
+      path: ancestor.path,
+      name: ancestor.meta.name,
+      type: ancestor.meta.type,
+      aspects: expanded,
+      artifactFilenames: availableFiles
+    };
+  });
+}
+function computeBudgetBreakdown(pkg2, graph) {
+  let own = 0;
+  let hierarchy = 0;
+  let aspects = 0;
+  let flows = 0;
+  let relational = 0;
+  for (const layer of pkg2.layers) {
+    const tokens = estimateTokens(layer.content);
+    switch (layer.type) {
+      case "global":
+      case "own":
+        own += tokens;
+        break;
+      case "hierarchy":
+        hierarchy += tokens;
+        break;
+      case "aspects":
+        aspects += tokens;
+        break;
+      case "flows":
+        flows += tokens;
+        break;
+      case "relational":
+        relational += tokens;
+        break;
+    }
+  }
+  let depAncestorTokens = 0;
+  const node = graph.nodes.get(pkg2.nodePath);
+  if (node) {
+    const ancestorPaths = new Set(collectAncestors(node).map((a) => a.path));
+    for (const relation of node.meta.relations ?? []) {
+      const target = graph.nodes.get(relation.target);
+      if (!target || ancestorPaths.has(relation.target)) continue;
+      const depAncestors = collectDependencyAncestors(target, graph.config, graph);
+      for (const anc of depAncestors) {
+        const ancNode = graph.nodes.get(anc.path);
+        if (!ancNode) continue;
+        for (const filename of anc.artifactFilenames) {
+          const art = ancNode.artifacts.find((a) => a.filename === filename);
+          if (art) {
+            depAncestorTokens += estimateTokens(art.content);
+          }
+        }
+      }
+    }
+  }
+  const dependencies = relational + depAncestorTokens;
+  const total = own + hierarchy + aspects + flows + dependencies;
+  return { own, hierarchy, aspects, flows, dependencies, total };
+}
 function toContextMapOutput(pkg2, graph) {
   const node = graph.nodes.get(pkg2.nodePath);
   const config = graph.config;
@@ -2093,11 +2174,12 @@ function toContextMapOutput(pkg2, graph) {
     depRefs.push(ref);
   }
   const registry = buildArtifactRegistry(node, ancestors, depRefs, graph);
+  const breakdown = computeBudgetBreakdown(pkg2, graph);
   const warningThreshold = config.quality?.context_budget?.warning ?? 1e4;
   const errorThreshold = config.quality?.context_budget?.error ?? 2e4;
-  const budgetStatus = pkg2.tokenCount >= errorThreshold ? "error" : pkg2.tokenCount >= warningThreshold ? "warning" : "ok";
+  const budgetStatus = breakdown.total >= errorThreshold ? "severe" : breakdown.total >= warningThreshold ? "warning" : "ok";
   return {
-    meta: { tokenCount: pkg2.tokenCount, budgetStatus },
+    meta: { tokenCount: breakdown.total, budgetStatus, breakdown },
     project: config.name,
     node: {
       path: pkg2.nodePath,
@@ -2962,26 +3044,42 @@ async function checkAnchorPresence(graph) {
 }
 async function checkContextBudget(graph) {
   const issues = [];
-  const warningThreshold = graph.config.quality?.context_budget.warning ?? 1e4;
-  const errorThreshold = graph.config.quality?.context_budget.error ?? 2e4;
-  for (const [nodePath, node] of graph.nodes) {
+  const budget = graph.config.quality?.context_budget ?? { warning: 1e4, error: 2e4 };
+  const warningThreshold = budget.warning;
+  const errorThreshold = budget.error;
+  const ownWarningThreshold = budget.own_warning;
+  for (const [nodePath] of graph.nodes) {
+    const node = graph.nodes.get(nodePath);
     if (node.meta.blackbox) continue;
     try {
       const pkg2 = await buildContext(graph, nodePath);
-      if (pkg2.tokenCount >= errorThreshold) {
+      const breakdown = computeBudgetBreakdown(pkg2, graph);
+      const breakdownLine = `own: ${breakdown.own.toLocaleString()} (${pct(breakdown.own, breakdown.total)}) | hierarchy: ${breakdown.hierarchy.toLocaleString()} (${pct(breakdown.hierarchy, breakdown.total)}) | aspects: ${breakdown.aspects.toLocaleString()} (${pct(breakdown.aspects, breakdown.total)}) | flows: ${breakdown.flows.toLocaleString()} (${pct(breakdown.flows, breakdown.total)}) | dependencies: ${breakdown.dependencies.toLocaleString()} (${pct(breakdown.dependencies, breakdown.total)})`;
+      if (breakdown.total >= errorThreshold) {
         issues.push({
           severity: "warning",
           code: "W006",
           rule: "budget-error",
-          message: `Context is ${pkg2.tokenCount.toLocaleString()} tokens (error threshold: ${errorThreshold.toLocaleString()}) \u2014 blocks materialization, node must be split`,
+          message: `Context is ${breakdown.total.toLocaleString()} tokens (error threshold: ${errorThreshold.toLocaleString()}).
+     ${breakdownLine}`,
           nodePath
         });
-      } else if (pkg2.tokenCount >= warningThreshold) {
+      } else if (breakdown.total >= warningThreshold) {
         issues.push({
           severity: "warning",
           code: "W005",
           rule: "budget-warning",
-          message: `Context is ${pkg2.tokenCount.toLocaleString()} tokens (warning threshold: ${warningThreshold.toLocaleString()}). Split the node into smaller units \u2014 do not delete knowledge from artifacts to reduce size.`,
+          message: `Context is ${breakdown.total.toLocaleString()} tokens (warning threshold: ${warningThreshold.toLocaleString()}).
+     ${breakdownLine}`,
+          nodePath
+        });
+      }
+      if (ownWarningThreshold !== void 0 && breakdown.own >= ownWarningThreshold) {
+        issues.push({
+          severity: "warning",
+          code: "W015",
+          rule: "own-budget-warning",
+          message: `Own artifacts: ${breakdown.own.toLocaleString()} tokens (threshold: ${ownWarningThreshold.toLocaleString()}). Consider splitting this node's responsibilities into child nodes.`,
           nodePath
         });
       }
@@ -2990,6 +3088,10 @@ async function checkContextBudget(graph) {
   }
   return issues;
 }
+function pct(value, total) {
+  if (total === 0) return "0%";
+  return `${Math.round(value / total * 100)}%`;
+}
 
 // src/cli/build-context.ts
 function collectRelevantNodePaths(graph, nodePath) {
@@ -4321,7 +4423,8 @@ async function runSimulation(graph, nodePaths, targetNodePath) {
   for (const dep of nodePaths) {
     try {
       const pkg2 = await buildContext(graph, dep);
-      const status = pkg2.tokenCount >= budget.error ? "error" : pkg2.tokenCount >= budget.warning ? "warning" : "ok";
+      const breakdown = computeBudgetBreakdown(pkg2, graph);
+      const status = breakdown.total >= budget.error ? "severe" : breakdown.total >= budget.warning ? "warning" : "ok";
       let baselineTokens = null;
       if (baselineGraph?.nodes.has(dep)) {
         try {
@@ -4335,8 +4438,8 @@ async function runSimulation(graph, nodePaths, targetNodePath) {
       );
       const changedLine = hasDepOnTarget ? `  + Changed dependency interface: ${targetNodePath}
 ` : "";
-      const budgetLine = baselineTokens !== null ? `  Budget: ${baselineTokens} -> ${pkg2.tokenCount} tokens (${status})
-` : `  Budget: ${pkg2.tokenCount} tokens (${status})
+      const budgetLine = baselineTokens !== null ? `  Budget: ${baselineTokens} -> ${breakdown.total} tokens (${status})
+` : `  Budget: ${breakdown.total} tokens (${status})
 `;
       const driftEntry = driftByNode.get(dep);
       const driftLine = driftEntry && driftEntry.status !== "ok" ? `  Mapped files (on-disk): ${driftEntry.status}${driftEntry.details ? ` (${driftEntry.details})` : ""}