@monoes/monograph 1.0.0

package/src/pipeline/runner.ts

@@ -0,0 +1,61 @@
+import type { PipelinePhase, PipelineContext } from './types.js';
+import { MonographError } from '../types.js';
+
+export class PipelineRunner {
+  private readonly order: string[];
+
+  constructor(private readonly phases: PipelinePhase<unknown>[]) {
+    this.order = topoSort(phases);
+  }
+
+  async run(ctx: PipelineContext): Promise<Map<string, unknown>> {
+    const outputs = new Map<string, unknown>();
+    const phaseMap = new Map(this.phases.map(p => [p.name, p]));
+
+    for (const name of this.order) {
+      const phase = phaseMap.get(name)!;
+      ctx.onProgress?.({ phase: name });
+      const output = await phase.execute(ctx, outputs);
+      outputs.set(name, output);
+    }
+
+    return outputs;
+  }
+}
+
+function topoSort(phases: PipelinePhase<unknown>[]): string[] {
+  const names = new Set(phases.map(p => p.name));
+  const inDegree = new Map<string, number>();
+  const adjList = new Map<string, string[]>();
+
+  for (const p of phases) {
+    inDegree.set(p.name, p.deps.length);
+    for (const dep of p.deps) {
+      if (!names.has(dep)) {
+        throw new MonographError(`Phase '${p.name}' depends on unknown phase '${dep}'`);
+      }
+      const adj = adjList.get(dep) ?? [];
+      adj.push(p.name);
+      adjList.set(dep, adj);
+    }
+  }
+
+  const queue = phases.filter(p => (inDegree.get(p.name) ?? 0) === 0).map(p => p.name);
+  const result: string[] = [];
+
+  while (queue.length) {
+    const name = queue.shift()!;
+    result.push(name);
+    for (const next of (adjList.get(name) ?? [])) {
+      const deg = (inDegree.get(next) ?? 0) - 1;
+      inDegree.set(next, deg);
+      if (deg === 0) queue.push(next);
+    }
+  }
+
+  if (result.length !== phases.length) {
+    throw new MonographError('Cycle detected in pipeline phase graph');
+  }
+
+  return result;
+}

package/src/pipeline/types.ts

@@ -0,0 +1,33 @@
+import type { MonographDb } from '../storage/db.js';
+import type { PipelineProgress } from '../types.js';
+import type Graph from 'graphology';
+
+export interface PipelineContext {
+  repoPath: string;
+  db: MonographDb;
+  graph: Graph;
+  onProgress: (p: PipelineProgress) => void;
+  options: PipelineOptions;
+}
+
+export interface PipelineOptions {
+  codeOnly: boolean;
+  maxFileSizeBytes: number;
+  workerPoolThreshold: number;
+  workerChunkBudgetBytes: number;
+  ignore: string[];
+}
+
+export const DEFAULT_OPTIONS: PipelineOptions = {
+  codeOnly: false,
+  maxFileSizeBytes: 524288,
+  workerPoolThreshold: 15,
+  workerChunkBudgetBytes: 20971520,
+  ignore: [],
+};
+
+export interface PipelinePhase<TOutput> {
+  name: string;
+  deps: string[];
+  execute(ctx: PipelineContext, depOutputs: Map<string, unknown>): Promise<TOutput>;
+}

package/src/storage/db.ts

@@ -0,0 +1,54 @@
+import Database from 'better-sqlite3';
+import { mkdirSync, existsSync, renameSync, unlinkSync } from 'fs';
+import { dirname } from 'path';
+import {
+  CREATE_NODES, CREATE_EDGES, CREATE_COMMUNITIES,
+  CREATE_INDEX_META, CREATE_NODES_FTS, CREATE_INDEXES, FTS_SYNC_TRIGGERS,
+} from './schema.js';
+import { MonographError } from '../types.js';
+
+export type MonographDb = Database.Database;
+
+export function openDb(dbPath: string): MonographDb {
+  try {
+    mkdirSync(dirname(dbPath), { recursive: true });
+    const db = new Database(dbPath);
+    db.pragma('journal_mode = WAL');
+    db.pragma('foreign_keys = ON');
+    applyMigrations(db);
+    return db;
+  } catch (err) {
+    throw new MonographError(`Failed to open database at ${dbPath}`, err);
+  }
+}
+
+export function closeDb(db: MonographDb): void {
+  db.close();
+}
+
+function applyMigrations(db: MonographDb): void {
+  db.exec(CREATE_NODES);
+  db.exec(CREATE_EDGES);
+  db.exec(CREATE_COMMUNITIES);
+  db.exec(CREATE_INDEX_META);
+  db.exec(CREATE_NODES_FTS);
+  for (const idx of CREATE_INDEXES) db.exec(idx);
+  db.exec(FTS_SYNC_TRIGGERS);
+}
+
+/** Write to a .tmp file then rename for atomic replacement. */
+export function atomicRebuild(dbPath: string, buildFn: (db: MonographDb) => void): void {
+  const tmpPath = dbPath + '.tmp';
+  const db = openDb(tmpPath);
+  try {
+    buildFn(db);
+    db.close();
+    renameSync(tmpPath, dbPath);
+  } catch (err) {
+    db.close();
+    if (existsSync(tmpPath)) {
+      try { unlinkSync(tmpPath); } catch { /* ignore */ }
+    }
+    throw err;
+  }
+}

package/src/storage/edge-store.ts

@@ -0,0 +1,61 @@
+import type Database from 'better-sqlite3';
+import type { MonographEdge } from '../types.js';
+
+export function insertEdge(db: Database.Database, edge: MonographEdge): void {
+  db.prepare(`
+    INSERT OR REPLACE INTO edges (id, source_id, target_id, relation, confidence, confidence_score)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `).run(
+    edge.id,
+    edge.sourceId,
+    edge.targetId,
+    edge.relation,
+    edge.confidence,
+    edge.confidenceScore,
+  );
+}
+
+export function insertEdges(db: Database.Database, edges: MonographEdge[]): void {
+  const insertMany = db.transaction((rows: MonographEdge[]) => {
+    for (const e of rows) {
+      insertEdge(db, e);
+    }
+  });
+  insertMany(edges);
+}
+
+export function getEdgesForSource(db: Database.Database, sourceId: string): MonographEdge[] {
+  const rows = db
+    .prepare('SELECT * FROM edges WHERE source_id = ?')
+    .all(sourceId) as Record<string, unknown>[];
+  return rows.map(rowToEdge);
+}
+
+export function getEdgesForTarget(db: Database.Database, targetId: string): MonographEdge[] {
+  const rows = db
+    .prepare('SELECT * FROM edges WHERE target_id = ?')
+    .all(targetId) as Record<string, unknown>[];
+  return rows.map(rowToEdge);
+}
+
+export function deleteEdgesForFile(db: Database.Database, filePath: string): void {
+  db.prepare(`
+    DELETE FROM edges WHERE source_id IN (SELECT id FROM nodes WHERE file_path = ?)
+  `).run(filePath);
+}
+
+export function countEdges(db: Database.Database): number {
+  const row = db.prepare('SELECT COUNT(*) as n FROM edges').get() as { n: number };
+  return row.n;
+}
+
+function rowToEdge(row: Record<string, unknown>): MonographEdge {
+  return {
+    id: row.id as string,
+    sourceId: row.source_id as string,
+    targetId: row.target_id as string,
+    relation: row.relation as MonographEdge['relation'],
+    confidence: row.confidence as MonographEdge['confidence'],
+    confidenceScore: row.confidence_score as number,
+  };
+}

package/src/storage/fts-store.ts

@@ -0,0 +1,52 @@
+import type Database from 'better-sqlite3';
+
+export interface FtsResult {
+  id: string;
+  name: string;
+  normLabel: string;
+  filePath: string | null;
+  label: string;
+  rank: number;
+}
+
+export function ftsSearch(
+  db: Database.Database,
+  query: string,
+  limit: number,
+  label?: string,
+): FtsResult[] {
+  // Clean and sanitize the query for FTS5
+  const safeQuery = query.replace(/['"*]/g, ' ').trim();
+  if (!safeQuery) return [];
+
+  // Add wildcard for prefix matching
+  const ftsPrefixQuery = safeQuery.split(/\s+/).map((term) => term + '*').join(' ');
+
+  let sql = `
+    SELECT n.id, n.name, n.norm_label, n.file_path, n.label,
+           nodes_fts.rank
+    FROM nodes_fts
+    JOIN nodes n ON n.rowid = nodes_fts.rowid
+    WHERE nodes_fts MATCH ?
+  `;
+  const params: unknown[] = [ftsPrefixQuery];
+  if (label) {
+    sql += ' AND n.label = ?';
+    params.push(label);
+  }
+  sql += ' ORDER BY nodes_fts.rank LIMIT ?';
+  params.push(limit);
+
+  const rows = db.prepare(sql).all(...(params as [string, ...unknown[]])) as Record<
+    string,
+    unknown
+  >[];
+  return rows.map((r) => ({
+    id: r.id as string,
+    name: r.name as string,
+    normLabel: r.norm_label as string,
+    filePath: (r.file_path as string | null) ?? null,
+    label: r.label as string,
+    rank: r.rank as number,
+  }));
+}

package/src/storage/node-store.ts

@@ -0,0 +1,72 @@
+import type Database from 'better-sqlite3';
+import type { MonographNode } from '../types.js';
+import { toNormLabel } from '../types.js';
+
+export function insertNode(db: Database.Database, node: MonographNode): void {
+  db.prepare(`
+    INSERT OR REPLACE INTO nodes
+      (id, label, name, norm_label, file_path, start_line, end_line,
+       community_id, is_exported, language, properties)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    node.id,
+    node.label,
+    node.name,
+    node.normLabel ?? toNormLabel(node.name),
+    node.filePath ?? null,
+    node.startLine ?? null,
+    node.endLine ?? null,
+    node.communityId ?? null,
+    node.isExported ? 1 : 0,
+    node.language ?? null,
+    node.properties ? JSON.stringify(node.properties) : null,
+  );
+}
+
+export function insertNodes(db: Database.Database, nodes: MonographNode[]): void {
+  const insertMany = db.transaction((rows: MonographNode[]) => {
+    for (const n of rows) {
+      insertNode(db, n);
+    }
+  });
+  insertMany(nodes);
+}
+
+export function getNode(db: Database.Database, id: string): MonographNode | undefined {
+  const row = db
+    .prepare('SELECT * FROM nodes WHERE id = ?')
+    .get(id) as Record<string, unknown> | undefined;
+  return row ? rowToNode(row) : undefined;
+}
+
+export function getNodesForFile(db: Database.Database, filePath: string): MonographNode[] {
+  const rows = db
+    .prepare('SELECT * FROM nodes WHERE file_path = ?')
+    .all(filePath) as Record<string, unknown>[];
+  return rows.map(rowToNode);
+}
+
+export function deleteNodesForFile(db: Database.Database, filePath: string): void {
+  db.prepare('DELETE FROM nodes WHERE file_path = ?').run(filePath);
+}
+
+export function countNodes(db: Database.Database): number {
+  const row = db.prepare('SELECT COUNT(*) as n FROM nodes').get() as { n: number };
+  return row.n;
+}
+
+function rowToNode(row: Record<string, unknown>): MonographNode {
+  return {
+    id: row.id as string,
+    label: row.label as MonographNode['label'],
+    name: row.name as string,
+    normLabel: row.norm_label as string,
+    filePath: row.file_path as string | undefined,
+    startLine: row.start_line as number | undefined,
+    endLine: row.end_line as number | undefined,
+    communityId: row.community_id as number | undefined,
+    isExported: (row.is_exported as number) === 1,
+    language: row.language as string | undefined,
+    properties: row.properties ? JSON.parse(row.properties as string) : undefined,
+  };
+}

package/src/storage/schema.ts

@@ -0,0 +1,77 @@
+export const CREATE_NODES = `
+CREATE TABLE IF NOT EXISTS nodes (
+  id TEXT PRIMARY KEY,
+  label TEXT NOT NULL,
+  name TEXT NOT NULL,
+  norm_label TEXT NOT NULL DEFAULT '',
+  file_path TEXT,
+  start_line INTEGER,
+  end_line INTEGER,
+  community_id INTEGER,
+  is_exported INTEGER NOT NULL DEFAULT 0,
+  language TEXT,
+  properties TEXT
+)`;
+
+export const CREATE_EDGES = `
+CREATE TABLE IF NOT EXISTS edges (
+  id TEXT PRIMARY KEY,
+  source_id TEXT NOT NULL,
+  target_id TEXT NOT NULL,
+  relation TEXT NOT NULL,
+  confidence TEXT NOT NULL DEFAULT 'EXTRACTED',
+  confidence_score REAL NOT NULL DEFAULT 1.0,
+  FOREIGN KEY (source_id) REFERENCES nodes(id),
+  FOREIGN KEY (target_id) REFERENCES nodes(id)
+)`;
+
+export const CREATE_COMMUNITIES = `
+CREATE TABLE IF NOT EXISTS communities (
+  id INTEGER PRIMARY KEY,
+  label TEXT,
+  size INTEGER NOT NULL DEFAULT 0,
+  cohesion_score REAL NOT NULL DEFAULT 0.0
+)`;
+
+export const CREATE_INDEX_META = `
+CREATE TABLE IF NOT EXISTS index_meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+)`;
+
+export const CREATE_NODES_FTS = `
+CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(
+  id UNINDEXED,
+  name,
+  norm_label,
+  file_path,
+  label UNINDEXED,
+  content='nodes',
+  content_rowid='rowid'
+)`;
+
+export const CREATE_INDEXES = [
+  `CREATE INDEX IF NOT EXISTS idx_nodes_file ON nodes(file_path)`,
+  `CREATE INDEX IF NOT EXISTS idx_nodes_label ON nodes(label)`,
+  `CREATE INDEX IF NOT EXISTS idx_nodes_norm ON nodes(norm_label)`,
+  `CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source_id)`,
+  `CREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target_id)`,
+  `CREATE INDEX IF NOT EXISTS idx_edges_relation ON edges(relation)`,
+  `CREATE INDEX IF NOT EXISTS idx_edges_confidence ON edges(confidence)`,
+];
+
+export const FTS_SYNC_TRIGGERS = `
+CREATE TRIGGER IF NOT EXISTS nodes_fts_insert AFTER INSERT ON nodes BEGIN
+  INSERT INTO nodes_fts(rowid, id, name, norm_label, file_path, label)
+  VALUES (new.rowid, new.id, new.name, new.norm_label, new.file_path, new.label);
+END;
+CREATE TRIGGER IF NOT EXISTS nodes_fts_delete AFTER DELETE ON nodes BEGIN
+  INSERT INTO nodes_fts(nodes_fts, rowid, id, name, norm_label, file_path, label)
+  VALUES ('delete', old.rowid, old.id, old.name, old.norm_label, old.file_path, old.label);
+END;
+CREATE TRIGGER IF NOT EXISTS nodes_fts_update AFTER UPDATE ON nodes BEGIN
+  INSERT INTO nodes_fts(nodes_fts, rowid, id, name, norm_label, file_path, label)
+  VALUES ('delete', old.rowid, old.id, old.name, old.norm_label, old.file_path, old.label);
+  INSERT INTO nodes_fts(rowid, id, name, norm_label, file_path, label)
+  VALUES (new.rowid, new.id, new.name, new.norm_label, new.file_path, new.label);
+END`;

package/src/types.ts

@@ -0,0 +1,131 @@
+// ── Node labels ───────────────────────────────────────────────────────────────
+
+export type NodeLabel =
+  | 'File' | 'Folder' | 'Function' | 'Class' | 'Method' | 'Interface'
+  | 'Variable' | 'Struct' | 'Enum' | 'Macro' | 'Typedef' | 'Union'
+  | 'Namespace' | 'Trait' | 'Impl' | 'TypeAlias' | 'Const' | 'Static'
+  | 'Property' | 'Record' | 'Delegate' | 'Annotation' | 'Constructor'
+  | 'Template' | 'Module' | 'Process' | 'Route' | 'Community' | 'Concept';
+
+export const SYMBOL_NODE_LABELS = new Set<NodeLabel>([
+  'Function', 'Class', 'Method', 'Interface', 'Variable', 'Struct', 'Enum',
+  'Macro', 'Typedef', 'Union', 'Namespace', 'Trait', 'Impl', 'TypeAlias',
+  'Const', 'Static', 'Property', 'Record', 'Delegate', 'Annotation',
+  'Constructor', 'Template', 'Module',
+]);
+
+// ── Edge relations ────────────────────────────────────────────────────────────
+
+export type EdgeRelation =
+  | 'CONTAINS' | 'DEFINES' | 'CALLS' | 'IMPORTS' | 'EXTENDS' | 'IMPLEMENTS'
+  | 'HAS_METHOD' | 'HAS_PROPERTY' | 'ACCESSES' | 'METHOD_OVERRIDES'
+  | 'METHOD_IMPLEMENTS' | 'MEMBER_OF' | 'STEP_IN_PROCESS' | 'HANDLES_ROUTE'
+  | 'FETCHES' | 'HANDLES_TOOL' | 'ENTRY_POINT_OF' | 'WRAPS' | 'QUERIES';
+
+// ── Confidence ────────────────────────────────────────────────────────────────
+
+export type EdgeConfidence = 'EXTRACTED' | 'INFERRED' | 'AMBIGUOUS';
+
+export const CONFIDENCE_SCORE: Record<EdgeConfidence, number> = {
+  EXTRACTED: 1.0,
+  INFERRED: 0.5,
+  AMBIGUOUS: 0.2,
+};
+
+// ── Nodes ─────────────────────────────────────────────────────────────────────
+
+export interface MonographNode {
+  id: string;
+  label: NodeLabel;
+  name: string;
+  normLabel: string;
+  filePath?: string;
+  startLine?: number;
+  endLine?: number;
+  communityId?: number;
+  isExported: boolean;
+  language?: string;
+  properties?: Record<string, unknown>;
+}
+
+// ── Edges ─────────────────────────────────────────────────────────────────────
+
+export interface MonographEdge {
+  id: string;
+  sourceId: string;
+  targetId: string;
+  relation: EdgeRelation;
+  confidence: EdgeConfidence;
+  confidenceScore: number;
+}
+
+// ── Communities ───────────────────────────────────────────────────────────────
+
+export interface MonographCommunity {
+  id: number;
+  label?: string;
+  size: number;
+  cohesionScore: number;
+}
+
+// ── God nodes ─────────────────────────────────────────────────────────────────
+
+export interface GodNode extends MonographNode {
+  degree: number;
+  inDegree: number;
+  outDegree: number;
+}
+
+// ── Surprising connections ────────────────────────────────────────────────────
+
+export interface SurprisingConnection {
+  edge: MonographEdge;
+  score: number;
+  reasons: string[];
+}
+
+// ── Suggested questions ───────────────────────────────────────────────────────
+
+export type SuggestedQuestion =
+  | { type: 'ambiguous_edge'; edge: MonographEdge; reason: string }
+  | { type: 'bridge_node'; node: MonographNode; commA: number; commB: number }
+  | { type: 'verify_inferred'; edge: MonographEdge; inferredFrom: string }
+  | { type: 'isolated_nodes'; nodes: MonographNode[]; reason: string }
+  | { type: 'low_cohesion'; community: MonographCommunity };
+
+// ── ID generation ─────────────────────────────────────────────────────────────
+
+export function makeId(...parts: string[]): string {
+  return parts
+    .join('_')
+    .replace(/[^a-z0-9_]/gi, '_')
+    .replace(/^_+|_+$/g, '')
+    .toLowerCase();
+}
+
+// ── Norm label ────────────────────────────────────────────────────────────────
+
+export function toNormLabel(name: string): string {
+  return name
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase();
+}
+
+// ── Pipeline progress ─────────────────────────────────────────────────────────
+
+export interface PipelineProgress {
+  phase: string;
+  filesProcessed?: number;
+  totalFiles?: number;
+  message?: string;
+}
+
+// ── Errors ────────────────────────────────────────────────────────────────────
+
+export class MonographError extends Error {
+  constructor(message: string, public readonly cause?: unknown) {
+    super(message);
+    this.name = 'MonographError';
+  }
+}

package/src/watch/watcher.ts

@@ -0,0 +1,66 @@
+import chokidar from 'chokidar';
+import { EventEmitter } from 'events';
+import { isSupportedExtension } from '../parsers/loader.js';
+import { extname } from 'path';
+import { platform } from 'os';
+
+export interface WatcherOptions {
+  debounceMs?: number;  // default 3000ms
+}
+
+export class MonographWatcher extends EventEmitter {
+  private watcher: chokidar.FSWatcher | null = null;
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  private pendingChanges = new Set<string>();
+  private readonly debounceMs: number;
+
+  constructor(private readonly repoPath: string, opts: WatcherOptions = {}) {
+    super();
+    this.debounceMs = opts.debounceMs ?? 3000;
+  }
+
+  async start(): Promise<void> {
+    const usePolling = platform() === 'darwin';
+
+    this.watcher = chokidar.watch(this.repoPath, {
+      ignored: [
+        /(^|[/\\])\../,     // dotfiles
+        /node_modules/,
+        /\.monomind/,
+        /dist\//,
+        /build\//,
+      ],
+      persistent: true,
+      ignoreInitial: true,
+      usePolling,
+      interval: usePolling ? 1000 : undefined,
+    });
+
+    this.watcher.on('change', (path: string) => this.handleChange(path));
+    this.watcher.on('add', (path: string) => this.handleChange(path));
+    this.watcher.on('unlink', (path: string) => this.handleChange(path));
+    this.watcher.on('error', (err: unknown) => this.emit('monograph:error', err));
+
+    await new Promise<void>(resolve => this.watcher!.once('ready', resolve));
+  }
+
+  async stop(): Promise<void> {
+    if (this.debounceTimer) clearTimeout(this.debounceTimer);
+    if (this.watcher) await this.watcher.close();
+    this.watcher = null;
+  }
+
+  private handleChange(filePath: string): void {
+    const ext = extname(filePath);
+    if (!isSupportedExtension(ext)) return;
+
+    this.pendingChanges.add(filePath);
+
+    if (this.debounceTimer) clearTimeout(this.debounceTimer);
+    this.debounceTimer = setTimeout(() => {
+      const changed = [...this.pendingChanges];
+      this.pendingChanges.clear();
+      this.emit('monograph:updated', changed);
+    }, this.debounceMs);
+  }
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": ".",
+    "composite": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "__tests__"]
+}

package/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['__tests__/**/*.test.ts', 'src/__tests__/**/*.test.ts'],
+    globals: true,
+    coverage: {
+      enabled: false,
+    },
+  },
+});