@monoes/monograph 1.5.6 → 1.5.7

package/src/graph/maintainability.ts

@@ -1,156 +0,0 @@
-import type { MonographDb } from '../storage/db.js';
-
-export interface MaintainabilityResult {
-  nodeId: string;
-  name: string;
-  filePath: string | null;
-  mi: number;          // Maintainability Index 0-100
-  grade: 'A' | 'B' | 'C' | 'D' | 'F';
-  halsteadVolume: number;   // proxy: node degree × log2(max(degree, 2))
-  linesOfCode: number;
-}
-
-export interface MaintainabilityReport {
-  results: MaintainabilityResult[];
-  averageMi: number;
-  lowMiCount: number;   // MI < 65
-  criticalCount: number; // MI < 25
-}
-
-function gradeFromMi(mi: number): 'A' | 'B' | 'C' | 'D' | 'F' {
-  if (mi > 85) return 'A';
-  if (mi > 65) return 'B';
-  if (mi > 50) return 'C';
-  if (mi > 25) return 'D';
-  return 'F';
-}
-
-export function computeMaintainabilityIndex(db: MonographDb): MaintainabilityReport {
-  // Fetch all Function and Method Symbol nodes
-  const nodes = db.prepare(`
-    SELECT id, name, file_path, start_line, end_line, properties
-    FROM nodes
-    WHERE label IN ('Function', 'Method', 'Symbol')
-      AND start_line IS NOT NULL
-      AND end_line IS NOT NULL
-  `).all() as {
-    id: string;
-    name: string;
-    file_path: string | null;
-    start_line: number;
-    end_line: number;
-    properties: string | null;
-  }[];
-
-  if (nodes.length === 0) {
-    return { results: [], averageMi: 100, lowMiCount: 0, criticalCount: 0 };
-  }
-
-  // ── Batch degree lookup: one query replaces 2×N individual queries ────────
-  // Combine in-degree and out-degree via UNION ALL + GROUP BY in a single pass.
-  const degreeMap = new Map<string, number>();
-  for (const { node_id, deg } of db.prepare(`
-    SELECT node_id, SUM(cnt) as deg FROM (
-      SELECT target_id AS node_id, COUNT(*) AS cnt FROM edges GROUP BY target_id
-      UNION ALL
-      SELECT source_id AS node_id, COUNT(*) AS cnt FROM edges GROUP BY source_id
-    ) GROUP BY node_id
-  `).all() as { node_id: string; deg: number }[]) {
-    degreeMap.set(node_id, deg);
-  }
-
-  const results: MaintainabilityResult[] = [];
-  const propUpdates: Array<{ id: string; props: string }> = [];
-
-  for (const node of nodes) {
-    const loc = Math.max(1, node.end_line - node.start_line + 1);
-    const degree = degreeMap.get(node.id) ?? 0;
-    const hvProxy = degree * Math.log2(Math.max(degree, 2));
-
-    // Maintainability Index formula
-    const rawMi = 171 - 5.2 * Math.log(hvProxy + 1) - 0.23 * (loc / 10) - 16.2 * Math.log(Math.max(1, loc));
-    const mi = Math.max(0, Math.min(100, rawMi));
-    const grade = gradeFromMi(mi);
-
-    // Stage property update — batched below
-    const props: Record<string, unknown> = node.properties ? JSON.parse(node.properties) : {};
-    props.maintainabilityIndex = mi;
-    propUpdates.push({ id: node.id, props: JSON.stringify(props) });
-
-    results.push({
-      nodeId: node.id,
-      name: node.name,
-      filePath: node.file_path,
-      mi: Math.round(mi * 100) / 100,
-      grade,
-      halsteadVolume: Math.round(hvProxy * 100) / 100,
-      linesOfCode: loc,
-    });
-  }
-
-  // ── Batch UPDATE all property writes in one transaction ───────────────────
-  const updateStmt = db.prepare('UPDATE nodes SET properties = ? WHERE id = ?');
-  db.transaction((updates: typeof propUpdates) => {
-    for (const { id, props } of updates) updateStmt.run(props, id);
-  })(propUpdates);
-
-  // Sort by MI ascending (worst first)
-  results.sort((a, b) => a.mi - b.mi);
-
-  const averageMi = results.length > 0
-    ? results.reduce((sum, r) => sum + r.mi, 0) / results.length
-    : 100;
-
-  return {
-    results,
-    averageMi: Math.round(averageMi * 100) / 100,
-    lowMiCount: results.filter(r => r.mi < 65).length,
-    criticalCount: results.filter(r => r.mi < 25).length,
-  };
-}
-
-/**
- * Format a MaintainabilityReport as structured text with file:line hints for LLM navigation.
- *
- * @param report - MaintainabilityReport from computeMaintainabilityIndex()
- * @param topN - number of worst files to list (default 10)
- * @returns structured text suitable for LLM consumption
- */
-export function formatMaintainability(report: MaintainabilityReport, topN = 10): string {
-  const { results, averageMi, lowMiCount, criticalCount } = report;
-
-  if (results.length === 0) {
-    return 'maintainability: no Function/Method/Symbol nodes with line info found\n';
-  }
-
-  const lines: string[] = [
-    `maintainability: ${results.length} nodes analysed`,
-    `  avg_mi: ${averageMi}  low(mi<65): ${lowMiCount}  critical(mi<25): ${criticalCount}`,
-    '',
-  ];
-
-  // results already sorted by MI ascending (worst first)
-  const worst = results.slice(0, topN);
-  if (worst.length > 0) {
-    lines.push(`top_${topN}_worst_mi:`);
-    for (const r of worst) {
-      const loc = r.filePath ? `${r.filePath}:1` : `<unknown>:1`;
-      lines.push(`  - ${r.name}  grade:${r.grade}  mi:${r.mi}`);
-      lines.push(`    file: ${loc}`);
-      lines.push(`    loc: ${r.linesOfCode}  halstead_vol: ${r.halsteadVolume}`);
-    }
-    lines.push('');
-  }
-
-  const critical = results.filter(r => r.mi < 25);
-  if (critical.length > 0) {
-    lines.push(`critical_nodes(mi<25): ${critical.length}`);
-    for (const r of critical.slice(0, 5)) {
-      const loc = r.filePath ? `${r.filePath}:1` : `<unknown>:1`;
-      lines.push(`  - ${r.name}  file: ${loc}  mi:${r.mi}  grade:${r.grade}`);
-    }
-    if (critical.length > 5) lines.push(`  ... and ${critical.length - 5} more`);
-  }
-
-  return lines.join('\n');
-}

package/src/graph/merge.ts

@@ -1,174 +0,0 @@
-import type { MonographNode, MonographEdge } from '../types.js';
-import type { MonographDb } from '../storage/db.js';
-
-// ── Merge strategy ─────────────────────────────────────────────────────────────
-
-export type MergeConflictStrategy =
-  /** Skip the incoming node/edge if one with the same id already exists (default). */
-  | 'skip'
-  /** Replace the existing node/edge with the incoming one. */
-  | 'replace';
-
-export interface GraphMergeOptions {
-  /** How to handle id collisions. Default: 'skip'. */
-  onConflict?: MergeConflictStrategy;
-}
-
-export interface GraphMergeResult {
-  nodesAdded: number;
-  nodesSkipped: number;
-  edgesAdded: number;
-  edgesSkipped: number;
-}
-
-// ── In-memory merge ────────────────────────────────────────────────────────────
-
-/**
- * Merge two sets of nodes and edges into a single deduplicated set.
- *
- * @param base   - The base graph (nodes + edges).
- * @param incoming - The graph to merge in.
- * @param options  - Conflict resolution strategy.
- * @returns Merged nodes + edges, plus per-type counters.
- */
-export function mergeGraphs(
-  base: { nodes: MonographNode[]; edges: MonographEdge[] },
-  incoming: { nodes: MonographNode[]; edges: MonographEdge[] },
-  options: GraphMergeOptions = {},
-): { nodes: MonographNode[]; edges: MonographEdge[] } & GraphMergeResult {
-  const strategy = options.onConflict ?? 'skip';
-
-  const nodeMap = new Map<string, MonographNode>(base.nodes.map(n => [n.id, n]));
-  const edgeMap = new Map<string, MonographEdge>(base.edges.map(e => [e.id, e]));
-
-  let nodesAdded = 0;
-  let nodesSkipped = 0;
-  let edgesAdded = 0;
-  let edgesSkipped = 0;
-
-  for (const node of incoming.nodes) {
-    if (nodeMap.has(node.id)) {
-      if (strategy === 'replace') {
-        nodeMap.set(node.id, node);
-        nodesAdded++;
-      } else {
-        nodesSkipped++;
-      }
-    } else {
-      nodeMap.set(node.id, node);
-      nodesAdded++;
-    }
-  }
-
-  for (const edge of incoming.edges) {
-    if (edgeMap.has(edge.id)) {
-      if (strategy === 'replace') {
-        edgeMap.set(edge.id, edge);
-        edgesAdded++;
-      } else {
-        edgesSkipped++;
-      }
-    } else {
-      edgeMap.set(edge.id, edge);
-      edgesAdded++;
-    }
-  }
-
-  return {
-    nodes: Array.from(nodeMap.values()),
-    edges: Array.from(edgeMap.values()),
-    nodesAdded,
-    nodesSkipped,
-    edgesAdded,
-    edgesSkipped,
-  };
-}
-
-// ── DB-backed merge ────────────────────────────────────────────────────────────
-
-/**
- * Merge incoming nodes and edges into an existing MonographDb.
- *
- * Nodes are inserted via INSERT OR IGNORE (skip) or INSERT OR REPLACE (replace).
- * Edges are handled the same way.
- *
- * @param targetDb  - The destination database.
- * @param incoming  - The graph data to merge in.
- * @param options   - Conflict resolution strategy.
- * @returns Per-type counters.
- */
-export function mergeGraphIntoDb(
-  targetDb: MonographDb,
-  incoming: { nodes: MonographNode[]; edges: MonographEdge[] },
-  options: GraphMergeOptions = {},
-): GraphMergeResult {
-  const strategy = options.onConflict ?? 'skip';
-  const orClause = strategy === 'replace' ? 'OR REPLACE' : 'OR IGNORE';
-
-  const insertNode = targetDb.prepare(
-    `INSERT ${orClause} INTO nodes
-       (id, label, name, norm_label, file_path, start_line, end_line, community_id, is_exported, language, properties)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-  );
-
-  const insertEdge = targetDb.prepare(
-    `INSERT ${orClause} INTO edges
-       (id, source_id, target_id, relation, confidence, confidence_score, reason, evidence)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
-  );
-
-  let nodesAdded = 0;
-  let nodesSkipped = 0;
-  let edgesAdded = 0;
-  let edgesSkipped = 0;
-
-  const nodeExists = targetDb.prepare('SELECT 1 FROM nodes WHERE id = ?');
-  const edgeExists = targetDb.prepare('SELECT 1 FROM edges WHERE id = ?');
-
-  const mergeAll = targetDb.transaction(() => {
-    for (const n of incoming.nodes) {
-      const exists = !!nodeExists.get(n.id);
-      insertNode.run(
-        n.id,
-        n.label,
-        n.name,
-        n.normLabel,
-        n.filePath ?? null,
-        n.startLine ?? null,
-        n.endLine ?? null,
-        n.communityId ?? null,
-        n.isExported ? 1 : 0,
-        n.language ?? null,
-        n.properties ? JSON.stringify(n.properties) : null,
-      );
-      if (exists) {
-        strategy === 'replace' ? nodesAdded++ : nodesSkipped++;
-      } else {
-        nodesAdded++;
-      }
-    }
-
-    for (const e of incoming.edges) {
-      const exists = !!edgeExists.get(e.id);
-      insertEdge.run(
-        e.id,
-        e.sourceId,
-        e.targetId,
-        e.relation,
-        e.confidence,
-        e.confidenceScore,
-        e.reason ?? null,
-        null, // evidence kept as null for merge
-      );
-      if (exists) {
-        strategy === 'replace' ? edgesAdded++ : edgesSkipped++;
-      } else {
-        edgesAdded++;
-      }
-    }
-  });
-
-  mergeAll();
-
-  return { nodesAdded, nodesSkipped, edgesAdded, edgesSkipped };
-}

package/src/graph/mirrored-dirs.ts

@@ -1,202 +0,0 @@
-import type { MonographDb } from '../storage/db.js';
-import type { CloneFamily } from '../graph/clone-families.js';
-
-export interface MirroredDirPair {
-  dirA: string;
-  dirB: string;
-  similarity: number;         // 0-1, file name overlap ratio
-  sharedFileNames: string[];  // basenames that appear in both
-  uniqueToA: number;
-  uniqueToB: number;
-}
-
-export interface MirroredDirsReport {
-  pairs: MirroredDirPair[];
-  totalDirsAnalyzed: number;
-}
-
-/**
- * Detect directory subtrees that are structural mirrors of each other.
- * Uses Jaccard similarity of file basenames within each directory.
- *
- * @param db - monograph database
- * @param minSimilarity - minimum Jaccard similarity threshold (default 0.7)
- */
-export function detectMirroredDirs(db: MonographDb, minSimilarity = 0.7): MirroredDirsReport {
-  // Query all File nodes with a file_path
-  const rows = db.prepare(
-    `SELECT file_path FROM nodes WHERE label = 'File' AND file_path IS NOT NULL`,
-  ).all() as { file_path: string }[];
-
-  // Build map: dirPath → Set<basename>
-  const dirMap = new Map<string, Set<string>>();
-  for (const { file_path } of rows) {
-    const lastSlash = Math.max(file_path.lastIndexOf('/'), file_path.lastIndexOf('\\'));
-    if (lastSlash === -1) continue;
-    const dir = file_path.slice(0, lastSlash);
-    const base = file_path.slice(lastSlash + 1);
-    if (!dirMap.has(dir)) dirMap.set(dir, new Set());
-    dirMap.get(dir)!.add(base);
-  }
-
-  const dirs = [...dirMap.keys()];
-  const pairs: MirroredDirPair[] = [];
-
-  // Compare each pair of directories
-  for (let i = 0; i < dirs.length; i++) {
-    for (let j = i + 1; j < dirs.length; j++) {
-      const dirA = dirs[i];
-      const dirB = dirs[j];
-      const setA = dirMap.get(dirA)!;
-      const setB = dirMap.get(dirB)!;
-
-      // Only compare directories that share a parent OR one is a suffix of the other
-      const parentA = dirA.slice(0, Math.max(dirA.lastIndexOf('/'), dirA.lastIndexOf('\\')));
-      const parentB = dirB.slice(0, Math.max(dirB.lastIndexOf('/'), dirB.lastIndexOf('\\')));
-      const relatedDirs = parentA === parentB
-        || dirA.endsWith(dirB)
-        || dirB.endsWith(dirA)
-        || dirA.includes(dirB)
-        || dirB.includes(dirA);
-      if (!relatedDirs) continue;
-
-      // Compute Jaccard similarity
-      const shared: string[] = [];
-      for (const name of setA) {
-        if (setB.has(name)) shared.push(name);
-      }
-      const union = setA.size + setB.size - shared.length;
-      if (union === 0) continue;
-      const similarity = shared.length / union;
-
-      if (similarity >= minSimilarity) {
-        pairs.push({
-          dirA,
-          dirB,
-          similarity,
-          sharedFileNames: shared.sort(),
-          uniqueToA: setA.size - shared.length,
-          uniqueToB: setB.size - shared.length,
-        });
-      }
-    }
-  }
-
-  // Sort by similarity descending
-  pairs.sort((a, b) => b.similarity - a.similarity);
-
-  return {
-    pairs,
-    totalDirsAnalyzed: dirs.length,
-  };
-}
-
-export interface MirroredDirResult {
-  mirrored: MirroredDirPair[];
-  remaining: CloneFamily[];
-}
-
-export function detectMirroredFamilies(
-  families: CloneFamily[],
-  root: string,
-): MirroredDirResult {
-  const normalizedRoot = root.replace(/\\/g, '/').replace(/\/$/, '');
-
-  function dirOf(filePath: string): string {
-    const normalized = filePath.replace(/\\/g, '/');
-    const rel = normalized.startsWith(normalizedRoot + '/')
-      ? normalized.slice(normalizedRoot.length + 1)
-      : normalized;
-    const lastSlash = rel.lastIndexOf('/');
-    return lastSlash === -1 ? '' : rel.slice(0, lastSlash);
-  }
-
-  function baseName(filePath: string): string {
-    const normalized = filePath.replace(/\\/g, '/');
-    return normalized.slice(normalized.lastIndexOf('/') + 1);
-  }
-
-  const mirrored: MirroredDirPair[] = [];
-  const remainingIndices = new Set<number>(families.map((_, i) => i));
-
-  for (let i = 0; i < families.length; i++) {
-    for (let j = i + 1; j < families.length; j++) {
-      if (!remainingIndices.has(i) || !remainingIndices.has(j)) continue;
-
-      const fa = families[i];
-      const fb = families[j];
-
-      // Single pass: extract dir and basename together to avoid two separate .map() iterations
-      let firstDirA: string | undefined;
-      let singleDirA = true;
-      let firstDirB: string | undefined;
-      let singleDirB = true;
-      const namesA = new Set<string>();
-      const namesB = new Set<string>();
-      for (const f of fa.files) {
-        const d = dirOf(f);
-        if (firstDirA === undefined) firstDirA = d;
-        else if (d !== firstDirA) { singleDirA = false; }
-        namesA.add(baseName(f));
-      }
-      for (const f of fb.files) {
-        const d = dirOf(f);
-        if (firstDirB === undefined) firstDirB = d;
-        else if (d !== firstDirB) { singleDirB = false; }
-        namesB.add(baseName(f));
-      }
-
-      if (!singleDirA || !singleDirB) continue;
-
-      const dirA = firstDirA!;
-      const dirB = firstDirB!;
-
-      const shared: string[] = [];
-      for (const n of namesA) {
-        if (namesB.has(n)) shared.push(n);
-      }
-      const union = namesA.size + namesB.size - shared.length;
-      if (union === 0) continue;
-      const similarity = shared.length / union;
-
-      if (similarity >= 0.5) {
-        mirrored.push({
-          dirA,
-          dirB,
-          similarity,
-          sharedFileNames: shared.sort(),
-          uniqueToA: namesA.size - shared.length,
-          uniqueToB: namesB.size - shared.length,
-        });
-        remainingIndices.delete(i);
-        remainingIndices.delete(j);
-      }
-    }
-  }
-
-  mirrored.sort((a, b) => b.similarity - a.similarity);
-
-  const remaining: CloneFamily[] = [];
-  for (const i of remainingIndices) remaining.push(families[i]);
-
-  return { mirrored, remaining };
-}
-
-/**
- * Format a MirroredDirsReport as structured text for LLM consumption.
- */
-export function formatMirroredDirs(report: MirroredDirsReport): string {
-  if (report.pairs.length === 0) {
-    return `No mirrored directories found (${report.totalDirsAnalyzed} dirs analyzed).`;
-  }
-  const lines: string[] = [
-    `Mirrored directories: ${report.pairs.length} pair(s) of ${report.totalDirsAnalyzed} analyzed`,
-    '',
-  ];
-  for (const p of report.pairs) {
-    lines.push(
-      `  ${p.dirA} <-> ${p.dirB}  similarity=${(p.similarity * 100).toFixed(0)}%  shared=${p.sharedFileNames.length}  uniqueA=${p.uniqueToA}  uniqueB=${p.uniqueToB}`,
-    );
-  }
-  return lines.join('\n');
-}

package/src/graph/narrowing.ts

@@ -1,92 +0,0 @@
-export interface AccessedMembers {
-  members: Set<string>;
-  hasNamespaceAccess: boolean;
-}
-
-export function isUnusedImportBinding(
-  importedName: string,
-  accessedMembers: Set<string>,
-): boolean {
-  return !accessedMembers.has(importedName);
-}
-
-export function extractAccessedMembers(usages: string[]): AccessedMembers {
-  const members = new Set<string>();
-  let hasNamespaceAccess = false;
-
-  for (const usage of usages) {
-    const dotIdx = usage.indexOf('.');
-    if (dotIdx === -1) {
-      hasNamespaceAccess = true;
-    } else {
-      const member = usage.slice(dotIdx + 1);
-      if (member) members.add(member);
-    }
-  }
-
-  return { members, hasNamespaceAccess };
-}
-
-export function markAllExportsReferenced(exports: string[]): Set<string> {
-  return new Set(exports);
-}
-
-export function markMemberExportsReferenced(
-  exports: string[],
-  accessed: AccessedMembers,
-): Set<string> {
-  if (accessed.hasNamespaceAccess) {
-    return new Set(exports);
-  }
-  const result = new Set<string>();
-  for (const exp of exports) {
-    if (accessed.members.has(exp)) {
-      result.add(exp);
-    }
-  }
-  return result;
-}
-
-export interface NarrowingReport {
-  filePath: string;
-  totalExports: number;
-  referencedExports: string[];
-  unusedExports: string[];
-}
-
-/**
- * Given a file's exports and the accessed members from all import sites,
- * return a report of which exports are unused.
- */
-export function filterUnusedExports(
-  filePath: string,
-  exports: string[],
-  accessed: AccessedMembers,
-): NarrowingReport {
-  const referenced = markMemberExportsReferenced(exports, accessed);
-  const unusedExports: string[] = [];
-  for (const exp of exports) {
-    if (!referenced.has(exp)) unusedExports.push(exp);
-  }
-  return {
-    filePath,
-    totalExports: exports.length,
-    referencedExports: Array.from(referenced),
-    unusedExports,
-  };
-}
-
-/**
- * Format narrowing reports as structured text for LLM dead-import diagnostics.
- */
-export function formatNarrowingReport(reports: NarrowingReport[]): string {
-  const withUnused = reports.filter(r => r.unusedExports.length > 0);
-  if (withUnused.length === 0) return 'No unused exports found.';
-
-  const lines: string[] = [`Unused exports in ${withUnused.length} file(s):`, ''];
-  for (const r of withUnused) {
-    lines.push(`  ${r.filePath} (${r.unusedExports.length}/${r.totalExports} unused)`);
-    for (const exp of r.unusedExports) lines.push(`    - ${exp}`);
-  }
-  return lines.join('\n');
-}