aios-core 4.2.15 → 4.3.0

package/.aios-core/cli/commands/validate/index.js

@@ -189,7 +189,7 @@ async function runValidation(options) {
     const possibleSources = [
       path.join(__dirname, '../../../../..'), // npm package root
       path.join(projectRoot, 'node_modules/aios-core'),
-      path.join(projectRoot, 'node_modules/@synkra/aios-core'),
+      path.join(projectRoot, 'node_modules/aios-core'),
     ];
 
     for (const src of possibleSources) {

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

@@ -0,0 +1,183 @@
+'use strict';
+
+const { getEnricher, getClient, isCodeIntelAvailable } = require('../index');
+
+/**
+ * CreationHelper — Code intelligence helper for squad-creator and artefact creation tasks.
+ *
+ * All functions return null gracefully when no provider is available.
+ * Never throws — safe to call unconditionally in task workflows.
+ *
+ * Functions:
+ *   - getCodebaseContext(targetPath) — project structure + conventions for agent creation
+ *   - checkDuplicateArtefact(name, description) — duplicate detection before artefact creation
+ *   - enrichRegistryEntry(entityName, entityPath) — pre-populate usedBy/dependencies for entity registry
+ */
+
+/**
+ * Get codebase context for enriching agent/artefact creation.
+ * Combines describeProject + getConventions to provide full awareness.
+ * Used by squad-creator when creating new agents — advisory, never blocks creation.
+ *
+ * @param {string} [targetPath='.'] - Path to analyze
+ * @returns {Promise<{project: Object, conventions: Object}|null>} Codebase context or null
+ */
+async function getCodebaseContext(targetPath) {
+  const path = targetPath || '.';
+  if (!isCodeIntelAvailable()) return null;
+
+  try {
+    const enricher = getEnricher();
+
+    // Per-capability try/catch — partial results accepted
+    let project = null;
+    let conventions = null;
+
+    try {
+      project = await enricher.describeProject(path);
+    } catch { /* skip — partial result ok */ }
+
+    try {
+      conventions = await enricher.getConventions(path);
+    } catch { /* skip — partial result ok */ }
+
+    // Return null only if we got nothing at all
+    if (!project && !conventions) return null;
+
+    return {
+      project,
+      conventions,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check for duplicate artefacts before creating a new one.
+ * Combines detectDuplicates + findReferences for comprehensive detection.
+ * Used by task creation workflows — returns advisory warning, never blocks.
+ *
+ * @param {string} name - Name of the artefact to create
+ * @param {string} description - Description of the artefact
+ * @returns {Promise<{duplicates: Array, references: Array, warning: string}|null>} Duplicate info or null
+ */
+async function checkDuplicateArtefact(name, description) {
+  if (!name && !description) return null;
+  if (!isCodeIntelAvailable()) return null;
+
+  try {
+    const enricher = getEnricher();
+    const client = getClient();
+
+    // Per-capability try/catch — partial results accepted
+    let dupes = null;
+    let refs = null;
+
+    try {
+      const searchText = description || name;
+      dupes = await enricher.detectDuplicates(searchText, { path: '.' });
+    } catch { /* skip — partial result ok */ }
+
+    try {
+      refs = await client.findReferences(name);
+    } catch { /* skip — partial result ok */ }
+
+    const hasMatches = (dupes && dupes.matches && dupes.matches.length > 0) ||
+      (refs && refs.length > 0);
+
+    if (!hasMatches) return null;
+
+    return {
+      duplicates: dupes ? (dupes.matches || []) : [],
+      references: refs || [],
+      warning: _formatDuplicateWarning(name, dupes, refs),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Enrich an entity registry entry with real dependency data.
+ * Combines findReferences + analyzeDependencies to pre-populate usedBy/dependencies.
+ * Used during entity auto-registration — advisory, registry works without it.
+ *
+ * @param {string} entityName - Name of the entity being registered
+ * @param {string} entityPath - File path of the entity
+ * @returns {Promise<{usedBy: Array, dependencies: Object}|null>} Registry enrichment data or null
+ */
+async function enrichRegistryEntry(entityName, entityPath) {
+  if (!entityName && !entityPath) return null;
+  if (!isCodeIntelAvailable()) return null;
+
+  try {
+    const client = getClient();
+
+    // Per-capability try/catch — partial results accepted
+    let usedBy = null;
+    let dependencies = null;
+
+    try {
+      const refs = await client.findReferences(entityName);
+      if (refs && refs.length > 0) {
+        usedBy = refs.map((ref) => ref.file).filter(Boolean);
+        // Deduplicate
+        usedBy = [...new Set(usedBy)];
+      }
+    } catch { /* skip — partial result ok */ }
+
+    try {
+      if (entityPath) {
+        const deps = await client.analyzeDependencies(entityPath);
+        if (deps) {
+          dependencies = deps;
+        }
+      }
+    } catch { /* skip — partial result ok */ }
+
+    // Return null only if we got nothing at all
+    if (!usedBy && !dependencies) return null;
+
+    return {
+      usedBy: usedBy || [],
+      dependencies: dependencies || { nodes: [], edges: [] },
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format a human-readable duplicate warning message.
+ * @param {string} name - Artefact name
+ * @param {Object|null} dupes - Result from detectDuplicates
+ * @param {Array|null} refs - Result from findReferences
+ * @returns {string} Formatted warning message
+ * @private
+ */
+function _formatDuplicateWarning(name, dupes, refs) {
+  const parts = [];
+
+  if (dupes && dupes.matches && dupes.matches.length > 0) {
+    const firstMatch = dupes.matches[0];
+    const location = firstMatch.file || firstMatch.path || 'unknown';
+    parts.push(`Similar artefact exists: ${location}`);
+  }
+
+  if (refs && refs.length > 0) {
+    parts.push(`"${name}" already referenced in ${refs.length} location(s)`);
+  }
+
+  parts.push('Consider extending instead of creating new (IDS Article IV-A)');
+
+  return parts.join('. ') + '.';
+}
+
+module.exports = {
+  getCodebaseContext,
+  checkDuplicateArtefact,
+  enrichRegistryEntry,
+  // Exposed for testing
+  _formatDuplicateWarning,
+};

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

@@ -0,0 +1,166 @@
+'use strict';
+
+const { getEnricher, isCodeIntelAvailable } = require('../index');
+
+/**
+ * DevOpsHelper — Code intelligence helper for @devops agent tasks.
+ *
+ * All functions return null gracefully when no provider is available.
+ * Never throws — safe to call unconditionally in task workflows.
+ *
+ * Functions:
+ *   - assessPrePushImpact(files) — for @devops pre-push quality gate (blast radius + risk)
+ *   - generateImpactSummary(files) — for @devops PR automation (impact summary for PR description)
+ *   - classifyRiskLevel(blastRadius) — pure logic risk classification (LOW/MEDIUM/HIGH)
+ *   - _formatImpactReport(impact, riskLevel) — private formatting helper
+ */
+
+/**
+ * Assess impact of changed files for the pre-push quality gate.
+ * Used by @devops during *pre-push — returns blast radius, risk level, and formatted report.
+ *
+ * @param {string[]} files - Array of changed file paths
+ * @returns {Promise<{impact: Object, riskLevel: string, report: string}|null>} Impact analysis or null
+ */
+async function assessPrePushImpact(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 {
+        impact: null,
+        riskLevel: 'LOW',
+        report: _formatImpactReport(null, 'LOW'),
+      };
+    }
+
+    const riskLevel = classifyRiskLevel(impact.blastRadius);
+
+    return {
+      impact,
+      riskLevel,
+      report: _formatImpactReport(impact, riskLevel),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Generate an impact summary for PR description enrichment.
+ * Composes assessImpact + findTests to provide summary text and test coverage info.
+ * Used by @devops during *create-pr — returns summary for PR body.
+ *
+ * @param {string[]} files - Array of changed file paths
+ * @returns {Promise<{summary: string, testCoverage: Array|null}|null>} Impact summary or null
+ */
+async function generateImpactSummary(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;
+
+    // Per-capability try/catch — partial results accepted
+    let testCoverage = null;
+    try {
+      const tests = await enricher.findTests(files[0]);
+      if (tests) {
+        testCoverage = tests;
+      }
+    } catch { /* skip — partial result ok */ }
+
+    const riskLevel = classifyRiskLevel(impact.blastRadius);
+    const fileCount = impact.references ? impact.references.length : 0;
+    const topFiles = (impact.references || [])
+      .map((r) => r.file || r.path || 'unknown')
+      .slice(0, 10);
+
+    const summaryLines = [
+      `**Blast Radius:** ${impact.blastRadius} files affected`,
+      `**Risk Level:** ${riskLevel}`,
+      `**Avg Complexity:** ${impact.complexity ? impact.complexity.average.toFixed(1) : 'N/A'}`,
+    ];
+
+    if (topFiles.length > 0) {
+      summaryLines.push('', '**Affected Files:**');
+      topFiles.forEach((f) => summaryLines.push(`- ${f}`));
+    }
+
+    if (testCoverage && testCoverage.length > 0) {
+      summaryLines.push('', `**Related Tests:** ${testCoverage.length} test file(s) found`);
+    } else {
+      summaryLines.push('', '**Related Tests:** No related tests found');
+    }
+
+    return {
+      summary: summaryLines.join('\n'),
+      testCoverage,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Classify risk level based on blast radius count.
+ * Pure logic function — no provider dependency.
+ *
+ * @param {number} blastRadius - Number of affected files
+ * @returns {string} 'LOW' | 'MEDIUM' | 'HIGH'
+ */
+function classifyRiskLevel(blastRadius) {
+  if (!blastRadius || blastRadius <= 5) return 'LOW';
+  if (blastRadius <= 15) return 'MEDIUM';
+  return 'HIGH';
+}
+
+/**
+ * Format a human-readable impact report for pre-push output.
+ * @param {Object|null} impact - Impact analysis result from enricher.assessImpact
+ * @param {string} riskLevel - Risk level classification
+ * @returns {string} Formatted report string
+ * @private
+ */
+function _formatImpactReport(impact, riskLevel) {
+  if (!impact) {
+    return '📊 Impact Analysis: No impact data available (code intelligence returned empty result)';
+  }
+
+  const lines = [
+    '📊 Impact Analysis:',
+    `   Blast Radius: ${impact.blastRadius} files affected`,
+    `   Risk Level: ${riskLevel}`,
+    `   Avg Complexity: ${impact.complexity ? impact.complexity.average.toFixed(1) : 'N/A'}`,
+  ];
+
+  const topFiles = (impact.references || [])
+    .map((r) => r.file || r.path || 'unknown')
+    .slice(0, 10);
+
+  if (topFiles.length > 0) {
+    lines.push('   Top affected files:');
+    topFiles.forEach((f) => lines.push(`     - ${f}`));
+  }
+
+  if (riskLevel === 'HIGH') {
+    lines.push('', `   ⚠️  HIGH RISK: ${impact.blastRadius} files affected. Confirm push?`);
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  assessPrePushImpact,
+  generateImpactSummary,
+  classifyRiskLevel,
+  // Exposed for testing
+  _formatImpactReport,
+};

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

@@ -0,0 +1,248 @@
+'use strict';
+
+const { getEnricher, getClient, isCodeIntelAvailable } = require('../index');
+
+// Risk level thresholds based on blast radius (reference count)
+// Consistent with dev-helper.js and qa-helper.js
+const RISK_THRESHOLDS = {
+  LOW_MAX: 4,       // 0-4 refs = LOW
+  MEDIUM_MAX: 15,   // 5-15 refs = MEDIUM
+                     // >15 refs = HIGH
+};
+
+/**
+ * PlanningHelper — Code intelligence helper for @pm/@architect agent tasks.
+ *
+ * All functions return null gracefully when no provider is available.
+ * Never throws — safe to call unconditionally in task workflows.
+ */
+
+/**
+ * Get codebase overview with project description and statistics.
+ * Used by brownfield-create-epic and create-doc for Codebase Intelligence section.
+ *
+ * @param {string} path - Path to analyze
+ * @returns {Promise<{codebase: Object, stats: Object}|null>}
+ */
+async function getCodebaseOverview(path) {
+  if (!path) return null;
+  if (!isCodeIntelAvailable()) return null;
+
+  try {
+    const enricher = getEnricher();
+    const project = await enricher.describeProject(path);
+
+    if (!project) return null;
+
+    return {
+      codebase: project.codebase || null,
+      stats: project.stats || null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get dependency graph summary for a path.
+ * Used by brownfield-create-epic and analyze-project-structure for dependency analysis.
+ *
+ * @param {string} path - Path to analyze dependencies for
+ * @returns {Promise<{dependencies: Object, summary: {totalDeps: number, depth: string}}|null>}
+ */
+async function getDependencyGraph(path) {
+  if (!path) return null;
+  if (!isCodeIntelAvailable()) return null;
+
+  try {
+    const client = getClient();
+    const deps = await client.analyzeDependencies(path);
+
+    if (!deps) return null;
+
+    return {
+      dependencies: deps,
+      summary: _buildDependencySummary(deps),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get complexity analysis for a set of files.
+ * Used by analyze-project-structure for complexity metrics per file.
+ *
+ * @param {string[]} files - Files to analyze complexity for
+ * @returns {Promise<{perFile: Array<{file: string, complexity: Object}>, average: number}|null>}
+ */
+async function getComplexityAnalysis(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 complexity = await client.analyzeComplexity(file);
+          return {
+            file,
+            complexity: complexity || null,
+          };
+        } catch {
+          return {
+            file,
+            complexity: null,
+          };
+        }
+      }),
+    );
+
+    const validResults = results.filter((r) => r.complexity !== null);
+    const scores = validResults
+      .map((r) => r.complexity && typeof r.complexity.score === 'number' ? r.complexity.score : null)
+      .filter((s) => s !== null);
+    const average = scores.length > 0
+      ? scores.reduce((sum, s) => sum + s, 0) / scores.length
+      : 0;
+
+    return {
+      perFile: results,
+      average,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get implementation context for a set of symbols.
+ * Composes findDefinition + analyzeDependencies + findTests for each symbol.
+ * Used by plan-create-context for precise implementation context.
+ *
+ * @param {string[]} symbols - Symbol names to get context for
+ * @returns {Promise<{definitions: Array, dependencies: Array, relatedTests: Array}|null>}
+ */
+async function getImplementationContext(symbols) {
+  if (!symbols || symbols.length === 0) return null;
+  if (!isCodeIntelAvailable()) return null;
+
+  try {
+    const client = getClient();
+    const enricher = getEnricher();
+
+    const definitions = [];
+    const dependencies = [];
+    const relatedTests = [];
+
+    await Promise.all(
+      symbols.map(async (symbol) => {
+        // Per-item try/catch — partial results accepted
+        try {
+          const def = await client.findDefinition(symbol);
+          if (def) definitions.push({ symbol, ...def });
+        } catch { /* skip */ }
+
+        try {
+          const deps = await client.analyzeDependencies(symbol);
+          if (deps) dependencies.push({ symbol, deps });
+        } catch { /* skip */ }
+
+        try {
+          const tests = await enricher.findTests(symbol);
+          if (tests) relatedTests.push({ symbol, tests });
+        } catch { /* skip */ }
+      }),
+    );
+
+    return {
+      definitions,
+      dependencies,
+      relatedTests,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get implementation impact analysis for a set of files.
+ * Used by plan-create-implementation for blast radius and risk assessment.
+ *
+ * @param {string[]} files - Files to assess impact for
+ * @returns {Promise<{blastRadius: number, riskLevel: string, references: Array}|null>}
+ */
+async function getImplementationImpact(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;
+  }
+}
+
+/**
+ * Build a summary from dependency analysis results.
+ * @param {Object} deps - Raw dependency graph from analyzeDependencies
+ * @returns {{totalDeps: number, depth: string}}
+ * @private
+ */
+function _buildDependencySummary(deps) {
+  if (!deps) return { totalDeps: 0, depth: 'none' };
+
+  // Handle various shapes of dependency data
+  let totalDeps = 0;
+  if (Array.isArray(deps)) {
+    totalDeps = deps.length;
+  } else if (deps.dependencies && Array.isArray(deps.dependencies)) {
+    totalDeps = deps.dependencies.length;
+  } else if (typeof deps === 'object') {
+    totalDeps = Object.keys(deps).length;
+  }
+
+  let depth = 'shallow';
+  if (totalDeps > RISK_THRESHOLDS.MEDIUM_MAX) {
+    depth = 'deep';
+  } else if (totalDeps > RISK_THRESHOLDS.LOW_MAX) {
+    depth = 'moderate';
+  }
+
+  return { totalDeps, depth };
+}
+
+/**
+ * Calculate risk level from blast radius count.
+ * Consistent with dev-helper.js and qa-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';
+}
+
+module.exports = {
+  getCodebaseOverview,
+  getDependencyGraph,
+  getComplexityAnalysis,
+  getImplementationContext,
+  getImplementationImpact,
+  // Exposed for testing
+  _buildDependencySummary,
+  _calculateRiskLevel,
+  RISK_THRESHOLDS,
+};