forge-server 0.1.0

package/src/storage/falkordb-store.ts

@@ -0,0 +1,388 @@
+/**
+ * FalkorDB implementation of GraphStore.
+ * FalkorDB speaks Redis protocol + GRAPH commands.
+ * Connects to localhost:6380 (remapped from container port 6379 per ADR-7).
+ *
+ * FalkorDB GRAPH.QUERY --compact response format:
+ * [
+ *   ["header", [...column_names]],
+ *   ["data", [[row], [row], ...]],
+ *   ["stats", ["Query internal execution time: X ms"]]
+ * ]
+ *
+ * Without --compact:
+ * [header_array, data_array, stats_array]
+ * where header_array = [column_names]
+ * and data_array = [[cell, cell, ...], ...]
+ */
+
+import { createClient, type RedisClientType } from 'redis';
+import type { GraphStore } from './interfaces.js';
+import type { GraphQueryResult } from '../util/types.js';
+import { logger } from '../util/logger.js';
+import { CircuitBreaker } from '../util/circuit-breaker.js';
+
+const DEFAULT_QUERY_TIMEOUT_MS = 5000;
+const RECONNECT_DELAY_MS = 1000;
+const MAX_RECONNECT_ATTEMPTS = 3;
+
+export class FalkorDBGraphStore implements GraphStore {
+  private client: RedisClientType | null = null;
+  private readonly url: string;
+  private readonly graphName: string;
+  private readonly queryTimeoutMs: number;
+  private connected = false;
+  private reconnectAttempts = 0;
+  private readonly breaker: CircuitBreaker;
+
+  constructor(
+    url: string = 'redis://localhost:6380',
+    graphName: string = 'forge_knowledge',
+    queryTimeoutMs: number = DEFAULT_QUERY_TIMEOUT_MS
+  ) {
+    this.url = url;
+    this.graphName = graphName;
+    this.queryTimeoutMs = queryTimeoutMs;
+    this.breaker = new CircuitBreaker({
+      name: 'falkordb',
+      failureThreshold: 5,
+      resetTimeoutMs: 30_000,
+    });
+  }
+
+  async connect(): Promise<void> {
+    if (this.connected) return;
+
+    this.client = createClient({
+      url: this.url,
+      socket: {
+        connectTimeout: this.queryTimeoutMs,
+        reconnectStrategy: (retries) => {
+          if (retries >= MAX_RECONNECT_ATTEMPTS) {
+            logger.error('FalkorDB max reconnect attempts reached');
+            return new Error('Max reconnect attempts reached');
+          }
+          const delay = RECONNECT_DELAY_MS * Math.pow(2, retries);
+          logger.warn('FalkorDB reconnecting', { attempt: retries + 1, delayMs: delay });
+          return delay;
+        },
+      },
+    }) as RedisClientType;
+
+    this.client.on('error', (err: Error) => {
+      logger.error('FalkorDB connection error', { error: err.message });
+      this.connected = false;
+    });
+
+    this.client.on('ready', () => {
+      this.connected = true;
+      this.reconnectAttempts = 0;
+      logger.info('FalkorDB ready', { url: this.url, graph: this.graphName });
+    });
+
+    this.client.on('reconnecting', () => {
+      this.reconnectAttempts++;
+      logger.warn('FalkorDB reconnecting', { attempt: this.reconnectAttempts });
+    });
+
+    await this.client.connect();
+    this.connected = true;
+    logger.info('FalkorDB connected', { url: this.url, graph: this.graphName });
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.client && this.connected) {
+      await this.client.disconnect();
+      this.client = null;
+      this.connected = false;
+      logger.info('FalkorDB disconnected');
+    }
+  }
+
+  async isHealthy(): Promise<boolean> {
+    // Circuit breaker short-circuits when OPEN — no ping needed
+    if (!this.breaker.isHealthy()) return false;
+    if (!this.client || !this.connected) return false;
+    try {
+      const result = await this.withTimeout(
+        this.client.ping(),
+        this.queryTimeoutMs
+      );
+      return result === 'PONG';
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Execute a raw Cypher query and return typed results.
+   * Parses FalkorDB's non-compact response format.
+   */
+  async query(cypher: string, params?: Record<string, unknown>): Promise<GraphQueryResult> {
+    try {
+      const raw = await this.graphQuery(cypher, params);
+      return this.parseGraphQueryResult(raw);
+    } catch (err) {
+      logger.error('Graph query error', { error: String(err), cypher: cypher.slice(0, 100) });
+      return { nodes: [], edges: [], raw: [] };
+    }
+  }
+
+  async upsertNode(
+    label: string,
+    matchProps: Record<string, unknown>,
+    setProps: Record<string, unknown>
+  ): Promise<void> {
+    const matchClause = this.propsToMatch(matchProps);
+    const setClause = this.propsToSet(setProps, 'n');
+    const cypher = `MERGE (n:${label} {${matchClause}}) SET ${setClause}`;
+
+    try {
+      await this.graphQuery(cypher);
+    } catch (err) {
+      logger.warn('upsertNode failed', { label, error: String(err) });
+    }
+  }
+
+  async upsertEdge(
+    fromLabel: string,
+    fromProps: Record<string, unknown>,
+    edgeType: string,
+    edgeProps: Record<string, unknown>,
+    toLabel: string,
+    toProps: Record<string, unknown>
+  ): Promise<void> {
+    const fromMatch = this.propsToMatch(fromProps);
+    const toMatch = this.propsToMatch(toProps);
+    const edgeSet = Object.keys(edgeProps).length > 0
+      ? ` {${this.propsToMatch(edgeProps)}}`
+      : '';
+
+    const cypher = `
+      MATCH (a:${fromLabel} {${fromMatch}})
+      MATCH (b:${toLabel} {${toMatch}})
+      MERGE (a)-[r:${edgeType}${edgeSet}]->(b)
+    `;
+
+    try {
+      await this.graphQuery(cypher);
+    } catch (err) {
+      logger.warn('upsertEdge failed', { edgeType, error: String(err) });
+    }
+  }
+
+  async deleteFile(filePath: string, repoId: string): Promise<void> {
+    // Delete child nodes (symbols contained in the file)
+    const deleteChildren = `
+      MATCH (f:File {path: "${this.escape(filePath)}", repo_id: "${this.escape(repoId)}"})-[:CONTAINS]->(s)
+      DETACH DELETE s
+    `;
+    // Delete the file node itself
+    const deleteFile = `
+      MATCH (f:File {path: "${this.escape(filePath)}", repo_id: "${this.escape(repoId)}"})
+      DETACH DELETE f
+    `;
+
+    try {
+      await this.graphQuery(deleteChildren);
+      await this.graphQuery(deleteFile);
+    } catch (err) {
+      logger.warn('deleteFile failed', { filePath, error: String(err) });
+    }
+  }
+
+  async deleteRepo(repoId: string): Promise<void> {
+    const cypher = `
+      MATCH (n {repo_id: "${this.escape(repoId)}"})
+      DETACH DELETE n
+    `;
+    try {
+      await this.graphQuery(cypher);
+    } catch (err) {
+      logger.warn('deleteRepo failed', { repoId, error: String(err) });
+    }
+  }
+
+  async getCounts(): Promise<{ totalNodes: number; totalEdges: number; byLabel: Record<string, number> }> {
+    try {
+      // FalkorDB GRAPH.QUERY returns [headers, data, stats]
+      // MATCH (n) RETURN count(n) returns [[count_value]]
+      const nodeResult = await this.graphQuery('MATCH (n) RETURN count(n) AS cnt');
+      const edgeResult = await this.graphQuery('MATCH ()-[r]->() RETURN count(r) AS cnt');
+
+      const totalNodes = this.extractScalarNumber(nodeResult);
+      const totalEdges = this.extractScalarNumber(edgeResult);
+
+      // Get per-label counts for known node labels
+      const labels = ['File', 'Function', 'Class', 'Interface', 'Module', 'TypeAlias', 'Variable', 'Observation'];
+      const byLabel: Record<string, number> = {};
+
+      await Promise.all(labels.map(async (label) => {
+        try {
+          const result = await this.graphQuery(`MATCH (n:${label}) RETURN count(n) AS cnt`);
+          const count = this.extractScalarNumber(result);
+          if (count > 0) byLabel[label] = count;
+        } catch {
+          // Label might not exist in graph yet - skip
+        }
+      }));
+
+      return { totalNodes, totalEdges, byLabel };
+    } catch (err) {
+      logger.warn('getCounts failed', { error: String(err) });
+      return { totalNodes: 0, totalEdges: 0, byLabel: {} };
+    }
+  }
+
+  async ensureIndexes(): Promise<void> {
+    const indexes = [
+      'CREATE INDEX ON :File(path, repo_id)',
+      'CREATE INDEX ON :Function(name, repo_id)',
+      'CREATE INDEX ON :Class(name, repo_id)',
+      'CREATE INDEX ON :Interface(name, repo_id)',
+      'CREATE INDEX ON :Module(name, repo_id)',
+      'CREATE INDEX ON :Observation(id)',
+      'CREATE INDEX ON :Observation(session_id)',
+    ];
+
+    for (const idx of indexes) {
+      try {
+        await this.graphQuery(idx);
+      } catch {
+        // Index may already exist - FalkorDB throws on duplicate index creation.
+        // This is expected and safe to ignore.
+      }
+    }
+    logger.info('FalkorDB indexes ensured');
+  }
+
+  // ============================================================
+  // Private helpers
+  // ============================================================
+
+  /**
+   * Execute a GRAPH.QUERY command with timeout, wrapped in the circuit breaker.
+   * Returns the raw FalkorDB response array.
+   */
+  private async graphQuery(cypher: string, _params?: Record<string, unknown>): Promise<unknown[]> {
+    if (!this.client) throw new Error('FalkorDB not connected. Call connect() first.');
+
+    return this.breaker.execute(async () => {
+      const queryPromise = (this.client as RedisClientType).sendCommand([
+        'GRAPH.QUERY',
+        this.graphName,
+        cypher,
+      ]) as Promise<unknown[]>;
+
+      return this.withTimeout(queryPromise, this.queryTimeoutMs);
+    });
+  }
+
+  /**
+   * Wrap a promise with a timeout that rejects after timeoutMs.
+   */
+  private withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error(`FalkorDB query timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+
+      promise.then(
+        (value) => { clearTimeout(timer); resolve(value); },
+        (err) => { clearTimeout(timer); reject(err); }
+      );
+    });
+  }
+
+  /**
+   * Parse FalkorDB GRAPH.QUERY response into GraphQueryResult.
+   * FalkorDB non-compact format: [header_row, data_rows, stats_row]
+   * header_row: ["column1", "column2", ...]
+   * data_rows: [[val1, val2, ...], [val1, val2, ...], ...]
+   */
+  private parseGraphQueryResult(raw: unknown[]): GraphQueryResult {
+    if (!Array.isArray(raw) || raw.length < 2) {
+      return { nodes: [], edges: [], raw };
+    }
+
+    const headers = raw[0] as string[];
+    const dataRows = raw[1] as unknown[][];
+
+    if (!Array.isArray(headers) || !Array.isArray(dataRows)) {
+      return { nodes: [], edges: [], raw };
+    }
+
+    const nodes = [];
+    const edges = [];
+
+    for (const row of dataRows) {
+      if (!Array.isArray(row)) continue;
+      for (let i = 0; i < headers.length; i++) {
+        const cell = row[i];
+        if (cell && typeof cell === 'object' && !Array.isArray(cell)) {
+          const obj = cell as Record<string, unknown>;
+          // FalkorDB node: { id, labels, properties }
+          if (Array.isArray(obj.labels)) {
+            nodes.push({
+              id: String(obj.id ?? ''),
+              label: (obj.labels as string[])[0] ?? '',
+              properties: (obj.properties as Record<string, unknown>) ?? {},
+            });
+          }
+          // FalkorDB edge: { id, type, src_node, dest_node, properties }
+          if (typeof obj.type === 'string' && obj.src_node !== undefined) {
+            edges.push({
+              type: obj.type,
+              from: String(obj.src_node),
+              to: String(obj.dest_node ?? ''),
+              properties: (obj.properties as Record<string, unknown>) ?? {},
+            });
+          }
+        }
+      }
+    }
+
+    return { nodes, edges, raw };
+  }
+
+  /**
+   * Extract a single scalar number from a GRAPH.QUERY count result.
+   * Response: [["cnt"], [[42]], [...stats]]
+   */
+  private extractScalarNumber(raw: unknown[]): number {
+    if (!Array.isArray(raw) || raw.length < 2) return 0;
+    const dataRows = raw[1] as unknown[][];
+    if (!Array.isArray(dataRows) || dataRows.length === 0) return 0;
+    const firstRow = dataRows[0] as unknown[];
+    if (!Array.isArray(firstRow) || firstRow.length === 0) return 0;
+    const val = firstRow[0];
+    if (typeof val === 'number') return val;
+    if (typeof val === 'string') return parseInt(val, 10) || 0;
+    return 0;
+  }
+
+  private propsToMatch(props: Record<string, unknown>): string {
+    return Object.entries(props)
+      .map(([k, v]) => `${k}: ${this.valueToLiteral(v)}`)
+      .join(', ');
+  }
+
+  private propsToSet(props: Record<string, unknown>, alias: string): string {
+    return Object.entries(props)
+      .map(([k, v]) => `${alias}.${k} = ${this.valueToLiteral(v)}`)
+      .join(', ');
+  }
+
+  private valueToLiteral(v: unknown): string {
+    if (typeof v === 'string') return `"${this.escape(v)}"`;
+    if (typeof v === 'number') return String(v);
+    if (typeof v === 'boolean') return v ? 'true' : 'false';
+    if (v === null || v === undefined) return 'null';
+    if (Array.isArray(v)) return `[${v.map(x => this.valueToLiteral(x)).join(', ')}]`;
+    return `"${this.escape(JSON.stringify(v))}"`;
+  }
+
+  private escape(s: string): string {
+    return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+  }
+}

package/src/storage/file-cache.ts

@@ -0,0 +1,141 @@
+/**
+ * In-memory LRU file content cache.
+ * Provides the cross-agent shared context (ADR-8, section 4.6).
+ * Size-aware eviction with content-hash keying for invalidation.
+ */
+
+import { LRUCache } from 'lru-cache';
+import { createHash } from 'crypto';
+import type { FileContentCache } from './interfaces.js';
+import type { CacheEntry, CacheStats } from '../util/types.js';
+import { logger } from '../util/logger.js';
+
+const DEFAULT_MAX_SIZE_BYTES = 100 * 1024 * 1024;  // 100 MB
+const DEFAULT_MAX_ENTRIES = 2000;
+const DEFAULT_TTL_MS = 30 * 60 * 1000;               // 30 min
+
+export interface FileCacheOptions {
+  maxSizeBytes?: number;
+  maxEntries?: number;
+  ttlMs?: number;
+}
+
+export class LRUFileContentCache implements FileContentCache {
+  private cache: LRUCache<string, CacheEntry>;
+  private hits = 0;
+  private misses = 0;
+  private evictionCount = 0;
+  private startedAt = Date.now();
+
+  constructor(options: FileCacheOptions = {}) {
+    const maxSizeBytes = options.maxSizeBytes ?? DEFAULT_MAX_SIZE_BYTES;
+    const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+
+    this.cache = new LRUCache<string, CacheEntry>({
+      maxSize: maxSizeBytes,
+      // LRU cache requires sizeCalculation to return a positive integer.
+      // Use minimum of 1 so zero-byte content (empty string) is still accepted.
+      sizeCalculation: (entry) => Math.max(1, entry.sizeBytes),
+      ttl: ttlMs,
+      max: options.maxEntries ?? DEFAULT_MAX_ENTRIES,
+      // Use Date.now() for TTL tracking. This makes the cache compatible with
+      // vi.useFakeTimers() in tests (which replaces Date.now but not performance.now).
+      // lru-cache v11 defaults to performance.now which isn't affected by fake timers.
+      perf: { now: () => Date.now() },
+      dispose: () => {
+        this.evictionCount++;
+      },
+    });
+  }
+
+  private cacheKey(repoId: string, filePath: string): string {
+    return `${repoId}:${filePath}`;
+  }
+
+  get(repoId: string, filePath: string): CacheEntry | null {
+    const key = this.cacheKey(repoId, filePath);
+    const entry = this.cache.get(key);
+
+    if (entry) {
+      this.hits++;
+      // Update access count in-place
+      entry.accessCount++;
+      return entry;
+    }
+
+    this.misses++;
+    return null;
+  }
+
+  set(repoId: string, filePath: string, content: string, contentHash: string): void {
+    const key = this.cacheKey(repoId, filePath);
+    const sizeBytes = Buffer.byteLength(content, 'utf8');
+
+    const entry: CacheEntry = {
+      content,
+      contentHash,
+      cachedAt: Date.now(),
+      accessCount: 0,
+      sizeBytes, // Report the actual byte size (may be 0 for empty string)
+    };
+
+    this.cache.set(key, entry);
+    logger.debug('File cached', { filePath, sizeBytes, repoId });
+  }
+
+  invalidate(repoId: string, filePath: string): void {
+    const key = this.cacheKey(repoId, filePath);
+    this.cache.delete(key);
+    logger.debug('Cache invalidated', { filePath, repoId });
+  }
+
+  invalidateRepo(repoId: string): void {
+    const prefix = `${repoId}:`;
+    let count = 0;
+    for (const key of this.cache.keys()) {
+      if (key.startsWith(prefix)) {
+        this.cache.delete(key);
+        count++;
+      }
+    }
+    logger.info('Repo cache invalidated', { repoId, count });
+  }
+
+  clear(): void {
+    this.cache.clear();
+    this.hits = 0;
+    this.misses = 0;
+    logger.info('File content cache cleared');
+  }
+
+  getStats(): CacheStats {
+    const total = this.hits + this.misses;
+    const hitRate = total > 0 ? this.hits / total : 0;
+
+    // Calculate current memory usage
+    let totalBytes = 0;
+    let oldestAge = 0;
+    const now = Date.now();
+
+    for (const entry of this.cache.values()) {
+      totalBytes += entry.sizeBytes;
+      const age = (now - entry.cachedAt) / 1000;
+      if (age > oldestAge) oldestAge = age;
+    }
+
+    return {
+      entries: this.cache.size,
+      memoryUsageMb: totalBytes / (1024 * 1024),
+      hitRate,
+      evictionCount: this.evictionCount,
+      oldestEntryAgeSeconds: oldestAge,
+    };
+  }
+}
+
+/**
+ * Utility: compute SHA-256 hash of content string.
+ */
+export function hashContent(content: string): string {
+  return createHash('sha256').update(content, 'utf8').digest('hex');
+}