@monoes/monograph 1.1.0 → 1.2.0

package/src/graph/maintainability.ts

@@ -0,0 +1,106 @@
+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 };
+  }
+
+  const results: MaintainabilityResult[] = [];
+
+  for (const node of nodes) {
+    const loc = Math.max(1, node.end_line - node.start_line + 1);
+
+    // Count in/out degree from edges table
+    const inDegreeRow = db.prepare(
+      'SELECT COUNT(*) as c FROM edges WHERE target_id = ?'
+    ).get(node.id) as { c: number };
+    const outDegreeRow = db.prepare(
+      'SELECT COUNT(*) as c FROM edges WHERE source_id = ?'
+    ).get(node.id) as { c: number };
+
+    const degree = inDegreeRow.c + outDegreeRow.c;
+    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);
+
+    // Store maintainabilityIndex back on the node's properties
+    const props = node.properties ? JSON.parse(node.properties) : {};
+    props.maintainabilityIndex = mi;
+    db.prepare('UPDATE nodes SET properties = ? WHERE id = ?').run(
+      JSON.stringify(props),
+      node.id
+    );
+
+    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,
+    });
+  }
+
+  // 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;
+
+  const lowMiCount = results.filter(r => r.mi < 65).length;
+  const criticalCount = results.filter(r => r.mi < 25).length;
+
+  return {
+    results,
+    averageMi: Math.round(averageMi * 100) / 100,
+    lowMiCount,
+    criticalCount,
+  };
+}

package/src/graph/merge.ts

@@ -0,0 +1,174 @@
+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

@@ -0,0 +1,171 @@
+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];
+
+      const dirsA = new Set(fa.files.map(dirOf));
+      const dirsB = new Set(fb.files.map(dirOf));
+
+      if (dirsA.size !== 1 || dirsB.size !== 1) continue;
+
+      const [dirA] = dirsA;
+      const [dirB] = dirsB;
+
+      if (dirA === dirB) continue;
+
+      const namesA = new Set(fa.files.map(baseName));
+      const namesB = new Set(fb.files.map(baseName));
+
+      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);
+
+  return {
+    mirrored,
+    remaining: [...remainingIndices].map(i => families[i]),
+  };
+}

package/src/graph/narrowing.ts

@@ -0,0 +1,48 @@
+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;
+}

package/src/graph/node-search.ts

@@ -0,0 +1,155 @@
+import type { MonographNode, NodeLabel } from '../types.js';
+import type { MonographDb } from '../storage/db.js';
+
+// ── Node property search options ───────────────────────────────────────────────
+
+export interface NodeSearchOptions {
+  /** Filter by node label (e.g. 'Function', 'Class'). */
+  label?: NodeLabel;
+  /** Filter by programming language (case-insensitive). */
+  language?: string;
+  /** Filter by file extension, e.g. '.ts', 'ts' (leading dot optional). */
+  fileExtension?: string;
+  /** Filter by file path substring (case-insensitive). */
+  filePath?: string;
+  /** Only return exported nodes. */
+  isExported?: boolean;
+  /** Only return nodes inside this community. */
+  communityId?: number;
+  /** Maximum number of results (default: no limit). */
+  limit?: number;
+}
+
+// ── Row → node mapper (mirrors subgraph.ts) ───────────────────────────────────
+
+function rowToNode(r: {
+  id: string;
+  label: string;
+  name: string;
+  norm_label?: string;
+  file_path: string | null;
+  start_line: number | null;
+  end_line: number | null;
+  community_id: number | null;
+  is_exported: number;
+  language: string | null;
+  properties: string | null;
+}): MonographNode {
+  return {
+    id: r.id,
+    label: r.label as NodeLabel,
+    name: r.name,
+    normLabel: r.norm_label ?? r.name.toLowerCase(),
+    filePath: r.file_path ?? undefined,
+    startLine: r.start_line ?? undefined,
+    endLine: r.end_line ?? undefined,
+    communityId: r.community_id ?? undefined,
+    isExported: r.is_exported === 1,
+    language: r.language ?? undefined,
+    properties: r.properties ? (JSON.parse(r.properties) as Record<string, unknown>) : undefined,
+  };
+}
+
+// ── DB-backed search ───────────────────────────────────────────────────────────
+
+/**
+ * Search nodes by structured property criteria.
+ * All supplied criteria are combined with AND.
+ */
+export function searchNodesByProperty(
+  db: MonographDb,
+  options: NodeSearchOptions = {},
+): MonographNode[] {
+  const conditions: string[] = [];
+  const params: unknown[] = [];
+
+  if (options.label) {
+    conditions.push('label = ?');
+    params.push(options.label);
+  }
+
+  if (options.language) {
+    conditions.push('LOWER(language) = LOWER(?)');
+    params.push(options.language);
+  }
+
+  if (options.fileExtension !== undefined) {
+    // Normalise: ensure leading dot
+    const ext = options.fileExtension.startsWith('.')
+      ? options.fileExtension
+      : `.${options.fileExtension}`;
+    conditions.push("file_path LIKE ?");
+    params.push(`%${ext}`);
+  }
+
+  if (options.filePath !== undefined) {
+    conditions.push("LOWER(file_path) LIKE LOWER(?)");
+    params.push(`%${options.filePath}%`);
+  }
+
+  if (options.isExported !== undefined) {
+    conditions.push('is_exported = ?');
+    params.push(options.isExported ? 1 : 0);
+  }
+
+  if (options.communityId !== undefined) {
+    conditions.push('community_id = ?');
+    params.push(options.communityId);
+  }
+
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+  const limitClause = options.limit !== undefined ? `LIMIT ${Number(options.limit)}` : '';
+  const sql = `SELECT id, label, name, norm_label, file_path, start_line, end_line,
+                      community_id, is_exported, language, properties
+               FROM nodes ${where} ${limitClause}`;
+
+  const rows = db.prepare(sql).all(...params) as Parameters<typeof rowToNode>[0][];
+  return rows.map(rowToNode);
+}
+
+// ── In-memory search ───────────────────────────────────────────────────────────
+
+/**
+ * Filter an already-loaded array of nodes in memory.
+ */
+export function searchNodesInMemory(
+  nodes: MonographNode[],
+  options: NodeSearchOptions = {},
+): MonographNode[] {
+  let result = nodes;
+
+  if (options.label) {
+    result = result.filter(n => n.label === options.label);
+  }
+
+  if (options.language) {
+    const lang = options.language.toLowerCase();
+    result = result.filter(n => n.language?.toLowerCase() === lang);
+  }
+
+  if (options.fileExtension !== undefined) {
+    const ext = options.fileExtension.startsWith('.')
+      ? options.fileExtension.toLowerCase()
+      : `.${options.fileExtension.toLowerCase()}`;
+    result = result.filter(n => n.filePath?.toLowerCase().endsWith(ext));
+  }
+
+  if (options.filePath !== undefined) {
+    const fp = options.filePath.toLowerCase();
+    result = result.filter(n => n.filePath?.toLowerCase().includes(fp));
+  }
+
+  if (options.isExported !== undefined) {
+    result = result.filter(n => n.isExported === options.isExported);
+  }
+
+  if (options.communityId !== undefined) {
+    result = result.filter(n => n.communityId === options.communityId);
+  }
+
+  if (options.limit !== undefined) {
+    result = result.slice(0, options.limit);
+  }
+
+  return result;
+}