forge-server 0.1.0 → 0.1.1

package/src/storage/falkordb-store.ts

@@ -1,388 +0,0 @@
-/**
- * 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

@@ -1,141 +0,0 @@
-/**
- * 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');
-}