@dotdotgod/cli 0.1.30 → 0.1.36

package/src/graph/extract.mjs

@@ -0,0 +1,78 @@
+import { readFileSync } from 'node:fs';
+import { basename, dirname, resolve } from 'node:path';
+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';
+
+export function extractMarkdownGraph(root, file, graph, config = defaultMemoryConfig()) {
+  const path = rel(root, file);
+  const content = readFileSync(file, 'utf8');
+  const fileId = `file:${path}`;
+  const headingRe = /^(#{1,6})\s+(.+)$/gm;
+  let match;
+  while ((match = headingRe.exec(content)) !== null) {
+    const title = match[2].trim();
+    const id = headingId(path, title);
+    addNode(graph, id, 'heading', { path, title, depth: match[1].length });
+    addEdge(graph, fileId, id, 'contains_heading', { confidence: 'EXTRACTED' });
+  }
+  for (const { href, line } of extractLinks(content)) {
+    const pathPart = href.split('#')[0];
+    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' });
+    if (isReadmeIndexPath(path)) addEdge(graph, fileId, targetId, 'routes_to', { line, confidence: 'CURATED_INDEX', sourceRole: 'readme-index' });
+  }
+  addTraceabilityGraph(root, fileId, content, graph, config);
+}
+
+export function extractPackageGraph(root, file, graph) {
+  const path = rel(root, file);
+  const fileId = `file:${path}`;
+  let pkg;
+  try { pkg = JSON.parse(readFileSync(file, 'utf8')); } catch { return; }
+  if (pkg.name) {
+    const pkgId = `package:${pkg.name}`;
+    addNode(graph, pkgId, 'package', { name: pkg.name, path });
+    addEdge(graph, fileId, pkgId, 'declares_package', { confidence: 'EXTRACTED' });
+  }
+  for (const [name, command] of Object.entries(pkg.scripts ?? {})) {
+    const id = `script:${path}#${name}`;
+    addNode(graph, id, 'script', { name, command, path });
+    addEdge(graph, fileId, id, 'declares_script', { confidence: 'EXTRACTED' });
+  }
+  for (const [name, target] of Object.entries(typeof pkg.bin === 'string' ? { [pkg.name ?? 'bin']: pkg.bin } : pkg.bin ?? {})) {
+    const id = `bin:${name}`;
+    addNode(graph, id, 'binary', { name, target, path });
+    addEdge(graph, fileId, id, 'declares_bin', { confidence: 'EXTRACTED' });
+    addPackageResource(graph, fileId, path, name, target, 'bin');
+  }
+  for (const [index, target] of (Array.isArray(pkg.files) ? pkg.files : []).entries()) addPackageResource(graph, fileId, path, `files:${index}`, target, 'files');
+  for (const [kind, value] of Object.entries(pkg.pi ?? {})) {
+    for (const [index, target] of (Array.isArray(value) ? value : [value]).entries()) addPackageResource(graph, fileId, path, `pi:${kind}:${index}`, target, `pi:${kind}`);
+  }
+  for (const section of ['dependencies', 'devDependencies', 'peerDependencies']) {
+    for (const name of Object.keys(pkg[section] ?? {})) {
+      const id = `dependency:${name}`;
+      addNode(graph, id, 'dependency', { name });
+      addEdge(graph, fileId, id, 'depends_on', { section, confidence: 'EXTRACTED' });
+    }
+  }
+}
+
+export function buildGraph(root, files, config = defaultMemoryConfig()) {
+  const graph = { nodes: [], edges: [] };
+  for (const file of files) {
+    const path = rel(root, file);
+    const fileId = `file:${path}`;
+    addNode(graph, fileId, 'file', fileNodeMetadata(path, file, config));
+    addMemoryAreaMembership(graph, fileId, path, config);
+    if (path.endsWith('.md')) extractMarkdownGraph(root, file, graph, config);
+    else if (basename(file) === 'package.json') extractPackageGraph(root, file, graph);
+  }
+  return graph;
+}

package/src/graph/metadata.mjs

@@ -0,0 +1,88 @@
+import { existsSync } from 'node:fs';
+import { basename, extname, resolve } from 'node:path';
+import { rel } from '../common/paths.mjs';
+import { headingToAnchor } from '../docs/markdown.mjs';
+import { extractDotdotgodTraceabilityBlocks, isLocalRelativeTraceabilityPath } from '../docs/traceability.mjs';
+import { defaultMemoryConfig, resolveMemoryArea } from '../memory/config.mjs';
+import { addEdge, addNode } from './store.mjs';
+
+export function isReadmeIndexPath(path = '') {
+  return basename(path) === 'README.md';
+}
+
+function retrievalSignalsForPath(path = '', config = defaultMemoryConfig()) {
+  const signals = [];
+  const definition = resolveMemoryArea(path, config);
+  if (definition) signals.push('memory-area', `scope:${definition.scope}`, `freshness:${definition.freshness}`);
+  if (path.startsWith('docs/')) signals.push('docs-path');
+  if (isReadmeIndexPath(path)) signals.push('readme-index');
+  return signals;
+}
+
+export function retrievalMetadataForPath(path = '', config = defaultMemoryConfig()) {
+  const definition = resolveMemoryArea(path, config);
+  return {
+    area: definition?.id,
+    role: definition?.role,
+    priority: definition?.priority ?? 30,
+    scope: definition?.scope,
+    freshness: definition?.freshness,
+    includeBodiesByDefault: definition?.includeBodiesByDefault,
+    signals: retrievalSignalsForPath(path, config),
+  };
+}
+
+export function fileNodeMetadata(path, file, config = defaultMemoryConfig()) {
+  const retrieval = retrievalMetadataForPath(path, config);
+  return {
+    path,
+    extension: file ? extname(file) : extname(path),
+    memoryArea: retrieval.area,
+    memoryRole: retrieval.role,
+    memoryScope: retrieval.scope,
+    memoryFreshness: retrieval.freshness,
+    retrievalPriority: retrieval.priority,
+    retrieval,
+  };
+}
+
+export function addMemoryAreaMembership(graph, fileId, path, config = defaultMemoryConfig()) {
+  const definition = resolveMemoryArea(path, config);
+  if (!definition) return;
+  const areaId = `memory_area:${definition.id}`;
+  addNode(graph, areaId, 'memory_area', { area: definition.id, label: definition.label, role: definition.role, scope: definition.scope, freshness: definition.freshness, retrievalPriority: definition.priority, includeBodiesByDefault: definition.includeBodiesByDefault !== false });
+  addEdge(graph, fileId, areaId, 'belongs_to_area', { confidence: 'DETERMINISTIC', role: definition.role, scope: definition.scope, freshness: definition.freshness });
+}
+
+export function addPackageResource(graph, fileId, packagePath, name, target, kind) {
+  if (!target || typeof target !== 'string') return;
+  const id = `package_resource:${packagePath}#${kind}:${name}`;
+  addNode(graph, id, 'package_resource', { name, target, kind, path: packagePath });
+  addEdge(graph, fileId, id, 'includes_resource', { kind, confidence: 'EXTRACTED' });
+}
+
+function addTraceabilityTarget(graph, sourceId, root, relation, targetPath, data = {}, config = defaultMemoryConfig()) {
+  if (!isLocalRelativeTraceabilityPath(targetPath) || !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 });
+}
+
+export function addTraceabilityGraph(root, fileId, content, graph, config = defaultMemoryConfig()) {
+  for (const block of extractDotdotgodTraceabilityBlocks(content)) {
+    if (block.error || !block.data || block.data.kind !== 'spec') continue;
+    for (const target of block.data.implementedBy ?? []) addTraceabilityTarget(graph, fileId, root, 'implemented_by', target, {}, config);
+    for (const target of block.data.verifiedBy ?? []) addTraceabilityTarget(graph, fileId, root, 'verified_by', target, {}, config);
+    for (const target of block.data.relatedDocs ?? []) addTraceabilityTarget(graph, fileId, root, 'related_doc', target, {}, config);
+    for (const [index, command] of (Array.isArray(block.data.verificationCommands) ? block.data.verificationCommands : []).entries()) {
+      if (typeof command !== 'string' || command.trim().length === 0) continue;
+      const id = `verification_command:${fileId}#${index}`;
+      addNode(graph, id, 'verification_command', { command, path: fileId.replace(/^file:/, '') });
+      addEdge(graph, fileId, id, 'verification_command', { confidence: 'CURATED_TRACEABILITY' });
+    }
+  }
+}
+
+export function headingId(path, title) {
+  return `heading:${path}#${headingToAnchor(title)}`;
+}

package/src/graph/semantic.mjs

@@ -0,0 +1,100 @@
+import { basename } from 'node:path';
+import { DEFAULT_IMPACT_RANKING_POLICY, SEMANTIC_RELATIONS, cloneImpactRankingPolicy, defaultMemoryConfig } from '../memory/config.mjs';
+import { addEdge } from './store.mjs';
+
+const TOKEN_STOPWORDS = new Set(['a', 'an', 'and', 'app', 'bin', 'code', 'config', 'docs', 'file', 'index', 'lib', 'md', 'mjs', 'node', 'package', 'readme', 'src', 'test', 'tests', 'the', 'ts', 'tsx', 'utils']);
+
+function splitCamelCase(value = '') {
+  return value.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2');
+}
+
+function conceptTokens(value = '') {
+  const tokens = new Set();
+  for (const raw of splitCamelCase(String(value)).toLowerCase().split(/[^a-z0-9]+/)) {
+    if (raw.length < 3 || TOKEN_STOPWORDS.has(raw)) continue;
+    tokens.add(raw);
+  }
+  return tokens;
+}
+
+function addTokens(target, value) {
+  for (const token of conceptTokens(value)) target.add(token);
+}
+
+function intersectTokens(a, b) {
+  return [...a].filter((token) => b.has(token));
+}
+
+function jaccard(a, b) {
+  if (a.size === 0 || b.size === 0) return 0;
+  const intersection = intersectTokens(a, b).length;
+  const denominator = Math.min(a.size, b.size);
+  return denominator === 0 ? 0 : intersection / denominator;
+}
+
+function semanticSignalScore(source, target) {
+  const path = jaccard(source.pathTokens, target.pathTokens);
+  const heading = Math.max(jaccard(source.headingTokens, target.headingTokens), jaccard(source.headingTokens, target.allTokens), jaccard(source.allTokens, target.headingTokens));
+  const pkg = Math.max(jaccard(source.packageTokens, target.packageTokens), jaccard(source.allTokens, target.packageTokens), jaccard(source.packageTokens, target.allTokens));
+  return { path, filename: path, heading, package: pkg };
+}
+
+function semanticProfileForFile(fileNode, graph) {
+  const profile = { id: fileNode.id, path: fileNode.path, retrieval: fileNode.retrieval, pathTokens: new Set(), headingTokens: new Set(), packageTokens: new Set(), allTokens: new Set() };
+  addTokens(profile.pathTokens, fileNode.path ?? fileNode.id);
+  addTokens(profile.pathTokens, basename(fileNode.path ?? ''));
+
+  const nodeById = new Map(graph.nodes.map((node) => [node.id, node]));
+  for (const edge of graph.edges) {
+    if (edge.source !== fileNode.id) continue;
+    const target = nodeById.get(edge.target);
+    if (!target) continue;
+    if (edge.relation === 'contains_heading') addTokens(profile.headingTokens, target.title ?? target.id);
+    if (edge.relation === 'declares_package' || edge.relation === 'declares_bin' || edge.relation === 'includes_resource' || edge.relation === 'depends_on') addTokens(profile.packageTokens, target.name ?? target.target ?? target.id);
+  }
+  for (const set of [profile.pathTokens, profile.headingTokens, profile.packageTokens]) for (const token of set) profile.allTokens.add(token);
+  return profile;
+}
+
+function semanticRelationForProfiles(source, target, scores) {
+  if (scores.package >= 0.5) return 'mentions_package';
+  return 'semantic_similarity';
+}
+
+export function addDeterministicSemanticEdges(graph, config = defaultMemoryConfig()) {
+  const policy = cloneImpactRankingPolicy(config.impactRanking ?? DEFAULT_IMPACT_RANKING_POLICY);
+  if (policy.semantic.enabled === false || policy.semantic.topKPerFile === 0) return graph;
+
+  const threshold = policy.semantic.threshold ?? 0.5;
+  const topK = policy.semantic.topKPerFile ?? 5;
+  const includeArchiveBodies = policy.semantic.includeArchiveBodies === true;
+  const enabledSignals = new Set(policy.semantic.signals ?? DEFAULT_IMPACT_RANKING_POLICY.semantic.signals);
+  const baseGraph = { nodes: graph.nodes.map((node) => ({ ...node })), edges: graph.edges.filter((edge) => !SEMANTIC_RELATIONS.has(edge.relation)).map((edge) => ({ ...edge })) };
+  const files = baseGraph.nodes.filter((node) => node.type === 'file' && node.path);
+  const profiles = files.map((node) => semanticProfileForFile(node, baseGraph));
+
+  for (const source of profiles) {
+    if (!includeArchiveBodies && source.retrieval?.area === 'archive-body') continue;
+    const candidates = [];
+    for (const target of profiles) {
+      if (source.id === target.id) continue;
+      if (!includeArchiveBodies && target.retrieval?.area === 'archive-body') continue;
+      const scores = semanticSignalScore(source, target);
+      const weighted = Object.entries(scores).filter(([signal]) => enabledSignals.has(signal));
+      const score = weighted.length === 0 ? 0 : Math.max(...weighted.map(([, value]) => value));
+      if (score < threshold) continue;
+      const matchedTerms = intersectTokens(source.allTokens, target.allTokens).slice(0, 12);
+      if (matchedTerms.length === 0) continue;
+      const relation = semanticRelationForProfiles(source, target, scores);
+      const signals = weighted.filter(([, value]) => value > 0).map(([signal]) => signal);
+      candidates.push({ target, relation, score, matchedTerms, signals });
+    }
+    candidates
+      .sort((a, b) => b.score - a.score || a.target.id.localeCompare(b.target.id))
+      .slice(0, topK)
+      .forEach((candidate) => {
+        addEdge(baseGraph, source.id, candidate.target.id, candidate.relation, { confidence: 'INFERRED_LEXICAL_SEMANTIC', score: Math.round(candidate.score * 1000) / 1000, matchedTerms: candidate.matchedTerms, signals: candidate.signals });
+      });
+  }
+  return baseGraph;
+}

package/src/impact/format.mjs

@@ -0,0 +1,92 @@
+import { commandUsage } from '../cli/usage.mjs';
+
+function formatCompactImpactGroup(name, group) {
+  const items = group?.items ?? [];
+  if (items.length === 0) return [];
+  return [
+    `${name}:`,
+    ...items.map((item) => {
+      const label = item.path ?? item.command ?? item.name ?? item.target ?? item.id;
+      const reasons = (item.reasons ?? []).slice(0, 3).join(', ');
+      return `- ${label} (${item.impactScore}; ${reasons})`;
+    }),
+  ];
+}
+
+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)`];
+  for (const name of ['docs', 'tests', 'files', 'commands', 'events', 'packageResources', 'symbols']) lines.push(...formatCompactImpactGroup(name, impact.groups[name]));
+  return lines.join('\n');
+}
+
+function ymlScalar(value) {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  return JSON.stringify(String(value));
+}
+
+function ymlList(values = []) {
+  return `[${values.map(ymlScalar).join(', ')}]`;
+}
+
+function formatYmlImpactItem(item) {
+  const label = item.path ?? item.command ?? item.name ?? item.target ?? item.id;
+  const lines = [`        - path: ${ymlScalar(label)}`];
+  lines.push(`          id: ${ymlScalar(item.id)}`);
+  lines.push(`          type: ${ymlScalar(item.type)}`);
+  lines.push(`          score: ${ymlScalar(item.impactScore)}`);
+  lines.push(`          reasons: ${ymlList((item.reasons ?? []).slice(0, 6))}`);
+  if (item.retrieval?.area) lines.push(`          area: ${ymlScalar(item.retrieval.area)}`);
+  if (item.retrieval?.role) lines.push(`          role: ${ymlScalar(item.retrieval.role)}`);
+  return lines;
+}
+
+function formatYmlImpactGroup(name, group) {
+  const items = group?.items ?? [];
+  const lines = [`    ${name}:`, `      omitted: ${group?.omitted ?? 0}`, '      items:'];
+  if (items.length === 0) lines.push('        []');
+  else for (const item of items) lines.push(...formatYmlImpactItem(item));
+  return lines;
+}
+
+export function formatYmlImpactOutput(payload, impact) {
+  const lines = [
+    'impact:',
+    `  ok: ${payload.ok ? 'true' : 'false'}`,
+    `  changed: ${ymlScalar(payload.changed)}`,
+    `  root: ${ymlScalar(payload.root)}`,
+    '  output: "yml"',
+    '  status:',
+    `    index: ${ymlScalar(payload.status.status)}`,
+    `    cache_refreshed: ${payload.metadata.cacheRefreshed ? 'true' : 'false'}`,
+    `  related_count: ${impact.related.length}`,
+    `  omitted_related: ${impact.omittedRelated ?? 0}`,
+    '  ranking:',
+    `    method: ${ymlScalar(impact.ranking?.method)}`,
+    `    preset: ${ymlScalar(impact.ranking?.preset)}`,
+    `    config_source: ${ymlScalar(impact.ranking?.configSource)}`,
+    '  groups:',
+  ];
+  for (const name of ['docs', 'tests', 'files', 'commands', 'events', 'packageResources', 'symbols']) lines.push(...formatYmlImpactGroup(name, impact.groups[name]));
+  lines.push('  recommended_actions:');
+  lines.push('    - "review_related_docs"');
+  lines.push('    - "run_related_tests"');
+  lines.push('    - "run_dotdotgod_validate"');
+  return lines.join('\n');
+}
+
+export function formatYmlGraphImpactError(options, message, code = 'GRAPH_IMPACT_ERROR') {
+  return [
+    'impact:',
+    '  ok: false',
+    '  command: "graph impact"',
+    '  output: "yml"',
+    `  compact: ${options.compact ? 'true' : 'false'}`,
+    `  root: ${ymlScalar(options.root)}`,
+    '  error:',
+    `    code: ${ymlScalar(code)}`,
+    `    message: ${ymlScalar(message)}`,
+    `  usage: ${ymlScalar(commandUsage('graph impact'))}`,
+  ].join('\n');
+}

package/src/impact/report.mjs

@@ -0,0 +1,126 @@
+import { DEFAULT_IMPACT_RANKING_POLICY, SEMANTIC_RELATIONS, cloneImpactRankingPolicy, defaultMemoryConfig } from '../memory/config.mjs';
+import { retrievalMetadataForPath } from '../graph/metadata.mjs';
+import { buildPersonalizedPageRank, compareImpactItems, docsArea, hasCuratedImpactReason, isLowActionabilityImpactItem, isSemanticOnlyImpactItem, isTestPath, scoreImpactItem } from './scoring.mjs';
+
+function addImpactItem(group, item, limit = 10) {
+  if (group.items.some((existing) => existing.id === item.id)) return;
+  if (group.items.length >= limit) {
+    group.omitted += 1;
+    return;
+  }
+  group.items.push(item);
+}
+
+function selectImpactItems(sortedItems, maxRelated, seed) {
+  const selected = [];
+  const selectedIds = new Set();
+  const deferred = [];
+  const firstPageLimit = Math.min(maxRelated, 10);
+  let semanticOnlyInFirstPage = 0;
+  let lowActionabilityInFirstPage = 0;
+  const firstPagePathCounts = new Map();
+  const add = (item, force = false) => {
+    if (selected.length >= maxRelated || selectedIds.has(item.id)) return;
+    const pathKey = item.path ?? item.id;
+    if (!force && item.id !== seed && selected.length < firstPageLimit) {
+      if (pathKey && (firstPagePathCounts.get(pathKey) ?? 0) >= 2) return deferred.push(item);
+      if (isLowActionabilityImpactItem(item) && lowActionabilityInFirstPage >= 2) return deferred.push(item);
+      if (isSemanticOnlyImpactItem(item) && semanticOnlyInFirstPage >= 3) return deferred.push(item);
+    }
+    selected.push(item);
+    selectedIds.add(item.id);
+    if (selected.length <= firstPageLimit && item.id !== seed) {
+      if (pathKey) firstPagePathCounts.set(pathKey, (firstPagePathCounts.get(pathKey) ?? 0) + 1);
+      if (isLowActionabilityImpactItem(item)) lowActionabilityInFirstPage += 1;
+      if (isSemanticOnlyImpactItem(item)) semanticOnlyInFirstPage += 1;
+    }
+  };
+  for (const item of sortedItems) if (item.id === seed) add(item, true);
+  for (const item of sortedItems) if (item.id !== seed) add(item);
+  for (const item of deferred) add(item, true);
+  return selected;
+}
+
+export function buildImpactReport(index, changedPath, limits = {}) {
+  const graph = index?.graph ?? { nodes: [], edges: [] };
+  const config = index?.memoryConfig ? { ...defaultMemoryConfig(), ...index.memoryConfig } : defaultMemoryConfig();
+  const policy = cloneImpactRankingPolicy(config.impactRanking ?? DEFAULT_IMPACT_RANKING_POLICY);
+  const nodeById = new Map(graph.nodes.map((node) => [node.id, node]));
+  const seed = `file:${changedPath}`;
+  const maxRelated = limits.related ?? 25;
+  const groups = { files: { items: [], omitted: 0 }, docs: { items: [], omitted: 0 }, tests: { items: [], omitted: 0 }, commands: { items: [], omitted: 0 }, events: { items: [], omitted: 0 }, packageResources: { items: [], omitted: 0 }, symbols: { items: [], omitted: 0 } };
+  const relatedIds = new Set([seed]);
+  const reasons = new Map([[seed, new Set(['changed-file'])]]);
+  const addReason = (id, reason) => {
+    relatedIds.add(id);
+    if (!reasons.has(id)) reasons.set(id, new Set());
+    reasons.get(id).add(reason);
+  };
+
+  for (const edge of graph.edges) {
+    if (edge.source === seed) addReason(edge.target, edge.relation);
+    if (edge.target === seed) addReason(edge.source, `incoming:${edge.relation}`);
+  }
+  const expansionRelations = new Set(['implemented_by', 'verified_by', 'related_doc', 'verification_command', ...SEMANTIC_RELATIONS]);
+  for (const edge of graph.edges) {
+    if (!expansionRelations.has(edge.relation)) continue;
+    if (relatedIds.has(edge.source) && edge.target !== seed) addReason(edge.target, edge.relation);
+  }
+
+  const pprScores = buildPersonalizedPageRank(graph, seed, policy);
+  const candidatePprMax = Math.max(0, ...[...relatedIds].filter((id) => id !== seed).map((id) => pprScores.get(id) ?? 0));
+  const relatedAll = [...relatedIds].map((id) => {
+    const node = nodeById.get(id) ?? { id };
+    const path = node.path ?? id.replace(/^file:/, '').replace(/^test:/, '');
+    const reasonList = [...(reasons.get(id) ?? [])];
+    const retrieval = node.retrieval ?? retrievalMetadataForPath(path);
+    const reasonSignals = reasonList.map((reason) => `reason:${reason}`);
+    const scored = scoreImpactItem({ ...node, reasons: reasonList, retrieval }, seed, changedPath, policy, pprScores, candidatePprMax);
+    return { ...node, reasons: reasonList, retrieval: { ...retrieval, signals: [...new Set([...(retrieval.signals ?? []), ...reasonSignals])] }, ...scored };
+  }).sort(compareImpactItems(seed));
+  const related = selectImpactItems(relatedAll, maxRelated, seed);
+  for (const item of related) {
+    if (item.type === 'file') {
+      const area = docsArea(item.path);
+      if (area) addImpactItem(groups.docs, { ...item, area }, limits.docs ?? 10);
+      else if (isTestPath(item.path)) addImpactItem(groups.tests, item, limits.tests ?? 10);
+      else addImpactItem(groups.files, item, limits.files ?? 10);
+    } else if (item.type === 'test') addImpactItem(groups.tests, item, limits.tests ?? 10);
+    else if (item.type === 'command') addImpactItem(groups.commands, item, limits.commands ?? 10);
+    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: changedPath, ranking: { method: policy.ppr.enabled === false ? 'policy-score' : 'personalized-pagerank+policy', preset: policy.preset, configSource: index?.memoryConfig?.source ?? 'default', weights: policy.weights, ppr: policy.ppr }, related, groups, omittedRelated: Math.max(0, relatedAll.length - related.length) };
+}
+
+function compactScoreBreakdown(scoreBreakdown = {}) {
+  const compact = {};
+  for (const [key, value] of Object.entries(scoreBreakdown)) if (value !== 0 && value !== undefined) compact[key] = value;
+  return compact;
+}
+
+export function compactImpactItem(item) {
+  const compact = { id: item.id, type: item.type, impactScore: item.impactScore, reasons: (item.reasons ?? []).slice(0, 6), scoreBreakdown: compactScoreBreakdown(item.scoreBreakdown) };
+  for (const key of ['path', 'area', 'name', 'command', 'target', 'kind', 'specifier', 'title']) if (item[key] !== undefined) compact[key] = item[key];
+  if (item.retrieval) compact.retrieval = { area: item.retrieval.area, role: item.retrieval.role, priority: item.retrieval.priority, freshness: item.retrieval.freshness };
+  return compact;
+}
+
+function compactImpactGroup(group = { items: [], omitted: 0 }, limit = 5) {
+  const items = (group.items ?? []).slice(0, limit).map(compactImpactItem);
+  return { items, omitted: (group.omitted ?? 0) + Math.max(0, (group.items?.length ?? 0) - items.length) };
+}
+
+export function buildCompactImpactReport(impact, limits = {}) {
+  const relatedLimit = limits.related ?? 10;
+  const groupLimit = limits.groupItems ?? 5;
+  const related = (impact.related ?? []).slice(0, relatedLimit).map(compactImpactItem);
+  const groupNames = ['files', 'docs', 'tests', 'commands', 'events', 'packageResources', 'symbols'];
+  const groups = Object.fromEntries(groupNames.map((name) => [name, compactImpactGroup(impact.groups?.[name], groupLimit)]));
+  const top10 = (impact.related ?? []).filter((item) => item.id !== `file:${impact.changed}`).slice(0, 10);
+  return { changed: impact.changed, compact: true, ranking: { method: impact.ranking?.method, preset: impact.ranking?.preset, configSource: impact.ranking?.configSource }, 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 } };
+}
+
+export function neighborhood(index, changedPath) {
+  return buildImpactReport(index, changedPath).related;
+}

package/src/impact/scoring.mjs

@@ -0,0 +1,134 @@
+import { SEMANTIC_RELATIONS } from '../memory/config.mjs';
+import { relationWeight } from '../graph/communities.mjs';
+
+export function isTestPath(path = '') {
+  return /(^|\/)(test|tests)\//.test(path) || /\.(test|spec)\.(mjs|cjs|js|jsx|ts|tsx)$/.test(path);
+}
+
+export function docsArea(path = '') {
+  if (path.startsWith('docs/spec/')) return 'spec';
+  if (path.startsWith('docs/arch/')) return 'arch';
+  if (path.startsWith('docs/test/')) return 'test-docs';
+  if (path.startsWith('docs/plan/')) return 'plan';
+  if (path.startsWith('docs/archive/')) return 'archive-index';
+  if (path.startsWith('docs/')) return 'docs';
+  return undefined;
+}
+
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+
+function roundScore(value) {
+  return Math.round(value * 10) / 10;
+}
+
+function sumReasonBoosts(reasons, boosts) {
+  return reasons.reduce((sum, reason) => sum + (boosts[reason] ?? 0), 0);
+}
+
+function cappedTraceabilityScore(reasons, boosts, cap) {
+  const values = reasons.map((reason) => boosts[reason] ?? 0).filter((value) => value > 0);
+  if (values.length === 0) return 0;
+  return clamp(Math.max(...values) + Math.min(5, Math.max(0, values.length - 1) * 2), 0, cap);
+}
+
+export function buildPersonalizedPageRank(graph, seed, policy) {
+  if (policy.ppr.enabled === false) return new Map();
+  const damping = policy.ppr.damping ?? 0.85;
+  const iterations = policy.ppr.iterations ?? 20;
+  const tolerance = policy.ppr.tolerance ?? 0.000001;
+  const ids = new Set(graph.nodes.map((node) => node.id));
+  ids.add(seed);
+  const adjacency = new Map([...ids].map((id) => [id, []]));
+  for (const edge of graph.edges) {
+    const weight = policy.relationWeights[edge.relation] ?? relationWeight(edge.relation);
+    if (weight <= 0) continue;
+    if (!adjacency.has(edge.source)) adjacency.set(edge.source, []);
+    if (!adjacency.has(edge.target)) adjacency.set(edge.target, []);
+    adjacency.get(edge.source).push([edge.target, weight]);
+    adjacency.get(edge.target).push([edge.source, weight]);
+  }
+  let ranks = new Map([...adjacency.keys()].map((id) => [id, id === seed ? 1 : 0]));
+  for (let i = 0; i < iterations; i += 1) {
+    const next = new Map([...adjacency.keys()].map((id) => [id, id === seed ? 1 - damping : 0]));
+    for (const [id, edges] of adjacency.entries()) {
+      const rank = ranks.get(id) ?? 0;
+      const total = edges.reduce((sum, [, weight]) => sum + weight, 0);
+      if (total === 0) continue;
+      for (const [target, weight] of edges) next.set(target, (next.get(target) ?? 0) + damping * rank * (weight / total));
+    }
+    const delta = [...next.entries()].reduce((sum, [id, rank]) => sum + Math.abs(rank - (ranks.get(id) ?? 0)), 0);
+    ranks = next;
+    if (delta < tolerance) break;
+  }
+  return ranks;
+}
+
+export function scoreImpactItem(item, seed, changedPath, policy, pprScores, maxPpr) {
+  if (item.id === seed) return { impactScore: 100, scoreBreakdown: { seed: 100, ppr: 40, traceability: 0, memoryPolicy: 0, verification: 0, proximity: 0, semantic: 0, freshness: 0, archivePenalty: 0 } };
+  const reasons = item.reasons ?? [];
+  const retrieval = item.retrieval ?? {};
+  const pprNormalized = maxPpr > 0 ? (pprScores.get(item.id) ?? 0) / maxPpr : 0;
+  const ppr = clamp(pprNormalized * (policy.weights.ppr ?? 40), 0, Math.abs(policy.weights.ppr ?? 40));
+  const traceability = cappedTraceabilityScore(reasons, policy.traceabilityBoosts, Math.abs(policy.weights.traceability ?? 30));
+  const memoryPolicy = clamp(((retrieval.priority ?? 30) / 100) * Math.abs(policy.weights.memoryPolicy ?? 10), 0, Math.abs(policy.weights.memoryPolicy ?? 10));
+  const verification = clamp(sumReasonBoosts(reasons, policy.verificationBoosts) + (item.type === 'test' || isTestPath(item.path ?? '') ? 10 : 0) + (item.type === 'verification_command' ? 12 : 0), 0, Math.abs(policy.weights.verification ?? 15));
+  const proximity = clamp(sumReasonBoosts(reasons, policy.proximityBoosts), 0, Math.abs(policy.weights.proximity ?? 10));
+  const semantic = clamp(sumReasonBoosts(reasons, policy.semanticBoosts), 0, Math.abs(policy.weights.semantic ?? 10));
+  const freshness = retrieval.freshness === 'fresh' ? Math.abs(policy.weights.freshness ?? 5) : retrieval.freshness === 'stale' ? -Math.abs(policy.weights.freshness ?? 5) : 0;
+  let archivePenalty = 0;
+  if (!changedPath.startsWith('docs/archive/')) {
+    if (retrieval.area === 'archive-body') archivePenalty -= Math.abs(policy.weights.archivePenalty ?? -25);
+    if (retrieval.includeBodiesByDefault === false) archivePenalty -= 10;
+    if (retrieval.freshness === 'stale' && retrieval.area !== 'archive-map') archivePenalty -= 5;
+  }
+  archivePenalty = clamp(archivePenalty, -Math.abs(policy.weights.archivePenalty ?? -25), 0);
+  const impactScore = clamp(ppr + traceability + memoryPolicy + verification + proximity + semantic + freshness + archivePenalty, 0, 100);
+  return { impactScore: roundScore(impactScore), scoreBreakdown: { ppr: roundScore(ppr), traceability: roundScore(traceability), memoryPolicy: roundScore(memoryPolicy), verification: roundScore(verification), proximity: roundScore(proximity), semantic: roundScore(semantic), freshness: roundScore(freshness), archivePenalty: roundScore(archivePenalty) } };
+}
+
+const CURATED_IMPACT_REASONS = new Set(['implemented_by', 'verified_by', 'related_doc', 'verification_command', 'links_to', 'routes_to', 'belongs_to_area']);
+const LOW_ACTIONABILITY_IMPACT_TYPES = new Set(['dependency', 'package', 'script', 'binary', 'heading', 'memory_area']);
+
+function baseImpactReason(reason = '') {
+  return reason.replace(/^incoming:/, '');
+}
+
+export function isSemanticImpactReason(reason = '') {
+  return SEMANTIC_RELATIONS.has(baseImpactReason(reason));
+}
+
+function isCuratedImpactReason(reason = '') {
+  return CURATED_IMPACT_REASONS.has(baseImpactReason(reason));
+}
+
+export function hasCuratedImpactReason(item) {
+  return (item.reasons ?? []).some((reason) => isCuratedImpactReason(reason));
+}
+
+export function isSemanticOnlyImpactItem(item) {
+  const reasons = item.reasons ?? [];
+  return reasons.length > 0 && reasons.every((reason) => isSemanticImpactReason(reason));
+}
+
+export function isLowActionabilityImpactItem(item) {
+  return LOW_ACTIONABILITY_IMPACT_TYPES.has(item.type);
+}
+
+function impactSelectionScore(item) {
+  let score = item.impactScore ?? 0;
+  if (hasCuratedImpactReason(item)) score += 4;
+  if (item.type === 'file' || item.type === 'test' || item.type === 'verification_command') score += 2;
+  if (isSemanticOnlyImpactItem(item)) score -= 12;
+  if (isLowActionabilityImpactItem(item)) score -= 15;
+  return score;
+}
+
+export function compareImpactItems(seed) {
+  return (a, b) => {
+    if (a.id === seed) return -1;
+    if (b.id === seed) return 1;
+    return impactSelectionScore(b) - impactSelectionScore(a) || (b.impactScore ?? 0) - (a.impactScore ?? 0) || a.id.localeCompare(b.id);
+  };
+}