@monoes/monograph 1.5.6 → 1.5.8

package/src/pipeline/phases/suggest.ts

@@ -1,92 +0,0 @@
-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) {
-    if (_ctx.allFilesCached) return { questions: [] };
-    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) {
-        // Record the NEIGHBOR's community for each endpoint so a node accumulates
-        // the communities it bridges TO, enabling comms.size >= 2 to fire correctly.
-        for (const [nid, comm] of [[edge.sourceId, tgtComm], [edge.targetId, srcComm]] 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' });
-    }
-
-    // Signal 5: no_signal — AMBIGUOUS edges with very low confidence
-    for (const edge of allEdges) {
-      if (edge.confidence === 'AMBIGUOUS' && (edge.confidenceScore ?? 1) < 0.2) {
-        questions.push({ type: 'no_signal', edge, reason: 'Very low confidence — no supporting evidence found' });
-      }
-    }
-
-    // Signal 6: thin_community — communities with fewer than 3 members
-    const commMemberCount = new Map<number, number>();
-    for (const [, commId] of memberships) {
-      commMemberCount.set(commId, (commMemberCount.get(commId) ?? 0) + 1);
-    }
-    for (const [commId, count] of commMemberCount) {
-      if (count < 3) {
-        questions.push({ type: 'thin_community', communityId: commId, memberCount: count, reason: `Community has only ${count} members — may need merging` });
-      }
-    }
-
-    const PRIORITY: Record<string, number> = {
-      bridge_node: 5, ambiguous_edge: 4, verify_inferred: 3, no_signal: 3, low_cohesion: 2, thin_community: 2, isolated_nodes: 1
-    };
-    questions.sort((a, b) => (PRIORITY[b.type] ?? 0) - (PRIORITY[a.type] ?? 0));
-
-    return { questions };
-  },
-};

package/src/pipeline/phases/surprises.ts

@@ -1,83 +0,0 @@
-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';
-import { classifyFile } from '../../analysis/file-classifier.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 = [...inDeg.values()].reduce((a, b) => Math.max(a, b), 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');
-        }
-
-        // Cross-filetype bonus: CODE↔DOCUMENT/PAPER edges get extra weight
-        const srcFilePath = symbolNodes.find(n => n.id === e.sourceId)?.filePath;
-        const tgtFilePath = symbolNodes.find(n => n.id === e.targetId)?.filePath;
-        if (srcFilePath && tgtFilePath) {
-          const srcFileType = classifyFile(srcFilePath);
-          const tgtFileType = classifyFile(tgtFilePath);
-          if (srcFileType !== tgtFileType && srcFileType !== 'UNKNOWN' && tgtFileType !== 'UNKNOWN') {
-            score += WEIGHTS.crossRepo;  // reuse unused crossRepo weight (0.15)
-            reasons.push(`cross-filetype (${srcFileType}→${tgtFileType})`);
-          }
-        }
-
-        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 };
-  },
-};

package/src/pipeline/phases/tools.ts

@@ -1,180 +0,0 @@
-import { readFileSync, statSync } from 'fs';
-import { extname } from 'path';
-import type { PipelinePhase } from '../types.js';
-import type { MonographNode, MonographEdge } from '../../types.js';
-import { makeId, toNormLabel } from '../../types.js';
-import { insertNodes } from '../../storage/node-store.js';
-import { insertEdges } from '../../storage/edge-store.js';
-import type { StructureOutput } from './structure.js';
-
-// ── Constants ─────────────────────────────────────────────────────────────────
-
-const CODE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
-
-// ── Output types ──────────────────────────────────────────────────────────────
-
-export interface ToolDef {
-  name: string;
-  filePath: string;
-  description?: string;
-  handlerNodeId?: string;
-  toolNodeId: string;
-}
-
-export interface ToolsOutput {
-  toolDefs: ToolDef[];
-}
-
-// ── Detection regexes ─────────────────────────────────────────────────────────
-
-/** server.tool('name', ...) or server.tool("name", ...) */
-const SERVER_TOOL_RE = /server\.tool\(\s*['"]([^'"]+)['"]/g;
-
-/** export const FOO_TOOL = { name: 'foo', description: '...' } */
-const EXPORTED_TOOL_CONST_RE = /export\s+const\s+\w+[Tt][Oo][Oo][Ll]\w*\s*=\s*\{[^}]*name:\s*['"]([^'"]+)['"]/g;
-
-/** Array variable name pattern: TOOLS, tools, MY_TOOLS, toolsList, etc. (case-insensitive on 'tools') */
-const TOOLS_ARRAY_VAR_RE = /(?:export\s+)?(?:const|let|var)\s+(\w*[Tt][Oo][Oo][Ll][Ss]?\w*)\s*(?::\s*\w+\[\])?\s*=\s*\[/g;
-
-// ── Phase ─────────────────────────────────────────────────────────────────────
-
-export const toolsPhase: PipelinePhase<ToolsOutput> = {
-  name: 'tools',
-  deps: ['parse', 'structure'],
-  async execute(ctx, deps) {
-    if (ctx.allFilesCached) return { toolDefs: [], toolNodes: [], handlesEdges: [] };
-    const { fileNodes } = deps.get('structure') as StructureOutput;
-    const toolDefs: ToolDef[] = [];
-    const toolNodes: MonographNode[] = [];
-    const handlesEdges: MonographEdge[] = [];
-
-    for (const fileNode of fileNodes) {
-      const relPath = fileNode.filePath ?? '';
-      const ext = extname(relPath).toLowerCase();
-
-      if (!CODE_EXTENSIONS.has(ext)) continue;
-
-      const source = safeReadSource(`${ctx.repoPath}/${relPath}`, ctx.options.maxFileSizeBytes);
-      if (!source) continue;
-
-      const detectedNames = new Set<string>();
-
-      // ── 1. server.tool('name', ...) pattern ───────────────────────────────
-      const serverToolRe = new RegExp(SERVER_TOOL_RE.source, 'g');
-      let m: RegExpExecArray | null;
-      while ((m = serverToolRe.exec(source)) !== null) {
-        detectedNames.add(m[1]);
-      }
-
-      // ── 2. Exported constant tool pattern ─────────────────────────────────
-      const exportedToolRe = new RegExp(EXPORTED_TOOL_CONST_RE.source, 'g');
-      while ((m = exportedToolRe.exec(source)) !== null) {
-        detectedNames.add(m[1]);
-      }
-
-      // ── 3. TOOLS array pattern ────────────────────────────────────────────
-      const toolsArrayRe = new RegExp(TOOLS_ARRAY_VAR_RE.source, 'g');
-      while ((m = toolsArrayRe.exec(source)) !== null) {
-        const arrayStart = m.index + m[0].length;
-        // Extract the array block (up to 4000 chars to avoid huge allocations)
-        const block = source.slice(arrayStart, arrayStart + 4000);
-        // Only match if array contains a description property (reduces false positives)
-        if (!block.includes('description')) continue;
-        // Find all name: 'foo' entries in the block
-        const nameRe = /name:\s*['"]([^'"]+)['"]/g;
-        let nm: RegExpExecArray | null;
-        while ((nm = nameRe.exec(block)) !== null) {
-          detectedNames.add(nm[1]);
-        }
-      }
-
-      // ── Create nodes & edges for each detected tool ───────────────────────
-      for (const toolName of detectedNames) {
-        const toolNodeId = makeId('tool', toolName, relPath);
-
-        const toolNode: MonographNode = {
-          id: toolNodeId,
-          label: 'Tool',
-          name: toolName,
-          normLabel: toNormLabel(toolName),
-          filePath: relPath,
-          startLine: 0,
-          endLine: 0,
-          isExported: true,
-          language: langFromExt(ext),
-        };
-        toolNodes.push(toolNode);
-
-        const def: ToolDef = { name: toolName, filePath: relPath, toolNodeId };
-
-        // Attempt handler lookup in the DB
-        if (ctx.db) {
-          const lowerTool = toolName.toLowerCase().replace(/[_-]/g, '');
-          // Query Function/Method nodes in the same file
-          const rows = ctx.db
-            .prepare(
-              `SELECT id, name FROM nodes
-               WHERE file_path = ?
-               AND label IN ('Function', 'Method')`,
-            )
-            .all(relPath) as { id: string; name: string }[];
-
-          // Find nodes whose name contains the tool name (case-insensitive, stripped)
-          const matches = rows.filter(row => {
-            const n = row.name.toLowerCase().replace(/[_-]/g, '');
-            return n.includes(lowerTool) || (n.length > 0 && lowerTool.includes(n));
-          });
-
-          if (matches.length >= 1) {
-            // Pick best match: exact name > name contains tool > tool contains name
-            const scored = matches
-              .map(row => {
-                const n = row.name.toLowerCase().replace(/[_-]/g, '');
-                const score = n === lowerTool ? 3 : n.includes(lowerTool) ? 2 : 1;
-                return { row, score };
-              })
-              .sort((a, b) => b.score - a.score);
-            const { row: best, score } = scored[0];
-            const edgeId = makeId(toolNodeId, best.id, 'handles_tool');
-            handlesEdges.push({
-              id: edgeId,
-              sourceId: toolNodeId,
-              targetId: best.id,
-              relation: 'HANDLES_TOOL',
-              confidence: 'EXTRACTED',
-              confidenceScore: score === 3 ? 0.95 : 0.75,
-            });
-            def.handlerNodeId = best.id;
-          }
-        }
-
-        toolDefs.push(def);
-      }
-    }
-
-    if (ctx.db) {
-      insertNodes(ctx.db, toolNodes);
-      insertEdges(ctx.db, handlesEdges);
-    }
-
-    return { toolDefs };
-  },
-};
-
-// ── Utilities ─────────────────────────────────────────────────────────────────
-
-function safeReadSource(absPath: string, maxBytes: number): string | undefined {
-  try {
-    const stat = statSync(absPath);
-    if (stat.size > maxBytes) return undefined;
-    return readFileSync(absPath, 'utf-8');
-  } catch {
-    return undefined;
-  }
-}
-
-function langFromExt(ext: string): string {
-  if (ext === '.ts' || ext === '.tsx') return 'typescript';
-  if (ext === '.js' || ext === '.jsx' || ext === '.mjs' || ext === '.cjs') return 'javascript';
-  return 'unknown';
-}

package/src/pipeline/phases/variables-phase.ts

@@ -1,37 +0,0 @@
-import type { PipelinePhase, PipelineContext } from '../types.js';
-import type { ParseOutput } from './parse.js';
-import { extractVariables, variableToNode } from './variables.js';
-
-export interface VariablesOutput {
-  variableCount: number;
-}
-
-export const variablesPhase: PipelinePhase<VariablesOutput> = {
-  name: 'variables',
-  deps: ['parse'],
-  async execute(ctx: PipelineContext, deps: Map<string, unknown>): Promise<VariablesOutput> {
-    if (ctx.allFilesCached) return { variableCount: 0 };
-    const { fileContents } = deps.get('parse') as ParseOutput;
-
-    const stmt = ctx.db.prepare(`
-      INSERT OR IGNORE INTO nodes (id, label, name, norm_label, file_path, start_line, end_line, is_exported)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-    `);
-
-    let variableCount = 0;
-    for (const [filePath, source] of fileContents) {
-      const vars = extractVariables(source, filePath);
-      for (const v of vars) {
-        const node = variableToNode(v);
-        stmt.run(
-          node.id, node.label, node.name, node.normLabel ?? node.name.toLowerCase(),
-          node.filePath ?? null, node.startLine ?? null, node.endLine ?? null,
-          node.isExported ? 1 : 0,
-        );
-        variableCount++;
-      }
-    }
-
-    return { variableCount };
-  },
-};

package/src/pipeline/phases/variables.ts

@@ -1,67 +0,0 @@
-import type { MonographNode } from '../../types.js';
-
-export interface VariableInfo {
-  name: string;
-  isExported: boolean;
-  line: number;
-  filePath: string;
-}
-
-// Regex for top-level variable declarations.
-// We detect nesting depth by counting braces before the match.
-const TOP_LEVEL_VAR = /^(export\s+)?(const|let|var)\s+(\w+)\s*[=:]/gm;
-
-/**
- * Strip string literals, template literals, and comments from source text before
- * brace-depth counting, so braces inside those constructs don't skew the depth.
- */
-function stripNonCodeBraces(src: string): string {
-  // Replace content inside single/double-quoted strings and block comments with
-  // equal-length spaces (preserving offsets/line numbers), then strip line comments.
-  return src
-    .replace(/`[^`\\]*(?:\\[\s\S][^`\\]*)*`/g, m => ' '.repeat(m.length))
-    .replace(/"(?:[^"\\]|\\.)*"/g, m => ' '.repeat(m.length))
-    .replace(/'(?:[^'\\]|\\.)*'/g, m => ' '.repeat(m.length))
-    .replace(/\/\*[\s\S]*?\*\//g, m => ' '.repeat(m.length))
-    .replace(/\/\/[^\n]*/g, m => ' '.repeat(m.length));
-}
-
-export function extractVariables(source: string, filePath: string): VariableInfo[] {
-  const results: VariableInfo[] = [];
-  let match: RegExpExecArray | null;
-  TOP_LEVEL_VAR.lastIndex = 0;
-
-  // Pre-process: strip string/comment content so braces inside them don't count
-  const stripped = stripNonCodeBraces(source);
-
-  while ((match = TOP_LEVEL_VAR.exec(source)) !== null) {
-    const before = stripped.slice(0, match.index);
-    // Count brace depth — top-level means depth == 0
-    let depth = 0;
-    for (const ch of before) {
-      if (ch === '{') depth++;
-      else if (ch === '}') depth--;
-    }
-    if (depth !== 0) continue;
-
-    const isExported = !!match[1];
-    const name = match[3];
-    const line = before.split('\n').length;
-    results.push({ name, isExported, line, filePath });
-  }
-
-  return results;
-}
-
-export function variableToNode(v: VariableInfo): MonographNode {
-  return {
-    id: `var:${v.filePath}:${v.name}`,
-    label: 'Variable',
-    name: v.name,
-    normLabel: v.name.toLowerCase(),
-    filePath: v.filePath,
-    startLine: v.line,
-    endLine: v.line,
-    isExported: v.isExported,
-  };
-}

package/src/pipeline/phases/wildcard-phase.ts

@@ -1,50 +0,0 @@
-import type { PipelinePhase, PipelineContext } from '../types.js';
-import type { ParseOutput } from './parse.js';
-import type { CrossFileOutput } from './cross-file.js';
-import { synthesizeWildcardImports } from './wildcard-synthesis.js';
-import type { MonographNode, MonographEdge } from '../../types.js';
-
-export interface WildcardSynthesisOutput {
-  synthesizedCount: number;
-}
-
-export const wildcardSynthesisPhase: PipelinePhase<WildcardSynthesisOutput> = {
-  name: 'wildcard-synthesis',
-  deps: ['parse', 'cross-file'],
-  async execute(ctx: PipelineContext, deps: Map<string, unknown>): Promise<WildcardSynthesisOutput> {
-    if (ctx.allFilesCached) return { synthesizedCount: 0 };
-    const { symbolNodes: allNodes, allEdges, fileContents } = deps.get('parse') as ParseOutput;
-    const { resolvedEdges } = deps.get('cross-file') as CrossFileOutput;
-
-    const allKnownEdges: MonographEdge[] = [...allEdges, ...resolvedEdges];
-    const allKnownNodes: MonographNode[] = allNodes;
-
-    let synthesizedCount = 0;
-
-    const fileNodeIndex = new Map<string, string>();
-    for (const node of allKnownNodes) {
-      if (node.filePath) fileNodeIndex.set(node.filePath, node.id);
-    }
-
-    const stmt = ctx.db.prepare(`
-      INSERT OR IGNORE INTO edges (id, source_id, target_id, relation, confidence, confidence_score)
-      VALUES (?, ?, ?, ?, ?, ?)
-    `);
-
-    for (const [filePath, source] of fileContents) {
-      const fileNodeId = fileNodeIndex.get(filePath);
-      // No real node for this file (e.g. no parsed symbols) — there's no
-      // valid row to attach a source_id to, and fabricating one violates the
-      // edges table's FOREIGN KEY constraint on source_id (issue #40).
-      if (!fileNodeId) continue;
-      const { synthesizedEdges } = synthesizeWildcardImports(fileNodeId, source, allKnownNodes, allKnownEdges);
-
-      for (const edge of synthesizedEdges) {
-        stmt.run(edge.id, edge.sourceId, edge.targetId, edge.relation, edge.confidence, edge.confidenceScore);
-        synthesizedCount++;
-      }
-    }
-
-    return { synthesizedCount };
-  },
-};