aios-core 4.2.15 → 4.4.0

package/.aios-core/core/code-intel/helpers/qa-helper.js

@@ -0,0 +1,187 @@
+'use strict';
+
+const { getEnricher, getClient, isCodeIntelAvailable } = require('../index');
+
+// Risk level thresholds based on blast radius (reference count)
+// Consistent with dev-helper.js
+const RISK_THRESHOLDS = {
+  LOW_MAX: 4,       // 0-4 refs = LOW
+  MEDIUM_MAX: 15,   // 5-15 refs = MEDIUM
+                     // >15 refs = HIGH
+};
+
+// Coverage status thresholds based on test reference count
+const COVERAGE_THRESHOLDS = {
+  INDIRECT_MAX: 2,  // 1-2 test refs = INDIRECT
+  MINIMAL_MAX: 5,   // 3-5 test refs = MINIMAL
+                     // >5 test refs = GOOD
+};
+
+/**
+ * QaHelper — Code intelligence helper for @qa agent tasks.
+ *
+ * All functions return null gracefully when no provider is available.
+ * Never throws — safe to call unconditionally in task workflows.
+ */
+
+/**
+ * Get blast radius and risk level for a set of files.
+ * Used by qa-gate to assess impact of changes in gate decisions.
+ *
+ * @param {string[]} files - Files to assess blast radius for
+ * @returns {Promise<{blastRadius: number, riskLevel: string, references: Array}|null>}
+ */
+async function getBlastRadius(files) {
+  if (!files || files.length === 0) return null;
+  if (!isCodeIntelAvailable()) return null;
+
+  try {
+    const enricher = getEnricher();
+    const impact = await enricher.assessImpact(files);
+
+    if (!impact) return null;
+
+    return {
+      blastRadius: impact.blastRadius,
+      riskLevel: _calculateRiskLevel(impact.blastRadius),
+      references: impact.references || [],
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get test coverage status for a list of symbols.
+ * Used by qa-gate to assess test coverage per modified function.
+ *
+ * @param {string[]} symbols - Symbol names to check test coverage for
+ * @returns {Promise<Array<{symbol: string, status: string, testCount: number, tests: Array}>|null>}
+ */
+async function getTestCoverage(symbols) {
+  if (!symbols || symbols.length === 0) return null;
+  if (!isCodeIntelAvailable()) return null;
+
+  try {
+    const enricher = getEnricher();
+    const results = await Promise.all(
+      symbols.map(async (symbol) => {
+        try {
+          const tests = await enricher.findTests(symbol);
+          const testCount = tests ? tests.length : 0;
+          return {
+            symbol,
+            status: _calculateCoverageStatus(testCount),
+            testCount,
+            tests: tests || [],
+          };
+        } catch {
+          return {
+            symbol,
+            status: 'NO_TESTS',
+            testCount: 0,
+            tests: [],
+          };
+        }
+      }),
+    );
+
+    return results;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get reference impact for a set of files — which consumers are affected.
+ * Used by qa-review-story to show consumers affected by each change.
+ *
+ * @param {string[]} files - Files to check reference impact for
+ * @returns {Promise<Array<{file: string, consumers: Array}>|null>}
+ */
+async function getReferenceImpact(files) {
+  if (!files || files.length === 0) return null;
+  if (!isCodeIntelAvailable()) return null;
+
+  try {
+    const client = getClient();
+    const results = await Promise.all(
+      files.map(async (file) => {
+        try {
+          const refs = await client.findReferences(file);
+          return {
+            file,
+            consumers: refs || [],
+          };
+        } catch {
+          return {
+            file,
+            consumers: [],
+          };
+        }
+      }),
+    );
+
+    return results;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Suggest gate influence based on blast radius risk level.
+ * Returns advisory message when HIGH risk detected — never changes verdict automatically.
+ *
+ * @param {string} riskLevel - Risk level from getBlastRadius ('LOW'|'MEDIUM'|'HIGH')
+ * @returns {{advisory: string, suggestedGate: string}|null}
+ */
+function suggestGateInfluence(riskLevel) {
+  if (!riskLevel) return null;
+
+  if (riskLevel === 'HIGH') {
+    return {
+      advisory: 'HIGH blast radius detected. Consider CONCERNS gate with additional review recommended.',
+      suggestedGate: 'CONCERNS',
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Calculate risk level from blast radius count.
+ * Consistent with dev-helper.js thresholds.
+ * @param {number} blastRadius - Number of references affected
+ * @returns {string} 'LOW' | 'MEDIUM' | 'HIGH'
+ * @private
+ */
+function _calculateRiskLevel(blastRadius) {
+  if (blastRadius <= RISK_THRESHOLDS.LOW_MAX) return 'LOW';
+  if (blastRadius <= RISK_THRESHOLDS.MEDIUM_MAX) return 'MEDIUM';
+  return 'HIGH';
+}
+
+/**
+ * Calculate coverage status from test reference count.
+ * @param {number} testCount - Number of test references found
+ * @returns {string} 'NO_TESTS' | 'INDIRECT' | 'MINIMAL' | 'GOOD'
+ * @private
+ */
+function _calculateCoverageStatus(testCount) {
+  if (testCount === 0) return 'NO_TESTS';
+  if (testCount <= COVERAGE_THRESHOLDS.INDIRECT_MAX) return 'INDIRECT';
+  if (testCount <= COVERAGE_THRESHOLDS.MINIMAL_MAX) return 'MINIMAL';
+  return 'GOOD';
+}
+
+module.exports = {
+  getBlastRadius,
+  getTestCoverage,
+  getReferenceImpact,
+  suggestGateInfluence,
+  // Exposed for testing
+  _calculateRiskLevel,
+  _calculateCoverageStatus,
+  RISK_THRESHOLDS,
+  COVERAGE_THRESHOLDS,
+};

package/.aios-core/core/code-intel/helpers/story-helper.js

@@ -0,0 +1,146 @@
+'use strict';
+
+const { getEnricher, getClient, isCodeIntelAvailable } = require('../index');
+
+/**
+ * StoryHelper — Code intelligence helper for @sm/@po agent tasks.
+ *
+ * All functions return null gracefully when no provider is available.
+ * Never throws — safe to call unconditionally in task workflows.
+ *
+ * Functions:
+ *   - detectDuplicateStory(description) — for @sm story creation (advisory warning)
+ *   - suggestRelevantFiles(description) — for @sm story creation (file suggestions)
+ *   - validateNoDuplicates(description) — for @po story validation (checklist boolean)
+ */
+
+/**
+ * Detect duplicate stories/functionality in the codebase.
+ * Used by @sm during story creation — returns advisory warning only, never blocks.
+ *
+ * @param {string} description - Story description to check for duplicates
+ * @returns {Promise<{matches: Array, warning: string}|null>} Duplicate info or null
+ */
+async function detectDuplicateStory(description) {
+  if (!description) return null;
+  if (!isCodeIntelAvailable()) return null;
+
+  try {
+    const enricher = getEnricher();
+    const result = await enricher.detectDuplicates(description, { path: '.' });
+
+    if (!result || !result.matches || result.matches.length === 0) return null;
+
+    return {
+      matches: result.matches,
+      warning: _formatDuplicateWarning(result.matches),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Suggest relevant files for a new story based on description.
+ * Composes findReferences + analyzeCodebase for comprehensive file suggestions.
+ * Used by @sm during story creation to pre-populate "Suggested Files" section.
+ *
+ * @param {string} description - Story description to find relevant files for
+ * @returns {Promise<{files: Array, codebaseContext: Object|null}|null>} File suggestions or null
+ */
+async function suggestRelevantFiles(description) {
+  if (!description) return null;
+  if (!isCodeIntelAvailable()) return null;
+
+  try {
+    const client = getClient();
+
+    // Per-capability try/catch — partial results accepted
+    let files = null;
+    let codebaseContext = null;
+
+    try {
+      const refs = await client.findReferences(description);
+      if (refs) {
+        files = refs;
+      }
+    } catch { /* skip — partial result ok */ }
+
+    try {
+      const analysis = await client.analyzeCodebase('.');
+      if (analysis) {
+        codebaseContext = analysis;
+      }
+    } catch { /* skip — partial result ok */ }
+
+    // Return null only if we got nothing at all
+    if (!files && !codebaseContext) return null;
+
+    return {
+      files: files || [],
+      codebaseContext,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Validate that a story description does not duplicate existing functionality.
+ * Used by @po during story validation — returns boolean for checklist item.
+ *
+ * @param {string} description - Story description to validate
+ * @returns {Promise<{hasDuplicates: boolean, matches: Array, suggestion: string|null}|null>} Validation result or null
+ */
+async function validateNoDuplicates(description) {
+  if (!description) return null;
+  if (!isCodeIntelAvailable()) return null;
+
+  try {
+    const enricher = getEnricher();
+    const result = await enricher.detectDuplicates(description, { path: '.' });
+
+    if (!result) {
+      return {
+        hasDuplicates: false,
+        matches: [],
+        suggestion: null,
+      };
+    }
+
+    const hasDuplicates = result.matches && result.matches.length > 0;
+
+    return {
+      hasDuplicates,
+      matches: result.matches || [],
+      suggestion: hasDuplicates ? 'Consider ADAPT instead of CREATE — similar functionality exists' : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format a human-readable warning message from duplicate matches.
+ * @param {Array} matches - Array of duplicate match objects
+ * @returns {string} Formatted warning message
+ * @private
+ */
+function _formatDuplicateWarning(matches) {
+  if (!matches || matches.length === 0) return '';
+
+  const fileList = matches
+    .map((m) => m.file || m.path || 'unknown')
+    .slice(0, 5)
+    .join(', ');
+
+  return `Similar functionality already exists in: ${fileList}. Consider ADAPT instead of CREATE.`;
+}
+
+module.exports = {
+  detectDuplicateStory,
+  suggestRelevantFiles,
+  validateNoDuplicates,
+  // Exposed for testing
+  _formatDuplicateWarning,
+};

package/.aios-core/core/code-intel/hook-runtime.js

@@ -0,0 +1,186 @@
+'use strict';
+
+const path = require('path');
+const { RegistryProvider } = require('./providers/registry-provider');
+
+/** Cached provider instance (survives across hook invocations in same process). */
+let _provider = null;
+let _providerRoot = null;
+
+/**
+ * Get or create a RegistryProvider singleton.
+ * Resets if projectRoot changes between calls.
+ * @param {string} projectRoot - Project root directory
+ * @returns {RegistryProvider}
+ */
+function getProvider(projectRoot) {
+  if (!_provider || _providerRoot !== projectRoot) {
+    _provider = new RegistryProvider({ projectRoot });
+    _providerRoot = projectRoot;
+  }
+  return _provider;
+}
+
+/**
+ * Resolve code intelligence context for a file being written/edited.
+ *
+ * Queries RegistryProvider for:
+ * - Entity definition (path, layer, purpose, type)
+ * - References (files that use this entity)
+ * - Dependencies (entities this file depends on)
+ *
+ * @param {string} filePath - Absolute or relative path to the target file
+ * @param {string} cwd - Project root / working directory
+ * @returns {{ entity: Object|null, references: Array|null, dependencies: Object|null }|null}
+ */
+async function resolveCodeIntel(filePath, cwd) {
+  if (!filePath || !cwd) return null;
+
+  try {
+    const provider = getProvider(cwd);
+    if (!provider.isAvailable()) return null;
+
+    // Normalize to relative path (registry uses relative paths)
+    let relativePath = filePath;
+    if (path.isAbsolute(filePath)) {
+      relativePath = path.relative(cwd, filePath).replace(/\\/g, '/');
+    } else {
+      relativePath = filePath.replace(/\\/g, '/');
+    }
+
+    // Run all three queries in parallel
+    const [definition, references, dependencies] = await Promise.all([
+      provider.findDefinition(relativePath),
+      provider.findReferences(relativePath),
+      provider.analyzeDependencies(relativePath),
+    ]);
+
+    // Treat empty dependency graph as no data
+    const hasUsefulDeps = dependencies && dependencies.nodes && dependencies.nodes.length > 0;
+
+    // If nothing found at all, try searching by the file basename
+    if (!definition && !references && !hasUsefulDeps) {
+      const basename = path.basename(relativePath, path.extname(relativePath));
+      const fallbackDef = await provider.findDefinition(basename);
+      if (!fallbackDef) return null;
+
+      const [fallbackRefs, fallbackDeps] = await Promise.all([
+        provider.findReferences(basename),
+        provider.analyzeDependencies(basename),
+      ]);
+
+      return {
+        entity: fallbackDef,
+        references: fallbackRefs,
+        dependencies: fallbackDeps,
+      };
+    }
+
+    return {
+      entity: definition,
+      references,
+      dependencies,
+    };
+  } catch (_err) {
+    // Guard against provider exceptions to avoid unhandled rejections in hook runtime
+    return null;
+  }
+}
+
+/**
+ * Format code intelligence data as XML for injection into Claude context.
+ *
+ * @param {Object|null} intel - Result from resolveCodeIntel()
+ * @param {string} filePath - Target file path (for display)
+ * @returns {string|null} XML string or null if no data
+ */
+function formatAsXml(intel, filePath) {
+  if (!intel) return null;
+
+  const { entity, references, dependencies } = intel;
+
+  // At least one piece of data must exist
+  if (!entity && !references && !dependencies) return null;
+
+  const lines = ['<code-intel-context>'];
+  lines.push(`  <target-file>${escapeXml(filePath)}</target-file>`);
+
+  // Entity definition
+  if (entity) {
+    lines.push('  <existing-entity>');
+    if (entity.file) lines.push(`    <path>${escapeXml(entity.file)}</path>`);
+    if (entity.context) lines.push(`    <purpose>${escapeXml(entity.context)}</purpose>`);
+    lines.push('  </existing-entity>');
+  }
+
+  // References
+  if (references && references.length > 0) {
+    // Deduplicate by file path
+    const uniqueRefs = [];
+    const seen = new Set();
+    for (const ref of references) {
+      if (ref.file && !seen.has(ref.file)) {
+        seen.add(ref.file);
+        uniqueRefs.push(ref);
+      }
+    }
+
+    lines.push(`  <referenced-by count="${uniqueRefs.length}">`);
+    for (const ref of uniqueRefs.slice(0, 15)) {
+      const ctx = ref.context ? ` context="${escapeXml(ref.context)}"` : '';
+      lines.push(`    <ref file="${escapeXml(ref.file)}"${ctx} />`);
+    }
+    if (uniqueRefs.length > 15) {
+      lines.push(`    <!-- ...and ${uniqueRefs.length - 15} more -->`);
+    }
+    lines.push('  </referenced-by>');
+  }
+
+  // Dependencies
+  if (dependencies && dependencies.nodes && dependencies.nodes.length > 1) {
+    // First node is the target itself, rest are dependencies
+    const depNodes = dependencies.nodes.slice(1);
+    lines.push(`  <dependencies count="${depNodes.length}">`);
+    for (const dep of depNodes.slice(0, 10)) {
+      const layer = dep.layer ? ` layer="${dep.layer}"` : '';
+      lines.push(`    <dep name="${escapeXml(dep.name)}"${layer} />`);
+    }
+    if (depNodes.length > 10) {
+      lines.push(`    <!-- ...and ${depNodes.length - 10} more -->`);
+    }
+    lines.push('  </dependencies>');
+  }
+
+  lines.push('</code-intel-context>');
+  return lines.join('\n');
+}
+
+/**
+ * Escape special XML characters.
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeXml(str) {
+  if (!str) return '';
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/**
+ * Reset cached provider (for testing).
+ */
+function _resetForTesting() {
+  _provider = null;
+  _providerRoot = null;
+}
+
+module.exports = {
+  resolveCodeIntel,
+  formatAsXml,
+  escapeXml,
+  getProvider,
+  _resetForTesting,
+};

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

@@ -4,6 +4,7 @@ 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');
+const { RegistryProvider } = require('./providers/registry-provider');
 
 // Singleton client instance (lazily initialized)
 let _defaultClient = null;
@@ -127,6 +128,7 @@ module.exports = {
   CodeIntelEnricher,
   CodeIntelProvider,
   CodeGraphProvider,
+  RegistryProvider,
 
   // Constants
   CAPABILITIES,

package/.aios-core/core/code-intel/providers/code-graph-provider.js

@@ -29,6 +29,14 @@ class CodeGraphProvider extends CodeIntelProvider {
     this._mcpServerName = options.mcpServerName || 'code-graph';
   }
 
+  /**
+   * Code Graph provider is available when mcpCallFn is configured.
+   * @returns {boolean}
+   */
+  isAvailable() {
+    return typeof this.options.mcpCallFn === 'function';
+  }
+
   /**
    * Execute an MCP tool call via the configured server.
    * This method is the single point of MCP communication — all capabilities route through here.

package/.aios-core/core/code-intel/providers/provider-interface.js

@@ -14,6 +14,15 @@ class CodeIntelProvider {
     this.options = options;
   }
 
+  /**
+   * Check if this provider is available and can serve requests.
+   * Subclasses MUST override this to indicate availability.
+   * @returns {boolean}
+   */
+  isAvailable() {
+    return false;
+  }
+
   /**
    * Locate the definition of a symbol.
    * @param {string} symbol - Symbol name to find