@monoes/monograph 1.1.0 → 1.2.0

package/src/graph/node-types.ts

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

@@ -0,0 +1,114 @@
+/**
+ * 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)) {
+      const canonical = normToId.get(normalizeId(src));
+      if (canonical) {
+        src = canonical;
+        remapped = true;
+      }
+    }
+
+    if (!nodeIds.has(tgt)) {
+      const canonical = normToId.get(normalizeId(tgt));
+      if (canonical) {
+        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 };
+}

package/src/graph/pagerank.ts

@@ -0,0 +1,88 @@
+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;
+}
+
+/**
+ * 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.
+ *
+ * @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 nodeRows = db.prepare('SELECT id FROM nodes').all() as { id: string }[];
+  const edgeRows = db.prepare('SELECT source_id, target_id FROM edges').all() as {
+    source_id: string;
+    target_id: string;
+  }[];
+
+  if (nodeRows.length === 0) return new Map();
+
+  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]);
+  }
+  return result;
+}

package/src/graph/prune.ts

@@ -0,0 +1,19 @@
+import type { MonographDb } from '../storage/db.js';
+
+/**
+ * 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;
+}

package/src/graph/re-exports/propagate.ts

@@ -0,0 +1,95 @@
+import type { ModuleNode } from '../node-types.js';
+
+export interface Edge {
+  sourceIdx: number;
+  targetIdx: number;
+  importedName?: string;
+  exportedName?: string;
+  isTypeOnly: boolean;
+}
+
+export function propagateStarReExport(
+  modules: ModuleNode[],
+  edges: Edge[],
+  edgesByTarget: Map<number, number[]>,
+  barrelId: number,
+  barrelIdx: number,
+  sourceIdx: number,
+  entryStarTargets: Set<number>,
+): boolean {
+  const barrel = modules[barrelIdx];
+  const source = modules[sourceIdx];
+  const before = barrel.exports.length;
+
+  const existingNames = new Set(barrel.exports.map(e => e.name));
+
+  for (const sym of source.exports) {
+    if (!existingNames.has(sym.name)) {
+      barrel.exports.push({ ...sym, isReExport: true });
+      existingNames.add(sym.name);
+    }
+  }
+
+  const changed = barrel.exports.length > before;
+
+  if (changed && entryStarTargets.has(barrelId)) {
+    const upstreamEdgeIndices = edgesByTarget.get(barrelIdx) ?? [];
+    for (const ei of upstreamEdgeIndices) {
+      const edge = edges[ei];
+      if (edge.importedName === undefined) {
+        propagateStarReExport(
+          modules,
+          edges,
+          edgesByTarget,
+          modules[edge.targetIdx].fileId,
+          edge.targetIdx,
+          barrelIdx,
+          entryStarTargets,
+        );
+      }
+    }
+  }
+
+  return changed;
+}
+
+export function propagateNamedReExport(
+  modules: ModuleNode[],
+  barrelId: number,
+  barrelIdx: number,
+  sourceIdx: number,
+  importedName: string,
+  exportedName: string,
+  existingRefs: Set<number>,
+): boolean {
+  const source = modules[sourceIdx];
+  const barrel = modules[barrelIdx];
+
+  const sourceSym = source.exports.find(e => e.name === importedName);
+  if (!sourceSym) return false;
+
+  const existing = barrel.exports.find(e => e.name === exportedName);
+  if (existing) return false;
+
+  barrel.exports.push({
+    name: exportedName,
+    isType: sourceSym.isType,
+    isReExport: true,
+    line: sourceSym.line,
+  });
+
+  for (const refId of existingRefs) {
+    const refIdx = modules.findIndex(m => m.fileId === refId);
+    if (refIdx !== -1) {
+      const refMod = modules[refIdx];
+      const alreadyRefs = refMod.references.some(
+        r => r.name === exportedName && r.fromFile === barrel.filePath,
+      );
+      if (!alreadyRefs) {
+        refMod.references.push({ name: exportedName, kind: 'Unknown', fromFile: barrel.filePath });
+      }
+    }
+  }
+
+  return true;
+}

package/src/graph/reachability.ts

@@ -0,0 +1,99 @@
+import { ModuleNode, ModuleNodeFlags, setFlag } from './node-types.js';
+
+export interface ReachabilityOptions {
+  runtimeEntries?: Set<number>;
+  testEntries?: Set<number>;
+}
+
+function bfsReachable(
+  nodes: Map<number, ModuleNode>,
+  edges: Map<number, number[]>,
+  entryPoints: number[],
+): Set<number> {
+  const visited = new Set<number>();
+  const queue: number[] = [];
+
+  for (const ep of entryPoints) {
+    if (nodes.has(ep) && !visited.has(ep)) {
+      visited.add(ep);
+      queue.push(ep);
+    }
+  }
+
+  let i = 0;
+  while (i < queue.length) {
+    const current = queue[i++];
+    const neighbors = edges.get(current) ?? [];
+    for (const neighbor of neighbors) {
+      if (!visited.has(neighbor) && nodes.has(neighbor)) {
+        visited.add(neighbor);
+        queue.push(neighbor);
+      }
+    }
+  }
+
+  return visited;
+}
+
+function setsEqual(a: Set<number>, b: Set<number>): boolean {
+  if (a.size !== b.size) return false;
+  for (const v of a) {
+    if (!b.has(v)) return false;
+  }
+  return true;
+}
+
+export function markReachable(
+  nodes: Map<number, ModuleNode>,
+  edges: Map<number, number[]>,
+  entryPoints: number[],
+  opts?: ReachabilityOptions,
+): void {
+  const entrySet = new Set(entryPoints);
+  const visited = bfsReachable(nodes, edges, entryPoints);
+
+  const runtimeEntries = opts?.runtimeEntries;
+  const testEntries = opts?.testEntries;
+
+  const runtimeSame = runtimeEntries === undefined || setsEqual(runtimeEntries, entrySet);
+  const runtimeVisited = runtimeSame
+    ? null
+    : bfsReachable(nodes, edges, [...(runtimeEntries ?? [])]);
+
+  const testVisited =
+    !testEntries || testEntries.size === 0
+      ? null
+      : bfsReachable(nodes, edges, [...testEntries]);
+
+  for (const [id, node] of nodes) {
+    if (visited.has(id)) {
+      setFlag(node, ModuleNodeFlags.REACHABLE);
+    }
+    if (runtimeVisited ? runtimeVisited.has(id) : visited.has(id)) {
+      setFlag(node, ModuleNodeFlags.RUNTIME_REACHABLE);
+    }
+    if (testVisited?.has(id)) {
+      setFlag(node, ModuleNodeFlags.TEST_REACHABLE);
+    }
+  }
+}
+
+export function collectReachable(nodes: Map<number, ModuleNode>): Set<number> {
+  const result = new Set<number>();
+  for (const [id, node] of nodes) {
+    if ((node.flags & ModuleNodeFlags.REACHABLE) !== 0) {
+      result.add(id);
+    }
+  }
+  return result;
+}
+
+export function collectUnreachable(
+  nodes: Map<number, ModuleNode>,
+  allFileIds: number[],
+): number[] {
+  return allFileIds.filter(id => {
+    const node = nodes.get(id);
+    return !node || (node.flags & ModuleNodeFlags.REACHABLE) === 0;
+  });
+}

package/src/graph/regex-search.ts

@@ -0,0 +1,195 @@
+import type { MonographNode, MonographEdge } from '../types.js';
+import type { MonographDb } from '../storage/db.js';
+
+// ── Node regex search ──────────────────────────────────────────────────────────
+
+export interface RegexNodeMatch {
+  node: MonographNode;
+  /** Which field of the node matched. */
+  field: 'name' | 'filePath' | 'language' | 'label';
+}
+
+/**
+ * Search nodes whose name, filePath, language, or label matches the given
+ * regular expression.
+ *
+ * @param db      - The MonographDb instance.
+ * @param pattern - A RegExp (or a string that will be compiled to one).
+ * @param fields  - Which fields to test; default: ['name', 'filePath'].
+ */
+export function regexSearchNodes(
+  db: MonographDb,
+  pattern: RegExp | string,
+  fields: Array<'name' | 'filePath' | 'language' | 'label'> = ['name', 'filePath'],
+): RegexNodeMatch[] {
+  const re = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+
+  const rows = db.prepare(
+    `SELECT id, label, name, norm_label, file_path, start_line, end_line,
+            community_id, is_exported, language, properties
+     FROM nodes`,
+  ).all() as {
+    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;
+  }[];
+
+  const results: RegexNodeMatch[] = [];
+
+  for (const r of rows) {
+    const node: MonographNode = {
+      id: r.id,
+      label: r.label as MonographNode['label'],
+      name: r.name,
+      normLabel: r.norm_label,
+      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,
+    };
+
+    for (const field of fields) {
+      const value =
+        field === 'name' ? r.name :
+        field === 'filePath' ? (r.file_path ?? '') :
+        field === 'language' ? (r.language ?? '') :
+        r.label;
+
+      if (value && re.test(value)) {
+        results.push({ node, field });
+        break; // report once per node even if multiple fields match
+      }
+    }
+  }
+
+  return results;
+}
+
+// ── Edge regex search ──────────────────────────────────────────────────────────
+
+export interface RegexEdgeMatch {
+  edge: MonographEdge;
+  /** Which field of the edge matched. */
+  field: 'relation' | 'confidence' | 'reason';
+}
+
+/**
+ * Search edges whose relation, confidence, or reason matches the given
+ * regular expression.
+ *
+ * @param db      - The MonographDb instance.
+ * @param pattern - A RegExp (or a string that will be compiled to one).
+ * @param fields  - Which fields to test; default: ['relation', 'reason'].
+ */
+export function regexSearchEdges(
+  db: MonographDb,
+  pattern: RegExp | string,
+  fields: Array<'relation' | 'confidence' | 'reason'> = ['relation', 'reason'],
+): RegexEdgeMatch[] {
+  const re = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+
+  const rows = db.prepare(
+    `SELECT id, source_id, target_id, relation, confidence, confidence_score, reason
+     FROM edges`,
+  ).all() as {
+    id: string;
+    source_id: string;
+    target_id: string;
+    relation: string;
+    confidence: string;
+    confidence_score: number;
+    reason: string | null;
+  }[];
+
+  const results: RegexEdgeMatch[] = [];
+
+  for (const r of rows) {
+    const edge: MonographEdge = {
+      id: r.id,
+      sourceId: r.source_id,
+      targetId: r.target_id,
+      relation: r.relation as MonographEdge['relation'],
+      confidence: r.confidence as MonographEdge['confidence'],
+      confidenceScore: r.confidence_score,
+      reason: r.reason ?? undefined,
+    };
+
+    for (const field of fields) {
+      const value =
+        field === 'relation' ? r.relation :
+        field === 'confidence' ? r.confidence :
+        (r.reason ?? '');
+
+      if (value && re.test(value)) {
+        results.push({ edge, field });
+        break;
+      }
+    }
+  }
+
+  return results;
+}
+
+// ── In-memory variants ─────────────────────────────────────────────────────────
+
+export function regexSearchNodesInMemory(
+  nodes: MonographNode[],
+  pattern: RegExp | string,
+  fields: Array<'name' | 'filePath' | 'language' | 'label'> = ['name', 'filePath'],
+): RegexNodeMatch[] {
+  const re = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+  const results: RegexNodeMatch[] = [];
+
+  for (const node of nodes) {
+    for (const field of fields) {
+      const value =
+        field === 'name' ? node.name :
+        field === 'filePath' ? (node.filePath ?? '') :
+        field === 'language' ? (node.language ?? '') :
+        node.label;
+
+      if (value && re.test(value)) {
+        results.push({ node, field });
+        break;
+      }
+    }
+  }
+
+  return results;
+}
+
+export function regexSearchEdgesInMemory(
+  edges: MonographEdge[],
+  pattern: RegExp | string,
+  fields: Array<'relation' | 'confidence' | 'reason'> = ['relation', 'reason'],
+): RegexEdgeMatch[] {
+  const re = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+  const results: RegexEdgeMatch[] = [];
+
+  for (const edge of edges) {
+    for (const field of fields) {
+      const value =
+        field === 'relation' ? edge.relation :
+        field === 'confidence' ? edge.confidence :
+        (edge.reason ?? '');
+
+      if (value && re.test(value)) {
+        results.push({ edge, field });
+        break;
+      }
+    }
+  }
+
+  return results;
+}