@monoes/monograph 1.0.0

package/src/parsers/rust.ts

@@ -0,0 +1,25 @@
+import { createRequire } from 'module';
+import type { LanguageConfig } from './language-config.js';
+
+const require = createRequire(import.meta.url);
+
+export const rustConfig: LanguageConfig = {
+  name: 'rust',
+  extensions: ['.rs'],
+  treeSitterModule: 'tree-sitter-rust',
+  getLanguage: () => require('tree-sitter-rust'),
+  classNodeTypes: new Set([]),
+  structNodeTypes: new Set(['struct_item']),
+  enumNodeTypes: new Set(['enum_item']),
+  functionNodeTypes: new Set(['function_item']),
+  methodNodeTypes: new Set(['function_item']),
+  constructorNodeTypes: new Set([]),
+  interfaceNodeTypes: new Set(['trait_item']),
+  importNodeTypes: new Set(['use_declaration']),
+  callNodeTypes: new Set(['call_expression', 'method_call_expression']),
+  decoratorNodeTypes: new Set(['attribute_item']),
+  nameField: 'name',
+  importExtractor: (_source, node) => {
+    return node.text.replace(/^use\s+/, '').replace(/;$/, '').trim();
+  },
+};

package/src/parsers/typescript.ts

@@ -0,0 +1,41 @@
+import { createRequire } from 'module';
+import type { LanguageConfig } from './language-config.js';
+
+const require = createRequire(import.meta.url);
+
+export const typescriptConfig: LanguageConfig = {
+  name: 'typescript',
+  extensions: ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'],
+  treeSitterModule: 'tree-sitter-typescript',
+  getLanguage: () => {
+    const ts = require('tree-sitter-typescript');
+    return ts.typescript;
+  },
+  classNodeTypes: new Set(['class_declaration', 'class']),
+  structNodeTypes: new Set([]),
+  enumNodeTypes: new Set(['enum_declaration']),
+  functionNodeTypes: new Set([
+    'function_declaration', 'function', 'arrow_function',
+    'generator_function_declaration', 'generator_function',
+  ]),
+  methodNodeTypes: new Set(['method_definition', 'method_signature']),
+  constructorNodeTypes: new Set(['constructor']),
+  interfaceNodeTypes: new Set(['interface_declaration', 'type_alias_declaration']),
+  importNodeTypes: new Set(['import_statement', 'import_declaration']),
+  callNodeTypes: new Set(['call_expression', 'new_expression']),
+  decoratorNodeTypes: new Set(['decorator']),
+  nameField: 'name',
+  importExtractor: (_source, node) => {
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i)!;
+      if (child.type === 'string') {
+        return child.text.replace(/['"]/g, '');
+      }
+    }
+    return null;
+  },
+  exportDetector: (node, _source) => {
+    const parent = node.parent;
+    return parent?.type === 'export_statement' || parent?.type === 'export_default_declaration';
+  },
+};

package/src/pipeline/orchestrator.ts

@@ -0,0 +1,46 @@
+import { resolve, join } from 'path';
+import Graph from 'graphology';
+import { openDb, closeDb } from '../storage/db.js';
+import { PipelineRunner } from './runner.js';
+import { scanPhase } from './phases/scan.js';
+import { structurePhase } from './phases/structure.js';
+import { parsePhase } from './phases/parse.js';
+import { crossFilePhase } from './phases/cross-file.js';
+import { mroPhase } from './phases/mro.js';
+import { communitiesPhase } from './phases/communities.js';
+import { godNodesPhase } from './phases/god-nodes.js';
+import { surprisesPhase } from './phases/surprises.js';
+import { suggestPhase } from './phases/suggest.js';
+import type { PipelineOptions, PipelineContext } from './types.js';
+import { DEFAULT_OPTIONS } from './types.js';
+import type { PipelineProgress } from '../types.js';
+
+export interface BuildOptions extends Partial<PipelineOptions> {
+  onProgress?: (p: PipelineProgress) => void;
+  force?: boolean;
+}
+
+export async function buildAsync(repoPath: string, options: BuildOptions = {}): Promise<void> {
+  const dbPath = resolve(join(repoPath, '.monomind', 'monograph.db'));
+  const fullOptions: PipelineOptions = { ...DEFAULT_OPTIONS, ...options };
+  const db = openDb(dbPath);
+
+  try {
+    const graph = new Graph({ multi: true, type: 'directed' });
+    const ctx: PipelineContext = {
+      repoPath: resolve(repoPath),
+      db, graph,
+      onProgress: options.onProgress ?? (() => {}),
+      options: fullOptions,
+    };
+
+    const runner = new PipelineRunner([
+      scanPhase, structurePhase, parsePhase, crossFilePhase,
+      mroPhase, communitiesPhase, godNodesPhase, surprisesPhase, suggestPhase,
+    ]);
+
+    await runner.run(ctx);
+  } finally {
+    closeDb(db);
+  }
+}

package/src/pipeline/phases/communities.ts

@@ -0,0 +1,45 @@
+import louvain from 'graphology-communities-louvain';
+import type { PipelinePhase, PipelineContext } from '../types.js';
+import type { MonographEdge } from '../../types.js';
+import { loadGraphFromEdges } from '../../graph/loader.js';
+import type { CrossFileOutput } from './cross-file.js';
+import type { ParseOutput } from './parse.js';
+
+export interface CommunitiesOutput {
+  memberships: Map<string, number>;
+  communityLabels: Map<number, string>;
+}
+
+export const communitiesPhase: PipelinePhase<CommunitiesOutput> = {
+  name: 'communities',
+  deps: ['cross-file', 'mro'],
+  async execute(_ctx, deps) {
+    const { resolvedEdges } = deps.get('cross-file') as CrossFileOutput;
+    const { allEdges } = deps.get('parse') as ParseOutput;
+    const allUsedEdges: MonographEdge[] = [...allEdges, ...resolvedEdges];
+
+    const graph = loadGraphFromEdges(allUsedEdges);
+    let communities: Record<string, number> = {};
+    try {
+      communities = louvain(graph);
+    } catch {
+      // Empty or disconnected graph
+    }
+
+    const memberships = new Map<string, number>(Object.entries(communities).map(([k, v]) => [k, v]));
+    const communityLabels = new Map<number, string>();
+
+    const communityDegrees = new Map<number, Map<string, number>>();
+    for (const [nodeId, commId] of memberships) {
+      if (!communityDegrees.has(commId)) communityDegrees.set(commId, new Map());
+      const deg = graph.degree(nodeId) ?? 0;
+      communityDegrees.get(commId)!.set(nodeId, deg);
+    }
+    for (const [commId, nodeDegs] of communityDegrees) {
+      const topNode = [...nodeDegs.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? '';
+      communityLabels.set(commId, `community-${commId}(${topNode.slice(0, 20)})`);
+    }
+
+    return { memberships, communityLabels };
+  },
+};

package/src/pipeline/phases/cross-file.ts

@@ -0,0 +1,48 @@
+import type { PipelinePhase, PipelineContext } from '../types.js';
+import type { MonographEdge } from '../../types.js';
+import { makeId, CONFIDENCE_SCORE } from '../../types.js';
+import { insertEdges } from '../../storage/edge-store.js';
+import type { ParseOutput } from './parse.js';
+
+export interface CrossFileOutput {
+  resolvedEdges: MonographEdge[];
+}
+
+export const crossFilePhase: PipelinePhase<CrossFileOutput> = {
+  name: 'cross-file',
+  deps: ['parse'],
+  async execute(_ctx, deps) {
+    const { allEdges, symbolNodes } = deps.get('parse') as ParseOutput;
+
+    const nameIndex = new Map<string, string>();
+    for (const node of symbolNodes) {
+      nameIndex.set(node.name, node.id);
+      if (node.normLabel) nameIndex.set(node.normLabel, node.id);
+    }
+
+    const resolvedEdges: MonographEdge[] = [];
+
+    for (const edge of allEdges) {
+      if (edge.relation !== 'IMPORTS') continue;
+
+      const targetName = edge.targetId.replace(/^import_/, '').split('/').pop() ?? '';
+      const resolvedId = nameIndex.get(targetName) ?? nameIndex.get(targetName.toLowerCase());
+
+      if (resolvedId && resolvedId !== edge.targetId) {
+        resolvedEdges.push({
+          ...edge,
+          id: makeId(edge.sourceId, resolvedId, 'resolved'),
+          targetId: resolvedId,
+          confidence: 'INFERRED',
+          confidenceScore: CONFIDENCE_SCORE.INFERRED,
+        });
+      }
+    }
+
+    if (_ctx.db && resolvedEdges.length > 0) {
+      insertEdges(_ctx.db, resolvedEdges);
+    }
+
+    return { resolvedEdges };
+  },
+};

package/src/pipeline/phases/god-nodes.ts

@@ -0,0 +1,40 @@
+import type { PipelinePhase, PipelineContext } from '../types.js';
+import type { GodNode, MonographEdge } from '../../types.js';
+import type { ParseOutput } from './parse.js';
+import type { CrossFileOutput } from './cross-file.js';
+
+const EXCLUDED_LABELS = new Set(['File', 'Folder', 'Community', 'Concept']);
+
+export interface GodNodesOutput {
+  godNodes: GodNode[];
+}
+
+export const godNodesPhase: PipelinePhase<GodNodesOutput> = {
+  name: 'god-nodes',
+  deps: ['cross-file', 'parse'],
+  async execute(ctx, deps) {
+    const { resolvedEdges } = deps.get('cross-file') as CrossFileOutput;
+    const { allEdges, symbolNodes } = deps.get('parse') as ParseOutput;
+    const allEdgesCombined: MonographEdge[] = [...allEdges, ...resolvedEdges];
+
+    const inDeg = new Map<string, number>();
+    const outDeg = new Map<string, number>();
+    for (const e of allEdgesCombined) {
+      outDeg.set(e.sourceId, (outDeg.get(e.sourceId) ?? 0) + 1);
+      inDeg.set(e.targetId, (inDeg.get(e.targetId) ?? 0) + 1);
+    }
+
+    const godNodes: GodNode[] = symbolNodes
+      .filter(n => !EXCLUDED_LABELS.has(n.label) && (inDeg.get(n.id) ?? 0) + (outDeg.get(n.id) ?? 0) > 0)
+      .map(n => ({
+        ...n,
+        inDegree: inDeg.get(n.id) ?? 0,
+        outDegree: outDeg.get(n.id) ?? 0,
+        degree: (inDeg.get(n.id) ?? 0) + (outDeg.get(n.id) ?? 0),
+      }))
+      .sort((a, b) => b.degree - a.degree)
+      .slice(0, 20);
+
+    return { godNodes };
+  },
+};

package/src/pipeline/phases/mro.ts

@@ -0,0 +1,52 @@
+import type { PipelinePhase, PipelineContext } from '../types.js';
+import type { MonographEdge } from '../../types.js';
+import { makeId, CONFIDENCE_SCORE } from '../../types.js';
+import type { ParseOutput } from './parse.js';
+
+export interface MroOutput {
+  mroEdges: MonographEdge[];
+}
+
+export const mroPhase: PipelinePhase<MroOutput> = {
+  name: 'mro',
+  deps: ['cross-file'],
+  async execute(_ctx, deps) {
+    const { allEdges, symbolNodes } = deps.get('parse') as ParseOutput;
+
+    const classMethodsIndex = new Map<string, string[]>();
+    for (const edge of allEdges) {
+      if (edge.relation === 'HAS_METHOD') {
+        const methods = classMethodsIndex.get(edge.sourceId) ?? [];
+        methods.push(edge.targetId);
+        classMethodsIndex.set(edge.sourceId, methods);
+      }
+    }
+
+    const nameIndex = new Map(symbolNodes.map(n => [n.id, n.name]));
+    const mroEdges: MonographEdge[] = [];
+
+    for (const edge of allEdges) {
+      if (edge.relation !== 'EXTENDS' && edge.relation !== 'IMPLEMENTS') continue;
+
+      const parentMethods = classMethodsIndex.get(edge.targetId) ?? [];
+      const childMethods = classMethodsIndex.get(edge.sourceId) ?? [];
+      const parentMethodNames = new Map(parentMethods.map(id => [nameIndex.get(id) ?? id, id]));
+
+      for (const childMethodId of childMethods) {
+        const childName = nameIndex.get(childMethodId);
+        if (!childName) continue;
+        const parentMethodId = parentMethodNames.get(childName);
+        if (!parentMethodId) continue;
+
+        const relation = edge.relation === 'IMPLEMENTS' ? 'METHOD_IMPLEMENTS' : 'METHOD_OVERRIDES';
+        mroEdges.push({
+          id: makeId(childMethodId, parentMethodId, relation.toLowerCase()),
+          sourceId: childMethodId, targetId: parentMethodId,
+          relation, confidence: 'EXTRACTED', confidenceScore: CONFIDENCE_SCORE.EXTRACTED,
+        });
+      }
+    }
+
+    return { mroEdges };
+  },
+};

package/src/pipeline/phases/parse.ts

@@ -0,0 +1,62 @@
+import { readFileSync, statSync } from 'fs';
+import { extname } from 'path';
+import type { PipelinePhase, PipelineContext } from '../types.js';
+import type { MonographNode, MonographEdge } from '../../types.js';
+import { parseFile } from '../../parsers/loader.js';
+import { insertNodes } from '../../storage/node-store.js';
+import { insertEdges } from '../../storage/edge-store.js';
+import type { StructureOutput } from './structure.js';
+
+export interface ParseOutput {
+  symbolNodes: MonographNode[];
+  allEdges: MonographEdge[];
+  parseErrors: string[];
+}
+
+export const parsePhase: PipelinePhase<ParseOutput> = {
+  name: 'parse',
+  deps: ['structure'],
+  async execute(ctx, deps) {
+    const { fileNodes } = deps.get('structure') as StructureOutput;
+    const symbolNodes: MonographNode[] = [];
+    const allEdges: MonographEdge[] = [];
+    const parseErrors: string[] = [];
+    let processed = 0;
+
+    for (const fileNode of fileNodes) {
+      const absPath = fileNode.filePath ? `${ctx.repoPath}/${fileNode.filePath}` : '';
+      const ext = extname(absPath).toLowerCase();
+      let source: string;
+      try {
+        const stat = statSync(absPath);
+        if (stat.size > ctx.options.maxFileSizeBytes) {
+          parseErrors.push(`${fileNode.filePath}: skipped (too large)`);
+          continue;
+        }
+        source = readFileSync(absPath, 'utf-8');
+      } catch { continue; }
+
+      const result = await parseFile(absPath, source, fileNode.filePath ?? '');
+      symbolNodes.push(...result.nodes);
+      allEdges.push(...result.edges);
+      parseErrors.push(...result.parseErrors);
+      processed++;
+
+      if (processed % 50 === 0) {
+        ctx.onProgress?.({ phase: 'parse', filesProcessed: processed, totalFiles: fileNodes.length });
+      }
+    }
+
+    if (ctx.db) {
+      insertNodes(ctx.db, symbolNodes);
+      // Only insert edges whose target already exists in the DB (intra-file edges).
+      // Cross-file import edges with unresolved targets are handled by crossFilePhase
+      // after it resolves them to real node IDs.
+      const knownIds = new Set(symbolNodes.map(n => n.id));
+      const resolvableEdges = allEdges.filter(e => knownIds.has(e.targetId));
+      insertEdges(ctx.db, resolvableEdges);
+    }
+
+    return { symbolNodes, allEdges, parseErrors };
+  },
+};

package/src/pipeline/phases/scan.ts

@@ -0,0 +1,58 @@
+import { readdirSync, statSync } from 'fs';
+import { join, extname } from 'path';
+import type { PipelinePhase, PipelineContext } from '../types.js';
+import { isSupportedExtension } from '../../parsers/loader.js';
+
+const DEFAULT_IGNORE = new Set([
+  'node_modules', '.git', 'dist', 'build', '__pycache__',
+  '.cache', 'coverage', '.monomind', 'vendor', 'target',
+]);
+
+const BINARY_EXTENSIONS = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.svg', '.ico', '.woff', '.woff2',
+  '.ttf', '.eot', '.mp3', '.mp4', '.zip', '.gz', '.tar', '.pdf',
+  '.exe', '.dll', '.so', '.dylib', '.class', '.jar',
+]);
+
+const GENERATED_PATTERNS = [/\.min\.(js|css)$/, /\.pb\.go$/, /_generated\.ts$/];
+
+export interface ScanOutput {
+  filePaths: string[];
+  totalBytes: number;
+}
+
+export const scanPhase: PipelinePhase<ScanOutput> = {
+  name: 'scan',
+  deps: [],
+  async execute(ctx) {
+    const filePaths: string[] = [];
+    let totalBytes = 0;
+    const ignoreDirs = new Set([...DEFAULT_IGNORE, ...ctx.options.ignore]);
+
+    function walk(dir: string) {
+      let entries: string[];
+      try { entries = readdirSync(dir); } catch { return; }
+
+      for (const entry of entries) {
+        if (ignoreDirs.has(entry)) continue;
+        const fullPath = join(dir, entry);
+        let stat: ReturnType<typeof statSync>;
+        try { stat = statSync(fullPath); } catch { continue; }
+
+        if (stat.isDirectory()) { walk(fullPath); continue; }
+
+        const ext = extname(entry).toLowerCase();
+        if (BINARY_EXTENSIONS.has(ext)) continue;
+        if (GENERATED_PATTERNS.some(r => r.test(entry))) continue;
+        if (ctx.options.codeOnly && !isSupportedExtension(ext)) continue;
+
+        filePaths.push(fullPath);
+        totalBytes += stat.size;
+      }
+    }
+
+    walk(ctx.repoPath);
+    ctx.onProgress?.({ phase: 'scan', totalFiles: filePaths.length });
+    return { filePaths, totalBytes };
+  },
+};

package/src/pipeline/phases/structure.ts

@@ -0,0 +1,68 @@
+import { relative, dirname, basename } from 'path';
+import type { PipelinePhase, PipelineContext } from '../types.js';
+import type { MonographNode, MonographEdge } from '../../types.js';
+import { makeId, toNormLabel, CONFIDENCE_SCORE } from '../../types.js';
+import type { ScanOutput } from './scan.js';
+
+export interface StructureOutput {
+  fileNodes: MonographNode[];
+  folderNodes: MonographNode[];
+  containsEdges: MonographEdge[];
+}
+
+export const structurePhase: PipelinePhase<StructureOutput> = {
+  name: 'structure',
+  deps: ['scan'],
+  async execute(ctx, deps) {
+    const { filePaths } = deps.get('scan') as ScanOutput;
+    const fileNodes: MonographNode[] = [];
+    const folderNodes: MonographNode[] = [];
+    const containsEdges: MonographEdge[] = [];
+    const seenFolders = new Set<string>();
+
+    for (const absPath of filePaths) {
+      const rel = relative(ctx.repoPath, absPath);
+      const fileId = makeId(rel.replace(/\//g, '_'), 'file');
+      fileNodes.push({
+        id: fileId, label: 'File',
+        name: basename(rel), normLabel: toNormLabel(basename(rel)),
+        filePath: rel, isExported: false,
+      });
+
+      const parts = dirname(rel).split('/');
+      let current = '';
+      let parentFolderId: string | null = null;
+      for (const part of parts) {
+        if (part === '.') continue;
+        current = current ? `${current}/${part}` : part;
+        const folderId = makeId(current.replace(/\//g, '_'), 'folder');
+        if (!seenFolders.has(folderId)) {
+          seenFolders.add(folderId);
+          folderNodes.push({
+            id: folderId, label: 'Folder',
+            name: part, normLabel: toNormLabel(part),
+            filePath: current, isExported: false,
+          });
+          if (parentFolderId) {
+            containsEdges.push({
+              id: makeId(parentFolderId, folderId, 'contains'),
+              sourceId: parentFolderId, targetId: folderId,
+              relation: 'CONTAINS', confidence: 'EXTRACTED', confidenceScore: CONFIDENCE_SCORE.EXTRACTED,
+            });
+          }
+        }
+        parentFolderId = folderId;
+      }
+
+      if (parentFolderId) {
+        containsEdges.push({
+          id: makeId(parentFolderId, fileId, 'contains'),
+          sourceId: parentFolderId, targetId: fileId,
+          relation: 'CONTAINS', confidence: 'EXTRACTED', confidenceScore: CONFIDENCE_SCORE.EXTRACTED,
+        });
+      }
+    }
+
+    return { fileNodes, folderNodes, containsEdges };
+  },
+};

package/src/pipeline/phases/suggest.ts

@@ -0,0 +1,71 @@
+import type { PipelinePhase, PipelineContext } from '../types.js';
+import type { SuggestedQuestion } from '../../types.js';
+import type { ParseOutput } from './parse.js';
+import type { CommunitiesOutput } from './communities.js';
+
+export interface SuggestOutput {
+  questions: SuggestedQuestion[];
+}
+
+export const suggestPhase: PipelinePhase<SuggestOutput> = {
+  name: 'suggest',
+  deps: ['parse', 'cross-file', 'mro', 'communities', 'god-nodes', 'surprises'],
+  async execute(_ctx, deps) {
+    const { allEdges, symbolNodes } = deps.get('parse') as ParseOutput;
+    const { memberships } = deps.get('communities') as CommunitiesOutput;
+    const questions: SuggestedQuestion[] = [];
+
+    // Signal 1: ambiguous edges
+    for (const edge of allEdges) {
+      if (edge.confidence === 'AMBIGUOUS') {
+        questions.push({ type: 'ambiguous_edge', edge, reason: 'Dynamic dispatch or unresolved target' });
+      }
+    }
+
+    // Signal 2: bridge nodes
+    const nodeCommSet = new Map<string, Set<number>>();
+    for (const edge of allEdges) {
+      const srcComm = memberships.get(edge.sourceId);
+      const tgtComm = memberships.get(edge.targetId);
+      if (srcComm !== undefined && tgtComm !== undefined && srcComm !== tgtComm) {
+        for (const [nid, comm] of [[edge.sourceId, srcComm], [edge.targetId, tgtComm]] as const) {
+          const s = nodeCommSet.get(nid) ?? new Set();
+          s.add(comm);
+          nodeCommSet.set(nid, s);
+        }
+      }
+    }
+    for (const [nodeId, comms] of nodeCommSet) {
+      if (comms.size >= 2) {
+        const node = symbolNodes.find(n => n.id === nodeId);
+        if (!node) continue;
+        const [commA, commB] = [...comms];
+        questions.push({ type: 'bridge_node', node, commA, commB });
+      }
+    }
+
+    // Signal 3: verify_inferred
+    for (const edge of allEdges) {
+      if (edge.confidence === 'INFERRED') {
+        questions.push({ type: 'verify_inferred', edge, inferredFrom: 'type inference / alias resolution' });
+      }
+    }
+
+    // Signal 4: isolated nodes
+    const connectedIds = new Set<string>();
+    for (const e of allEdges) { connectedIds.add(e.sourceId); connectedIds.add(e.targetId); }
+    const isolated = symbolNodes.filter(n =>
+      !connectedIds.has(n.id) && n.label !== 'File' && n.label !== 'Folder'
+    );
+    if (isolated.length > 0) {
+      questions.push({ type: 'isolated_nodes', nodes: isolated.slice(0, 10), reason: 'No edges found' });
+    }
+
+    const PRIORITY: Record<string, number> = {
+      bridge_node: 5, ambiguous_edge: 4, verify_inferred: 3, low_cohesion: 2, isolated_nodes: 1
+    };
+    questions.sort((a, b) => (PRIORITY[b.type] ?? 0) - (PRIORITY[a.type] ?? 0));
+
+    return { questions };
+  },
+};

package/src/pipeline/phases/surprises.ts

@@ -0,0 +1,70 @@
+import type { PipelinePhase, PipelineContext } from '../types.js';
+import type { SurprisingConnection } from '../../types.js';
+import type { ParseOutput } from './parse.js';
+import type { CrossFileOutput } from './cross-file.js';
+import type { CommunitiesOutput } from './communities.js';
+
+const WEIGHTS = {
+  confidence: 0.30,
+  crossType: 0.20,
+  crossRepo: 0.15,
+  crossCommunity: 0.25,
+  peripheral: 0.10,
+};
+
+export interface SurprisesOutput {
+  surprises: SurprisingConnection[];
+}
+
+export const surprisesPhase: PipelinePhase<SurprisesOutput> = {
+  name: 'surprises',
+  deps: ['cross-file', 'communities', 'parse'],
+  async execute(_ctx, deps) {
+    const { allEdges, symbolNodes } = deps.get('parse') as ParseOutput;
+    const { resolvedEdges } = deps.get('cross-file') as CrossFileOutput;
+    const { memberships } = deps.get('communities') as CommunitiesOutput;
+
+    const edges = [...allEdges, ...resolvedEdges];
+    const labelIndex = new Map(symbolNodes.map(n => [n.id, n.label]));
+    const inDeg = new Map<string, number>();
+    for (const e of edges) inDeg.set(e.targetId, (inDeg.get(e.targetId) ?? 0) + 1);
+    const maxDeg = Math.max(...inDeg.values(), 1);
+    const peripheralThreshold = maxDeg * 0.1;
+
+    const surprises: SurprisingConnection[] = edges
+      .filter(e => e.confidence !== 'EXTRACTED')
+      .map(e => {
+        const reasons: string[] = [];
+        let score = 0;
+
+        const conf = 1 - e.confidenceScore;
+        score += WEIGHTS.confidence * conf;
+        if (conf > 0) reasons.push(`${e.confidence} confidence`);
+
+        const srcLabel = labelIndex.get(e.sourceId);
+        const tgtLabel = labelIndex.get(e.targetId);
+        if (srcLabel && tgtLabel && srcLabel !== tgtLabel) {
+          score += WEIGHTS.crossType;
+          reasons.push(`cross-type (${srcLabel}→${tgtLabel})`);
+        }
+
+        const srcComm = memberships.get(e.sourceId);
+        const tgtComm = memberships.get(e.targetId);
+        if (srcComm !== undefined && tgtComm !== undefined && srcComm !== tgtComm) {
+          score += WEIGHTS.crossCommunity;
+          reasons.push('cross-community');
+        }
+
+        if ((inDeg.get(e.targetId) ?? 0) < peripheralThreshold) {
+          score += WEIGHTS.peripheral;
+          reasons.push('peripheral target');
+        }
+
+        return { edge: e, score, reasons };
+      })
+      .sort((a, b) => b.score - a.score)
+      .slice(0, 50);
+
+    return { surprises };
+  },
+};