sdlc-agent-4-enterprise-server 1.0.0

package/src/engine/context/types.ts

@@ -0,0 +1,164 @@
+/**
+ * KSA-158/159/160: Shared types for AI Context tools.
+ */
+
+export interface AIContextParams {
+  symbol: string;
+  intent?: string;
+  token_budget?: number;
+  caller_depth?: number;
+}
+
+export interface AIContextResponse {
+  symbol: string;
+  file_path: string;
+  kind: string;
+  intent: string;
+  context: Record<string, any>;
+  metadata: {
+    budget_used: number;
+    budget_total: number;
+    sections_included: string[];
+    sections_omitted: string[];
+    query_time_ms: number;
+  };
+}
+
+export interface EditContextParams {
+  symbol: string;
+  include_callers?: boolean;
+  include_tests?: boolean;
+  include_memories?: boolean;
+  include_git?: boolean;
+  token_budget?: number;
+  caller_depth?: number;
+}
+
+export interface EditContextResult {
+  symbol: string;
+  file: string;
+  line: number;
+  kind: string;
+  source: string;
+  signature: string | null;
+  callers?: CallerContext[];
+  tests?: TestContext[];
+  dependencies?: DependencyContext[];
+  memories?: MemoryContext[];
+  git_history?: GitCommit[];
+  siblings?: SiblingContext[];
+  metadata: {
+    tokenCount: number;
+    tokenBudget: number;
+    sectionsIncluded: string[];
+    sectionsExcluded: string[];
+    queryTimeMs: number;
+  };
+}
+
+export interface CallerContext {
+  symbol: string;
+  file: string;
+  line: number;
+  context: string;
+}
+
+export interface TestContext {
+  file: string;
+  testName: string;
+  source: string;
+}
+
+export interface DependencyContext {
+  file: string;
+  symbols: string[];
+  direction: 'imports' | 'imported_by';
+}
+
+export interface MemoryContext {
+  id: number;
+  type: string;
+  summary: string;
+}
+
+export interface GitCommit {
+  hash: string;
+  message: string;
+}
+
+export interface SiblingContext {
+  name: string;
+  kind: string;
+  signature: string | null;
+  line: number;
+}
+
+export interface CuratedContextParams {
+  query: string;
+  max_tokens?: number;
+  scope?: string;
+  modules?: string[];
+  languages?: string[];
+  include_source?: boolean;
+  include_memory?: boolean;
+  include_graph?: boolean;
+  source_weights?: SourceWeights;
+}
+
+export interface SourceWeights {
+  code: number;
+  memory: number;
+  graph: number;
+}
+
+export interface CuratedContextResponse {
+  query: string;
+  sections: ContextSection[];
+  metadata: {
+    tokens_used: number;
+    tokens_budget: number;
+    sources_queried: string[];
+    total_candidates: number;
+    results_returned: number;
+    execution_time_ms: number;
+  };
+}
+
+export interface ContextSection {
+  title: string;
+  source: 'code' | 'memory' | 'graph';
+  items: ContextItem[];
+}
+
+export interface ContextItem {
+  name: string;
+  kind?: string;
+  file?: string;
+  line?: number;
+  relevance: number;
+  detail: 'full' | 'signature' | 'reference';
+  content: string;
+  relationship?: string;
+}
+
+export interface QueryAnalysis {
+  originalQuery: string;
+  keywords: string[];
+  symbolCandidates: string[];
+  phrases: string[];
+  ftsQuery: string;
+}
+
+export interface MergedResult {
+  id?: number;
+  name: string;
+  kind?: string;
+  file?: string;
+  line?: number;
+  signature?: string;
+  source_code?: string;
+  content?: string;
+  relevance_score: number;
+  sources: string[];
+  relationship?: string;
+}

package/src/engine/database/graph-repository.ts

@@ -0,0 +1,166 @@
+/**
+ * KSA-153: Graph Repository — CRUD operations for the code relationship graph.
+ * Provides prepared-statement-based access to the relationships table.
+ */
+
+import Database from 'better-sqlite3';
+
+export interface CallerResult {
+  name: string;
+  kind: string;
+  file_path: string;
+  def_line: number;
+  call_line: number;
+  parameters: string | null;
+  is_async: number;
+  id: number;
+}
+
+export interface CalleeResult {
+  name: string;
+  call_line: number;
+  metadata: string | null;
+  kind: string | null;
+  file_path: string | null;
+  def_line: number | null;
+}
+
+export interface RelationshipInput {
+  sourceSymbolId: number;
+  targetSymbol: string;
+  targetSymbolId?: number | null;
+  kind: string;
+  filePath: string;
+  line: number;
+  metadata?: Record<string, unknown> | null;
+}
+
+export class GraphRepository {
+  private db: Database.Database;
+  private stmts!: {
+    insertRelationship: Database.Statement;
+    deleteFileRelationships: Database.Statement;
+    findCallers: Database.Statement;
+    findCallees: Database.Statement;
+    resolveTarget: Database.Statement;
+    countRelationships: Database.Statement;
+  };
+
+  constructor(db: Database.Database) {
+    this.db = db;
+    this.prepareStatements();
+  }
+
+  /** Insert a batch of relationships within a transaction. */
+  insertRelationships(relationships: RelationshipInput[]): void {
+    const transaction = this.db.transaction((rels: RelationshipInput[]) => {
+      for (const rel of rels) {
+        this.stmts.insertRelationship.run(
+          rel.sourceSymbolId,
+          rel.targetSymbol,
+          rel.targetSymbolId ?? null,
+          rel.kind,
+          rel.filePath,
+          rel.line,
+          rel.metadata ? JSON.stringify(rel.metadata) : null
+        );
+      }
+    });
+    transaction(relationships);
+  }
+
+  /** Delete all relationships originating from a file. */
+  deleteFileRelationships(filePath: string): void {
+    this.stmts.deleteFileRelationships.run(filePath);
+  }
+
+  /** Find direct callers of a symbol by name. */
+  findCallers(symbolName: string, kind: string = 'calls', limit: number = 20): CallerResult[] {
+    return this.stmts.findCallers.all(symbolName, kind, limit) as CallerResult[];
+  }
+
+  /** Find direct callees of a symbol by ID. */
+  findCallees(symbolId: number, kind: string = 'calls', limit: number = 20): CalleeResult[] {
+    return this.stmts.findCallees.all(symbolId, kind, limit) as CalleeResult[];
+  }
+
+  /** Resolve target_symbol_id for unresolved relationships (batch). */
+  resolveTargets(batchSize: number = 1000): number {
+    const unresolved = this.db.prepare(`
+      SELECT r.id, r.target_symbol
+      FROM relationships r
+      WHERE r.target_symbol_id IS NULL
+      LIMIT ?
+    `).all(batchSize) as { id: number; target_symbol: string }[];
+
+    let resolved = 0;
+    const findTarget = this.db.prepare('SELECT id FROM symbols WHERE name = ? LIMIT 1');
+
+    const transaction = this.db.transaction(() => {
+      for (const row of unresolved) {
+        const target = findTarget.get(row.target_symbol) as { id: number } | undefined;
+        if (target) {
+          this.stmts.resolveTarget.run(target.id, row.id);
+          resolved++;
+        }
+      }
+    });
+    transaction();
+
+    return resolved;
+  }
+
+  /** Get total relationship count. */
+  getRelationshipCount(): number {
+    const row = this.stmts.countRelationships.get() as { count: number };
+    return row.count;
+  }
+
+  /** Get relationship statistics by kind. */
+  getStats(): { kind: string; count: number }[] {
+    return this.db.prepare(`
+      SELECT kind, COUNT(*) as count
+      FROM relationships
+      GROUP BY kind
+      ORDER BY count DESC
+    `).all() as { kind: string; count: number }[];
+  }
+
+  private prepareStatements(): void {
+    this.stmts = {
+      insertRelationship: this.db.prepare(`
+        INSERT INTO relationships (source_symbol_id, target_symbol, target_symbol_id, kind, file_path, line, metadata)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+      `),
+      deleteFileRelationships: this.db.prepare(
+        'DELETE FROM relationships WHERE file_path = ?'
+      ),
+      findCallers: this.db.prepare(`
+        SELECT s.name, s.kind, f.relative_path as file_path, s.start_line as def_line, r.line as call_line,
+               s.parent_symbol as parameters, s.visibility as is_async, s.id
+        FROM relationships r
+        JOIN symbols s ON s.id = r.source_symbol_id
+        JOIN files f ON f.id = s.file_id
+        WHERE r.target_symbol = ? AND r.kind = ?
+        ORDER BY f.relative_path, r.line
+        LIMIT ?
+      `),
+      findCallees: this.db.prepare(`
+        SELECT r.target_symbol as name, r.line as call_line, r.metadata,
+               ts.kind, tf.relative_path as file_path, ts.start_line as def_line
+        FROM relationships r
+        LEFT JOIN symbols ts ON ts.id = r.target_symbol_id
+        LEFT JOIN files tf ON tf.id = ts.file_id
+        WHERE r.source_symbol_id = ? AND r.kind = ?
+        ORDER BY r.line
+        LIMIT ?
+      `),
+      resolveTarget: this.db.prepare(
+        'UPDATE relationships SET target_symbol_id = ? WHERE id = ?'
+      ),
+      countRelationships: this.db.prepare(
+        'SELECT COUNT(*) as count FROM relationships'
+      ),
+    };
+  }
+}

package/src/engine/database/incremental-updater.ts

@@ -0,0 +1,117 @@
+/**
+ * KSA-169: Incremental Updater — Detect file changes using FNV-1a content hashing.
+ * Compares disk state against stored file_index to determine what needs re-indexing.
+ */
+
+import * as fs from 'fs';
+import Database from 'better-sqlite3';
+
+export interface ChangeSet {
+  added: string[];
+  modified: string[];
+  deleted: string[];
+  unchanged: number;
+}
+
+export class IncrementalUpdater {
+  private db: Database.Database;
+
+  constructor(db: Database.Database) {
+    this.db = db;
+  }
+
+  /** Scan workspace and compare against stored file index. */
+  scanChanges(files: { relativePath: string; absolutePath: string }[]): ChangeSet {
+    const result: ChangeSet = { added: [], modified: [], deleted: [], unchanged: 0 };
+
+    const indexedPaths = new Set<string>();
+    const rows = this.db.prepare('SELECT path, content_hash, mtime FROM file_index').all() as {
+      path: string; content_hash: string; mtime: number;
+    }[];
+    const indexMap = new Map(rows.map(r => [r.path, r]));
+    for (const r of rows) indexedPaths.add(r.path);
+
+    for (const file of files) {
+      const indexed = indexMap.get(file.relativePath);
+
+      if (!indexed) {
+        result.added.push(file.relativePath);
+        continue;
+      }
+
+      indexedPaths.delete(file.relativePath);
+
+      try {
+        const stat = fs.statSync(file.absolutePath);
+        const mtime = Math.floor(stat.mtimeMs);
+
+        if (mtime !== indexed.mtime) {
+          const content = fs.readFileSync(file.absolutePath);
+          const hash = fnv1aHash(content);
+
+          if (hash !== indexed.content_hash) {
+            result.modified.push(file.relativePath);
+          } else {
+            this.updateMtime(file.relativePath, mtime);
+            result.unchanged++;
+          }
+        } else {
+          result.unchanged++;
+        }
+      } catch {
+        result.deleted.push(file.relativePath);
+      }
+    }
+
+    for (const deletedPath of indexedPaths) {
+      result.deleted.push(deletedPath);
+    }
+
+    return result;
+  }
+
+  /** Update file index entry after successful indexing. */
+  updateFileIndex(relativePath: string, absolutePath: string, symbolCount: number): void {
+    try {
+      const stat = fs.statSync(absolutePath);
+      const content = fs.readFileSync(absolutePath);
+      const hash = fnv1aHash(content);
+
+      this.db.prepare(`
+        INSERT OR REPLACE INTO file_index (path, mtime, content_hash, size_bytes, last_indexed, symbol_count)
+        VALUES (?, ?, ?, ?, datetime('now'), ?)
+      `).run(relativePath, Math.floor(stat.mtimeMs), hash, stat.size, symbolCount);
+    } catch (err) {
+      console.error(`[incremental-updater] Failed to update index for ${relativePath}:`, err);
+    }
+  }
+
+  /** Remove a file from the index. */
+  removeFromIndex(relativePath: string): void {
+    this.db.prepare('DELETE FROM file_index WHERE path = ?').run(relativePath);
+  }
+
+  /** Get total indexed file count. */
+  getIndexedCount(): number {
+    const row = this.db.prepare('SELECT COUNT(*) as count FROM file_index').get() as { count: number };
+    return row.count;
+  }
+
+  private updateMtime(relativePath: string, mtime: number): void {
+    this.db.prepare('UPDATE file_index SET mtime = ? WHERE path = ?').run(mtime, relativePath);
+  }
+}
+
+/** FNV-1a 32-bit hash for fast content comparison. */
+export function fnv1aHash(data: Buffer): string {
+  const FNV_OFFSET = 2166136261;
+  const FNV_PRIME = 16777619;
+  let hash = FNV_OFFSET;
+
+  for (let i = 0; i < data.length; i++) {
+    hash ^= data[i];
+    hash = Math.imul(hash, FNV_PRIME) >>> 0;
+  }
+
+  return hash.toString(16).padStart(8, '0');
+}

package/src/engine/database/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Database module barrel export.
+ * KSA-153: Graph storage
+ * KSA-169: Incremental updater + persistence
+ */
+
+export { GraphRepository } from './graph-repository.js';
+export type { CallerResult, CalleeResult, RelationshipInput } from './graph-repository.js';
+
+export { runGraphMigrations, isGraphSchemaReady } from './migrator.js';
+
+export { IncrementalUpdater, fnv1aHash } from './incremental-updater.js';
+export type { ChangeSet } from './incremental-updater.js';

package/src/engine/database/migrations/002-graph-schema.sql

@@ -0,0 +1,24 @@
+-- ============================================
+-- Migration 002: Graph Data Model
+-- Ticket: KSA-153
+-- ============================================
+
+-- Relationships table
+CREATE TABLE IF NOT EXISTS relationships (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    source_symbol_id INTEGER NOT NULL,
+    target_symbol TEXT NOT NULL,
+    target_symbol_id INTEGER,
+    kind TEXT NOT NULL CHECK(kind IN ('calls','imports','inherits','implements','uses','decorates')),
+    file_path TEXT NOT NULL,
+    line INTEGER NOT NULL,
+    metadata TEXT,
+    FOREIGN KEY (source_symbol_id) REFERENCES symbols(id) ON DELETE CASCADE,
+    FOREIGN KEY (target_symbol_id) REFERENCES symbols(id) ON DELETE SET NULL
+);
+
+-- Indexes for graph traversal
+CREATE INDEX IF NOT EXISTS idx_rel_source_kind ON relationships(source_symbol_id, kind);
+CREATE INDEX IF NOT EXISTS idx_rel_target_kind ON relationships(target_symbol, kind);
+CREATE INDEX IF NOT EXISTS idx_rel_target_id ON relationships(target_symbol_id) WHERE target_symbol_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_rel_file ON relationships(file_path);

package/src/engine/database/migrator.ts

@@ -0,0 +1,148 @@
+/**
+ * KSA-153: Schema Migrator — Applies graph schema migrations.
+ * Extends the existing migration system with graph-specific tables and columns.
+ */
+
+import Database from 'better-sqlite3';
+
+/** Enhanced symbol columns added for tree-sitter (KSA-145/153). */
+const ENHANCED_SYMBOL_COLUMNS = [
+  { name: 'parameters', type: 'TEXT' },
+  { name: 'return_type', type: 'TEXT' },
+  { name: 'parent_symbol_id', type: 'INTEGER' },
+  { name: 'decorators', type: 'TEXT' },
+  { name: 'complexity', type: 'INTEGER' },
+  { name: 'is_async', type: 'INTEGER DEFAULT 0' },
+  { name: 'is_exported', type: 'INTEGER DEFAULT 0' },
+  { name: 'doc_comment_full', type: 'TEXT' },
+  { name: 'modifiers', type: 'TEXT' },
+] as const;
+
+const GRAPH_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS relationships (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    source_symbol_id INTEGER NOT NULL,
+    target_symbol TEXT NOT NULL,
+    target_symbol_id INTEGER,
+    kind TEXT NOT NULL CHECK(kind IN ('calls','imports','inherits','implements','uses','decorates')),
+    file_path TEXT NOT NULL,
+    line INTEGER NOT NULL,
+    metadata TEXT,
+    FOREIGN KEY (source_symbol_id) REFERENCES symbols(id) ON DELETE CASCADE,
+    FOREIGN KEY (target_symbol_id) REFERENCES symbols(id) ON DELETE SET NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_rel_source_kind ON relationships(source_symbol_id, kind);
+CREATE INDEX IF NOT EXISTS idx_rel_target_kind ON relationships(target_symbol, kind);
+CREATE INDEX IF NOT EXISTS idx_rel_target_id ON relationships(target_symbol_id) WHERE target_symbol_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_rel_file ON relationships(file_path);
+`;
+
+const FILE_INDEX_SQL = `
+CREATE TABLE IF NOT EXISTS file_index (
+    path TEXT PRIMARY KEY,
+    mtime INTEGER NOT NULL,
+    content_hash TEXT NOT NULL,
+    size_bytes INTEGER NOT NULL,
+    last_indexed TEXT NOT NULL DEFAULT (datetime('now')),
+    symbol_count INTEGER DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS idx_file_index_hash ON file_index(content_hash);
+`;
+
+const GRAPH_META_SQL = `
+CREATE TABLE IF NOT EXISTS graph_meta (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+);
+
+INSERT OR IGNORE INTO graph_meta (key, value) VALUES
+    ('schema_version', '3'),
+    ('last_checkpoint', ''),
+    ('total_nodes', '0'),
+    ('total_edges', '0');
+`;
+
+const BODY_EMBEDDINGS_SQL = `
+CREATE TABLE IF NOT EXISTS body_embeddings (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    symbol_id INTEGER NOT NULL,
+    chunk_index INTEGER NOT NULL DEFAULT 0,
+    embedding BLOB NOT NULL,
+    token_count INTEGER NOT NULL,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    UNIQUE(symbol_id, chunk_index),
+    FOREIGN KEY (symbol_id) REFERENCES symbols(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_body_embeddings_symbol ON body_embeddings(symbol_id);
+`;
+
+/**
+ * Run graph-related migrations (KSA-153 + KSA-169).
+ * Safe to call multiple times — all operations are idempotent.
+ */
+export function runGraphMigrations(db: Database.Database): void {
+  console.error('[graph-migrator] Running graph schema migrations...');
+
+  addEnhancedSymbolColumns(db);
+  db.exec(GRAPH_SCHEMA_SQL);
+  console.error('[graph-migrator] Relationships table ready');
+
+  db.exec(FILE_INDEX_SQL);
+  console.error('[graph-migrator] File index table ready');
+
+  db.exec(GRAPH_META_SQL);
+  console.error('[graph-migrator] Graph metadata table ready');
+
+  db.exec(BODY_EMBEDDINGS_SQL);
+  console.error('[graph-migrator] Body embeddings table ready');
+
+  db.prepare('INSERT OR REPLACE INTO schema_version (version) VALUES (?)').run(3);
+  console.error('[graph-migrator] Schema version set to 3');
+}
+
+function addEnhancedSymbolColumns(db: Database.Database): void {
+  const existing = getExistingColumns(db, 'symbols');
+  let added = 0;
+
+  for (const col of ENHANCED_SYMBOL_COLUMNS) {
+    if (!existing.has(col.name)) {
+      try {
+        db.exec(`ALTER TABLE symbols ADD COLUMN ${col.name} ${col.type}`);
+        added++;
+      } catch {
+        // Column may already exist
+      }
+    }
+  }
+
+  if (added > 0) {
+    console.error(`[graph-migrator] Added ${added} enhanced symbol columns`);
+    try {
+      db.exec('CREATE INDEX IF NOT EXISTS idx_sym_parent ON symbols(parent_symbol_id) WHERE parent_symbol_id IS NOT NULL');
+      db.exec('CREATE INDEX IF NOT EXISTS idx_sym_exported ON symbols(is_exported) WHERE is_exported = 1');
+      db.exec('CREATE INDEX IF NOT EXISTS idx_sym_file_kind ON symbols(file_id, kind)');
+    } catch {
+      // Indexes may already exist
+    }
+  }
+}
+
+function getExistingColumns(db: Database.Database, table: string): Set<string> {
+  const rows = db.pragma(`table_info(${table})`) as { name: string }[];
+  return new Set(rows.map(r => r.name));
+}
+
+/** Check if graph migrations have been applied. */
+export function isGraphSchemaReady(db: Database.Database): boolean {
+  try {
+    const tables = db.prepare(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name='relationships'"
+    ).get();
+    return !!tables;
+  } catch {
+    return false;
+  }
+}