@dotdotgod/cli 0.3.11 → 0.4.0

package/README.md

@@ -37,6 +37,7 @@ dotdotgod init .
 dotdotgod validate .
 dotdotgod query . "project documentation"
 dotdotgod graph impact . --changed <path> --compact
+dotdotgod graph serve . --changed <path>
 ```
 
 ## What It Does
@@ -47,6 +48,7 @@ dotdotgod graph impact . --changed <path> --compact
 - `query` locally embeds shared Markdown with `Xenova/multilingual-e5-small`, incrementally stores vectors under `.dotdotgod/vectors/`, and returns the best-ranked chunk from each relevant Markdown file.
 - `resolve` and `expand` map explicit or high-signal prompt references to project files and can include related impact evidence.
 - `graph impact` ranks likely related specs, tests, docs, commands, and source files for one or more changed paths, with a combined ranking and per-file top five. Non-seed scores use fixed weighted PPR connection `80` plus memory policy `20`. A bounded request-local multilingual vector overlay participates in PPR when the query cache is available; vector preparation failures degrade to structural-only results.
+- `graph serve` starts a local read-only explorer rooted at one or more changed files. It keeps only connected shared structural nodes, lays them out by minimum structural hop, and supports persisted instant, layer, or one-by-one reveal modes.
 - `traceability links` checks or repairs generated Markdown traceability-link sections.
 
 ## Commands
@@ -72,6 +74,8 @@ dotdotgod traceability links . --write
 dotdotgod graph impact . --changed <path>
 dotdotgod graph impact . --changed <path> --changed <another-path> --compact
 dotdotgod graph impact . --changed <path> --changed <another-path> --yml
+dotdotgod graph serve . --changed <path>
+dotdotgod graph serve . --changed <path> --changed <another-path> --port 4313
 dotdotgod graph communities .
 ```
 
@@ -86,6 +90,7 @@ dotdotgod graph communities .
 | Resolve `[[...]]` references from a prompt | `dotdotgod expand . "Update [[PLAN_MODE]]"` |
 | Repair generated traceability-link sections | `dotdotgod traceability links . --write` |
 | See what else to inspect after a change | `dotdotgod graph impact . --changed <path> --compact` |
+| Explore the connected structural graph visually | `dotdotgod graph serve . --changed <path>` |
 
 ## Changed-File Impact
 
@@ -109,6 +114,24 @@ files:
 
 The indexed graph is built from maintained project files: Markdown links, README routes, headings, configured traceability relations, package metadata, scripts and packaged resources, dependencies, and memory-area membership. Impact analysis can add request-local vector edges for candidate discovery and PPR without mutating that indexed graph.
 
+## Local Impact Graph Explorer
+
+```bash
+dotdotgod graph serve . --changed packages/cli/src/core.mjs
+```
+
+`graph serve` prints a local URL and binds to `127.0.0.1` by default. Repeat `--changed` to use multiple roots. Set `--port 4313` for a fixed port or `--host <host>` when the default loopback binding is not suitable.
+
+The explorer includes only shared indexed nodes structurally connected to a retained changed-file root. Connectivity treats stored structural edges as undirected so incoming evidence remains discoverable, while rendered arrows preserve each relation's original direction. Local-memory nodes, disconnected nodes, and request-local vector edges are excluded from the canvas and search.
+
+Use **Node reveal** to choose:
+
+- **Instant** — place the complete connected graph immediately.
+- **By hop layer** — reveal the root first and then each minimum-hop layer.
+- **One by one** — reveal nodes in deterministic breadth-first order with an automatically bounded total delay.
+
+The browser remembers the selected mode. **Skip reveal** completes an active sequence immediately. Re-rooting and relation filters morph surviving nodes toward their new positions, while `prefers-reduced-motion` resolves every mode to immediate placement. Graph distance is layout-only and never represents impact score.
+
 ## Validation and Verification Boundaries
 
 | Command | Responsibility |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdotgod/cli",
-  "version": "0.3.11",
+  "version": "0.4.0",
   "description": "CLI for dotdotgod validation, local documentation search, and graph indexing.",
   "type": "module",
   "license": "Elastic-2.0",

package/src/commands/graph.mjs

@@ -5,7 +5,7 @@ import { buildCompactImpactReport, buildImpactReport } from '../impact/report.mj
 import { buildVectorImpactOverlay } from '../impact/vector-overlay.mjs';
 import { canonicalizeChangedPath } from '../impact/vector-profile.mjs';
 import { startImpactGraphServer } from '../graph-view/server.mjs';
-import { formatCompactImpactOutput, formatYmlGraphImpactError, formatYmlImpactOutput } from '../impact/format.mjs';
+import { formatCompactImpactOutput, formatImpactWarnings, formatYmlGraphImpactError, formatYmlImpactOutput } from '../impact/format.mjs';
 
 const MAX_CHANGED_FILES = 20;
 
@@ -86,7 +86,7 @@ export async function runGraph(argv) {
   if (isImpact) options.changed = [...new Set(options.changed.map((path) => canonicalizeChangedPath(options.root, path)).filter(Boolean))];
   const { status, index, metadata } = readFreshIndex(options.root);
   const overlay = isImpact ? await buildVectorImpactOverlay(options.root, index, options.changed) : undefined;
-  const rawImpact = isImpact ? buildImpactReport(index, options.changed, { overlay, verboseSemantic: options.json }) : undefined;
+  const rawImpact = isImpact ? buildImpactReport(index, options.changed, { root: options.root, overlay, verboseSemantic: options.json }) : undefined;
   const impact = isImpact && (options.compact || options.yml) ? buildCompactImpactReport(rawImpact) : rawImpact;
   const payload = isImpact
     ? { ok: status.ok, command: 'graph impact', compact: options.compact || undefined, root: options.root, status, metadata, changed: options.changed[0], changedFiles: options.changed, related: impact.related, impact }
@@ -95,6 +95,6 @@ export async function runGraph(argv) {
   if (options.json) console.log(JSON.stringify(payload, null, 2));
   else if (isImpact && options.yml) console.log(formatYmlImpactOutput(payload, impact));
   else if (isImpact && options.compact) console.log(formatCompactImpactOutput(payload, impact));
-  else if (isImpact) console.log(`graph impact: ${payload.related.length} related node(s), ${impact.omittedRelated ?? 0} omitted (${status.status}${refreshNote} index)`);
+  else if (isImpact) console.log([`graph impact: ${payload.related.length} related node(s), ${impact.omittedRelated ?? 0} omitted (${status.status}${refreshNote} index)`, ...formatImpactWarnings(impact.warnings)].join('\n'));
   else console.log(`graph communities: ${payload.communities.communities.length}/${payload.communities.total} shown, ${payload.communities.omitted} omitted (${status.status}${refreshNote} index)`);
 }

package/src/graph/extract.mjs

@@ -4,7 +4,7 @@ import { rel } from '../common/paths.mjs';
 import { extractLinks } from '../docs/markdown.mjs';
 import { defaultMemoryConfig } from '../memory/config.mjs';
 import { addEdge, addNode } from './store.mjs';
-import { addMemoryAreaMembership, addPackageResource, addTraceabilityGraph, fileNodeMetadata, headingId, isReadmeIndexPath } from './metadata.mjs';
+import { addMemoryAreaMembership, addPackageResource, addReferenceEvidence, addTraceabilityGraph, fileNodeMetadata, headingId, isReadmeIndexPath } from './metadata.mjs';
 
 function extractMarkdownGraph(root, file, graph, config = defaultMemoryConfig()) {
   const path = rel(root, file);
@@ -19,9 +19,14 @@ function extractMarkdownGraph(root, file, graph, config = defaultMemoryConfig())
     addEdge(graph, fileId, id, 'contains_heading', { confidence: 'EXTRACTED' });
   }
   for (const { href, line } of extractLinks(content)) {
-    const pathPart = href.split('#')[0];
+    const hashIndex = href.indexOf('#');
+    const pathPart = hashIndex < 0 ? href : href.slice(0, hashIndex);
+    const anchor = hashIndex < 0 ? '' : href.slice(hashIndex + 1);
+    const targetPath = pathPart ? rel(root, resolve(dirname(file), pathPart)) : path;
+    const data = { line, confidence: 'EXTRACTED' };
+    addReferenceEvidence(graph, fileId, { targetPath, href, anchor, relation: 'links_to', data });
+    if (pathPart && isReadmeIndexPath(path)) addReferenceEvidence(graph, fileId, { targetPath, href, anchor, relation: 'routes_to', data: { line, confidence: 'CURATED_INDEX', sourceRole: 'readme-index' } });
     if (!pathPart) continue;
-    const targetPath = rel(root, resolve(dirname(file), pathPart));
     const targetId = `file:${targetPath}`;
     addNode(graph, targetId, 'file', fileNodeMetadata(targetPath, null, config));
     addEdge(graph, fileId, targetId, 'links_to', { line, confidence: 'EXTRACTED' });

package/src/graph/metadata.mjs

@@ -62,8 +62,17 @@ export function addPackageResource(graph, fileId, packagePath, name, target, kin
   addEdge(graph, fileId, id, 'includes_resource', { kind, confidence: 'EXTRACTED' });
 }
 
+export function addReferenceEvidence(graph, sourceId, reference) {
+  const source = graph.nodes.find((node) => node.id === sourceId);
+  if (!source) return;
+  source.references ??= [];
+  source.references.push(reference);
+}
+
 function addTraceabilityTarget(graph, sourceId, root, relation, targetPath, data = {}, config = defaultMemoryConfig()) {
-  if (!isLocalRelativeTraceabilityPath(targetPath) || !existsSync(resolve(root, targetPath))) return;
+  if (!isLocalRelativeTraceabilityPath(targetPath)) return;
+  addReferenceEvidence(graph, sourceId, { targetPath, href: targetPath, relation, data: { confidence: 'CURATED_TRACEABILITY', ...data } });
+  if (!existsSync(resolve(root, targetPath))) return;
   const targetId = `file:${targetPath}`;
   addNode(graph, targetId, 'file', fileNodeMetadata(targetPath, null, config));
   addEdge(graph, sourceId, targetId, relation, { confidence: 'CURATED_TRACEABILITY', ...data });

package/src/graph-view/assets/app.css

@@ -109,3 +109,7 @@ h3 { font-size: 1rem; }
   .evidence { min-height: 70vh; }
 }
 @media (prefers-reduced-motion: reduce) { *, *::before, *::after { scroll-behavior: auto !important; transition: none !important; animation: none !important; } }
+
+.reference-warnings { padding: 12px; border: 1px solid var(--border, #ddd); border-radius: 8px; }
+.reference-warnings h3 { margin: 0; }
+.reference-warnings ul { padding-left: 18px; overflow-wrap: anywhere; }

package/src/graph-view/assets/app.js

@@ -222,6 +222,15 @@
     const omitted = payload.graph.diagnostics?.disconnectedNodesOmitted ?? 0;
     const depth = payload.graph.diagnostics?.maximumDepth ?? 0;
     elements.summary.textContent = `${payload.graph.nodes.length} connected nodes · ${payload.graph.edges.length} relations · ${depth} hops · ${omitted} disconnected omitted`;
+    const warnings = payload.impact.warnings ?? { total: 0, omitted: 0, items: [] };
+    document.querySelector('#reference-warnings').hidden = warnings.total === 0;
+    document.querySelector('#reference-warning-summary').textContent = `${warnings.total} reference warning(s), ${warnings.omitted} omitted. Broken references are excluded; uncertain access is not proof of breakage.`;
+    const warningList = document.querySelector('#reference-warning-list');
+    warningList.replaceChildren(...warnings.items.map((warning) => {
+      const item = document.createElement('li');
+      item.textContent = `${warning.source}${warning.line ? `:${warning.line}` : ''} → ${warning.target} [${warning.reason}]`;
+      return item;
+    }));
     renderFilters(payload.graph.edges); renderGraph(); renderList(); renderSearch();
     if (state.selected && payload.graph.nodes.some((node) => node.id === state.selected)) renderInspection(payload.graph.nodes.find((node) => node.id === state.selected));
     else if (payload.graph.nodes.length === 0) elements.inspection.innerHTML = '<h3>No shared structural nodes</h3><p>Add indexable shared files or relations to populate this graph. Local memory and headings are intentionally hidden.</p>';

package/src/graph-view/assets/index.html

@@ -58,6 +58,11 @@
         <ul id="node-search-results" class="node-search-results"></ul>
       </section>
       <div class="evidence-heading"><h2 id="evidence-title">Ranked evidence</h2><span id="result-count"></span></div>
+      <section id="reference-warnings" class="reference-warnings" aria-live="polite" hidden>
+        <h3>Reference warnings</h3>
+        <p id="reference-warning-summary"></p>
+        <ul id="reference-warning-list"></ul>
+      </section>
       <ol id="result-list" class="result-list"></ol>
       <section id="inspection" class="inspection" aria-live="polite">
         <h3>Select an impacted file</h3>

package/src/graph-view/payload.mjs

@@ -45,7 +45,7 @@ function rootReachability(nodes, edges, seedIds) {
 }
 
 export function buildImpactGraphPayload(index, impact) {
-  const graph = index?.graph ?? { nodes: [], edges: [] };
+  const graph = impact.structuralGraph ?? index?.graph ?? { nodes: [], edges: [] };
   const config = index?.memoryConfig;
   const seedIds = new Set((impact.changedFiles ?? [impact.changed]).map((path) => `file:${path}`));
   const impactItems = new Map((impact.related ?? []).map((item) => [item.id, item]));

package/src/graph-view/server.mjs

@@ -36,7 +36,7 @@ export async function buildServedImpact(root, changedPaths) {
   const normalized = [...new Set(changedPaths.map((path) => canonicalizeChangedPath(root, path)).filter(Boolean))];
   const { status, index, metadata } = readFreshIndex(root);
   const overlay = await buildVectorImpactOverlay(root, index, normalized);
-  const impact = buildImpactReport(index, normalized, { overlay, verboseSemantic: false, related: 40 });
+  const impact = buildImpactReport(index, normalized, { root, overlay, verboseSemantic: false, related: 40 });
   const graph = buildImpactGraphPayload(index, impact);
   const graphIds = new Set(graph.nodes.map((node) => node.id));
   const explorerImpact = {

package/src/impact/format.mjs

@@ -1,5 +1,13 @@
 import { commandUsage } from '../cli/usage.mjs';
 
+export function formatImpactWarnings(warnings) {
+  if (!warnings?.total) return [];
+  return [
+    `Reference warnings: ${warnings.total} (${warnings.omitted} omitted); broken references excluded from impact.`,
+    ...warnings.items.map((item) => `- ${item.source}${item.line ? `:${item.line}` : ''} -> ${item.target} [${item.reason}]${item.reason === 'REFERENCE_UNAVAILABLE' ? ' (access uncertain; not excluded)' : ''}`),
+  ];
+}
+
 function formatCompactImpactGroup(name, group) {
   const items = group?.items ?? [];
   if (items.length === 0) return [];
@@ -16,6 +24,7 @@ function formatCompactImpactGroup(name, group) {
 export function formatCompactImpactOutput(payload, impact) {
   const refreshNote = payload.metadata.cacheRefreshed ? ', refreshed' : '';
   const lines = [`graph impact compact: ${impact.related.length} related node(s), ${impact.omittedRelated ?? 0} omitted (${payload.status.status}${refreshNote} index)`, `changed files: ${(impact.changedFiles ?? [impact.changed]).join(', ')}`];
+  lines.push(...formatImpactWarnings(impact.warnings));
   for (const entry of impact.perSeed ?? []) lines.push(...formatCompactImpactGroup(`top for ${entry.changed}`, { items: entry.related }));
   for (const name of ['docs', 'contracts', 'tests', 'files', 'commands', 'events', 'packageResources', 'symbols']) lines.push(...formatCompactImpactGroup(name, impact.groups[name]));
   return lines.join('\n');
@@ -84,6 +93,13 @@ export function formatYmlImpactOutput(payload, impact) {
   }
   lines.push('  groups:');
   for (const name of ['docs', 'contracts', 'tests', 'files', 'commands', 'events', 'packageResources', 'symbols']) lines.push(...formatYmlImpactGroup(name, impact.groups[name]));
+  lines.push('  warnings:');
+  lines.push(`    total: ${impact.warnings?.total ?? 0}`, `    omitted: ${impact.warnings?.omitted ?? 0}`, '    items:');
+  if (!impact.warnings?.items?.length) lines.push('      []');
+  else for (const item of impact.warnings.items) {
+    lines.push(`      - source: ${ymlScalar(item.source)}`, `        target: ${ymlScalar(item.target)}`, `        target_path: ${ymlScalar(item.targetPath)}`, `        relation: ${ymlScalar(item.relation)}`, `        reason: ${ymlScalar(item.reason)}`);
+    if (item.line) lines.push(`        line: ${item.line}`);
+  }
   lines.push('  recommended_actions:');
   lines.push('    - "review_related_docs"');
   lines.push('    - "run_related_tests"');

package/src/impact/references.mjs

@@ -0,0 +1,78 @@
+import { readFileSync, statSync } from 'node:fs';
+import { extname, resolve } from 'node:path';
+import { extractAnchors } from '../docs/markdown.mjs';
+import { fileNodeMetadata } from '../graph/metadata.mjs';
+
+const WARNING_LIMIT = 20;
+const edgeKey = (source, target, relation) => `${source}\0${target}\0${relation}`;
+
+// Request-local: persisted source evidence remains intact for target restoration.
+export function prepareImpactReferences(index, root, changedPaths) {
+  const graph = index?.graph ?? { nodes: [], edges: [] };
+  if (!root) return { index, warnings: { items: [], total: 0, omitted: 0 } };
+  const seeds = new Set(changedPaths.map((path) => `file:${path}`));
+  const checks = new Map();
+  const inspect = (path) => {
+    if (checks.has(path)) return checks.get(path);
+    let result;
+    try {
+      const absolute = resolve(root, path);
+      const stat = statSync(absolute);
+      result = { status: 'exists' };
+      if (stat.isFile() && extname(absolute) === '.md') result.anchors = extractAnchors(readFileSync(absolute, 'utf8'));
+    } catch (error) {
+      result = { status: ['ENOENT', 'ENOTDIR'].includes(error.code) ? 'missing' : 'unavailable' };
+    }
+    checks.set(path, result);
+    return result;
+  };
+  const references = graph.nodes.flatMap((node) => (node.references ?? []).map((reference) => ({ ...reference, source: node.id, sourcePath: node.path })));
+  const managedEdges = new Set(references.map((ref) => edgeKey(ref.source, `file:${ref.targetPath}`, ref.relation)));
+  const adjacency = new Map();
+  const connect = (source, target) => {
+    if (!adjacency.has(source)) adjacency.set(source, new Set());
+    if (!adjacency.has(target)) adjacency.set(target, new Set());
+    adjacency.get(source).add(target);
+    adjacency.get(target).add(source);
+  };
+  for (const edge of graph.edges) connect(edge.source, edge.target);
+  for (const ref of references) connect(ref.source, `file:${ref.targetPath}`);
+  const reachable = new Set(seeds);
+  const queue = [...seeds];
+  for (let i = 0; i < queue.length; i += 1) for (const id of adjacency.get(queue[i]) ?? []) {
+    if (!reachable.has(id)) { reachable.add(id); queue.push(id); }
+  }
+  const missing = new Set(graph.nodes.filter((node) => node.path && inspect(node.path).status === 'missing' && !seeds.has(node.id)).map((node) => node.id));
+  const nodes = new Map(graph.nodes.filter((node) => !missing.has(node.id)).map((node) => [node.id, node]));
+  const edges = graph.edges.filter((edge) => !missing.has(edge.source) && !missing.has(edge.target) && !managedEdges.has(edgeKey(edge.source, edge.target, edge.relation)));
+  for (const path of changedPaths) {
+    const id = `file:${path}`;
+    if (!nodes.has(id)) nodes.set(id, { id, type: 'file', ...fileNodeMetadata(path, null, index?.memoryConfig) });
+  }
+  const warnings = new Map();
+  for (const ref of references) {
+    if (/^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(ref.href)) continue;
+    const targetId = `file:${ref.targetPath}`;
+    const check = inspect(ref.targetPath);
+    let reason = check.status === 'missing' ? 'MISSING_FILE' : check.status === 'unavailable' ? 'REFERENCE_UNAVAILABLE' : undefined;
+    if (!reason && ref.anchor && check.anchors) {
+      try { if (!check.anchors.has(decodeURIComponent(ref.anchor))) reason = 'BROKEN_ANCHOR'; }
+      catch { reason = 'BROKEN_ANCHOR'; }
+    }
+    if (reason) {
+      if (reachable.has(ref.source) && !missing.has(ref.source)) {
+        // README routes repeat ordinary links; show the original reference once.
+        const key = `${ref.source}\0${ref.href}\0${ref.data?.line ?? ''}\0${reason}`;
+        if (!warnings.has(key)) warnings.set(key, { source: ref.sourcePath ?? ref.source, target: ref.href, targetPath: ref.targetPath, relation: ref.relation, reason, ...(ref.data?.line ? { line: ref.data.line } : {}) });
+      }
+      // Deleted seeds retain incoming evidence so their referring docs remain reviewable.
+      // Uncertain access does not prove that a relation is broken.
+      if (reason !== 'REFERENCE_UNAVAILABLE' && !(reason === 'MISSING_FILE' && seeds.has(targetId))) continue;
+    }
+    if (missing.has(ref.source)) continue;
+    if (!nodes.has(targetId)) nodes.set(targetId, { id: targetId, type: 'file', ...fileNodeMetadata(ref.targetPath, null, index?.memoryConfig) });
+    edges.push({ source: ref.source, target: targetId, relation: ref.relation, ...ref.data });
+  }
+  const items = [...warnings.values()].sort((a, b) => a.source.localeCompare(b.source) || (a.line ?? 0) - (b.line ?? 0) || a.target.localeCompare(b.target) || a.reason.localeCompare(b.reason));
+  return { index: { ...index, graph: { nodes: [...nodes.values()], edges: edges.filter((edge) => nodes.has(edge.source) && nodes.has(edge.target)) } }, warnings: { items: items.slice(0, WARNING_LIMIT), total: items.length, omitted: Math.max(0, items.length - WARNING_LIMIT) } };
+}

package/src/impact/report.mjs

@@ -1,6 +1,7 @@
 import { DEFAULT_IMPACT_RANKING_POLICY, SEMANTIC_RELATIONS, cloneImpactRankingPolicy, defaultMemoryConfig, traceabilityRelationWeights } from '../memory/config.mjs';
 import { retrievalMetadataForPath } from '../graph/metadata.mjs';
 import { buildPersonalizedPageRank, compareImpactItems, docsArea, hasCuratedImpactReason, isLowActionabilityImpactItem, isSemanticOnlyImpactItem, isTestPath, scoreImpactItem } from './scoring.mjs';
+import { prepareImpactReferences } from './references.mjs';
 import { normalizeChangedPath } from './vector-profile.mjs';
 import { MAX_VECTOR_EVIDENCE_CHUNK_ID_CHARS, MAX_VECTOR_EVIDENCE_HEADING_CHARS } from './vector-overlay.mjs';
 
@@ -58,7 +59,7 @@ function buildCombinedImpactReport(index, changedPaths, limits = {}) {
   const traceabilityWeights = traceabilityRelationWeights(config.traceability);
   policy.relationWeights = { ...policy.relationWeights, ...traceabilityWeights };
   const curatedRelations = new Set(Object.keys(traceabilityWeights));
-  const nodeById = new Map(graph.nodes.map((node) => [node.id, node]));
+  const nodeById = new Map(graph.nodes.map(({ references, ...node }) => [node.id, node]));
   const seeds = changedPaths.map((path) => `file:${path}`);
   const seedSet = new Set(seeds);
   const maxRelated = Math.max(limits.related ?? 25, 0);
@@ -99,7 +100,8 @@ function buildCombinedImpactReport(index, changedPaths, limits = {}) {
     const scored = scoreImpactItem({ ...node, reasons: reasonList, retrieval }, seedSet, changedPaths, policy, pprScores, config);
     return { ...node, reasons: reasonList, hasCuratedEvidence, ...(vectorEvidence.has(id) ? { vectorEvidence: vectorEvidence.get(id) } : {}), retrieval: { ...retrieval, signals: [...new Set([...(retrieval.signals ?? []), ...reasonSignals])] }, ...scored };
   }).sort(compareImpactItems(seeds));
-  const rankedRelated = relatedAll.filter((item) => !seedSet.has(item.id));
+  const excludedIds = new Set(limits.excludeRelatedIds ?? seeds);
+  const rankedRelated = relatedAll.filter((item) => !excludedIds.has(item.id));
   const related = selectImpactItems(rankedRelated, maxRelated, []);
   for (const item of related) {
     if (item.type === 'file') {
@@ -113,17 +115,23 @@ function buildCombinedImpactReport(index, changedPaths, limits = {}) {
     else if (item.type === 'event') addImpactItem(groups.events, item, limits.events ?? 10);
     else if (item.type === 'package_resource') addImpactItem(groups.packageResources, item, limits.packageResources ?? 10);
   }
-  return { changed: changedPaths[0], changedFiles: changedPaths, semantic: { status: overlay.status ?? 'disabled', ...(limits.verboseSemantic ? { diagnostics: overlay.diagnostics } : {}) }, ranking: { method: 'weighted-personalized-pagerank+memory', configSource: index?.memoryConfig?.source ?? 'default', connectionCap: policy.connectionCap, memoryCap: policy.memoryCap, pprReference: policy.ppr.reference }, related, groups, omittedRelated: Math.max(0, relatedAll.length - related.length) };
+  return { changed: changedPaths[0], changedFiles: changedPaths, semantic: { status: overlay.status ?? 'disabled', ...(limits.verboseSemantic ? { diagnostics: overlay.diagnostics } : {}) }, ranking: { method: 'weighted-personalized-pagerank+memory', configSource: index?.memoryConfig?.source ?? 'default', connectionCap: policy.connectionCap, memoryCap: policy.memoryCap, pprReference: policy.ppr.reference }, related, groups, omittedRelated: Math.max(0, rankedRelated.length - related.length) };
 }
 
 export function buildImpactReport(index, changedPaths, limits = {}) {
   const normalized = normalizeChangedPaths(changedPaths);
+  const prepared = prepareImpactReferences(index, limits.root, normalized);
+  index = prepared.index;
+  const validIds = new Set(index?.graph?.nodes.map((node) => node.id) ?? []);
+  if (limits.overlay) limits = { ...limits, overlay: { ...limits.overlay, edges: (limits.overlay.edges ?? []).filter((edge) => validIds.has(edge.target)) } };
   const aggregate = buildCombinedImpactReport(index, normalized, limits);
+  aggregate.warnings = prepared.warnings;
+  Object.defineProperty(aggregate, 'structuralGraph', { value: index?.graph, enumerable: false });
   const perSeedLimit = limits.perSeed ?? 5;
   aggregate.perSeed = normalized.map((changed) => {
     const seedId = `file:${changed}`;
     const seedOverlay = limits.overlay ? { ...limits.overlay, edges: (limits.overlay.edges ?? []).filter((edge) => edge.source === seedId) } : undefined;
-    const report = buildCombinedImpactReport(index, [changed], { ...limits, overlay: seedOverlay, related: Math.max(limits.related ?? 25, perSeedLimit) });
+    const report = buildCombinedImpactReport(index, [changed], { ...limits, excludeRelatedIds: normalized.map((path) => `file:${path}`), overlay: seedOverlay, related: Math.max(limits.related ?? 25, perSeedLimit) });
     const related = report.related.slice(0, perSeedLimit);
     return { changed, related, omittedRelated: Math.max(0, report.related.length - related.length) + report.omittedRelated };
   });
@@ -158,5 +166,5 @@ export function buildCompactImpactReport(impact, limits = {}) {
   const groups = Object.fromEntries(groupNames.map((name) => [name, compactImpactGroup(impact.groups?.[name], groupLimit)]));
   const perSeed = (impact.perSeed ?? []).map((entry) => ({ changed: entry.changed, related: (entry.related ?? []).slice(0, limits.perSeed ?? 5).map(compactImpactItem), omittedRelated: entry.omittedRelated ?? 0 }));
   const top10 = (impact.related ?? []).filter((item) => !seedIds.has(item.id)).slice(0, 10);
-  return { changed: impact.changed, changedFiles, perSeed, semantic: impact.semantic, compact: true, ranking: { method: impact.ranking?.method, configSource: impact.ranking?.configSource, connectionCap: impact.ranking?.connectionCap, memoryCap: impact.ranking?.memoryCap, pprReference: impact.ranking?.pprReference }, related, groups, omittedRelated: (impact.omittedRelated ?? 0) + Math.max(0, (impact.related?.length ?? 0) - related.length), quality: { rawRelated: impact.related?.length ?? 0, compactRelated: related.length, semanticOnlyTop10: top10.filter((item) => isSemanticOnlyImpactItem(item)).length, curatedTop10: top10.filter((item) => hasCuratedImpactReason(item)).length, lowActionabilityTop10: top10.filter((item) => isLowActionabilityImpactItem(item)).length } };
+  return { changed: impact.changed, changedFiles, perSeed, warnings: impact.warnings, semantic: impact.semantic, compact: true, ranking: { method: impact.ranking?.method, configSource: impact.ranking?.configSource, connectionCap: impact.ranking?.connectionCap, memoryCap: impact.ranking?.memoryCap, pprReference: impact.ranking?.pprReference }, related, groups, omittedRelated: (impact.omittedRelated ?? 0) + Math.max(0, (impact.related?.length ?? 0) - related.length), quality: { rawRelated: impact.related?.length ?? 0, compactRelated: related.length, semanticOnlyTop10: top10.filter((item) => isSemanticOnlyImpactItem(item)).length, curatedTop10: top10.filter((item) => hasCuratedImpactReason(item)).length, lowActionabilityTop10: top10.filter((item) => isLowActionabilityImpactItem(item)).length } };
 }

package/src/index/constants.mjs

@@ -1,3 +1,3 @@
-export const CACHE_VERSION = 14;
+export const CACHE_VERSION = 15;
 export const CACHE_DIR = '.dotdotgod';
 export const MANIFEST_FILE = 'manifest.json';

package/src/reference/resolve.mjs

@@ -117,8 +117,8 @@ export function runExpand(argv) {
   if (options.withImpact) refs = refs.map((item) => {
     const topPath = item.top?.path;
     if (!topPath) return item;
-    const impact = buildCompactImpactReport(buildImpactReport(index, topPath));
-    return { ...item, impact: { changed: topPath, related: impact.related, groups: impact.groups, omittedRelated: impact.omittedRelated, quality: impact.quality } };
+    const impact = buildCompactImpactReport(buildImpactReport(index, topPath, { root: options.root }));
+    return { ...item, impact: { changed: topPath, warnings: impact.warnings, related: impact.related, groups: impact.groups, omittedRelated: impact.omittedRelated, quality: impact.quality } };
   });
   const payload = { ok: status.ok, command: 'expand', root: options.root, prompt, status, metadata, refs, omitted: refs.reduce((sum, item) => sum + item.omitted, 0) };
   if (options.json) console.log(JSON.stringify(payload, null, 2));