@monoes/graph 1.0.0

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@monoes/graph",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Knowledge graph engine for monobrain — AST extraction, graph construction, community detection, and persistent codebase understanding",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/src/index.d.ts", "import": "./dist/src/index.js" }
+  },
+  "files": ["dist", "src"],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "graphology": "^0.25.4",
+    "graphology-communities-louvain": "^2.0.1",
+    "graphology-shortest-path": "^2.0.2",
+    "graphology-traversal": "^0.3.1",
+    "graphology-metrics": "^2.4.0",
+    "chokidar": "^3.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.1.4"
+  },
+  "optionalDependencies": {
+    "node-tree-sitter": "^0.22.4",
+    "tree-sitter-typescript": "^0.23.2",
+    "tree-sitter-javascript": "^0.23.1",
+    "tree-sitter-python": "^0.23.6",
+    "tree-sitter-go": "^0.23.4",
+    "tree-sitter-rust": "^0.23.2",
+    "tree-sitter-java": "^0.23.5",
+    "tree-sitter-c": "^0.23.4",
+    "tree-sitter-cpp": "^0.23.4",
+    "tree-sitter-ruby": "^0.23.1",
+    "tree-sitter-c-sharp": "^0.23.1"
+  },
+  "publishConfig": { "access": "public" }
+}

package/src/analyze.ts

@@ -0,0 +1,122 @@
+import type Graph from 'graphology';
+import type { GodNode, SurpriseEdge, GraphAnalysis, GraphStats, Confidence } from './types.js';
+
+/**
+ * Find the most connected nodes (god nodes) — core abstractions of the codebase.
+ * Sorted by total degree (in + out), descending.
+ */
+export function godNodes(graph: Graph, topN = 15): GodNode[] {
+  const nodes: GodNode[] = [];
+
+  graph.forEachNode((id, attrs) => {
+    nodes.push({
+      id,
+      label: (attrs.label as string) || id,
+      degree: graph.degree(id),
+      community: attrs.community as number | undefined,
+      sourceFile: (attrs.sourceFile as string) || '',
+      neighbors: graph
+        .neighbors(id)
+        .slice(0, 8)
+        .map((n) => (graph.getNodeAttribute(n, 'label') as string) || n),
+    });
+  });
+
+  return nodes.sort((a, b) => b.degree - a.degree).slice(0, topN);
+}
+
+/**
+ * Find surprising cross-community connections.
+ * An edge is surprising when its endpoints belong to different communities.
+ * Scored by the product of their degrees — high degree on both sides = high surprise.
+ */
+export function surprisingConnections(graph: Graph, topN = 20): SurpriseEdge[] {
+  const surprises: SurpriseEdge[] = [];
+
+  graph.forEachEdge((_, attrs, source, target) => {
+    const cu = graph.getNodeAttribute(source, 'community') as number | undefined;
+    const cv = graph.getNodeAttribute(target, 'community') as number | undefined;
+
+    if (cu !== undefined && cv !== undefined && cu !== cv) {
+      surprises.push({
+        from: (graph.getNodeAttribute(source, 'label') as string) || source,
+        fromCommunity: cu,
+        fromFile: (graph.getNodeAttribute(source, 'sourceFile') as string) || '',
+        to: (graph.getNodeAttribute(target, 'label') as string) || target,
+        toCommunity: cv,
+        toFile: (graph.getNodeAttribute(target, 'sourceFile') as string) || '',
+        relation: (attrs.relation as string) || '',
+        confidence: (attrs.confidence as Confidence) ?? 'AMBIGUOUS',
+        score: graph.degree(source) * graph.degree(target),
+      });
+    }
+  });
+
+  return surprises.sort((a, b) => b.score - a.score).slice(0, topN);
+}
+
+/**
+ * Compute high-level graph statistics.
+ */
+export function graphStats(graph: Graph, graphPath?: string): GraphStats {
+  const confidence: Record<string, number> = {};
+  const relations: Record<string, number> = {};
+  const fileTypes: Record<string, number> = {};
+  const commSet = new Set<number>();
+
+  graph.forEachEdge((_, attrs) => {
+    const c = (attrs.confidence as string) || 'UNKNOWN';
+    confidence[c] = (confidence[c] ?? 0) + 1;
+
+    const r = (attrs.relation as string) || 'unknown';
+    relations[r] = (relations[r] ?? 0) + 1;
+  });
+
+  graph.forEachNode((_, attrs) => {
+    const ft = (attrs.fileType as string) || 'unknown';
+    fileTypes[ft] = (fileTypes[ft] ?? 0) + 1;
+
+    const c = attrs.community as number | undefined;
+    if (c !== undefined) commSet.add(c);
+  });
+
+  const topRelations = Object.fromEntries(
+    Object.entries(relations)
+      .sort(([, a], [, b]) => b - a)
+      .slice(0, 10),
+  );
+
+  return {
+    nodes: graph.order,
+    edges: graph.size,
+    communities: commSet.size,
+    confidence: confidence as Record<Confidence, number>,
+    fileTypes,
+    topRelations,
+    isDirected: graph.type === 'directed',
+    graphPath,
+  };
+}
+
+/**
+ * Build a complete GraphAnalysis object from an annotated graph.
+ * Assumes community detection has already been run (nodes have `community` attribute).
+ */
+export function buildAnalysis(graph: Graph, graphPath?: string): GraphAnalysis {
+  // Reconstruct communities map from node attributes
+  const communities: Record<number, string[]> = {};
+  graph.forEachNode((id, attrs) => {
+    const c = attrs.community as number | undefined;
+    if (c !== undefined) {
+      if (!communities[c]) communities[c] = [];
+      communities[c].push(id);
+    }
+  });
+
+  return {
+    godNodes: godNodes(graph),
+    surprises: surprisingConnections(graph),
+    communities,
+    stats: graphStats(graph, graphPath),
+  };
+}

package/src/build.ts

@@ -0,0 +1,62 @@
+import Graph from 'graphology';
+import type { ExtractionResult } from './types.js';
+
+/**
+ * Build a graphology Graph from extracted nodes and edges.
+ * Deduplicates nodes by id, merges parallel edges with higher weight.
+ */
+export function buildGraph(extraction: ExtractionResult): Graph {
+  const graph = new Graph({ type: 'directed', multi: false });
+
+  // Add all nodes — merge attributes if already present (dedup by id)
+  for (const node of extraction.nodes) {
+    if (!graph.hasNode(node.id)) {
+      graph.addNode(node.id, { ...node });
+    } else {
+      graph.mergeNodeAttributes(node.id, { ...node });
+    }
+  }
+
+  // Add edges — skip self-loops, auto-stub missing endpoints
+  for (const edge of extraction.edges) {
+    if (edge.source === edge.target) continue;
+
+    // Create stub nodes for referenced endpoints not in the extraction
+    if (!graph.hasNode(edge.source)) {
+      graph.addNode(edge.source, {
+        id: edge.source,
+        label: edge.source,
+        fileType: 'unknown',
+        sourceFile: '',
+      });
+    }
+    if (!graph.hasNode(edge.target)) {
+      graph.addNode(edge.target, {
+        id: edge.target,
+        label: edge.target,
+        fileType: 'unknown',
+        sourceFile: '',
+      });
+    }
+
+    try {
+      graph.addEdge(edge.source, edge.target, {
+        relation: edge.relation,
+        confidence: edge.confidence,
+        confidenceScore: edge.confidenceScore,
+        weight: edge.weight ?? 1,
+        sourceFile: edge.sourceFile,
+        sourceLocation: edge.sourceLocation,
+      });
+    } catch {
+      // Edge already exists — bump its weight
+      const existing = graph.edge(edge.source, edge.target);
+      if (existing) {
+        const prev = (graph.getEdgeAttribute(existing, 'weight') as number) ?? 1;
+        graph.setEdgeAttribute(existing, 'weight', prev + 1);
+      }
+    }
+  }
+
+  return graph;
+}

package/src/cache.ts

@@ -0,0 +1,38 @@
+import { createHash } from 'crypto';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import type { ExtractionResult } from './types.js';
+
+export class FileCache {
+  private cacheDir: string;
+
+  constructor(outputDir: string) {
+    this.cacheDir = join(outputDir, 'cache');
+    mkdirSync(this.cacheDir, { recursive: true });
+  }
+
+  key(filePath: string, content: string): string {
+    return createHash('sha256')
+      .update(filePath + content)
+      .digest('hex');
+  }
+
+  get(key: string): ExtractionResult | null {
+    const p = join(this.cacheDir, `${key}.json`);
+    if (!existsSync(p)) return null;
+    try {
+      return JSON.parse(readFileSync(p, 'utf-8')) as ExtractionResult;
+    } catch {
+      return null;
+    }
+  }
+
+  set(key: string, result: ExtractionResult): void {
+    const p = join(this.cacheDir, `${key}.json`);
+    writeFileSync(p, JSON.stringify(result), 'utf-8');
+  }
+
+  has(key: string): boolean {
+    return existsSync(join(this.cacheDir, `${key}.json`));
+  }
+}

package/src/cluster.ts

@@ -0,0 +1,54 @@
+import type Graph from 'graphology';
+
+/**
+ * Run Louvain community detection on the graph.
+ * Assigns the `community` attribute to each node in-place.
+ * Returns a map from communityId → list of nodeIds.
+ */
+export async function detectCommunities(graph: Graph): Promise<Record<number, string[]>> {
+  try {
+    const { default: louvain } = await import('graphology-communities-louvain');
+    const assignment = louvain(graph) as Record<string, number>;
+
+    // Write community id back onto each node
+    for (const [nodeId, communityId] of Object.entries(assignment)) {
+      graph.setNodeAttribute(nodeId, 'community', communityId);
+    }
+
+    // Build communityId → members map
+    const communities: Record<number, string[]> = {};
+    for (const [nodeId, communityId] of Object.entries(assignment)) {
+      if (!communities[communityId]) communities[communityId] = [];
+      communities[communityId].push(nodeId);
+    }
+    return communities;
+  } catch {
+    // Louvain unavailable — fall back to directory-based clustering
+    return fallbackCluster(graph);
+  }
+}
+
+/**
+ * Fallback: group nodes by the directory portion of their sourceFile attribute.
+ * Deterministic and zero-dependency.
+ */
+function fallbackCluster(graph: Graph): Record<number, string[]> {
+  const dirMap = new Map<string, number>();
+  let nextId = 0;
+  const communities: Record<number, string[]> = {};
+
+  graph.forEachNode((id, attrs) => {
+    const file = (attrs.sourceFile as string) || '';
+    const parts = file.split('/');
+    const dir = parts.length > 1 ? parts.slice(0, -1).join('/') : 'root';
+
+    if (!dirMap.has(dir)) dirMap.set(dir, nextId++);
+    const cid = dirMap.get(dir)!;
+
+    graph.setNodeAttribute(id, 'community', cid);
+    if (!communities[cid]) communities[cid] = [];
+    communities[cid].push(id);
+  });
+
+  return communities;
+}

package/src/detect.ts

@@ -0,0 +1,123 @@
+import { readdirSync, statSync } from 'fs';
+import { join, extname, relative } from 'path';
+import type { BuildOptions, ClassifiedFile, FileType } from './types.js';
+
+const DEFAULT_MAX_FILE_SIZE = 500 * 1024; // 500KB
+
+const EXCLUDED_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  '.monobrain',
+  '__pycache__',
+  '.pytest_cache',
+  'target',
+  '.cache',
+]);
+
+// Maps file extension to [fileType, language]
+const EXTENSION_MAP: Record<string, [FileType, string]> = {
+  '.ts':    ['code', 'typescript'],
+  '.tsx':   ['code', 'typescript'],
+  '.js':    ['code', 'javascript'],
+  '.jsx':   ['code', 'javascript'],
+  '.py':    ['code', 'python'],
+  '.go':    ['code', 'go'],
+  '.rs':    ['code', 'rust'],
+  '.java':  ['code', 'java'],
+  '.c':     ['code', 'c'],
+  '.cpp':   ['code', 'cpp'],
+  '.h':     ['code', 'c'],
+  '.cs':    ['code', 'csharp'],
+  '.rb':    ['code', 'ruby'],
+  '.php':   ['code', 'php'],
+  '.swift': ['code', 'swift'],
+  '.kt':    ['code', 'kotlin'],
+  '.scala': ['code', 'scala'],
+  '.md':    ['document', 'markdown'],
+  '.txt':   ['document', 'text'],
+  '.rst':   ['document', 'rst'],
+};
+
+/**
+ * Recursively collects and classifies all files under rootPath, applying
+ * exclusion rules for directories, file size limits, and optional language
+ * filtering from BuildOptions.
+ */
+export function collectFiles(
+  rootPath: string,
+  options: BuildOptions = {},
+): ClassifiedFile[] {
+  const maxFileSizeBytes = options.maxFileSizeBytes ?? DEFAULT_MAX_FILE_SIZE;
+  const codeOnly = options.codeOnly ?? false;
+  const languageFilter = options.languages ? new Set(options.languages) : null;
+  const excludePatterns = options.excludePatterns ?? [];
+
+  const results: ClassifiedFile[] = [];
+
+  function walkDir(dirPath: string): void {
+    let entries: string[];
+    try {
+      entries = readdirSync(dirPath);
+    } catch {
+      // Skip unreadable directories
+      return;
+    }
+
+    for (const entry of entries) {
+      const fullPath = join(dirPath, entry);
+
+      // Check against custom exclude patterns (matched against relative path)
+      const relPath = relative(rootPath, fullPath);
+      if (excludePatterns.some((pat) => relPath.includes(pat))) {
+        continue;
+      }
+
+      let stat;
+      try {
+        stat = statSync(fullPath);
+      } catch {
+        continue;
+      }
+
+      if (stat.isDirectory()) {
+        // Skip excluded directory names
+        if (EXCLUDED_DIRS.has(entry)) continue;
+        walkDir(fullPath);
+        continue;
+      }
+
+      if (!stat.isFile()) continue;
+
+      // Enforce file size limit
+      if (stat.size > maxFileSizeBytes) continue;
+
+      const ext = extname(entry).toLowerCase();
+      const mapping = EXTENSION_MAP[ext];
+
+      if (!mapping) {
+        // Unknown extension — skip rather than emit 'unknown' noise
+        continue;
+      }
+
+      const [fileType, language] = mapping;
+
+      // Apply codeOnly filter
+      if (codeOnly && fileType !== 'code') continue;
+
+      // Apply language filter
+      if (languageFilter && !languageFilter.has(language)) continue;
+
+      results.push({
+        path: fullPath,
+        fileType,
+        language,
+        sizeBytes: stat.size,
+      });
+    }
+  }
+
+  walkDir(rootPath);
+  return results;
+}

package/src/export.ts

@@ -0,0 +1,78 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import Graph from 'graphology';
+import type { SerializedGraph } from './types.js';
+
+/**
+ * Serialize a graphology graph to disk as a JSON file.
+ * Creates the output directory if it does not exist.
+ * Returns the absolute path to the written file.
+ */
+export function saveGraph(graph: Graph, outputDir: string, projectPath: string): string {
+  mkdirSync(outputDir, { recursive: true });
+  const graphPath = join(outputDir, 'graph.json');
+
+  const nodes: Array<{ id: string } & Record<string, unknown>> = [];
+  graph.forEachNode((id, attrs) => nodes.push({ id, ...attrs }));
+
+  const links: Array<{ source: string; target: string } & Record<string, unknown>> = [];
+  graph.forEachEdge((_, attrs, source, target) => links.push({ source, target, ...attrs }));
+
+  const serialized: SerializedGraph = {
+    version: '1.0.0',
+    builtAt: new Date().toISOString(),
+    projectPath,
+    nodes,
+    links,
+    directed: graph.type === 'directed',
+    multigraph: graph.multi,
+  };
+
+  writeFileSync(graphPath, JSON.stringify(serialized, null, 2), 'utf-8');
+  return graphPath;
+}
+
+/**
+ * Deserialize a graph from a previously saved JSON file.
+ * Silently skips edges whose endpoints are missing from the node list.
+ */
+export function loadGraph(graphPath: string): Graph {
+  const raw = readFileSync(graphPath, 'utf-8');
+  const data = JSON.parse(raw) as SerializedGraph;
+
+  const graph = new Graph({
+    type: data.directed ? 'directed' : 'undirected',
+    multi: false,
+  });
+
+  for (const node of data.nodes) {
+    const { id, ...attrs } = node;
+    graph.addNode(id, attrs);
+  }
+
+  for (const link of data.links) {
+    const { source, target, ...attrs } = link;
+    if (!graph.hasNode(source) || !graph.hasNode(target)) continue;
+    try {
+      graph.addEdge(source, target, attrs);
+    } catch {
+      // Duplicate edge — ignore
+    }
+  }
+
+  return graph;
+}
+
+/**
+ * Return true when a graph.json already exists in the given output directory.
+ */
+export function graphExists(outputDir: string): boolean {
+  return existsSync(join(outputDir, 'graph.json'));
+}
+
+/**
+ * Return the canonical path to graph.json inside an output directory.
+ */
+export function getGraphPath(outputDir: string): string {
+  return join(outputDir, 'graph.json');
+}