aios-core 4.2.4 → 4.2.6

package/.aios-core/core/code-intel/code-intel-client.js

@@ -0,0 +1,280 @@
+'use strict';
+
+const { CodeGraphProvider } = require('./providers/code-graph-provider');
+
+// --- Constants (adjustable, not hardcoded magic numbers) ---
+const CIRCUIT_BREAKER_THRESHOLD = 3;
+const CIRCUIT_BREAKER_RESET_MS = 60000;
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+// Circuit breaker states
+const CB_CLOSED = 'CLOSED';
+const CB_OPEN = 'OPEN';
+const CB_HALF_OPEN = 'HALF-OPEN';
+
+/**
+ * CodeIntelClient — Central entry point for code intelligence.
+ *
+ * Features:
+ * - Provider auto-detection and registry
+ * - Circuit breaker pattern (threshold 3, reset 60s)
+ * - Session cache (Map-based, TTL 5min)
+ * - Graceful fallback (returns null without throw when no provider available)
+ * - Latency logging per capability
+ * - Cache hit/miss counters
+ */
+class CodeIntelClient {
+  constructor(options = {}) {
+    this._providers = [];
+    this._activeProvider = null;
+    this._options = options;
+
+    // Circuit breaker state
+    this._cbState = CB_CLOSED;
+    this._cbFailures = 0;
+    this._cbOpenedAt = null;
+
+    // Session cache
+    this._cache = new Map();
+
+    // Metrics
+    this._cacheHits = 0;
+    this._cacheMisses = 0;
+    this._latencyLog = [];
+
+    // Warning dedup
+    this._noProviderWarned = false;
+
+    // Auto-register default providers
+    this._registerDefaultProviders(options);
+  }
+
+  /**
+   * Register default providers based on configuration.
+   * @private
+   */
+  _registerDefaultProviders(options) {
+    // Code Graph MCP is the primary (and currently only) provider
+    const codeGraphProvider = new CodeGraphProvider({
+      mcpServerName: options.mcpServerName || 'code-graph',
+      mcpCallFn: options.mcpCallFn || null,
+    });
+    this._providers.push(codeGraphProvider);
+  }
+
+  /**
+   * Register an additional provider.
+   * @param {import('./providers/provider-interface').CodeIntelProvider} provider
+   */
+  registerProvider(provider) {
+    this._providers.push(provider);
+    // Reset active provider so next call re-detects
+    this._activeProvider = null;
+  }
+
+  /**
+   * Detect and return the first available provider.
+   * @returns {import('./providers/provider-interface').CodeIntelProvider|null}
+   * @private
+   */
+  _detectProvider() {
+    if (this._activeProvider) return this._activeProvider;
+
+    for (const provider of this._providers) {
+      // A provider is considered "available" if it has a configured mcpCallFn
+      if (provider.options && typeof provider.options.mcpCallFn === 'function') {
+        this._activeProvider = provider;
+        return provider;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Check if code intelligence is available.
+   * @returns {boolean}
+   */
+  isCodeIntelAvailable() {
+    return this._detectProvider() !== null;
+  }
+
+  /**
+   * Execute a capability with circuit breaker, cache, and fallback.
+   * @param {string} capability - One of the 8 primitive capability names
+   * @param {Array} args - Arguments to pass to the capability
+   * @returns {Promise<*>} Result or null on fallback
+   */
+  async _executeCapability(capability, args) {
+    const startTime = Date.now();
+
+    // Check provider availability
+    const provider = this._detectProvider();
+    if (!provider) {
+      if (!this._noProviderWarned) {
+        console.warn('[code-intel] No provider available. Code intelligence features disabled.');
+        this._noProviderWarned = true;
+      }
+      return null;
+    }
+
+    // Check cache
+    const cacheKey = `${capability}:${JSON.stringify(args)}`;
+    const cached = this._getFromCache(cacheKey);
+    if (cached !== undefined) {
+      this._cacheHits++;
+      this._logLatency(capability, Date.now() - startTime, true);
+      return cached;
+    }
+    this._cacheMisses++;
+
+    // Check circuit breaker
+    if (this._cbState === CB_OPEN) {
+      if (Date.now() - this._cbOpenedAt >= CIRCUIT_BREAKER_RESET_MS) {
+        this._cbState = CB_HALF_OPEN;
+      } else {
+        this._logLatency(capability, Date.now() - startTime, false);
+        return null;
+      }
+    }
+
+    // Execute capability
+    try {
+      const result = await provider[capability](...args);
+      this._onSuccess();
+      this._putInCache(cacheKey, result);
+      this._logLatency(capability, Date.now() - startTime, false);
+      return result;
+    } catch (_error) {
+      this._onFailure();
+      this._logLatency(capability, Date.now() - startTime, false);
+      return null;
+    }
+  }
+
+  // --- Circuit breaker helpers ---
+
+  _onSuccess() {
+    this._cbFailures = 0;
+    if (this._cbState === CB_HALF_OPEN) {
+      this._cbState = CB_CLOSED;
+    }
+  }
+
+  _onFailure() {
+    this._cbFailures++;
+    if (this._cbFailures >= CIRCUIT_BREAKER_THRESHOLD) {
+      this._cbState = CB_OPEN;
+      this._cbOpenedAt = Date.now();
+    }
+  }
+
+  getCircuitBreakerState() {
+    // Re-check if open timer expired
+    if (this._cbState === CB_OPEN && Date.now() - this._cbOpenedAt >= CIRCUIT_BREAKER_RESET_MS) {
+      this._cbState = CB_HALF_OPEN;
+    }
+    return this._cbState;
+  }
+
+  // --- Cache helpers ---
+
+  _getFromCache(key) {
+    const entry = this._cache.get(key);
+    if (!entry) return undefined;
+    if (Date.now() - entry.timestamp > CACHE_TTL_MS) {
+      this._cache.delete(key);
+      return undefined;
+    }
+    return entry.value;
+  }
+
+  _putInCache(key, value) {
+    // Evict expired entries periodically (every 50 puts)
+    if (this._cache.size > 0 && this._cache.size % 50 === 0) {
+      this._evictExpired();
+    }
+    this._cache.set(key, { value, timestamp: Date.now() });
+  }
+
+  _evictExpired() {
+    const now = Date.now();
+    for (const [key, entry] of this._cache) {
+      if (now - entry.timestamp > CACHE_TTL_MS) {
+        this._cache.delete(key);
+      }
+    }
+  }
+
+  // --- Latency logging ---
+
+  _logLatency(capability, durationMs, isCacheHit) {
+    this._latencyLog.push({
+      capability,
+      durationMs,
+      isCacheHit,
+      timestamp: Date.now(),
+    });
+  }
+
+  // --- Metrics ---
+
+  getMetrics() {
+    return {
+      cacheHits: this._cacheHits,
+      cacheMisses: this._cacheMisses,
+      cacheHitRate:
+        this._cacheHits + this._cacheMisses > 0
+          ? this._cacheHits / (this._cacheHits + this._cacheMisses)
+          : 0,
+      circuitBreakerState: this.getCircuitBreakerState(),
+      latencyLog: this._latencyLog,
+      providerAvailable: this.isCodeIntelAvailable(),
+      activeProvider: this._activeProvider ? this._activeProvider.name : null,
+    };
+  }
+
+  // --- 8 Primitive Capabilities (public API) ---
+
+  async findDefinition(symbol, options) {
+    return this._executeCapability('findDefinition', [symbol, options]);
+  }
+
+  async findReferences(symbol, options) {
+    return this._executeCapability('findReferences', [symbol, options]);
+  }
+
+  async findCallers(symbol, options) {
+    return this._executeCapability('findCallers', [symbol, options]);
+  }
+
+  async findCallees(symbol, options) {
+    return this._executeCapability('findCallees', [symbol, options]);
+  }
+
+  async analyzeDependencies(path, options) {
+    return this._executeCapability('analyzeDependencies', [path, options]);
+  }
+
+  async analyzeComplexity(path, options) {
+    return this._executeCapability('analyzeComplexity', [path, options]);
+  }
+
+  async analyzeCodebase(path, options) {
+    return this._executeCapability('analyzeCodebase', [path, options]);
+  }
+
+  async getProjectStats(options) {
+    return this._executeCapability('getProjectStats', [options]);
+  }
+}
+
+module.exports = {
+  CodeIntelClient,
+  CIRCUIT_BREAKER_THRESHOLD,
+  CIRCUIT_BREAKER_RESET_MS,
+  CACHE_TTL_MS,
+  CB_CLOSED,
+  CB_OPEN,
+  CB_HALF_OPEN,
+};

package/.aios-core/core/code-intel/code-intel-enricher.js

@@ -0,0 +1,159 @@
+'use strict';
+
+/**
+ * CodeIntelEnricher — Composite capabilities built on top of primitive capabilities.
+ *
+ * Each method composes multiple primitive capabilities from CodeIntelClient
+ * to provide higher-level analysis functions used by AIOS tasks.
+ */
+class CodeIntelEnricher {
+  /**
+   * @param {import('./code-intel-client').CodeIntelClient} client
+   */
+  constructor(client) {
+    this._client = client;
+  }
+
+  /**
+   * Assess impact of changes to given files.
+   * Composition: findReferences + analyzeComplexity
+   *
+   * @param {string[]} files - Files to assess impact for
+   * @returns {Promise<{references: Array, complexity: Object, blastRadius: number}|null>}
+   */
+  async assessImpact(files) {
+    if (!files || files.length === 0) return null;
+
+    try {
+      const results = await Promise.all(
+        files.map(async (file) => {
+          try {
+            const [refs, complexity] = await Promise.all([
+              this._client.findReferences(file),
+              this._client.analyzeComplexity(file),
+            ]);
+            return { file, references: refs, complexity };
+          } catch {
+            return { file, references: null, complexity: null };
+          }
+        }),
+      );
+
+      const allRefs = results.flatMap((r) => r.references || []);
+      const avgComplexity =
+        results.reduce((sum, r) => sum + ((r.complexity && r.complexity.score) || 0), 0) /
+        (results.length || 1);
+
+      return {
+        references: allRefs,
+        complexity: { average: avgComplexity, perFile: results },
+        blastRadius: allRefs.length,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Detect potential duplicates for a description/concept.
+   * Composition: findReferences + analyzeCodebase
+   *
+   * @param {string} description - Description of the capability to check
+   * @param {Object} [options] - Search options
+   * @returns {Promise<{matches: Array, codebaseOverview: Object}|null>}
+   */
+  async detectDuplicates(description, options = {}) {
+    try {
+      const [refs, codebase] = await Promise.all([
+        this._client.findReferences(description, options),
+        this._client.analyzeCodebase(options.path || '.', options),
+      ]);
+
+      if (!refs && !codebase) return null;
+
+      return {
+        matches: refs || [],
+        codebaseOverview: codebase || {},
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Get coding conventions for a path.
+   * Composition: analyzeCodebase + getProjectStats
+   *
+   * @param {string} path - Path to analyze conventions for
+   * @returns {Promise<{patterns: Array, stats: Object}|null>}
+   */
+  async getConventions(path) {
+    try {
+      const [codebase, stats] = await Promise.all([
+        this._client.analyzeCodebase(path),
+        this._client.getProjectStats(),
+      ]);
+
+      if (!codebase && !stats) return null;
+
+      return {
+        patterns: (codebase && codebase.patterns) || [],
+        stats: stats || {},
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Find tests related to a symbol.
+   * Composition: findReferences (filtered for test/spec files)
+   *
+   * @param {string} symbol - Symbol to find tests for
+   * @returns {Promise<Array<{file: string, line: number, context: string}>|null>}
+   */
+  async findTests(symbol) {
+    try {
+      const refs = await this._client.findReferences(symbol);
+      if (!refs) return null;
+
+      return refs.filter((ref) => {
+        const file = (ref.file || '').toLowerCase();
+        return (
+          file.includes('test') ||
+          file.includes('spec') ||
+          file.includes('__tests__')
+        );
+      });
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Describe the project overview.
+   * Composition: analyzeCodebase + getProjectStats
+   *
+   * @param {string} [path] - Root path (defaults to '.')
+   * @returns {Promise<{codebase: Object, stats: Object}|null>}
+   */
+  async describeProject(path = '.') {
+    try {
+      const [codebase, stats] = await Promise.all([
+        this._client.analyzeCodebase(path),
+        this._client.getProjectStats(),
+      ]);
+
+      if (!codebase && !stats) return null;
+
+      return {
+        codebase: codebase || {},
+        stats: stats || {},
+      };
+    } catch {
+      return null;
+    }
+  }
+}
+
+module.exports = { CodeIntelEnricher };

package/.aios-core/core/code-intel/index.js

@@ -0,0 +1,137 @@
+'use strict';
+
+const { CodeIntelClient } = require('./code-intel-client');
+const { CodeIntelEnricher } = require('./code-intel-enricher');
+const { CodeIntelProvider, CAPABILITIES } = require('./providers/provider-interface');
+const { CodeGraphProvider, TOOL_MAP } = require('./providers/code-graph-provider');
+
+// Singleton client instance (lazily initialized)
+let _defaultClient = null;
+let _defaultEnricher = null;
+
+/**
+ * Get the default CodeIntelClient singleton.
+ * @param {Object} [options] - Options to pass on first creation
+ * @returns {CodeIntelClient}
+ */
+function getClient(options) {
+  if (!_defaultClient) {
+    _defaultClient = new CodeIntelClient(options);
+  }
+  return _defaultClient;
+}
+
+/**
+ * Get the default CodeIntelEnricher singleton.
+ * @param {Object} [options] - Options to pass to client on first creation
+ * @returns {CodeIntelEnricher}
+ */
+function getEnricher(options) {
+  if (!_defaultEnricher) {
+    _defaultEnricher = new CodeIntelEnricher(getClient(options));
+  }
+  return _defaultEnricher;
+}
+
+/**
+ * Check if any code intelligence provider is available.
+ * @returns {boolean}
+ */
+function isCodeIntelAvailable() {
+  if (_defaultClient) {
+    return _defaultClient.isCodeIntelAvailable();
+  }
+  return false;
+}
+
+/**
+ * Enrich a base result with code intelligence data.
+ * Graceful — never throws, returns baseResult unchanged on failure.
+ *
+ * @param {*} baseResult - The base result to enrich
+ * @param {Object} options - Enrichment options
+ * @param {string[]} options.capabilities - List of enricher capabilities to use
+ * @param {number} [options.timeout=5000] - Timeout in ms
+ * @param {string} [options.fallbackBehavior='warn-and-continue'] - Fallback strategy
+ * @returns {Promise<*>} Enriched result or baseResult on failure
+ */
+async function enrichWithCodeIntel(baseResult, options = {}) {
+  if (!isCodeIntelAvailable()) {
+    return baseResult;
+  }
+
+  const enricher = getEnricher();
+  const enrichments = {};
+
+  try {
+    const timeout = options.timeout ?? 5000;
+    const capabilities = options.capabilities || [];
+
+    const capabilityArgs = {
+      assessImpact: () => [Array.isArray(options.files) ? options.files : []],
+      detectDuplicates: () => [options.description || '', options],
+      findTests: () => [options.symbol || ''],
+      getConventions: () => [options.target || '.'],
+      describeProject: () => [options.target || '.'],
+    };
+
+    const promises = capabilities.map(async (cap) => {
+      if (typeof enricher[cap] === 'function') {
+        let timer;
+        try {
+          const args = capabilityArgs[cap] ? capabilityArgs[cap]() : [options.target || '.'];
+          const result = await Promise.race([
+            enricher[cap](...args),
+            new Promise((_, reject) => {
+              timer = setTimeout(() => reject(new Error('timeout')), timeout);
+            }),
+          ]);
+          enrichments[cap] = result;
+        } finally {
+          clearTimeout(timer);
+        }
+      }
+    });
+
+    await Promise.allSettled(promises);
+  } catch (error) {
+    // Graceful — never throws, returns baseResult unchanged on failure
+    if (options.fallbackBehavior !== 'silent') {
+      console.warn('[code-intel] Enrichment failed, returning base result:', error.message);
+    }
+    return baseResult;
+  }
+
+  return { ...baseResult, _codeIntel: enrichments };
+}
+
+/**
+ * Reset singletons (for testing).
+ */
+function _resetForTesting() {
+  _defaultClient = null;
+  _defaultEnricher = null;
+}
+
+module.exports = {
+  // Singletons
+  getClient,
+  getEnricher,
+
+  // Convenience
+  isCodeIntelAvailable,
+  enrichWithCodeIntel,
+
+  // Classes (for custom instances)
+  CodeIntelClient,
+  CodeIntelEnricher,
+  CodeIntelProvider,
+  CodeGraphProvider,
+
+  // Constants
+  CAPABILITIES,
+  TOOL_MAP,
+
+  // Testing
+  _resetForTesting,
+};