aios-core 4.2.12 → 4.2.14

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

@@ -0,0 +1,206 @@
+'use strict';
+
+const { getEnricher, getClient, isCodeIntelAvailable } = require('../index');
+
+// Risk level thresholds based on blast radius (reference count)
+const RISK_THRESHOLDS = {
+  LOW_MAX: 4,       // 0-4 refs = LOW
+  MEDIUM_MAX: 15,   // 5-15 refs = MEDIUM
+                     // >15 refs = HIGH
+};
+
+// Minimum references to suggest REUSE (>threshold = REUSE, <=threshold = ADAPT)
+const REUSE_MIN_REFS = 2;
+
+/**
+ * DevHelper — Code intelligence helper for @dev agent tasks.
+ *
+ * All functions return null gracefully when no provider is available.
+ * Never throws — safe to call unconditionally in task workflows.
+ */
+
+/**
+ * Check for duplicates and similar code before writing a new file or function.
+ * Used by IDS Gate G4 in dev-develop-story and build-autonomous tasks.
+ *
+ * @param {string} fileName - Name of the file/function to be created
+ * @param {string} description - Description of what it does
+ * @returns {Promise<{duplicates: Object, references: Array, suggestion: string}|null>}
+ */
+async function checkBeforeWriting(fileName, description) {
+  if (!isCodeIntelAvailable()) {
+    return null;
+  }
+
+  try {
+    const enricher = getEnricher();
+    const dupes = await enricher.detectDuplicates(description, { path: '.' });
+
+    // Also search for the fileName as a symbol reference
+    const client = getClient();
+    const nameRefs = await client.findReferences(fileName);
+
+    const hasMatches = (dupes && dupes.matches && dupes.matches.length > 0) ||
+      (nameRefs && nameRefs.length > 0);
+
+    if (!hasMatches) {
+      return null;
+    }
+
+    return {
+      duplicates: dupes,
+      references: nameRefs || [],
+      suggestion: _formatSuggestion(dupes, nameRefs),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Suggest reuse of an existing symbol instead of creating a new one.
+ * Searches for definitions and references to determine REUSE vs ADAPT.
+ *
+ * @param {string} symbol - Symbol name to search for
+ * @returns {Promise<{file: string, line: number, references: number, suggestion: string}|null>}
+ */
+async function suggestReuse(symbol) {
+  if (!isCodeIntelAvailable()) {
+    return null;
+  }
+
+  try {
+    const client = getClient();
+    const [definition, refs] = await Promise.all([
+      client.findDefinition(symbol),
+      client.findReferences(symbol),
+    ]);
+
+    if (!definition && (!refs || refs.length === 0)) {
+      return null;
+    }
+
+    const refCount = refs ? refs.length : 0;
+    // REUSE if widely used, ADAPT if exists but lightly used
+    const suggestion = refCount > REUSE_MIN_REFS ? 'REUSE' : 'ADAPT';
+
+    return {
+      file: definition ? definition.file : (refs[0] ? refs[0].file : null),
+      line: definition ? definition.line : (refs[0] ? refs[0].line : null),
+      references: refCount,
+      suggestion,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get naming conventions and patterns for a given path.
+ * Used to ensure new code follows existing project conventions.
+ *
+ * @param {string} targetPath - Path to analyze conventions for
+ * @returns {Promise<{patterns: Array, stats: Object}|null>}
+ */
+async function getConventionsForPath(targetPath) {
+  if (!isCodeIntelAvailable()) {
+    return null;
+  }
+
+  try {
+    const enricher = getEnricher();
+    return await enricher.getConventions(targetPath);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Assess refactoring impact with blast radius and risk level.
+ * Used by dev-suggest-refactoring to show impact before changes.
+ *
+ * @param {string[]} files - Files to assess impact for
+ * @returns {Promise<{blastRadius: number, riskLevel: string, references: Array, complexity: Object}|null>}
+ */
+async function assessRefactoringImpact(files) {
+  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,
+      complexity: impact.complexity,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format a Code Intelligence Suggestion message from duplicate detection results.
+ * @param {Object|null} dupes - Result from detectDuplicates
+ * @param {Array|null} nameRefs - Result from findReferences
+ * @returns {string} Formatted suggestion message
+ * @private
+ */
+function _formatSuggestion(dupes, nameRefs) {
+  const parts = [];
+
+  if (dupes && dupes.matches && dupes.matches.length > 0) {
+    parts.push(`Found ${dupes.matches.length} similar match(es) in codebase`);
+    const firstMatch = dupes.matches[0];
+    if (firstMatch.file) {
+      parts.push(`Closest: ${firstMatch.file}${firstMatch.line ? ':' + firstMatch.line : ''}`);
+    }
+  }
+
+  if (nameRefs && nameRefs.length > 0) {
+    parts.push(`Symbol already referenced in ${nameRefs.length} location(s)`);
+    const firstRef = nameRefs[0];
+    if (firstRef.file) {
+      parts.push(`First ref: ${firstRef.file}${firstRef.line ? ':' + firstRef.line : ''}`);
+    }
+  }
+
+  parts.push('Consider REUSE or ADAPT before creating new code (IDS Article IV-A)');
+
+  return parts.join('. ') + '.';
+}
+
+/**
+ * Calculate risk level from blast radius count.
+ * @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 = {
+  checkBeforeWriting,
+  suggestReuse,
+  getConventionsForPath,
+  assessRefactoringImpact,
+  // Exposed for testing
+  _formatSuggestion,
+  _calculateRiskLevel,
+  RISK_THRESHOLDS,
+  REUSE_MIN_REFS,
+};

package/.aios-core/core/code-intel/registry-syncer.js

@@ -0,0 +1,331 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const { getClient, isCodeIntelAvailable } = require('../code-intel');
+const { RegistryLoader, DEFAULT_REGISTRY_PATH } = require('../ids/registry-loader');
+
+// Role inference from entity path (order matters: more specific patterns first)
+const ROLE_MAP = [
+  ['tasks/', 'task'],
+  ['templates/', 'template'],
+  ['agents/', 'agent'],
+  ['workflows/', 'workflow'],
+  ['scripts/', 'script'],
+  ['/data/', 'config'],
+  ['/core/', 'module'],
+];
+
+/**
+ * Infer entity role from its file path.
+ * @param {string} entityPath - Entity source path
+ * @returns {string} Inferred role
+ */
+function inferRole(entityPath) {
+  if (!entityPath) return 'unknown';
+  const normalized = entityPath.replace(/\\/g, '/');
+  for (const [pattern, role] of ROLE_MAP) {
+    if (normalized.includes(pattern)) return role;
+  }
+  return 'unknown';
+}
+
+/**
+ * RegistrySyncer — Enriches entity registry with code intelligence data.
+ *
+ * Features:
+ * - Batch enrichment of usedBy, dependencies, keywords via code intelligence
+ * - Incremental sync (mtime-based) and full resync (--full flag)
+ * - Atomic write (temp file + rename) to prevent registry corruption
+ * - Graceful fallback when no provider is available
+ */
+class RegistrySyncer {
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.registryPath] - Path to entity-registry.yaml
+   * @param {string} [options.repoRoot] - Repository root for resolving entity paths
+   * @param {Object} [options.client] - Code intel client (for testing injection)
+   * @param {Function} [options.logger] - Logger function (defaults to console.log)
+   */
+  constructor(options = {}) {
+    this._registryPath = options.registryPath || DEFAULT_REGISTRY_PATH;
+    this._repoRoot = options.repoRoot || path.resolve(__dirname, '../../../');
+    this._client = options.client || null;
+    this._logger = options.logger || console.log;
+    this._stats = { processed: 0, skipped: 0, errors: 0, total: 0 };
+  }
+
+  /**
+   * Get code intel client (lazy, allows injection for testing).
+   * @returns {Object|null}
+   */
+  _getClient() {
+    if (this._client) return this._client;
+    return getClient();
+  }
+
+  /**
+   * Sync the entity registry with code intelligence data.
+   * @param {Object} [options]
+   * @param {boolean} [options.full=false] - Force full resync (ignore lastSynced)
+   * @returns {Promise<Object>} Sync stats
+   */
+  async sync(options = {}) {
+    const isFull = options.full === true;
+
+    // AC5: Fallback — check provider availability first
+    if (!this._isProviderAvailable()) {
+      this._logger('[registry-syncer] No code intelligence provider available, skipping enrichment');
+      return { processed: 0, skipped: 0, errors: 0, total: 0, aborted: true };
+    }
+
+    // Load registry
+    const loader = new RegistryLoader(this._registryPath);
+    const registry = loader.load();
+    const entities = registry.entities || {};
+
+    // Flatten all entities for iteration
+    const allEntities = [];
+    for (const [category, categoryEntities] of Object.entries(entities)) {
+      if (!categoryEntities || typeof categoryEntities !== 'object') continue;
+      for (const [entityId, entityData] of Object.entries(categoryEntities)) {
+        allEntities.push({ id: entityId, category, data: entityData });
+      }
+    }
+
+    this._stats = { processed: 0, skipped: 0, errors: 0, total: allEntities.length };
+    this._logger(`[registry-syncer] Starting ${isFull ? 'full' : 'incremental'} sync of ${allEntities.length} entities`);
+
+    // Iterate and enrich
+    for (const entity of allEntities) {
+      try {
+        const wasProcessed = await this.syncEntity(entity, entities, isFull);
+        if (wasProcessed) {
+          this._stats.processed++;
+        } else {
+          this._stats.skipped++;
+        }
+      } catch (error) {
+        this._stats.errors++;
+        this._logger(`[registry-syncer] Error enriching ${entity.id}: ${error.message}`);
+      }
+    }
+
+    // Update metadata
+    registry.metadata = registry.metadata || {};
+    registry.metadata.lastUpdated = new Date().toISOString();
+    registry.metadata.entityCount = allEntities.length;
+
+    // Atomic write
+    this._atomicWrite(this._registryPath, registry);
+
+    this._logger(`[registry-syncer] Sync complete: ${this._stats.processed} processed, ${this._stats.skipped} skipped, ${this._stats.errors} errors`);
+    return { ...this._stats };
+  }
+
+  /**
+   * Enrich a single entity with code intelligence data.
+   * @param {Object} entity - { id, category, data }
+   * @param {Object} entities - Full entities map (for cross-reference)
+   * @param {boolean} isFull - Force full resync
+   * @returns {Promise<boolean>} true if entity was processed, false if skipped
+   */
+  async syncEntity(entity, entities, isFull) {
+    const { id, data } = entity;
+    const sourcePath = data.path;
+
+    // Skip entities without source path
+    if (!sourcePath) {
+      return false;
+    }
+
+    // AC6: Incremental sync — check mtime vs lastSynced
+    if (!isFull) {
+      const shouldSkip = this._shouldSkipIncremental(data);
+      if (shouldSkip) {
+        return false;
+      }
+    }
+
+    const client = this._getClient();
+    const now = new Date().toISOString();
+
+    // AC2: Populate usedBy via findReferences
+    const usedByIds = await this._findUsedBy(client, id, entities);
+    if (usedByIds !== null) {
+      data.usedBy = usedByIds;
+    }
+
+    // AC3: Populate dependencies via analyzeDependencies (JS/TS files only)
+    const deps = await this._findDependencies(client, sourcePath);
+    if (deps !== null) {
+      data.dependencies = deps;
+    }
+
+    // AC4: Populate codeIntelMetadata
+    const callerCount = Array.isArray(data.usedBy) ? data.usedBy.length : 0;
+    data.codeIntelMetadata = {
+      callerCount,
+      role: inferRole(sourcePath),
+      lastSynced: now,
+      provider: client._activeProvider ? client._activeProvider.name : 'unknown',
+    };
+
+    return true;
+  }
+
+  /**
+   * Check if provider is available.
+   * @returns {boolean}
+   * @private
+   */
+  _isProviderAvailable() {
+    if (this._client) {
+      return typeof this._client.findReferences === 'function';
+    }
+    return isCodeIntelAvailable();
+  }
+
+  /**
+   * Check if entity should be skipped in incremental mode.
+   * @param {Object} entityData
+   * @returns {boolean} true if should skip
+   * @private
+   */
+  _shouldSkipIncremental(entityData) {
+    const metadata = entityData.codeIntelMetadata;
+
+    // Entities without lastSynced are always processed (AC6)
+    if (!metadata || !metadata.lastSynced) {
+      return false;
+    }
+
+    // Get file mtime
+    const sourcePath = entityData.path;
+    if (!sourcePath) return true;
+
+    const fullPath = path.resolve(this._repoRoot, sourcePath);
+    try {
+      const stat = fs.statSync(fullPath);
+      const lastSyncedMs = new Date(metadata.lastSynced).getTime();
+      // Skip if file hasn't changed since last sync
+      return stat.mtimeMs <= lastSyncedMs;
+    } catch (_error) {
+      // File doesn't exist — clear metadata and skip
+      this._logger(`[registry-syncer] Warning: source file not found for ${sourcePath}, skipping`);
+      return true;
+    }
+  }
+
+  /**
+   * Find entities that reference this entity (usedBy).
+   * @param {Object} client - Code intel client
+   * @param {string} entityId - Entity ID to search for
+   * @param {Object} entities - Full entities map for cross-referencing
+   * @returns {Promise<string[]|null>} Array of entity IDs or null on failure
+   * @private
+   */
+  async _findUsedBy(client, entityId, entities) {
+    try {
+      const references = await client.findReferences(entityId);
+      if (!references || !Array.isArray(references)) return null;
+
+      // Cross-reference with registry to get entity IDs
+      const usedByIds = [];
+      for (const ref of references) {
+        const refPath = ref.file || ref.path || ref;
+        if (typeof refPath !== 'string') continue;
+
+        const matchedId = this._findEntityByPath(refPath, entities);
+        if (matchedId && matchedId !== entityId) {
+          usedByIds.push(matchedId);
+        }
+      }
+
+      return [...new Set(usedByIds)]; // Deduplicate
+    } catch (_error) {
+      return null;
+    }
+  }
+
+  /**
+   * Find dependencies of a source file.
+   * @param {Object} client - Code intel client
+   * @param {string} sourcePath - Source file path
+   * @returns {Promise<string[]|null>} Array of dependency names or null on failure
+   * @private
+   */
+  async _findDependencies(client, sourcePath) {
+    // Only analyze JS/TS files for import dependencies
+    if (!sourcePath.match(/\.(js|ts|mjs|cjs)$/)) return null;
+
+    try {
+      const fullPath = path.resolve(this._repoRoot, sourcePath);
+      const result = await client.analyzeDependencies(fullPath);
+      if (!result) return null;
+
+      // Filter to internal project dependencies only
+      const deps = [];
+      const items = result.dependencies || result.imports || result;
+      if (!Array.isArray(items)) return null;
+
+      for (const dep of items) {
+        const depPath = dep.path || dep.source || dep;
+        if (typeof depPath !== 'string') continue;
+        // Internal deps: relative paths or project paths (not node_modules)
+        if (depPath.startsWith('.') || depPath.startsWith('/') || depPath.includes('.aios-core')) {
+          deps.push(depPath);
+        }
+      }
+
+      return deps;
+    } catch (_error) {
+      return null;
+    }
+  }
+
+  /**
+   * Find entity ID by file path (cross-reference lookup).
+   * @param {string} filePath - File path from reference
+   * @param {Object} entities - Full entities map
+   * @returns {string|null} Entity ID or null
+   * @private
+   */
+  _findEntityByPath(filePath, entities) {
+    const normalized = filePath.replace(/\\/g, '/');
+    for (const [_category, categoryEntities] of Object.entries(entities)) {
+      if (!categoryEntities || typeof categoryEntities !== 'object') continue;
+      for (const [entityId, entityData] of Object.entries(categoryEntities)) {
+        if (entityData.path && normalized.includes(entityData.path.replace(/\\/g, '/'))) {
+          return entityId;
+        }
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Atomic write: write to temp file then rename.
+   * Prevents partial corruption if process crashes mid-write.
+   * @param {string} registryPath - Target path
+   * @param {Object} registry - Registry data to write
+   * @private
+   */
+  _atomicWrite(registryPath, registry) {
+    const tmpPath = registryPath + '.tmp';
+    const content = yaml.dump(registry, { lineWidth: 120, noRefs: true });
+    fs.writeFileSync(tmpPath, content, 'utf8');
+    fs.renameSync(tmpPath, registryPath);
+  }
+
+  /**
+   * Get sync statistics from last run.
+   * @returns {Object}
+   */
+  getStats() {
+    return { ...this._stats };
+  }
+}
+
+module.exports = { RegistrySyncer, inferRole, ROLE_MAP };

package/.aios-core/core/ids/registry-loader.js

@@ -232,6 +232,35 @@ class RegistryLoader {
     return entity;
   }
 
+  /**
+   * Get entity with code intelligence metadata (Story NOG-2).
+   * @param {string} entityId - Entity ID
+   * @returns {Object|null} Entity with codeIntelMetadata or null
+   */
+  getEntityWithIntel(entityId) {
+    const entity = this._findById(entityId);
+    if (!entity) return null;
+    return {
+      ...entity,
+      codeIntelMetadata: entity.codeIntelMetadata || null,
+    };
+  }
+
+  /**
+   * Query entities by keywords with optional role filter (Story NOG-2).
+   * @param {string[]} keywords - Keywords to search
+   * @param {Object} [options]
+   * @param {string} [options.role] - Filter by codeIntelMetadata.role
+   * @returns {Object[]} Matching entities
+   */
+  findByKeyword(keywords, options = {}) {
+    const results = this.queryByKeywords(keywords);
+    if (!options.role) return results;
+    return results.filter(
+      (e) => e.codeIntelMetadata && e.codeIntelMetadata.role === options.role,
+    );
+  }
+
   /**
    * Get registry metadata.
    */