optave-codegraph 3.13.0

package/src/features/sequence.ts

@@ -0,0 +1,410 @@
+import Database from 'better-sqlite3';
+import { openRepo, type Repository } from '../db/index.js';
+import { SqliteRepository } from '../db/repository/sqlite-repository.js';
+import { findMatchingNodes } from '../domain/queries.js';
+import { loadConfig } from '../infrastructure/config.js';
+import { isTestFile } from '../infrastructure/test-filter.js';
+import { paginateResult } from '../shared/paginate.js';
+import type { BetterSqlite3Database, CodegraphConfig, NodeRowWithFanIn } from '../types.js';
+import { FRAMEWORK_ENTRY_PREFIXES } from './structure.js';
+
+// ─── Alias generation ────────────────────────────────────────────────
+
+/** Build aliases for a group of paths that share the same basename.
+ *  Progressively adds parent dirs until all aliases are unique. */
+function resolveCollisionAliases(paths: string[], aliases: Map<string, string>): void {
+  for (let depth = 2; depth <= 10; depth++) {
+    const trial = new Map<string, string>();
+    let allUnique = true;
+    const seen = new Set<string>();
+
+    for (const p of paths) {
+      const parts = p.replace(/\.[^.]+$/, '').split('/');
+      const alias = parts
+        .slice(-depth)
+        .join('_')
+        .replace(/[^a-zA-Z0-9_-]/g, '_');
+      trial.set(p, alias);
+      if (seen.has(alias)) allUnique = false;
+      seen.add(alias);
+    }
+
+    if (allUnique || depth === 10) {
+      for (const [p, alias] of trial) {
+        aliases.set(p, alias);
+      }
+      break;
+    }
+  }
+}
+
+function buildAliases(files: string[]): Map<string, string> {
+  const aliases = new Map<string, string>();
+  const basenames = new Map<string, string[]>();
+
+  // Group by basename
+  for (const file of files) {
+    const base = (file.split('/').pop() ?? file).replace(/\.[^.]+$/, '');
+    if (!basenames.has(base)) basenames.set(base, []);
+    basenames.get(base)!.push(file);
+  }
+
+  for (const [base, paths] of basenames) {
+    if (paths.length === 1) {
+      aliases.set(paths[0]!, base);
+    } else {
+      // Collision — progressively add parent dirs until aliases are unique
+      resolveCollisionAliases(paths, aliases);
+    }
+  }
+
+  return aliases;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────
+
+interface MatchNode extends NodeRowWithFanIn {
+  _relevance: number;
+}
+
+function findEntryNode(
+  repo: Repository,
+  name: string,
+  opts: { noTests?: boolean; file?: string; kind?: string },
+): MatchNode | null {
+  let matchNode: MatchNode | null = findMatchingNodes(repo, name, opts)[0] ?? null;
+  if (!matchNode) {
+    for (const prefix of FRAMEWORK_ENTRY_PREFIXES) {
+      matchNode = findMatchingNodes(repo, `${prefix}${name}`, opts)[0] ?? null;
+      if (matchNode) break;
+    }
+  }
+  return matchNode;
+}
+
+interface SequenceMessage {
+  from: string;
+  to: string;
+  label: string;
+  type: 'call' | 'return';
+  depth: number;
+}
+
+interface BfsResult {
+  messages: SequenceMessage[];
+  fileSet: Set<string>;
+  idToNode: Map<number, { id: number; name: string; file: string; kind: string; line: number }>;
+  truncated: boolean;
+}
+
+type CalleeNode = { id: number; name: string; file: string; kind: string; line: number };
+
+interface BfsFrame {
+  visited: Set<number>;
+  messages: SequenceMessage[];
+  fileSet: Set<string>;
+  idToNode: Map<number, CalleeNode>;
+  nextFrontier: number[];
+}
+
+function processCallee(
+  c: CalleeNode,
+  caller: CalleeNode,
+  depth: number,
+  noTests: boolean,
+  frame: BfsFrame,
+): void {
+  if (noTests && isTestFile(c.file)) return;
+
+  frame.fileSet.add(c.file);
+  frame.messages.push({
+    from: caller.file,
+    to: c.file,
+    label: c.name,
+    type: 'call',
+    depth,
+  });
+
+  if (frame.visited.has(c.id)) return;
+  frame.visited.add(c.id);
+  frame.nextFrontier.push(c.id);
+  frame.idToNode.set(c.id, c);
+}
+
+function bfsCallees(
+  repo: Repository,
+  matchNode: MatchNode,
+  maxDepth: number,
+  noTests: boolean,
+): BfsResult {
+  const visited = new Set<number>([matchNode.id]);
+  let frontier = [matchNode.id];
+  const messages: SequenceMessage[] = [];
+  const fileSet = new Set<string>([matchNode.file]);
+  const idToNode = new Map<number, CalleeNode>();
+  idToNode.set(matchNode.id, matchNode);
+  let truncated = false;
+
+  for (let d = 1; d <= maxDepth; d++) {
+    const frame: BfsFrame = { visited, messages, fileSet, idToNode, nextFrontier: [] };
+
+    for (const fid of frontier) {
+      const caller = idToNode.get(fid)!;
+      for (const c of repo.findCallees(fid)) {
+        processCallee(c, caller, d, noTests, frame);
+      }
+    }
+
+    frontier = frame.nextFrontier;
+    if (frontier.length === 0) break;
+
+    if (d === maxDepth && frontier.some((fid) => repo.findCallees(fid).length > 0)) {
+      truncated = true;
+    }
+  }
+
+  return { messages, fileSet, idToNode, truncated };
+}
+
+function annotateDataflow(
+  repo: Repository,
+  messages: SequenceMessage[],
+  idToNode: Map<number, { id: number; name: string; file: string; kind: string; line: number }>,
+  dbPath?: string,
+): void {
+  const hasTable = repo.hasDataflowTable();
+  if (!hasTable) return;
+
+  let db: BetterSqlite3Database;
+  let ownDb = false;
+  if (repo instanceof SqliteRepository) {
+    db = repo.db;
+  } else if (dbPath) {
+    db = new Database(dbPath, { readonly: true }) as unknown as BetterSqlite3Database;
+    ownDb = true;
+  } else {
+    return;
+  }
+
+  try {
+    _annotateDataflowImpl(db, messages, idToNode);
+  } finally {
+    if (ownDb) db.close();
+  }
+}
+
+type DataflowStmts = {
+  getReturns: ReturnType<BetterSqlite3Database['prepare']>;
+  getFlowsTo: ReturnType<BetterSqlite3Database['prepare']>;
+};
+
+function appendReturnMessages(
+  messages: SequenceMessage[],
+  nodeByNameFile: Map<string, { id: number; name: string; file: string }>,
+  stmts: DataflowStmts,
+): void {
+  const seenReturns = new Set<string>();
+  for (const msg of [...messages]) {
+    if (msg.type !== 'call') continue;
+    const targetNode = nodeByNameFile.get(`${msg.label}|${msg.to}`);
+    if (!targetNode) continue;
+
+    const returnKey = `${msg.to}->${msg.from}:${msg.label}`;
+    if (seenReturns.has(returnKey)) continue;
+
+    const returns = stmts.getReturns.all(targetNode.id) as { expression: string }[];
+    if (returns.length === 0) continue;
+
+    seenReturns.add(returnKey);
+    messages.push({
+      from: msg.to,
+      to: msg.from,
+      label: returns[0]!.expression || 'result',
+      type: 'return',
+      depth: msg.depth,
+    });
+  }
+}
+
+function annotateCallParams(
+  messages: SequenceMessage[],
+  nodeByNameFile: Map<string, { id: number; name: string; file: string }>,
+  stmts: DataflowStmts,
+): void {
+  for (const msg of messages) {
+    if (msg.type !== 'call') continue;
+    const targetNode = nodeByNameFile.get(`${msg.label}|${msg.to}`);
+    if (!targetNode) continue;
+
+    const params = stmts.getFlowsTo.all(targetNode.id) as { expression: string }[];
+    const paramNames = params
+      .map((p) => p.expression)
+      .filter(Boolean)
+      .slice(0, 3);
+    if (paramNames.length > 0) {
+      msg.label = `${msg.label}(${paramNames.join(', ')})`;
+    }
+  }
+}
+
+function _annotateDataflowImpl(
+  db: BetterSqlite3Database,
+  messages: SequenceMessage[],
+  idToNode: Map<number, { id: number; name: string; file: string; kind: string; line: number }>,
+): void {
+  const nodeByNameFile = new Map<string, { id: number; name: string; file: string }>();
+  for (const n of idToNode.values()) {
+    nodeByNameFile.set(`${n.name}|${n.file}`, n);
+  }
+
+  const stmts: DataflowStmts = {
+    getReturns: db.prepare(
+      `SELECT d.expression FROM dataflow d
+         WHERE d.source_id = ? AND d.kind = 'returns'`,
+    ),
+    getFlowsTo: db.prepare(
+      `SELECT d.expression FROM dataflow d
+         WHERE d.target_id = ? AND d.kind = 'flows_to'
+         ORDER BY d.param_index`,
+    ),
+  };
+
+  appendReturnMessages(messages, nodeByNameFile, stmts);
+  annotateCallParams(messages, nodeByNameFile, stmts);
+}
+
+interface Participant {
+  id: string;
+  label: string;
+  file: string;
+}
+
+function buildParticipants(
+  fileSet: Set<string>,
+  entryFile: string,
+): { participants: Participant[]; aliases: Map<string, string> } {
+  const aliases = buildAliases([...fileSet]);
+  const participants: Participant[] = [...fileSet].map((file) => ({
+    id: aliases.get(file)!,
+    label: file.split('/').pop() ?? file,
+    file,
+  }));
+
+  participants.sort((a, b) => {
+    if (a.file === entryFile) return -1;
+    if (b.file === entryFile) return 1;
+    return a.file.localeCompare(b.file);
+  });
+
+  return { participants, aliases };
+}
+
+// ─── Core data function ──────────────────────────────────────────────
+
+interface SequenceDataOpts {
+  depth?: number;
+  noTests?: boolean;
+  file?: string;
+  kind?: string;
+  dataflow?: boolean;
+  limit?: number;
+  offset?: number;
+  config?: CodegraphConfig;
+  repo?: Repository;
+}
+
+interface SequenceEntry {
+  name: string;
+  file: string;
+  kind: string;
+  line: number;
+}
+
+interface SequenceDataResult {
+  entry: SequenceEntry | null;
+  participants: Participant[];
+  messages: SequenceMessage[];
+  depth: number;
+  totalMessages: number;
+  truncated: boolean;
+}
+
+export function sequenceData(
+  name: string,
+  dbPath?: string,
+  opts: SequenceDataOpts = {},
+): SequenceDataResult {
+  const { repo, close } = openRepo(dbPath, opts);
+  try {
+    const config = opts.config || loadConfig();
+    const maxDepth = opts.depth || config.analysis.sequenceDepth || 10;
+    const noTests = opts.noTests || false;
+
+    const matchNode = findEntryNode(repo, name, opts);
+    if (!matchNode) {
+      return {
+        entry: null,
+        participants: [],
+        messages: [],
+        depth: maxDepth,
+        totalMessages: 0,
+        truncated: false,
+      };
+    }
+
+    const entry: SequenceEntry = {
+      name: matchNode.name,
+      file: matchNode.file,
+      kind: matchNode.kind,
+      line: matchNode.line,
+    };
+
+    const { messages, fileSet, idToNode, truncated } = bfsCallees(
+      repo,
+      matchNode,
+      maxDepth,
+      noTests,
+    );
+
+    if (opts.dataflow && messages.length > 0) {
+      annotateDataflow(repo, messages, idToNode, dbPath);
+    }
+
+    messages.sort((a, b) => {
+      if (a.depth !== b.depth) return a.depth - b.depth;
+      if (a.type === 'call' && b.type === 'return') return -1;
+      if (a.type === 'return' && b.type === 'call') return 1;
+      return 0;
+    });
+
+    const { participants, aliases } = buildParticipants(fileSet, entry.file);
+
+    for (const msg of messages) {
+      msg.from = aliases.get(msg.from)!;
+      msg.to = aliases.get(msg.to)!;
+    }
+
+    const base = {
+      entry,
+      participants,
+      messages,
+      depth: maxDepth,
+      totalMessages: messages.length,
+      truncated,
+    };
+    const result = paginateResult(base, 'messages', {
+      limit: opts.limit,
+      offset: opts.offset,
+    }) as SequenceDataResult;
+    if (opts.limit !== undefined || opts.offset !== undefined) {
+      const activeFiles = new Set(result.messages.flatMap((m) => [m.from, m.to]));
+      result.participants = result.participants.filter((p) => activeFiles.has(p.id));
+    }
+    return result;
+  } finally {
+    close();
+  }
+}
+
+// Re-export Mermaid renderer from presentation layer
+export { sequenceToMermaid } from '../presentation/sequence-renderer.js';

package/src/features/shared/find-nodes.ts

@@ -0,0 +1,28 @@
+import { buildFileConditionSQL } from '../../db/query-builder.js';
+import { isTestFile } from '../../infrastructure/test-filter.js';
+import type { BetterSqlite3Database, NodeRow } from '../../types.js';
+
+export function findNodes(
+  db: BetterSqlite3Database,
+  name: string,
+  opts: { kind?: string; file?: string | string[]; noTests?: boolean } = {},
+  defaultKinds: string[] = [],
+): NodeRow[] {
+  const kinds = opts.kind ? [opts.kind] : defaultKinds;
+  if (kinds.length === 0) throw new Error('findNodes: no kinds specified');
+  const placeholders = kinds.map(() => '?').join(', ');
+  const params: unknown[] = [`%${name}%`, ...kinds];
+
+  const fc = buildFileConditionSQL(opts.file ?? [], 'file');
+  params.push(...fc.params);
+
+  const rows = db
+    .prepare(
+      `SELECT * FROM nodes
+       WHERE name LIKE ? AND kind IN (${placeholders})${fc.sql}
+       ORDER BY file, line`,
+    )
+    .all(...params) as NodeRow[];
+
+  return opts.noTests ? rows.filter((n) => !isTestFile(n.file)) : rows;
+}

package/src/features/snapshot.ts

@@ -0,0 +1,221 @@
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getDatabase } from '../db/better-sqlite3.js';
+import { findDbPath } from '../db/index.js';
+import { debug } from '../infrastructure/logger.js';
+import { ConfigError, DbError } from '../shared/errors.js';
+
+const NAME_RE = /^[a-zA-Z0-9_-]+$/;
+
+export function validateSnapshotName(name: string): void {
+  if (!name || !NAME_RE.test(name)) {
+    throw new ConfigError(
+      `Invalid snapshot name "${name}". Use only letters, digits, hyphens, and underscores.`,
+    );
+  }
+}
+
+export function snapshotsDir(dbPath: string): string {
+  return path.join(path.dirname(dbPath), 'snapshots');
+}
+
+interface SnapshotSaveOptions {
+  dbPath?: string;
+  force?: boolean;
+}
+
+/**
+ * Atomically place `tmp` at `dest`.
+ * - force=true: renameSync (overwrites any existing file).
+ * - force=false: linkSync so EEXIST is detected atomically; then unlink tmp.
+ * Callers are responsible for cleaning up `tmp` on any thrown error.
+ */
+function atomicPlaceFile(tmp: string, dest: string, name: string, force?: boolean): void {
+  if (force) {
+    // renameSync overwrites atomically — the correct semantics for --force.
+    fs.renameSync(tmp, dest);
+    return;
+  }
+
+  // Non-force path: linkSync fails atomically with EEXIST if dest exists,
+  // closing the TOCTOU window between existsSync above and the final
+  // placement. We then unlink the temp file; on POSIX and NTFS, link
+  // creates a second reference so tmp can safely be removed.
+  try {
+    fs.linkSync(tmp, dest);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'EEXIST') {
+      throw new ConfigError(`Snapshot "${name}" already exists. Use --force to overwrite.`);
+    }
+    throw err;
+  }
+  try {
+    fs.unlinkSync(tmp);
+  } catch (cleanupErr) {
+    // Best-effort — dest is already in place, so a leftover tmp file is
+    // harmless. Log at debug so repeated failures surface during
+    // troubleshooting without noising up normal operation.
+    debug(`snapshotSave: failed to remove temp file ${tmp}: ${cleanupErr}`);
+  }
+}
+
+export function snapshotSave(
+  name: string,
+  options: SnapshotSaveOptions = {},
+): { name: string; path: string; size: number } {
+  validateSnapshotName(name);
+  const dbPath = options.dbPath || findDbPath();
+  if (!fs.existsSync(dbPath)) {
+    throw new DbError(`Database not found: ${dbPath}`, { file: dbPath });
+  }
+
+  const dir = snapshotsDir(dbPath);
+  const dest = path.join(dir, `${name}.db`);
+
+  // Cheap fail-fast for the common non-force case; the authoritative check
+  // below uses an atomic linkSync that closes the TOCTOU window.
+  if (!options.force && fs.existsSync(dest)) {
+    throw new ConfigError(`Snapshot "${name}" already exists. Use --force to overwrite.`);
+  }
+
+  fs.mkdirSync(dir, { recursive: true });
+
+  // VACUUM INTO a unique temp path on the same filesystem, then atomically
+  // place it at the destination. This closes the TOCTOU window between
+  // existsSync/unlinkSync/VACUUM INTO where two concurrent saves could
+  // observe a missing file or interleave their VACUUM writes.
+  //
+  // Unique temp name: process.pid is shared across worker_threads in the
+  // same process, so we add random bytes to keep concurrent callers in any
+  // thread from colliding on the temp path.
+  const tmp = path.join(
+    dir,
+    `.${name}.db.tmp-${process.pid}-${Date.now()}-${randomBytes(6).toString('hex')}`,
+  );
+  try {
+    fs.unlinkSync(tmp);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+  }
+
+  const Database = getDatabase();
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    db.exec(`VACUUM INTO '${tmp.replace(/'/g, "''")}'`);
+  } finally {
+    db.close();
+  }
+
+  try {
+    atomicPlaceFile(tmp, dest, name, options.force);
+  } catch (err) {
+    try {
+      fs.unlinkSync(tmp);
+    } catch (cleanupErr) {
+      if ((cleanupErr as NodeJS.ErrnoException).code !== 'ENOENT') {
+        debug(`snapshotSave: failed to remove temp file ${tmp}: ${cleanupErr}`);
+      }
+    }
+    throw err;
+  }
+
+  const stat = fs.statSync(dest);
+  debug(`Snapshot saved: ${dest} (${stat.size} bytes)`);
+  return { name, path: dest, size: stat.size };
+}
+
+interface SnapshotDbPathOptions {
+  dbPath?: string;
+}
+
+export function snapshotRestore(name: string, options: SnapshotDbPathOptions = {}): void {
+  validateSnapshotName(name);
+  const dbPath = options.dbPath || findDbPath();
+  const dir = snapshotsDir(dbPath);
+  const src = path.join(dir, `${name}.db`);
+
+  if (!fs.existsSync(src)) {
+    throw new DbError(`Snapshot "${name}" not found at ${src}`, { file: src });
+  }
+
+  // Remove WAL/SHM sidecars first so the old journal can't be replayed over
+  // the restored DB. unlink then check ENOENT — avoids the existsSync/unlinkSync
+  // race another process could wedge into.
+  for (const suffix of ['-wal', '-shm']) {
+    const sidecar = dbPath + suffix;
+    try {
+      fs.unlinkSync(sidecar);
+      debug(`Removed sidecar: ${sidecar}`);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+    }
+  }
+
+  // Copy to a temp path next to the DB, then rename atomically. Readers that
+  // open dbPath during restore see either the pre-restore or post-restore
+  // file, never a partially-written one.
+  fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+  const tmp = `${dbPath}.restore-tmp-${process.pid}-${Date.now()}-${randomBytes(6).toString('hex')}`;
+  try {
+    fs.copyFileSync(src, tmp);
+    fs.renameSync(tmp, dbPath);
+  } catch (err) {
+    try {
+      fs.unlinkSync(tmp);
+    } catch (cleanupErr) {
+      if ((cleanupErr as NodeJS.ErrnoException).code !== 'ENOENT') {
+        debug(`snapshotRestore: failed to remove temp file ${tmp}: ${cleanupErr}`);
+      }
+    }
+    throw err;
+  }
+
+  debug(`Restored snapshot "${name}" → ${dbPath}`);
+}
+
+interface SnapshotEntry {
+  name: string;
+  path: string;
+  size: number;
+  createdAt: Date;
+}
+
+export function snapshotList(options: SnapshotDbPathOptions = {}): SnapshotEntry[] {
+  const dbPath = options.dbPath || findDbPath();
+  const dir = snapshotsDir(dbPath);
+
+  if (!fs.existsSync(dir)) return [];
+
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.db'))
+    .map((f) => {
+      const filePath = path.join(dir, f);
+      const stat = fs.statSync(filePath);
+      return {
+        name: f.replace(/\.db$/, ''),
+        path: filePath,
+        size: stat.size,
+        createdAt: stat.birthtime,
+      };
+    })
+    .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+}
+
+export function snapshotDelete(name: string, options: SnapshotDbPathOptions = {}): void {
+  validateSnapshotName(name);
+  const dbPath = options.dbPath || findDbPath();
+  const dir = snapshotsDir(dbPath);
+  const target = path.join(dir, `${name}.db`);
+
+  try {
+    fs.unlinkSync(target);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      throw new DbError(`Snapshot "${name}" not found at ${target}`, { file: target });
+    }
+    throw err;
+  }
+  debug(`Deleted snapshot: ${target}`);
+}