@monoes/monograph 1.5.6 → 1.5.7

package/src/graph/node-search.ts

@@ -1,201 +0,0 @@
-import Database from 'better-sqlite3';
-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,
-  };
-}
-
-// ── Prepared statement cache ───────────────────────────────────────────────────
-// Keyed by a fingerprint of which conditions are active (not by param values),
-// so the same query shape reuses the compiled statement across calls.
-
-// WeakMap ensures the cache is garbage-collected when the DB object is released.
-const stmtCache = new WeakMap<object, Map<string, Database.Statement>>();
-
-function getCachedStmt(
-  db: MonographDb,
-  key: string,
-  buildSql: () => string,
-): Database.Statement {
-  let dbCache = stmtCache.get(db);
-  if (!dbCache) {
-    dbCache = new Map();
-    stmtCache.set(db, dbCache);
-  }
-  let stmt = dbCache.get(key);
-  if (!stmt) {
-    stmt = db.prepare(buildSql());
-    dbCache.set(key, stmt);
-  }
-  return stmt;
-}
-
-// ── DB-backed search ───────────────────────────────────────────────────────────
-
-/**
- * Search nodes by structured property criteria.
- * All supplied criteria are combined with AND.
- *
- * Prepared statements are cached per-DB keyed by the active condition set so
- * repeated calls with the same filter shape reuse the compiled statement.
- */
-export function searchNodesByProperty(
-  db: MonographDb,
-  options: NodeSearchOptions = {},
-): MonographNode[] {
-  const conditions: string[] = [];
-  const params: unknown[] = [];
-  // fingerprint encodes which conditions are active (not their values)
-  const fingerprint: string[] = [];
-
-  if (options.label) {
-    conditions.push('label = ?');
-    params.push(options.label);
-    fingerprint.push('lbl');
-  }
-
-  if (options.language) {
-    conditions.push('LOWER(language) = LOWER(?)');
-    params.push(options.language);
-    fingerprint.push('lang');
-  }
-
-  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}`);
-    fingerprint.push('ext');
-  }
-
-  if (options.filePath !== undefined) {
-    conditions.push("LOWER(file_path) LIKE LOWER(?)");
-    params.push(`%${options.filePath}%`);
-    fingerprint.push('fp');
-  }
-
-  if (options.isExported !== undefined) {
-    conditions.push('is_exported = ?');
-    params.push(options.isExported ? 1 : 0);
-    fingerprint.push('exp');
-  }
-
-  if (options.communityId !== undefined) {
-    conditions.push('community_id = ?');
-    params.push(options.communityId);
-    fingerprint.push('com');
-  }
-
-  const hasLimit = options.limit !== undefined;
-  if (hasLimit) fingerprint.push('lim');
-
-  const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
-  const limitClause = hasLimit ? `LIMIT ${Number(options.limit)}` : '';
-  const cacheKey = fingerprint.join(':') || 'all';
-
-  const stmt = getCachedStmt(
-    db,
-    cacheKey,
-    () => `SELECT id, label, name, norm_label, file_path, start_line, end_line,
-                      community_id, is_exported, language, properties
-               FROM nodes ${where} ${limitClause}`,
-  );
-
-  const rows = stmt.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;
-}

package/src/graph/node-types.ts

@@ -1,67 +0,0 @@
-export type ReferenceKind = 'Value' | 'Type' | 'Namespace' | 'Unknown';
-
-export interface ExportSymbol {
-  name: string;
-  isType: boolean;
-  isReExport: boolean;
-  line?: number;
-}
-
-export interface ReExportEdge {
-  fromFile: string;
-  toFile: string;
-  symbol?: string;
-  isNamespace: boolean;
-}
-
-export interface SymbolReference {
-  name: string;
-  kind: ReferenceKind;
-  fromFile: string;
-  line?: number;
-}
-
-export const ModuleNodeFlags = {
-  ENTRY_POINT: 1,
-  REACHABLE: 2,
-  RUNTIME_REACHABLE: 4,
-  TEST_REACHABLE: 8,
-  CJS_EXPORTS: 16,
-} as const;
-
-export interface ModuleNode {
-  fileId: number;
-  filePath: string;
-  flags: number;
-  exports: ExportSymbol[];
-  reExports: ReExportEdge[];
-  references: SymbolReference[];
-}
-
-export function isEntryPoint(node: ModuleNode): boolean {
-  return (node.flags & ModuleNodeFlags.ENTRY_POINT) !== 0;
-}
-
-export function isReachable(node: ModuleNode): boolean {
-  return (node.flags & ModuleNodeFlags.REACHABLE) !== 0;
-}
-
-export function isRuntimeReachable(node: ModuleNode): boolean {
-  return (node.flags & ModuleNodeFlags.RUNTIME_REACHABLE) !== 0;
-}
-
-export function isTestReachable(node: ModuleNode): boolean {
-  return (node.flags & ModuleNodeFlags.TEST_REACHABLE) !== 0;
-}
-
-export function hasCjsExports(node: ModuleNode): boolean {
-  return (node.flags & ModuleNodeFlags.CJS_EXPORTS) !== 0;
-}
-
-export function setFlag(node: ModuleNode, flag: number): void {
-  node.flags |= flag;
-}
-
-export function clearFlag(node: ModuleNode, flag: number): void {
-  node.flags &= ~flag;
-}

package/src/graph/normalize-id.ts

@@ -1,138 +0,0 @@
-/**
- * Normalized-ID edge reconciliation.
- *
- * Mirrors graphify's `_normalize_id` / `norm_to_id` logic:
- * when an LLM-generated edge endpoint ID does not exactly match any node ID
- * in the graph, we try a normalized form (lowercase, non-alphanumeric → '_').
- * This lets edges survive across minor casing / punctuation mismatches between
- * the AST extractor and the LLM.
- */
-
-// ── Core normaliser ────────────────────────────────────────────────────────────
-
-/**
- * Normalise an ID string the same way graphify's `_normalize_id` does.
- *
- * Replaces all runs of non-alphanumeric characters with a single underscore,
- * strips leading/trailing underscores, and lowercases the result.
- *
- * @example
- * normalizeId('Session_ValidateToken') // 'session_validatetoken'
- * normalizeId('My-Class::method')      // 'my_class_method'
- */
-export function normalizeId(id: string): string {
-  return id
-    .replace(/[^a-zA-Z0-9]+/g, '_')
-    .replace(/^_+|_+$/g, '')
-    .toLowerCase();
-}
-
-// ── Lookup map builder ─────────────────────────────────────────────────────────
-
-/**
- * Build a Map from normalised id → canonical id from a set of known node ids.
- * Used during edge reconciliation to remap mismatched endpoints.
- *
- * @param nodeIds - The authoritative set of node ids.
- * @returns Map of `normalizeId(id)` → original `id`.
- */
-export function buildNormToIdMap(nodeIds: Iterable<string>): Map<string, string> {
-  const map = new Map<string, string>();
-  for (const id of nodeIds) {
-    map.set(normalizeId(id), id);
-  }
-  return map;
-}
-
-// ── Edge reconciliation ────────────────────────────────────────────────────────
-
-export interface RawEdge {
-  source: string;
-  target: string;
-  [key: string]: unknown;
-}
-
-export interface ReconciliationResult {
-  /** Edges whose endpoints were resolved (possibly with normalization). */
-  resolved: RawEdge[];
-  /** Edges that could not be matched even after normalization. */
-  dangling: RawEdge[];
-  /** Number of edges that required normalization to resolve. */
-  remappedCount: number;
-}
-
-/**
- * Reconcile a list of raw edges against a known set of node ids.
- *
- * For each edge:
- * 1. If both endpoints are in `nodeIds` → resolved as-is.
- * 2. If an endpoint is missing, try `normalizeId(endpoint)` lookup.
- * 3. If still missing → moved to `dangling` (not added to the graph).
- *
- * Mutates `source`/`target` fields on resolved edges in-place when remapping.
- */
-export function reconcileEdges(
-  edges: RawEdge[],
-  nodeIds: Set<string>,
-): ReconciliationResult {
-  const normToId = buildNormToIdMap(nodeIds);
-
-  const resolved: RawEdge[] = [];
-  const dangling: RawEdge[] = [];
-  let remappedCount = 0;
-
-  for (const edge of edges) {
-    let src = edge.source;
-    let tgt = edge.target;
-    let remapped = false;
-
-    if (!nodeIds.has(src)) {
-      // Cache normalizeId result to avoid calling it twice for the same string
-      const canonical = normToId.get(normalizeId(src));
-      if (canonical !== undefined) {
-        src = canonical;
-        remapped = true;
-      }
-    }
-
-    if (!nodeIds.has(tgt)) {
-      const canonical = normToId.get(normalizeId(tgt));
-      if (canonical !== undefined) {
-        tgt = canonical;
-        remapped = true;
-      }
-    }
-
-    if (nodeIds.has(src) && nodeIds.has(tgt)) {
-      resolved.push({ ...edge, source: src, target: tgt });
-      if (remapped) remappedCount++;
-    } else {
-      dangling.push(edge);
-    }
-  }
-
-  return { resolved, dangling, remappedCount };
-}
-
-/**
- * Format a ReconciliationResult as structured text for LLM consumption.
- */
-export function formatReconciliationResult(result: ReconciliationResult): string {
-  const total = result.resolved.length + result.dangling.length;
-  const lines: string[] = [
-    `Edge reconciliation: ${result.resolved.length}/${total} resolved, ${result.remappedCount} remapped, ${result.dangling.length} dangling`,
-  ];
-  if (result.dangling.length > 0) {
-    lines.push('');
-    lines.push('Dangling edges (unresolvable endpoints):');
-    const limit = Math.min(result.dangling.length, 20);
-    for (let i = 0; i < limit; i++) {
-      const e = result.dangling[i]!;
-      lines.push(`  ${e.source} -> ${e.target}`);
-    }
-    if (result.dangling.length > limit) {
-      lines.push(`  ... and ${result.dangling.length - limit} more`);
-    }
-  }
-  return lines.join('\n');
-}

package/src/graph/pagerank.ts

@@ -1,165 +0,0 @@
-import Database from 'better-sqlite3';
-import type { MonographDb } from '../storage/db.js';
-
-export interface PageRankOptions {
-  /** Damping factor (probability of following an edge). Default: 0.85 */
-  dampingFactor?: number;
-  /** Maximum number of power-iteration steps. Default: 100 */
-  maxIterations?: number;
-  /** Convergence threshold (L1 norm delta). Default: 1e-6 */
-  tolerance?: number;
-}
-
-// ---------------------------------------------------------------------------
-// Per-DB statement cache — avoids recompiling SQL on every pageRank() call.
-// ---------------------------------------------------------------------------
-interface StmtCache {
-  selectNodes: Database.Statement;
-  selectEdges: Database.Statement;
-}
-
-const _stmtCache = new Map<string, StmtCache>();
-
-function getStmts(db: MonographDb): StmtCache {
-  const key = (db as unknown as { name: string }).name ?? '__default__';
-  let cache = _stmtCache.get(key);
-  if (!cache) {
-    if (_stmtCache.size >= MAX_STMT_CACHE) {
-      const oldest = _stmtCache.keys().next().value!;
-      _stmtCache.delete(oldest);
-    }
-    cache = {
-      selectNodes: db.prepare('SELECT id FROM nodes'),
-      selectEdges: db.prepare('SELECT source_id, target_id FROM edges'),
-    };
-    _stmtCache.set(key, cache);
-  }
-  return cache;
-}
-
-// ---------------------------------------------------------------------------
-// Result cache — avoids re-running power iteration when the graph hasn't
-// changed. Keyed by (dbName, nodeCount, edgeCount) with a 5-second TTL.
-// ---------------------------------------------------------------------------
-const PAGERANK_CACHE_TTL_MS = 5_000;
-const MAX_RESULT_CACHE = 50;
-const MAX_STMT_CACHE = 20;
-
-interface PageRankCacheEntry {
-  result: Map<string, number>;
-  expiresAt: number;
-}
-
-const _resultCache = new Map<string, PageRankCacheEntry>();
-
-function resultCacheKey(db: MonographDb, nodeCount: number, edgeCount: number): string {
-  const name = (db as unknown as { name: string }).name ?? '__default__';
-  return `${name}:${nodeCount}:${edgeCount}`;
-}
-
-/**
- * Evict cached statements and results for a given DB instance (call after writes).
- */
-export function invalidatePageRankCache(db: MonographDb): void {
-  const key = (db as unknown as { name: string }).name ?? '__default__';
-  _stmtCache.delete(key);
-  // Purge all result-cache entries for this DB (they have the name as prefix)
-  for (const k of _resultCache.keys()) {
-    if (k.startsWith(`${key}:`)) _resultCache.delete(k);
-  }
-}
-
-/**
- * Compute PageRank scores for all nodes using power iteration.
- *
- * Each node's score is initialized to 1/N (so scores sum to 1).
- * After convergence the scores still sum to ~1 (standard normalized PageRank).
- * Dangling nodes (out-degree 0) distribute their rank equally to all nodes.
- *
- * Results are cached for 5 seconds when the graph's node+edge counts are
- * unchanged, making repeated calls (e.g. during context preloading) free.
- *
- * @param db - The MonographDb instance
- * @param options - Optional tuning parameters
- * @returns Map of nodeId → PageRank score
- */
-export function pageRank(db: MonographDb, options: PageRankOptions = {}): Map<string, number> {
-  const { dampingFactor = 0.85, maxIterations = 100, tolerance = 1e-6 } = options;
-
-  const stmts = getStmts(db);
-  const nodeRows = stmts.selectNodes.all() as { id: string }[];
-  const edgeRows = stmts.selectEdges.all() as {
-    source_id: string;
-    target_id: string;
-  }[];
-
-  if (nodeRows.length === 0) return new Map();
-
-  // Check result cache before running power iteration
-  const cacheKey = resultCacheKey(db, nodeRows.length, edgeRows.length);
-  const now = Date.now();
-  const cached = _resultCache.get(cacheKey);
-  if (cached && now < cached.expiresAt) return cached.result;
-
-  const nodes = nodeRows.map(r => r.id);
-  const n = nodes.length;
-  const nodeIndex = new Map<string, number>();
-  nodes.forEach((id, i) => nodeIndex.set(id, i));
-
-  // Build adjacency: outEdges[i] = list of target indices
-  const outEdges: number[][] = nodes.map(() => []);
-  const inEdges: number[][] = nodes.map(() => []);
-
-  for (const { source_id: src, target_id: tgt } of edgeRows) {
-    if (src === tgt) continue;
-    const si = nodeIndex.get(src);
-    const ti = nodeIndex.get(tgt);
-    if (si === undefined || ti === undefined) continue;
-    outEdges[si].push(ti);
-    inEdges[ti].push(si);
-  }
-
-  // Power iteration — initialize to uniform 1/N so scores sum to 1
-  let scores = new Float64Array(n).fill(1 / n);
-  const dangling1OverN = (1 - dampingFactor) / n;
-
-  for (let iter = 0; iter < maxIterations; iter++) {
-    const newScores = new Float64Array(n);
-
-    // Collect dangling node contribution
-    let danglingSum = 0;
-    for (let i = 0; i < n; i++) {
-      if (outEdges[i].length === 0) danglingSum += scores[i];
-    }
-    const danglingContrib = (dampingFactor * danglingSum) / n;
-
-    for (let i = 0; i < n; i++) {
-      let incoming = 0;
-      for (const j of inEdges[i]) {
-        incoming += scores[j] / outEdges[j].length;
-      }
-      newScores[i] = dangling1OverN + dampingFactor * incoming + danglingContrib;
-    }
-
-    // Check convergence
-    let delta = 0;
-    for (let i = 0; i < n; i++) {
-      delta += Math.abs(newScores[i] - scores[i]);
-    }
-    scores = newScores;
-    if (delta < tolerance) break;
-  }
-
-  const result = new Map<string, number>();
-  for (let i = 0; i < n; i++) {
-    result.set(nodes[i], scores[i]);
-  }
-
-  if (_resultCache.size >= MAX_RESULT_CACHE) {
-    const oldest = _resultCache.keys().next().value!;
-    _resultCache.delete(oldest);
-  }
-  _resultCache.set(cacheKey, { result, expiresAt: now + PAGERANK_CACHE_TTL_MS });
-
-  return result;
-}

package/src/graph/prune.ts

@@ -1,95 +0,0 @@
-import type { MonographDb } from '../storage/db.js';
-
-export interface PruneResult {
-  danglingEdgesRemoved: number;
-  orphanNodesRemoved: number;
-  staleFileNodesRemoved: number;
-}
-
-/**
- * Remove edges whose source or target node does not exist in the nodes table.
- *
- * @param db - The MonographDb instance (better-sqlite3 Database)
- * @returns The number of dangling edges pruned
- */
-export function pruneDanglingEdges(db: MonographDb): number {
-  // Single-statement DELETE avoids fetching all dangling IDs then re-binding them
-  // as SQL variables (which would fail when edge count exceeds SQLITE_MAX_VARIABLE_NUMBER).
-  const result = db.prepare(`
-    DELETE FROM edges
-    WHERE NOT EXISTS (SELECT 1 FROM nodes n WHERE n.id = source_id)
-       OR NOT EXISTS (SELECT 1 FROM nodes n WHERE n.id = target_id)
-  `).run();
-
-  return result.changes;
-}
-
-/**
- * Remove non-File nodes that have no incoming or outgoing edges.
- * Leaves File nodes in place so they can still be queried even if isolated.
- *
- * @param db - The MonographDb instance
- * @returns Number of orphan nodes removed
- */
-export function pruneOrphanNodes(db: MonographDb): number {
-  const result = db.prepare(`
-    DELETE FROM nodes
-    WHERE label != 'File'
-      AND NOT EXISTS (SELECT 1 FROM edges WHERE source_id = nodes.id OR target_id = nodes.id)
-  `).run();
-  return result.changes;
-}
-
-/**
- * Remove File nodes whose file_path no longer exists on disk.
- * Also cascades to remove any edges connected to those nodes (via pruneDanglingEdges).
- *
- * @param db - The MonographDb instance
- * @param existingPaths - Set of file paths that currently exist on disk
- * @returns Number of stale File nodes removed (call pruneDanglingEdges after to clean edges)
- */
-export function pruneStaleFileNodes(db: MonographDb, existingPaths: Set<string>): number {
-  const staleRows = db.prepare(
-    `SELECT id, file_path FROM nodes WHERE label = 'File' AND file_path IS NOT NULL`,
-  ).all() as { id: string; file_path: string }[];
-
-  let removed = 0;
-  const deleteStmt = db.prepare(`DELETE FROM nodes WHERE id = ?`);
-  const tx = db.transaction(() => {
-    for (const row of staleRows) {
-      if (!existingPaths.has(row.file_path)) {
-        deleteStmt.run(row.id);
-        removed++;
-      }
-    }
-  });
-  tx();
-  return removed;
-}
-
-/**
- * Run a full prune pass: dangling edges → orphan nodes → stale file nodes.
- * Optionally pass existingPaths to also remove deleted-file nodes.
- */
-export function pruneAll(db: MonographDb, existingPaths?: Set<string>): PruneResult {
-  const danglingEdgesRemoved = pruneDanglingEdges(db);
-  const orphanNodesRemoved = pruneOrphanNodes(db);
-  const staleFileNodesRemoved = existingPaths ? pruneStaleFileNodes(db, existingPaths) : 0;
-  // A second dangling-edge pass cleans up any edges left by stale file node removal
-  if (staleFileNodesRemoved > 0) pruneDanglingEdges(db);
-  return { danglingEdgesRemoved, orphanNodesRemoved, staleFileNodesRemoved };
-}
-
-/**
- * Format a PruneResult as structured text for LLM consumption.
- */
-export function formatPruneResult(result: PruneResult): string {
-  const total = result.danglingEdgesRemoved + result.orphanNodesRemoved + result.staleFileNodesRemoved;
-  if (total === 0) return 'Prune pass: nothing to remove — graph is clean.';
-  return [
-    `Prune pass removed ${total} artifact(s):`,
-    `  dangling edges:    ${result.danglingEdgesRemoved}`,
-    `  orphan nodes:      ${result.orphanNodesRemoved}`,
-    `  stale file nodes:  ${result.staleFileNodesRemoved}`,
-  ].join('\n');
-}