sdlc-agent-4-enterprise-server 1.0.0

package/src/engine/context/ai-context-service.ts

@@ -0,0 +1,302 @@
+/**
+ * KSA-158: AI Context Service — intent-aware context assembly with token budgeting.
+ * Orchestrates symbol resolution, section fetching, and budget management.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import Database from 'better-sqlite3';
+import { SymbolResolver, ResolvedSymbol } from '../graph/symbol-resolver.js';
+import { CallGraphService } from '../graph/call-graph-service.js';
+import { TokenBudgetManager } from './token-budget-manager.js';
+import { getStrategy, SectionDef } from './intent-strategies.js';
+import { GitService } from './git-service.js';
+import { AIContextParams, AIContextResponse } from './types.js';
+
+export class AIContextService {
+  private db: Database.Database;
+  private resolver: SymbolResolver;
+  private callGraph: CallGraphService;
+  private gitService: GitService;
+  private workspace: string;
+
+  constructor(
+    db: Database.Database,
+    resolver: SymbolResolver,
+    callGraph: CallGraphService,
+    workspace: string
+  ) {
+    this.db = db;
+    this.resolver = resolver;
+    this.callGraph = callGraph;
+    this.gitService = new GitService(workspace);
+    this.workspace = workspace;
+  }
+
+  /** Get intent-aware context for a symbol within token budget. */
+  async getContext(params: AIContextParams): Promise<AIContextResponse> {
+    const startTime = Date.now();
+    const { symbol, intent = 'explain', token_budget = 4000, caller_depth = 1 } = params;
+
+    // 1. Resolve symbol
+    const resolved = this.resolver.resolve(symbol);
+    if (resolved.length === 0) {
+      return this.notFoundResponse(symbol, intent, token_budget, startTime);
+    }
+
+    const targetSymbol = resolved[0];
+
+    // 2. Get intent strategy
+    const strategy = getStrategy(intent);
+
+    // 3. Assemble context with budget
+    const budgetManager = new TokenBudgetManager(token_budget);
+    const context: Record<string, any> = {};
+    const sectionsIncluded: string[] = [];
+    const sectionsOmitted: string[] = [];
+
+    for (const section of strategy.sections) {
+      if (budgetManager.isExhausted()) {
+        sectionsOmitted.push(section.name);
+        continue;
+      }
+
+      const content = this.fetchSection(section, targetSymbol, caller_depth);
+      if (content == null) {
+        continue; // Section not available
+      }
+
+      const tokens = budgetManager.estimateTokens(content);
+
+      if (budgetManager.canFit(tokens)) {
+        context[section.name] = content;
+        budgetManager.consume(tokens);
+        sectionsIncluded.push(section.name);
+      } else if (budgetManager.remaining() > 100) {
+        // Partial fit
+        const truncated = budgetManager.truncateToFit(content);
+        context[section.name] = truncated;
+        context[`${section.name}_truncated`] = true;
+        budgetManager.consumeAll();
+        sectionsIncluded.push(section.name);
+      } else {
+        sectionsOmitted.push(section.name);
+      }
+    }
+
+    return {
+      symbol: targetSymbol.name,
+      file_path: targetSymbol.filePath,
+      kind: targetSymbol.kind,
+      intent,
+      context,
+      metadata: {
+        budget_used: budgetManager.used(),
+        budget_total: token_budget,
+        sections_included: sectionsIncluded,
+        sections_omitted: sectionsOmitted,
+        query_time_ms: Date.now() - startTime
+      }
+    };
+  }
+
+  private fetchSection(section: SectionDef, symbol: ResolvedSymbol, callerDepth: number): any {
+    try {
+      switch (section.name) {
+        case 'source':
+          return this.fetchSource(symbol);
+        case 'callers':
+          return this.fetchCallers(symbol, callerDepth, section.format);
+        case 'callees':
+          return this.fetchCallees(symbol, callerDepth);
+        case 'siblings':
+          return this.fetchSiblings(symbol);
+        case 'imports':
+          return this.fetchImports(symbol);
+        case 'tests':
+          return this.fetchRelatedTests(symbol);
+        case 'type_definitions':
+          return this.fetchTypeDefinitions(symbol);
+        case 'doc_comment':
+          return this.fetchDocComment(symbol);
+        case 'error_patterns':
+          return this.fetchErrorPatterns(symbol);
+        case 'recent_changes':
+          return this.fetchRecentChanges(symbol);
+        case 'test_patterns':
+          return this.fetchTestPatterns(symbol);
+        case 'mocks_needed':
+          return this.fetchMocksNeeded(symbol);
+        default:
+          return null;
+      }
+    } catch {
+      return null; // Section fetch failed, skip gracefully
+    }
+  }
+
+  private fetchSource(symbol: ResolvedSymbol): string | null {
+    try {
+      const fullPath = path.resolve(this.workspace, symbol.filePath);
+      if (!fs.existsSync(fullPath)) return null;
+      const content = fs.readFileSync(fullPath, 'utf-8');
+      const lines = content.split('\n');
+      const startLine = symbol.line - 1;
+      const endLine = this.getSymbolEndLine(symbol) || startLine + 50;
+      return lines.slice(startLine, endLine).join('\n');
+    } catch {
+      return null;
+    }
+  }
+
+  private fetchCallers(symbol: ResolvedSymbol, depth: number, format: string): any {
+    const result = this.callGraph.findCallers(symbol.name, depth, 10);
+    if (result.results.length === 0) return null;
+
+    if (format === 'summary') {
+      return result.results.map(r => `${r.symbol} (${r.filePath}:${r.callSiteLine})`);
+    }
+    return result.results.map(r => ({
+      symbol: r.symbol,
+      file: r.filePath,
+      line: r.callSiteLine,
+      kind: r.kind
+    }));
+  }
+
+  private fetchCallees(symbol: ResolvedSymbol, depth: number): any {
+    const result = this.callGraph.findCallees(symbol.name, depth, 10);
+    if (result.results.length === 0) return null;
+    return result.results.map(r => ({
+      symbol: r.symbol,
+      file: r.filePath,
+      line: r.callSiteLine,
+      kind: r.kind
+    }));
+  }
+
+  private fetchSiblings(symbol: ResolvedSymbol): any {
+    const query = symbol.parentSymbolId
+      ? `SELECT name, kind, signature, start_line as line FROM symbols WHERE parent_symbol_id = ? AND id != ? ORDER BY start_line`
+      : `SELECT s.name, s.kind, s.signature, s.start_line as line FROM symbols s JOIN files f ON s.file_id = f.id WHERE f.relative_path = ? AND s.parent_symbol_id IS NULL AND s.id != ? ORDER BY s.start_line`;
+
+    const params = symbol.parentSymbolId
+      ? [symbol.parentSymbolId, symbol.id]
+      : [symbol.filePath, symbol.id];
+
+    const rows = this.db.prepare(query).all(...params) as any[];
+    if (rows.length === 0) return null;
+    return rows.map(r => ({ name: r.name, kind: r.kind, signature: r.signature, line: r.line }));
+  }
+
+  private fetchImports(symbol: ResolvedSymbol): any {
+    const rows = this.db.prepare(`
+      SELECT DISTINCT r.target_symbol as name, r.file_path
+      FROM relationships r
+      WHERE r.source_symbol_id = ? AND r.kind = 'imports'
+    `).all(symbol.id) as any[];
+    if (rows.length === 0) return null;
+    return rows.map(r => r.name);
+  }
+
+  private fetchRelatedTests(symbol: ResolvedSymbol): any {
+    const rows = this.db.prepare(`
+      SELECT DISTINCT f.relative_path as file_path
+      FROM relationships r
+      JOIN files f ON r.file_path = f.relative_path
+      WHERE r.target_symbol LIKE ?
+      AND (f.relative_path LIKE '%test%' OR f.relative_path LIKE '%spec%')
+      LIMIT 5
+    `).all(`%${symbol.name}%`) as any[];
+    if (rows.length === 0) return null;
+    return rows.map(r => r.file_path);
+  }
+
+  private fetchTypeDefinitions(symbol: ResolvedSymbol): any {
+    const rows = this.db.prepare(`
+      SELECT DISTINCT s.name, s.kind, s.signature, f.relative_path as file
+      FROM relationships r
+      JOIN symbols s ON s.id = r.target_symbol_id
+      JOIN files f ON s.file_id = f.id
+      WHERE r.source_symbol_id = ? AND s.kind IN ('interface', 'type_alias', 'enum', 'class')
+      LIMIT 10
+    `).all(symbol.id) as any[];
+    if (rows.length === 0) return null;
+    return rows;
+  }
+
+  private fetchDocComment(symbol: ResolvedSymbol): string | null {
+    const row = this.db.prepare(`
+      SELECT doc_comment FROM symbols WHERE id = ?
+    `).get(symbol.id) as { doc_comment: string | null } | undefined;
+    return row?.doc_comment || null;
+  }
+
+  private fetchErrorPatterns(symbol: ResolvedSymbol): any {
+    const source = this.fetchSource(symbol);
+    if (!source) return null;
+
+    const patterns: any[] = [];
+    const lines = source.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+      if (line.startsWith('throw ')) patterns.push({ type: 'throw', line: i + 1, text: line });
+      if (line.startsWith('catch')) patterns.push({ type: 'catch', line: i + 1, text: line });
+      if (line.includes('.catch(')) patterns.push({ type: 'promise-catch', line: i + 1, text: line });
+    }
+    return patterns.length > 0 ? patterns : null;
+  }
+
+  private fetchRecentChanges(symbol: ResolvedSymbol): any {
+    const commits = this.gitService.getFileHistory(symbol.filePath, 5);
+    return commits.length > 0 ? commits : null;
+  }
+
+  private fetchTestPatterns(symbol: ResolvedSymbol): any {
+    const rows = this.db.prepare(`
+      SELECT DISTINCT s.name, s.signature
+      FROM symbols s
+      JOIN files f ON s.file_id = f.id
+      WHERE (f.relative_path LIKE '%test%' OR f.relative_path LIKE '%spec%')
+      AND s.kind = 'function'
+      AND f.module = (SELECT module FROM files WHERE relative_path = ?)
+      LIMIT 10
+    `).all(symbol.filePath) as any[];
+    if (rows.length === 0) return null;
+    return rows.map(r => r.name);
+  }
+
+  private fetchMocksNeeded(symbol: ResolvedSymbol): any {
+    const result = this.callGraph.findCallees(symbol.name, 1, 20);
+    if (result.results.length === 0) return null;
+
+    const externalDeps = result.results
+      .filter(r => r.filePath !== symbol.filePath && r.filePath !== '(external)')
+      .map(r => ({ symbol: r.symbol, file: r.filePath }));
+
+    return externalDeps.length > 0 ? externalDeps : null;
+  }
+
+  private getSymbolEndLine(symbol: ResolvedSymbol): number | null {
+    const row = this.db.prepare(`SELECT end_line FROM symbols WHERE id = ?`).get(symbol.id) as { end_line: number } | undefined;
+    return row?.end_line || null;
+  }
+
+  private notFoundResponse(symbol: string, intent: string, budget: number, startTime: number): AIContextResponse {
+    const suggestions = this.resolver.suggest(symbol);
+    return {
+      symbol,
+      file_path: '',
+      kind: 'unknown',
+      intent,
+      context: { error: `Symbol "${symbol}" not found`, suggestions },
+      metadata: {
+        budget_used: 0,
+        budget_total: budget,
+        sections_included: [],
+        sections_omitted: [],
+        query_time_ms: Date.now() - startTime
+      }
+    };
+  }
+}

package/src/engine/context/budget-allocator.ts

@@ -0,0 +1,66 @@
+/**
+ * KSA-160: Budget Allocator — allocates token budget across ranked results.
+ * Top results get full source, middle get signatures, bottom get references.
+ */
+
+import { MergedResult, ContextItem } from './types.js';
+
+export interface AllocatedResult extends MergedResult {
+  detail: 'full' | 'signature' | 'reference';
+  content: string;
+  tokens: number;
+}
+
+export class BudgetAllocator {
+  private CHARS_PER_TOKEN = 4;
+
+  /** Allocate token budget across merged results with progressive detail levels. */
+  allocate(results: MergedResult[], maxTokens: number): AllocatedResult[] {
+    const allocated: AllocatedResult[] = [];
+    let tokensUsed = 100; // Response overhead
+
+    const highThreshold = Math.max(1, Math.ceil(results.length * 0.2));
+    const medThreshold = Math.ceil(results.length * 0.6);
+
+    for (let i = 0; i < results.length; i++) {
+      if (tokensUsed >= maxTokens) break;
+
+      const result = results[i];
+      let detail: 'full' | 'signature' | 'reference';
+      let content: string;
+      let tokens: number;
+
+      if (i < highThreshold) {
+        detail = 'full';
+        content = result.source_code || result.content || result.signature || result.name;
+        tokens = this.estimateTokens(content);
+      } else if (i < medThreshold) {
+        detail = 'signature';
+        content = result.signature || result.name;
+        tokens = this.estimateTokens(content);
+      } else {
+        detail = 'reference';
+        content = `${result.name} (${result.file || 'unknown'}:${result.line || 0})`;
+        tokens = 15;
+      }
+
+      // Downgrade if exceeds budget
+      if (tokensUsed + tokens > maxTokens && detail === 'full') {
+        detail = 'signature';
+        content = result.signature || result.name;
+        tokens = this.estimateTokens(content);
+      }
+
+      if (tokensUsed + tokens <= maxTokens) {
+        allocated.push({ ...result, detail, content, tokens });
+        tokensUsed += tokens;
+      }
+    }
+
+    return allocated;
+  }
+
+  private estimateTokens(text: string): number {
+    return Math.ceil(text.length / this.CHARS_PER_TOKEN);
+  }
+}

package/src/engine/context/curated-context-service.ts

@@ -0,0 +1,268 @@
+/**
+ * KSA-160: Curated Context Service — NL query → parallel search → RRF merge → budget allocation.
+ */
+
+import Database from 'better-sqlite3';
+import { QueryAnalyzer } from './query-analyzer.js';
+import { RRFMerger } from './rrf-merger.js';
+import { BudgetAllocator, AllocatedResult } from './budget-allocator.js';
+import { SymbolResolver } from '../graph/symbol-resolver.js';
+import { GraphTraverser } from '../graph/traverser.js';
+import { QueryLayer } from '../query/query-layer.js';
+import {
+  CuratedContextParams, CuratedContextResponse, ContextSection, ContextItem,
+  SourceWeights, MergedResult
+} from './types.js';
+
+export class CuratedContextService {
+  private analyzer: QueryAnalyzer;
+  private merger: RRFMerger;
+  private allocator: BudgetAllocator;
+  private db: Database.Database;
+  private queryLayer: QueryLayer;
+  private traverser: GraphTraverser;
+  private resolver: SymbolResolver;
+
+  constructor(
+    db: Database.Database,
+    queryLayer: QueryLayer,
+    traverser: GraphTraverser,
+    resolver: SymbolResolver
+  ) {
+    this.analyzer = new QueryAnalyzer();
+    this.merger = new RRFMerger();
+    this.allocator = new BudgetAllocator();
+    this.db = db;
+    this.queryLayer = queryLayer;
+    this.traverser = traverser;
+    this.resolver = resolver;
+  }
+
+  /** Execute curated context search with NL query. */
+  async getContext(params: CuratedContextParams): Promise<CuratedContextResponse> {
+    const startTime = Date.now();
+    const {
+      query,
+      max_tokens = 4000,
+      include_source = true,
+      include_memory = true,
+      include_graph = true,
+      source_weights
+    } = params;
+
+    // 1. Analyze query
+    const analysis = this.analyzer.analyze(query);
+
+    // 2. Parallel search
+    const [codeResults, memoryResults] = await Promise.all([
+      include_source ? this.searchCode(analysis) : Promise.resolve({ source: 'code', results: [] }),
+      include_memory ? this.searchMemory(analysis) : Promise.resolve({ source: 'memory', results: [] })
+    ]);
+
+    // 3. Graph expansion (depends on code results)
+    let graphResults = { source: 'graph', results: [] as any[] };
+    if (include_graph && codeResults.results.length > 0) {
+      graphResults = await this.expandGraph(codeResults.results.slice(0, 5));
+    }
+
+    // 4. Merge with RRF
+    const merged = this.merger.merge(
+      { code: codeResults, memory: memoryResults, graph: graphResults },
+      source_weights
+    );
+
+    // 5. Allocate token budget
+    const allocated = this.allocator.allocate(merged, max_tokens);
+
+    // 6. Format response
+    const sections = this.formatSections(allocated);
+    const tokensUsed = allocated.reduce((sum, r) => sum + r.tokens, 0) + 100;
+
+    return {
+      query,
+      sections,
+      metadata: {
+        tokens_used: tokensUsed,
+        tokens_budget: max_tokens,
+        sources_queried: [
+          ...(include_source ? ['code'] : []),
+          ...(include_memory ? ['memory'] : []),
+          ...(include_graph ? ['graph'] : [])
+        ],
+        total_candidates: codeResults.results.length + memoryResults.results.length + graphResults.results.length,
+        results_returned: allocated.length,
+        execution_time_ms: Date.now() - startTime
+      }
+    };
+  }
+
+  private async searchCode(analysis: { ftsQuery: string; symbolCandidates: string[] }): Promise<{ source: string; results: any[] }> {
+    try {
+      const ftsResults = this.queryLayer.searchCode(analysis.ftsQuery, 30);
+
+      // Also try direct symbol resolution for candidates
+      const symbolResults: any[] = [];
+      for (const candidate of analysis.symbolCandidates.slice(0, 5)) {
+        const resolved = this.resolver.resolve(candidate);
+        for (const sym of resolved.slice(0, 3)) {
+          symbolResults.push({
+            id: sym.id,
+            name: sym.name,
+            kind: sym.kind,
+            file: sym.filePath,
+            line: sym.line,
+            signature: null
+          });
+        }
+      }
+
+      // Combine FTS + symbol results (mini-RRF)
+      const combined = this.miniRRF(
+        ftsResults.map(r => ({
+          id: undefined,
+          name: r.name,
+          kind: r.kind,
+          file: r.filePath,
+          line: r.startLine,
+          signature: r.signature,
+          source_code: null
+        })),
+        symbolResults
+      );
+
+      return { source: 'code', results: combined.slice(0, 20) };
+    } catch {
+      return { source: 'code', results: [] };
+    }
+  }
+
+  private async searchMemory(analysis: { ftsQuery: string; keywords: string[] }): Promise<{ source: string; results: any[] }> {
+    try {
+      // Search memory/KB using FTS on knowledge entries
+      const query = analysis.keywords.slice(0, 5).join(' ');
+      const rows = this.db.prepare(`
+        SELECT id, content, summary, type, tags, created_at
+        FROM knowledge_entries
+        WHERE id IN (
+          SELECT rowid FROM knowledge_fts WHERE knowledge_fts MATCH ?
+        )
+        ORDER BY created_at DESC
+        LIMIT 10
+      `).all(query) as any[];
+
+      return {
+        source: 'memory',
+        results: rows.map(r => ({
+          id: r.id,
+          name: r.summary || r.content?.substring(0, 50) || 'entry',
+          kind: r.type || 'memory',
+          content: r.summary || r.content?.substring(0, 200),
+          file: undefined,
+          line: undefined
+        }))
+      };
+    } catch {
+      // KB tables may not exist
+      return { source: 'memory', results: [] };
+    }
+  }
+
+  private async expandGraph(topSymbols: any[]): Promise<{ source: string; results: any[] }> {
+    const expanded: any[] = [];
+    const seen = new Set<string>();
+
+    for (const symbol of topSymbols) {
+      try {
+        const startNode = this.traverser.resolveNode(symbol.name);
+        if (!startNode) continue;
+
+        const results = this.traverser.traverse(startNode, {
+          edgeTypes: ['calls', 'imports', 'inherits'],
+          nodeTypes: [],
+          direction: 'both',
+          maxDepth: 1,
+          maxResults: 5
+        });
+
+        for (const r of results) {
+          const key = `${r.node.name}:${r.node.filePath}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+
+          expanded.push({
+            id: r.node.id,
+            name: r.node.name,
+            kind: r.node.kind,
+            file: r.node.filePath,
+            line: r.node.startLine,
+            relationship: `${r.edgeType} ${symbol.name}`
+          });
+        }
+      } catch {
+        // Skip if symbol not in graph
+      }
+    }
+
+    return { source: 'graph', results: expanded };
+  }
+
+  private miniRRF(listA: any[], listB: any[]): any[] {
+    const k = 60;
+    const scores = new Map<string, { score: number; item: any }>();
+
+    for (let i = 0; i < listA.length; i++) {
+      const key = listA[i].name + ':' + (listA[i].file || '');
+      scores.set(key, { score: 1 / (k + i), item: listA[i] });
+    }
+
+    for (let i = 0; i < listB.length; i++) {
+      const key = listB[i].name + ':' + (listB[i].file || '');
+      if (scores.has(key)) {
+        scores.get(key)!.score += 1 / (k + i);
+      } else {
+        scores.set(key, { score: 1 / (k + i), item: listB[i] });
+      }
+    }
+
+    return Array.from(scores.values())
+      .sort((a, b) => b.score - a.score)
+      .map(e => e.item);
+  }
+
+  private formatSections(allocated: AllocatedResult[]): ContextSection[] {
+    const bySource = new Map<string, ContextItem[]>();
+
+    for (const item of allocated) {
+      const source = (item.sources?.[0] || 'code') as 'code' | 'memory' | 'graph';
+      if (!bySource.has(source)) bySource.set(source, []);
+
+      bySource.get(source)!.push({
+        name: item.name,
+        kind: item.kind,
+        file: item.file,
+        line: item.line,
+        relevance: item.relevance_score,
+        detail: item.detail,
+        content: item.content,
+        relationship: item.relationship
+      });
+    }
+
+    const sections: ContextSection[] = [];
+    const titleMap: Record<string, string> = {
+      code: 'Code Symbols',
+      memory: 'Knowledge Base',
+      graph: 'Related (Graph)'
+    };
+
+    for (const [source, items] of bySource) {
+      sections.push({
+        title: titleMap[source] || source,
+        source: source as 'code' | 'memory' | 'graph',
+        items
+      });
+    }
+
+    return sections;
+  }
+}