sdlc-agent-4-enterprise-server 1.0.0

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

@@ -0,0 +1,279 @@
+/**
+ * KSA-159: Edit Context Service — source + callers + tests + git for editing.
+ * Gathers everything needed before modifying a symbol.
+ */
+
+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 { TestDetector } from '../graph/test-detector.js';
+import { TokenBudgetManager } from './token-budget-manager.js';
+import { GitService } from './git-service.js';
+import {
+  EditContextParams, EditContextResult,
+  CallerContext, TestContext, SiblingContext, GitCommit, MemoryContext
+} from './types.js';
+
+interface ResolvedSymbolFull extends ResolvedSymbol {
+  endLine?: number;
+  signature?: string;
+}
+
+export class EditContextService {
+  private db: Database.Database;
+  private resolver: SymbolResolver;
+  private callGraph: CallGraphService;
+  private testDetector: TestDetector;
+  private gitService: GitService;
+  private budgetManager: TokenBudgetManager;
+  private workspace: string;
+
+  constructor(
+    db: Database.Database,
+    resolver: SymbolResolver,
+    callGraph: CallGraphService,
+    testDetector: TestDetector,
+    workspace: string
+  ) {
+    this.db = db;
+    this.resolver = resolver;
+    this.callGraph = callGraph;
+    this.testDetector = testDetector;
+    this.gitService = new GitService(workspace);
+    this.budgetManager = new TokenBudgetManager(4000);
+    this.workspace = workspace;
+  }
+
+  /** Get full edit context for a symbol. */
+  async getContext(params: EditContextParams): Promise<EditContextResult> {
+    const startTime = Date.now();
+    const {
+      symbol: symbolInput,
+      include_callers = true,
+      include_tests = true,
+      include_memories = false,
+      include_git = true,
+      token_budget = 4000,
+      caller_depth = 1
+    } = params;
+
+    // 1. Resolve symbol
+    const symbol = this.resolveSymbolInput(symbolInput);
+    if (!symbol) {
+      return this.symbolNotFoundResponse(symbolInput, token_budget, startTime);
+    }
+
+    // 2. Read source (always included)
+    const source = this.readSymbolSource(symbol);
+    const signature = this.getSignature(symbol);
+
+    // 3. Gather sections in parallel
+    const [callers, tests, gitHistory, siblings] = await Promise.all([
+      include_callers ? this.getCallerContext(symbol, caller_depth) : Promise.resolve(null),
+      include_tests ? this.getTestContext(symbol) : Promise.resolve(null),
+      include_git ? this.getGitContext(symbol) : Promise.resolve(null),
+      this.getSiblingContext(symbol)
+    ]);
+
+    // 4. Assemble within token budget
+    const sections: Record<string, { content: any; priority: number }> = {
+      source: { content: source, priority: 1 },
+    };
+    if (callers && callers.length > 0) sections.callers = { content: callers, priority: 2 };
+    if (tests && tests.length > 0) sections.tests = { content: tests, priority: 3 };
+    if (gitHistory && gitHistory.length > 0) sections.git_history = { content: gitHistory, priority: 5 };
+    if (siblings && siblings.length > 0) sections.siblings = { content: siblings, priority: 6 };
+
+    const assembled = this.budgetManager.assemble(sections, token_budget);
+
+    const result: EditContextResult = {
+      symbol: symbol.name,
+      file: symbol.filePath,
+      line: symbol.line,
+      kind: symbol.kind,
+      source: assembled.result.source || source,
+      signature,
+      metadata: {
+        tokenCount: assembled.tokenCount,
+        tokenBudget: token_budget,
+        sectionsIncluded: assembled.included,
+        sectionsExcluded: assembled.excluded,
+        queryTimeMs: Date.now() - startTime
+      }
+    };
+
+    if (assembled.result.callers) result.callers = assembled.result.callers;
+    if (assembled.result.tests) result.tests = assembled.result.tests;
+    if (assembled.result.git_history) result.git_history = assembled.result.git_history;
+    if (assembled.result.siblings) result.siblings = assembled.result.siblings;
+
+    return result;
+  }
+
+  private resolveSymbolInput(input: string): ResolvedSymbolFull | null {
+    // Try file:line format
+    if (input.includes(':') && /:\d+$/.test(input)) {
+      const colonIdx = input.lastIndexOf(':');
+      const file = input.substring(0, colonIdx);
+      const line = parseInt(input.substring(colonIdx + 1));
+      return this.findSymbolAtLine(file, line);
+    }
+
+    // Standard resolution
+    const resolved = this.resolver.resolve(input);
+    if (resolved.length === 0) return null;
+
+    // Enrich with end_line and signature
+    const sym = resolved[0];
+    const extra = this.db.prepare(`
+      SELECT end_line as endLine, signature FROM symbols WHERE id = ?
+    `).get(sym.id) as { endLine: number; signature: string } | undefined;
+
+    return {
+      ...sym,
+      endLine: extra?.endLine,
+      signature: extra?.signature || undefined
+    };
+  }
+
+  private findSymbolAtLine(file: string, line: number): ResolvedSymbolFull | null {
+    const row = this.db.prepare(`
+      SELECT s.id, s.name, s.kind, f.relative_path as filePath, s.start_line as line,
+             s.end_line as endLine, s.signature, s.parent_symbol_id as parentSymbolId
+      FROM symbols s
+      JOIN files f ON s.file_id = f.id
+      WHERE f.relative_path LIKE ? AND s.start_line <= ? AND s.end_line >= ?
+      ORDER BY (s.end_line - s.start_line) ASC
+      LIMIT 1
+    `).get(`%${file}`, line, line) as ResolvedSymbolFull | undefined;
+    return row || null;
+  }
+
+  private readSymbolSource(symbol: ResolvedSymbolFull): string {
+    try {
+      const fullPath = path.resolve(this.workspace, symbol.filePath);
+      const content = fs.readFileSync(fullPath, 'utf-8');
+      const lines = content.split('\n');
+      const start = symbol.line - 1;
+      const end = symbol.endLine || start + 50;
+      return lines.slice(start, end).join('\n');
+    } catch {
+      return '';
+    }
+  }
+
+  private getSignature(symbol: ResolvedSymbolFull): string | null {
+    if (symbol.signature) return symbol.signature;
+    const row = this.db.prepare(`SELECT signature FROM symbols WHERE id = ?`).get(symbol.id) as { signature: string | null } | undefined;
+    return row?.signature || null;
+  }
+
+  private async getCallerContext(symbol: ResolvedSymbolFull, depth: number): Promise<CallerContext[]> {
+    const result = this.callGraph.findCallers(symbol.name, depth, 10);
+
+    return result.results.map(caller => {
+      const context = this.getLineContext(caller.filePath, caller.callSiteLine, 2);
+      return {
+        symbol: caller.qualifiedName || caller.symbol,
+        file: caller.filePath,
+        line: caller.callSiteLine,
+        context
+      };
+    });
+  }
+
+  private getLineContext(file: string, line: number, surroundingLines: number): string {
+    try {
+      const fullPath = path.resolve(this.workspace, file);
+      const content = fs.readFileSync(fullPath, 'utf-8');
+      const lines = content.split('\n');
+      const start = Math.max(0, line - 1 - surroundingLines);
+      const end = Math.min(lines.length, line + surroundingLines);
+      return lines.slice(start, end).join('\n');
+    } catch {
+      return '';
+    }
+  }
+
+  private async getTestContext(symbol: ResolvedSymbolFull): Promise<TestContext[]> {
+    const testFiles = this.testDetector.findRelatedTests([symbol], []);
+    const results: TestContext[] = [];
+
+    for (const tf of testFiles.slice(0, 3)) {
+      try {
+        const fullPath = path.resolve(this.workspace, tf.file);
+        const content = fs.readFileSync(fullPath, 'utf-8');
+        const testBlocks = this.extractTestBlocks(content, symbol.name);
+        for (const block of testBlocks.slice(0, 2)) {
+          results.push({
+            file: tf.file,
+            testName: block.name,
+            source: block.source
+          });
+        }
+      } catch { /* skip unreadable files */ }
+    }
+
+    return results;
+  }
+
+  private extractTestBlocks(content: string, symbolName: string): Array<{ name: string; source: string }> {
+    const blocks: Array<{ name: string; source: string }> = [];
+    const lines = content.split('\n');
+
+    const testPattern = /(?:it|test|describe)\s*\(\s*['"`]([^'"`]*?)['"`]/;
+
+    for (let i = 0; i < lines.length; i++) {
+      const match = lines[i].match(testPattern);
+      if (match && (lines[i].includes(symbolName) || (i + 10 < lines.length && lines.slice(i, i + 10).join('\n').includes(symbolName)))) {
+        const name = match[1];
+        const end = Math.min(i + 15, lines.length);
+        const source = lines.slice(i, end).join('\n');
+        blocks.push({ name, source });
+      }
+    }
+
+    return blocks;
+  }
+
+  private async getGitContext(symbol: ResolvedSymbolFull): Promise<GitCommit[]> {
+    return this.gitService.getFileHistory(symbol.filePath, 5);
+  }
+
+  private async getSiblingContext(symbol: ResolvedSymbolFull): Promise<SiblingContext[]> {
+    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];
+
+    return (this.db.prepare(query).all(...params) as any[]).map(r => ({
+      name: r.name,
+      kind: r.kind,
+      signature: r.signature,
+      line: r.line
+    }));
+  }
+
+  private symbolNotFoundResponse(symbol: string, budget: number, startTime: number): EditContextResult {
+    return {
+      symbol,
+      file: '',
+      line: 0,
+      kind: 'unknown',
+      source: '',
+      signature: null,
+      metadata: {
+        tokenCount: 0,
+        tokenBudget: budget,
+        sectionsIncluded: [],
+        sectionsExcluded: ['error: symbol not found'],
+        queryTimeMs: Date.now() - startTime
+      }
+    };
+  }
+}

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

@@ -0,0 +1,48 @@
+/**
+ * KSA-159: Git Service — wraps git log for file history.
+ */
+
+import { execSync } from 'child_process';
+import { GitCommit } from './types.js';
+
+export class GitService {
+  private workspaceRoot: string;
+
+  constructor(workspaceRoot: string) {
+    this.workspaceRoot = workspaceRoot;
+  }
+
+  /** Get recent commit history for a file. */
+  getFileHistory(filePath: string, limit: number = 5): GitCommit[] {
+    try {
+      const output = execSync(
+        `git log --oneline --follow -n ${limit} -- "${filePath}"`,
+        { cwd: this.workspaceRoot, encoding: 'utf-8', timeout: 5000 }
+      );
+
+      return output.trim().split('\n').filter(Boolean).map(line => {
+        const spaceIdx = line.indexOf(' ');
+        return {
+          hash: line.substring(0, spaceIdx),
+          message: line.substring(spaceIdx + 1)
+        };
+      });
+    } catch {
+      return []; // Git not available or file not tracked
+    }
+  }
+
+  /** Check if git is available in the workspace. */
+  isAvailable(): boolean {
+    try {
+      execSync('git rev-parse --is-inside-work-tree', {
+        cwd: this.workspaceRoot,
+        encoding: 'utf-8',
+        timeout: 2000
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/engine/context/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Context module barrel export.
+ * KSA-158: AI Context, KSA-159: Edit Context, KSA-160: Curated Context
+ */
+
+export { AIContextService } from './ai-context-service.js';
+export { EditContextService } from './edit-context-service.js';
+export { CuratedContextService } from './curated-context-service.js';
+export { TokenBudgetManager } from './token-budget-manager.js';
+export { QueryAnalyzer } from './query-analyzer.js';
+export { RRFMerger } from './rrf-merger.js';
+export { BudgetAllocator } from './budget-allocator.js';
+export { GitService } from './git-service.js';
+export { getStrategy, getSupportedIntents } from './intent-strategies.js';
+export * from './types.js';

package/src/engine/context/intent-strategies.ts

@@ -0,0 +1,75 @@
+/**
+ * KSA-158: Intent Strategies — maps intent to prioritized section list.
+ */
+
+export interface SectionDef {
+  name: string;
+  priority: number;
+  format: 'full' | 'summary' | 'signatures';
+}
+
+export interface IntentStrategy {
+  intent: string;
+  sections: SectionDef[];
+}
+
+const STRATEGIES: Record<string, IntentStrategy> = {
+  explain: {
+    intent: 'explain',
+    sections: [
+      { name: 'source', priority: 1, format: 'full' },
+      { name: 'doc_comment', priority: 2, format: 'full' },
+      { name: 'siblings', priority: 3, format: 'signatures' },
+      { name: 'imports', priority: 4, format: 'full' },
+      { name: 'callers', priority: 5, format: 'summary' },
+      { name: 'callees', priority: 6, format: 'summary' },
+      { name: 'type_definitions', priority: 7, format: 'full' },
+    ]
+  },
+  modify: {
+    intent: 'modify',
+    sections: [
+      { name: 'source', priority: 1, format: 'full' },
+      { name: 'callers', priority: 2, format: 'full' },
+      { name: 'callees', priority: 3, format: 'full' },
+      { name: 'tests', priority: 4, format: 'full' },
+      { name: 'imports', priority: 5, format: 'full' },
+      { name: 'type_definitions', priority: 6, format: 'full' },
+      { name: 'siblings', priority: 7, format: 'signatures' },
+    ]
+  },
+  debug: {
+    intent: 'debug',
+    sections: [
+      { name: 'source', priority: 1, format: 'full' },
+      { name: 'callers', priority: 2, format: 'full' },
+      { name: 'error_patterns', priority: 3, format: 'full' },
+      { name: 'recent_changes', priority: 4, format: 'full' },
+      { name: 'imports', priority: 5, format: 'full' },
+      { name: 'siblings', priority: 6, format: 'signatures' },
+      { name: 'callees', priority: 7, format: 'summary' },
+    ]
+  },
+  test: {
+    intent: 'test',
+    sections: [
+      { name: 'source', priority: 1, format: 'full' },
+      { name: 'tests', priority: 2, format: 'full' },
+      { name: 'test_patterns', priority: 3, format: 'full' },
+      { name: 'callees', priority: 4, format: 'full' },
+      { name: 'type_definitions', priority: 5, format: 'full' },
+      { name: 'mocks_needed', priority: 6, format: 'full' },
+      { name: 'siblings', priority: 7, format: 'signatures' },
+    ]
+  }
+};
+
+/** Get the intent strategy (section priorities) for a given intent. Falls back to 'explain'. */
+export function getStrategy(intent: string): IntentStrategy {
+  return STRATEGIES[intent] || STRATEGIES.explain;
+}
+
+/** Get all supported intent names. */
+export function getSupportedIntents(): string[] {
+  return Object.keys(STRATEGIES);
+}

package/src/engine/context/query-analyzer.ts

@@ -0,0 +1,49 @@
+/**
+ * KSA-160: Query Analyzer — extracts keywords, symbol candidates, and phrases from NL queries.
+ */
+
+import { QueryAnalysis } from './types.js';
+
+const STOP_WORDS = new Set([
+  'how', 'does', 'the', 'is', 'what', 'where', 'when', 'a', 'an', 'in',
+  'for', 'to', 'of', 'and', 'or', 'not', 'this', 'that', 'with', 'from',
+  'are', 'was', 'were', 'been', 'being', 'have', 'has', 'had', 'do', 'did',
+  'will', 'would', 'could', 'should', 'may', 'might', 'can', 'shall',
+  'its', 'it', 'they', 'them', 'their', 'we', 'our', 'you', 'your',
+  'all', 'each', 'every', 'both', 'few', 'more', 'most', 'other', 'some',
+  'such', 'than', 'too', 'very', 'just', 'but', 'about', 'above', 'after',
+  'before', 'between', 'into', 'through', 'during', 'until', 'while'
+]);
+
+export class QueryAnalyzer {
+  /** Analyze a natural language query into search components. */
+  analyze(query: string): QueryAnalysis {
+    // Tokenize: lowercase, remove special chars, split
+    const tokens = query.toLowerCase()
+      .replace(/[^\w\s.\-_]/g, ' ')
+      .split(/\s+/)
+      .filter(t => t.length > 2 && !STOP_WORDS.has(t));
+
+    // Identify symbol candidates (camelCase, PascalCase, snake_case, dot.notation)
+    const symbolCandidates = query.match(
+      /[A-Z][a-zA-Z0-9]*(?:\.[a-zA-Z][a-zA-Z0-9]*)?|[a-z]+(?:_[a-z_]+)+|[a-z]+[A-Z][a-zA-Z0-9]*/g
+    ) || [];
+
+    // Extract bigrams for phrase search
+    const phrases: string[] = [];
+    for (let i = 0; i < tokens.length - 1; i++) {
+      phrases.push(`${tokens[i]} ${tokens[i + 1]}`);
+    }
+
+    // Build FTS query (OR-joined keywords)
+    const ftsQuery = tokens.length > 0 ? tokens.join(' OR ') : query;
+
+    return {
+      originalQuery: query,
+      keywords: tokens,
+      symbolCandidates,
+      phrases,
+      ftsQuery
+    };
+  }
+}

package/src/engine/context/rrf-merger.ts

@@ -0,0 +1,63 @@
+/**
+ * KSA-160: RRF Merger — Reciprocal Rank Fusion for merging multi-source results.
+ */
+
+import { SourceWeights, MergedResult } from './types.js';
+
+interface SourceResults {
+  source: string;
+  results: any[];
+}
+
+export class RRFMerger {
+  private k = 60; // RRF constant
+
+  /** Merge results from multiple sources using Reciprocal Rank Fusion. */
+  merge(
+    sources: { code: SourceResults; memory: SourceResults; graph: SourceResults },
+    weights?: SourceWeights
+  ): MergedResult[] {
+    const w = weights || { code: 0.5, memory: 0.3, graph: 0.2 };
+    const scores = new Map<string, { score: number; item: any; sources: string[] }>();
+
+    this.addScores(scores, sources.code.results, w.code, 'code');
+    this.addScores(scores, sources.memory.results, w.memory, 'memory');
+    this.addScores(scores, sources.graph.results, w.graph, 'graph');
+
+    return Array.from(scores.values())
+      .sort((a, b) => b.score - a.score)
+      .map(entry => ({
+        ...entry.item,
+        relevance_score: entry.score,
+        sources: entry.sources
+      }));
+  }
+
+  private addScores(
+    scores: Map<string, { score: number; item: any; sources: string[] }>,
+    results: any[],
+    weight: number,
+    source: string
+  ): void {
+    for (let rank = 0; rank < results.length; rank++) {
+      const item = results[rank];
+      const key = this.getKey(item);
+      const rrfScore = weight * (1 / (this.k + rank));
+
+      if (scores.has(key)) {
+        const existing = scores.get(key)!;
+        existing.score += rrfScore;
+        existing.sources.push(source);
+      } else {
+        scores.set(key, { score: rrfScore, item, sources: [source] });
+      }
+    }
+  }
+
+  private getKey(item: any): string {
+    if (item.id) return String(item.id);
+    if (item.name && item.file) return `${item.name}:${item.file}`;
+    if (item.name) return item.name;
+    return JSON.stringify(item).substring(0, 100);
+  }
+}

package/src/engine/context/token-budget-manager.ts

@@ -0,0 +1,129 @@
+/**
+ * KSA-158/159: Token Budget Manager — estimates tokens and assembles context within budget.
+ */
+
+export class TokenBudgetManager {
+  private budget: number;
+  private consumed: number = 0;
+
+  constructor(budget: number) {
+    this.budget = Math.max(budget, 500); // Minimum 500 tokens
+  }
+
+  /** Estimate token count for content (~4 chars per token). */
+  estimateTokens(content: any): number {
+    const text = typeof content === 'string' ? content : JSON.stringify(content);
+    return Math.ceil(text.length / 4);
+  }
+
+  /** Check if tokens can fit within remaining budget. */
+  canFit(tokens: number): boolean {
+    return this.consumed + tokens <= this.budget;
+  }
+
+  /** Consume tokens from budget. */
+  consume(tokens: number): void {
+    this.consumed += tokens;
+  }
+
+  /** Mark budget as fully consumed. */
+  consumeAll(): void {
+    this.consumed = this.budget;
+  }
+
+  /** Get remaining token budget. */
+  remaining(): number {
+    return Math.max(0, this.budget - this.consumed);
+  }
+
+  /** Get total tokens consumed. */
+  used(): number {
+    return this.consumed;
+  }
+
+  /** Check if budget is effectively exhausted (<50 tokens remaining). */
+  isExhausted(): boolean {
+    return this.remaining() < 50;
+  }
+
+  /** Truncate content to fit remaining budget. */
+  truncateToFit(content: any): any {
+    const maxChars = this.remaining() * 4;
+
+    if (typeof content === 'string') {
+      if (content.length <= maxChars) return content;
+      return content.substring(0, maxChars) + '\n... (truncated)';
+    }
+
+    if (Array.isArray(content)) {
+      let chars = 0;
+      const result: any[] = [];
+      for (const item of content) {
+        const itemStr = JSON.stringify(item);
+        if (chars + itemStr.length > maxChars) break;
+        result.push(item);
+        chars += itemStr.length;
+      }
+      return result;
+    }
+
+    const text = JSON.stringify(content);
+    if (text.length <= maxChars) return content;
+    return text.substring(0, maxChars);
+  }
+
+  /**
+   * Assemble multiple sections into a result within token budget.
+   * Sections are sorted by priority (lower = higher priority).
+   */
+  assemble(
+    sections: Record<string, { content: any; priority: number }>,
+    budget: number
+  ): { result: Record<string, any>; tokenCount: number; included: string[]; excluded: string[] } {
+    const sorted = Object.entries(sections)
+      .filter(([_, v]) => v.content != null)
+      .sort(([_, a], [__, b]) => a.priority - b.priority);
+
+    const result: Record<string, any> = {};
+    let usedTokens = 0;
+    const included: string[] = [];
+    const excluded: string[] = [];
+
+    for (const [key, { content }] of sorted) {
+      const tokens = this.estimateTokens(content);
+
+      if (usedTokens + tokens <= budget) {
+        result[key] = content;
+        usedTokens += tokens;
+        included.push(key);
+      } else if (Array.isArray(content) && content.length > 0) {
+        // Try truncation for arrays
+        const remaining = budget - usedTokens;
+        const truncated = this.truncateArray(content, remaining);
+        if (truncated.length > 0) {
+          result[key] = truncated;
+          usedTokens += this.estimateTokens(truncated);
+          included.push(`${key} (truncated: ${truncated.length}/${content.length})`);
+          continue;
+        }
+        excluded.push(key);
+      } else {
+        excluded.push(key);
+      }
+    }
+
+    return { result, tokenCount: usedTokens, included, excluded };
+  }
+
+  private truncateArray(arr: any[], tokenBudget: number): any[] {
+    const result: any[] = [];
+    let used = 0;
+    for (const item of arr) {
+      const tokens = this.estimateTokens(item);
+      if (used + tokens > tokenBudget) break;
+      result.push(item);
+      used += tokens;
+    }
+    return result;
+  }
+}