forge-server 0.1.0

package/src/context/codebase.ts

@@ -0,0 +1,393 @@
+// CodebaseContext — B7
+//
+// Wraps the local hybrid-search + file-cache modules so that the ContextInjector
+// can retrieve codebase context without coupling to the query internals directly.
+//
+// When either graph or vector store is unavailable the class degrades gracefully:
+//   - If vectorStore is null/unhealthy:  returns empty pivot files and a warning.
+//   - If graphStore is null/unhealthy:   falls back to vector-only search.
+//   - If fileCache is null:              returns file paths without content.
+
+import type { VectorStore, GraphStore, FileContentCache } from '../storage/interfaces.js';
+import type { RepoSharing } from '../util/types.js';
+import { hybridSearch } from '../query/hybrid-search.js';
+import { estimateTokens } from '../util/token-counter.js';
+import { logger } from '../util/logger.js';
+import { readFileSync, existsSync } from 'node:fs';
+
+/**
+ * Resolves the sharing mode for a given repo ID.
+ * Returns undefined if the repo is not found.
+ */
+export type SharingResolver = (repoId: string) => RepoSharing | undefined;
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface CodebaseContextOptions {
+  repoId?: string;
+  detail?: 'full' | 'skeleton' | 'paths';
+  maxResults?: number;
+  includeTests?: boolean;
+  includeCrossRepo?: boolean;
+  maxTokens?: number;
+  vectorWeight?: number;   // from intent strategy, default 0.6
+  graphWeight?: number;    // from intent strategy, default 0.3
+}
+
+export interface PivotFile {
+  filePath: string;
+  content: string;
+  relevanceScore: number;
+  matchReason: string;
+}
+
+export interface SupportingSkeleton {
+  filePath: string;
+  skeleton: string;
+  relevanceScore: number;
+}
+
+export interface CodebaseContextResult {
+  pivotFiles: PivotFile[];
+  supportingSkeletons: SupportingSkeleton[];
+  warnings: string[];
+  tokenCount: number;
+  executionTimeMs: number;
+}
+
+// ---------------------------------------------------------------------------
+// CodebaseContext
+// ---------------------------------------------------------------------------
+
+export class CodebaseContext {
+  constructor(
+    private readonly graphStore: GraphStore | null,
+    private readonly vectorStore: VectorStore | null,
+    private readonly fileCache: FileContentCache | null,
+    private readonly sharingResolver?: SharingResolver,
+  ) {}
+
+  /**
+   * Retrieve codebase context for a natural-language query.
+   * Uses hybrid search (vector + graph) when both stores are available.
+   * Falls back to vector-only when graph is down.
+   * Returns empty results with warnings when vector store is unavailable.
+   */
+  async getContext(
+    query: string,
+    options: CodebaseContextOptions = {},
+  ): Promise<CodebaseContextResult> {
+    const startTime = Date.now();
+    const warnings: string[] = [];
+    const {
+      repoId,
+      detail = 'full',
+      maxResults = 10,
+      includeTests = false,
+      includeCrossRepo = true,
+      maxTokens = 8000,
+      vectorWeight,
+      graphWeight,
+    } = options;
+
+    // Guard: no vector store means no code search at all
+    if (!this.vectorStore) {
+      return {
+        pivotFiles: [],
+        supportingSkeletons: [],
+        warnings: ['Vector store not configured — codebase context unavailable'],
+        tokenCount: 0,
+        executionTimeMs: Date.now() - startTime,
+      };
+    }
+
+    const vectorHealthy = await this.vectorStore.isHealthy();
+    if (!vectorHealthy) {
+      return {
+        pivotFiles: [],
+        supportingSkeletons: [],
+        warnings: ['Vector store (Qdrant) is unavailable — codebase context unavailable'],
+        tokenCount: 0,
+        executionTimeMs: Date.now() - startTime,
+      };
+    }
+
+    const graphHealthy = this.graphStore
+      ? await this.graphStore.isHealthy()
+      : false;
+    if (!graphHealthy) {
+      warnings.push('Graph store (FalkorDB) is unavailable — using vector-only search');
+    }
+
+    // Use a no-op graph store when graph is unhealthy to satisfy hybridSearch signature
+    const effectiveGraph = graphHealthy && this.graphStore
+      ? this.graphStore
+      : createNullGraphStore();
+
+    let searchResults;
+    try {
+      searchResults = await hybridSearch(
+        this.vectorStore,
+        effectiveGraph,
+        {
+          query,
+          repoId,
+          limit: maxResults * 2, // fetch extra to fill budget after skeletons split
+          includeTests,
+          vectorWeight,
+          graphWeight,
+        },
+      );
+    } catch (err) {
+      logger.warn('CodebaseContext: hybrid search failed', { error: String(err) });
+      return {
+        pivotFiles: [],
+        supportingSkeletons: [],
+        warnings: [`Search failed: ${String(err)}`],
+        tokenCount: 0,
+        executionTimeMs: Date.now() - startTime,
+      };
+    }
+
+    // Sharing enforcement: filter out results from private repos that aren't
+    // the caller's own repo. Only applies when includeCrossRepo is true and
+    // a sharingResolver is available.
+    if (includeCrossRepo && this.sharingResolver && repoId) {
+      const sharingCache = new Map<string, RepoSharing | undefined>();
+      searchResults.results = searchResults.results.filter(r => {
+        // Own repo results always pass
+        if (r.repoId === repoId) return true;
+
+        // Look up sharing for the result's repo
+        if (!sharingCache.has(r.repoId)) {
+          sharingCache.set(r.repoId, this.sharingResolver!(r.repoId));
+        }
+        const sharing = sharingCache.get(r.repoId);
+
+        // Only include results from team/public repos
+        return sharing === 'team' || sharing === 'public';
+      });
+    } else if (includeCrossRepo && this.sharingResolver && !repoId) {
+      // No caller repo context — only allow team/public repos
+      const sharingCache = new Map<string, RepoSharing | undefined>();
+      searchResults.results = searchResults.results.filter(r => {
+        if (!sharingCache.has(r.repoId)) {
+          sharingCache.set(r.repoId, this.sharingResolver!(r.repoId));
+        }
+        const sharing = sharingCache.get(r.repoId);
+        return sharing === 'team' || sharing === 'public';
+      });
+    }
+
+    const pivotFiles: PivotFile[] = [];
+    const supportingSkeletons: SupportingSkeleton[] = [];
+    let usedTokens = 0;
+    const tokenBudget = maxTokens;
+
+    for (const result of searchResults.results.slice(0, maxResults)) {
+      const { filePath, finalScore, matchReason } = result;
+
+      if (detail === 'paths') {
+        // No content — just return file paths as minimal pivot entries
+        pivotFiles.push({
+          filePath,
+          content: '',
+          relevanceScore: Math.round(finalScore * 1000) / 1000,
+          matchReason,
+        });
+        continue;
+      }
+
+      // Try to read file content
+      const content = this.readFile(filePath, repoId);
+      if (content === null) {
+        // File not readable — add as skeleton with just the path
+        supportingSkeletons.push({
+          filePath,
+          skeleton: `// File not readable: ${filePath}`,
+          relevanceScore: Math.round(finalScore * 1000) / 1000,
+        });
+        continue;
+      }
+
+      const contentTokens = estimateTokens(content);
+
+      if (detail === 'full' && usedTokens + contentTokens <= tokenBudget) {
+        pivotFiles.push({
+          filePath,
+          content,
+          relevanceScore: Math.round(finalScore * 1000) / 1000,
+          matchReason,
+        });
+        usedTokens += contentTokens;
+      } else if (detail === 'skeleton' || usedTokens + contentTokens > tokenBudget) {
+        // Build a structural skeleton (exports and top-level declarations only)
+        const skeleton = buildSkeleton(content, filePath);
+        const skeletonTokens = estimateTokens(skeleton);
+
+        if (usedTokens + skeletonTokens <= tokenBudget) {
+          supportingSkeletons.push({
+            filePath,
+            skeleton,
+            relevanceScore: Math.round(finalScore * 1000) / 1000,
+          });
+          usedTokens += skeletonTokens;
+        }
+        // If even the skeleton is too big, omit this file entirely
+      }
+    }
+
+    const tokenCount = pivotFiles.reduce(
+      (sum, f) => sum + estimateTokens(f.content),
+      0,
+    ) + supportingSkeletons.reduce(
+      (sum, s) => sum + estimateTokens(s.skeleton),
+      0,
+    );
+
+    logger.debug('CodebaseContext: context assembled', {
+      query: query.slice(0, 50),
+      pivots: pivotFiles.length,
+      skeletons: supportingSkeletons.length,
+      tokenCount,
+      durationMs: Date.now() - startTime,
+    });
+
+    return {
+      pivotFiles,
+      supportingSkeletons,
+      warnings,
+      tokenCount,
+      executionTimeMs: Date.now() - startTime,
+    };
+  }
+
+  /** True when at least the vector store is configured and reachable. */
+  isAvailable(): boolean {
+    // Synchronous best-effort check — callers that need precision should await getContext()
+    return this.vectorStore !== null;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Read file content. Checks cache first; falls back to disk read.
+   * Returns null if the file cannot be read.
+   */
+  private readFile(filePath: string, repoId?: string): string | null {
+    // Try cache first
+    if (this.fileCache && repoId) {
+      const cached = this.fileCache.get(repoId, filePath);
+      if (cached) return cached.content;
+    }
+
+    // Disk read
+    try {
+      if (!existsSync(filePath)) return null;
+      const content = readFileSync(filePath, 'utf8');
+
+      // Populate cache for future hits
+      if (this.fileCache && repoId) {
+        this.fileCache.set(repoId, filePath, content, '');
+      }
+
+      return content;
+    } catch {
+      return null;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Skeleton builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a token-efficient skeleton of a TypeScript/JavaScript file.
+ * Extracts export declarations, class names, function signatures, and
+ * interface/type definitions without the full bodies.
+ */
+function buildSkeleton(content: string, filePath: string): string {
+  const lines = content.split('\n');
+  const skeleton: string[] = [`// Skeleton: ${filePath}`];
+
+  const KEEP_PATTERNS = [
+    /^export\s+(default\s+)?class\s+/,
+    /^export\s+(default\s+)?function\s+/,
+    /^export\s+(default\s+)?async\s+function\s+/,
+    /^export\s+(default\s+)?interface\s+/,
+    /^export\s+(default\s+)?type\s+/,
+    /^export\s+(const|let|var)\s+/,
+    /^export\s+enum\s+/,
+    /^import\s+/,
+    /^\/\*\*/, // JSDoc block start
+    /^\s+\/\*\*/, // indented JSDoc
+    /^class\s+/,
+    /^function\s+/,
+    /^async\s+function\s+/,
+    /^\s+(public|private|protected)\s+(static\s+)?(async\s+)?\w+\s*\(/,
+    /^\s+(public|private|protected)\s+(readonly\s+)?\w+[\?!]?\s*:/,
+  ];
+
+  let inDocBlock = false;
+  let depth = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    const trimmed = line.trim();
+
+    // Track JSDoc blocks
+    if (trimmed.startsWith('/**')) {
+      inDocBlock = true;
+    }
+    if (inDocBlock) {
+      skeleton.push(line);
+      if (trimmed.includes('*/')) inDocBlock = false;
+      continue;
+    }
+
+    // Track brace depth to identify top-level vs nested
+    const openBraces = (line.match(/\{/g) ?? []).length;
+    const closeBraces = (line.match(/\}/g) ?? []).length;
+
+    // Include lines that match key patterns OR are at top level (depth 0)
+    const isKeyLine = KEEP_PATTERNS.some((p) => p.test(line));
+
+    if (depth <= 1 && (isKeyLine || trimmed === '')) {
+      // For function/class bodies, show only the signature line
+      if (trimmed.endsWith('{') && !trimmed.startsWith('//')) {
+        skeleton.push(line.replace(/\{$/, '{ ... }'));
+      } else {
+        skeleton.push(line);
+      }
+    }
+
+    depth += openBraces - closeBraces;
+    if (depth < 0) depth = 0;
+  }
+
+  return skeleton.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Null graph store for vector-only degradation
+// ---------------------------------------------------------------------------
+
+function createNullGraphStore(): GraphStore {
+  return {
+    connect: async () => {},
+    disconnect: async () => {},
+    isHealthy: async () => false,
+    query: async () => ({ nodes: [], edges: [], raw: [] }),
+    upsertNode: async () => {},
+    upsertEdge: async () => {},
+    deleteFile: async () => {},
+    deleteRepo: async () => {},
+    getCounts: async () => ({ totalNodes: 0, totalEdges: 0, byLabel: {} }),
+    ensureIndexes: async () => {},
+  };
+}