claude-mycelium 2.0.0

package/src/core/mode-selector.ts

@@ -0,0 +1,243 @@
+/**
+ * Mode Selection
+ * Per initial-spec §3
+ *
+ * Selects agent mode based on file's dominant signal.
+ * Each mode focuses on a specific type of improvement.
+ *
+ * Modes:
+ * - error_reducer: Fix bugs and add error handling
+ * - complexity_reducer: Simplify and refactor
+ * - debt_payer: Fix lint issues and improve types
+ * - stabilizer: Reduce churn with tests and docs
+ * - explorer: Challenge assumptions (Phase 4)
+ */
+
+import { logDebug, logWarn } from '../utils/logger.js';
+import type { Mode } from '../types/index.js';
+import type { GradientScore } from './gradient.js';
+
+/**
+ * Minimum signal value to be considered "dominant"
+ * Per initial-spec §3, signals must exceed 0.3 threshold
+ */
+const DOMINANCE_THRESHOLD = 0.3;
+
+/**
+ * Select mode based on gradient score
+ */
+export function selectMode(gradient: GradientScore): Mode {
+  const { dominantSignal } = gradient;
+
+  // Check if dominant signal exceeds threshold
+  if (dominantSignal.value < DOMINANCE_THRESHOLD) {
+    // No signal is dominant - default to debt_payer
+    logDebug('No dominant signal, defaulting to debt_payer', {
+      file: gradient.file,
+      maxSignal: dominantSignal.value.toFixed(3),
+    });
+    return 'debt_payer';
+  }
+
+  // Map dominant signal to mode
+  const modeMap: Record<string, Mode> = {
+    error_rate: 'error_reducer',
+    complexity: 'complexity_reducer',
+    debt: 'debt_payer',
+    churn: 'stabilizer',
+  };
+
+  const mode = modeMap[dominantSignal.name];
+
+  logDebug('Mode selected', {
+    file: gradient.file,
+    mode,
+    signal: dominantSignal.name,
+    value: dominantSignal.value.toFixed(3),
+  });
+
+  return mode;
+}
+
+/**
+ * Get mode-specific instructions for the agent
+ * These guide the LLM on what to focus on
+ */
+export function getModeInstructions(mode: Mode): string {
+  const instructions: Record<Mode, string> = {
+    error_reducer: `## Error Reducer Mode
+
+Your focus: Fix bugs and improve error handling.
+
+Allowed actions:
+- Fix logic errors and type errors
+- Add try/catch blocks for error handling
+- Improve error messages and logging
+- Add input validation
+- Fix off-by-one errors and edge cases
+
+Avoid:
+- Large refactors (use complexity_reducer for that)
+- Fixing lint warnings (use debt_payer for that)
+- Major architectural changes`,
+
+    complexity_reducer: `## Complexity Reducer Mode
+
+Your focus: Simplify and refactor complex code.
+
+Allowed actions:
+- Extract functions to reduce nesting
+- Split large functions into smaller ones
+- Simplify conditional logic
+- Remove duplicate code
+- Improve variable naming for clarity
+
+Avoid:
+- Changing functionality (keep behavior identical)
+- Fixing bugs (use error_reducer for that)
+- Removing tests or validation`,
+
+    debt_payer: `## Debt Payer Mode
+
+Your focus: Fix lint issues and improve code quality.
+
+Allowed actions:
+- Fix ESLint errors and warnings
+- Add missing type annotations
+- Fix naming conventions
+- Remove unused imports and variables
+- Improve code formatting
+
+Avoid:
+- Large refactors (use complexity_reducer for that)
+- Fixing logic bugs (use error_reducer for that)
+- Major functionality changes`,
+
+    stabilizer: `## Stabilizer Mode
+
+Your focus: Reduce churn by improving stability.
+
+Allowed actions:
+- Add unit tests for untested code
+- Improve API interfaces to reduce breaking changes
+- Add documentation and comments
+- Extract constants from magic numbers
+- Improve encapsulation
+
+Avoid:
+- Large refactors
+- Changing public APIs without good reason
+- Removing tests`,
+
+    explorer: `## Explorer Mode
+
+Your focus: Challenge assumptions and find better approaches.
+
+You have more freedom than other modes, but still bounded:
+- Can modify up to 50 lines
+- Must stay in one file
+- Cannot delete tests
+- Cannot remove validation
+- Cannot modify public APIs
+- Must pass CI
+
+This mode is for trying novel approaches when conventional modes have failed.`,
+  };
+
+  return instructions[mode] || instructions.debt_payer;
+}
+
+/**
+ * Get mode description for UI/logging
+ */
+export function getModeDescription(mode: Mode): string {
+  const descriptions: Record<Mode, string> = {
+    error_reducer: 'Fix bugs and add error handling',
+    complexity_reducer: 'Simplify and refactor code',
+    debt_payer: 'Fix lint issues and improve types',
+    stabilizer: 'Add tests and reduce churn',
+    explorer: 'Try novel approaches (bounded)',
+  };
+
+  return descriptions[mode] || 'Unknown mode';
+}
+
+/**
+ * Check if a mode is allowed for a file
+ * Some modes may be restricted based on file state
+ */
+export function isModeAllowed(
+  mode: Mode,
+  filePath: string,
+  isQuarantined: boolean = false
+): boolean {
+  // Only explorer can work on quarantined files
+  if (isQuarantined && mode !== 'explorer') {
+    logWarn('Mode not allowed on quarantined file', {
+      file: filePath,
+      mode,
+      reason: 'file is quarantined',
+    });
+    return false;
+  }
+
+  // All modes allowed for normal files
+  return true;
+}
+
+/**
+ * Suggest modes based on signal values
+ * Returns ranked list of modes that might be helpful
+ */
+export function suggestModes(gradient: GradientScore): Array<{
+  mode: Mode;
+  reason: string;
+  priority: number;
+}> {
+  const suggestions: Array<{ mode: Mode; reason: string; priority: number }> = [];
+  const { signals } = gradient;
+
+  // Check each signal
+  if (signals.error_rate >= DOMINANCE_THRESHOLD) {
+    suggestions.push({
+      mode: 'error_reducer',
+      reason: `High error rate: ${signals.error_rate.toFixed(2)}`,
+      priority: signals.error_rate,
+    });
+  }
+
+  if (signals.complexity >= DOMINANCE_THRESHOLD) {
+    suggestions.push({
+      mode: 'complexity_reducer',
+      reason: `High complexity: ${signals.complexity.toFixed(2)}`,
+      priority: signals.complexity,
+    });
+  }
+
+  if (signals.debt >= DOMINANCE_THRESHOLD) {
+    suggestions.push({
+      mode: 'debt_payer',
+      reason: `High technical debt: ${signals.debt.toFixed(2)}`,
+      priority: signals.debt,
+    });
+  }
+
+  if (signals.churn >= DOMINANCE_THRESHOLD) {
+    suggestions.push({
+      mode: 'stabilizer',
+      reason: `High churn: ${signals.churn.toFixed(2)}`,
+      priority: signals.churn,
+    });
+  }
+
+  // Sort by priority (highest signal first)
+  suggestions.sort((a, b) => b.priority - a.priority);
+
+  logDebug('Mode suggestions', {
+    file: gradient.file,
+    count: suggestions.length,
+    top: suggestions[0]?.mode || 'none',
+  });
+
+  return suggestions;
+}

package/src/core/signals/centrality.ts

@@ -0,0 +1,328 @@
+/**
+ * Centrality Signal Computation
+ * Per ADR-001 and second-spec §2.3 (lines 504-620)
+ *
+ * Calculates file centrality by building an import graph:
+ * - Extracts imports using regex patterns
+ * - Builds bidirectional import graph
+ * - Calculates fan-in (files that import this file)
+ * - Calculates fan-out (files this file imports)
+ * - Normalizes: (fanIn/maxFanIn)*0.67 + (fanOut/maxFanOut)*0.33
+ *
+ * Fan-in weighted 2x because heavily depended-on files are more critical
+ * Graph cached for 5 minutes to avoid repeated file scanning
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { readFile, listFilesRecursive, isTestFile } from '../../utils/file-utils.js';
+import { logDebug, logWarn } from '../../utils/logger.js';
+
+export interface CentralityResult {
+  fanIn: number;
+  fanOut: number;
+  normalized: number; // 0.0 - 1.0
+}
+
+export interface ImportGraph {
+  imports: Record<string, string[]>;
+  importedBy: Record<string, string[]>;
+}
+
+interface CachedGraph {
+  graph: ImportGraph;
+  computedAt: number;
+}
+
+// Cache graph for 5 minutes per spec
+const GRAPH_CACHE_TTL_MS = 5 * 60 * 1000;
+let cachedGraph: CachedGraph | null = null;
+
+/**
+ * Calculate centrality for a single file
+ * Builds import graph if needed (with caching)
+ */
+export async function calculateCentrality(filePath: string): Promise<CentralityResult> {
+  try {
+    // Determine root directory (go up until we find package.json or reach filesystem root)
+    const rootDir = findProjectRoot(filePath);
+
+    // Build or retrieve cached graph
+    const graph = await getOrBuildImportGraph(rootDir);
+
+    // Make file path relative to root for lookup
+    const relativeFile = path.relative(rootDir, filePath);
+
+    // Calculate fan-in and fan-out
+    const fanIn = (graph.importedBy[relativeFile] || []).length;
+    const fanOut = (graph.imports[relativeFile] || []).length;
+
+    // Find max values for normalization
+    let maxFanIn = 1;
+    let maxFanOut = 1;
+
+    for (const file of Object.keys(graph.imports)) {
+      const fileImportedBy = (graph.importedBy[file] || []).length;
+      const fileImports = (graph.imports[file] || []).length;
+
+      maxFanIn = Math.max(maxFanIn, fileImportedBy);
+      maxFanOut = Math.max(maxFanOut, fileImports);
+    }
+
+    // Normalize: fan-in weighted 2x (67% vs 33%)
+    const normalizedFanIn = fanIn / maxFanIn;
+    const normalizedFanOut = fanOut / maxFanOut;
+    const normalized = normalizedFanIn * 0.67 + normalizedFanOut * 0.33;
+
+    logDebug('Calculated centrality', {
+      file: relativeFile,
+      fanIn,
+      fanOut,
+      maxFanIn,
+      maxFanOut,
+      normalized: normalized.toFixed(3),
+    });
+
+    return {
+      fanIn,
+      fanOut,
+      normalized,
+    };
+  } catch (error) {
+    logWarn('Failed to calculate centrality, returning 0', {
+      file: filePath,
+      error: error instanceof Error ? error.message : String(error),
+    });
+
+    return {
+      fanIn: 0,
+      fanOut: 0,
+      normalized: 0,
+    };
+  }
+}
+
+/**
+ * Build import graph for entire project
+ * Public for testing and manual use
+ */
+export async function buildImportGraph(rootDir: string): Promise<ImportGraph> {
+  const imports: Record<string, string[]> = {};
+  const importedBy: Record<string, string[]> = {};
+
+  try {
+    // Find all TypeScript/JavaScript files
+    const allFiles = listFilesRecursive(rootDir);
+    const sourceFiles = allFiles.filter(file => {
+      // Include .ts, .tsx, .js, .jsx
+      const isSourceFile = /\.(ts|tsx|js|jsx)$/.test(file);
+      // Exclude node_modules, test files, and .d.ts files
+      const isExcluded = file.includes('node_modules') ||
+                         isTestFile(file) ||
+                         file.endsWith('.d.ts');
+      return isSourceFile && !isExcluded;
+    });
+
+    logDebug('Building import graph', {
+      rootDir,
+      totalFiles: sourceFiles.length,
+    });
+
+    // Extract imports for each file
+    for (const filePath of sourceFiles) {
+      const relativeFile = path.relative(rootDir, filePath);
+      const fileImports = extractImports(filePath, rootDir);
+
+      imports[relativeFile] = fileImports;
+
+      // Build reverse index (importedBy)
+      for (const importedFile of fileImports) {
+        if (!importedBy[importedFile]) {
+          importedBy[importedFile] = [];
+        }
+        importedBy[importedFile].push(relativeFile);
+      }
+    }
+
+    logDebug('Import graph built', {
+      totalFiles: Object.keys(imports).length,
+      totalEdges: Object.values(imports).reduce((sum, arr) => sum + arr.length, 0),
+    });
+
+    return { imports, importedBy };
+  } catch (error) {
+    logWarn('Failed to build import graph, returning empty', {
+      rootDir,
+      error: error instanceof Error ? error.message : String(error),
+    });
+
+    return { imports, importedBy };
+  }
+}
+
+/**
+ * Extract import paths from a file using regex
+ * Matches:
+ * - import ... from '...'
+ * - import '...'
+ * - require('...')
+ * - import('...')
+ */
+function extractImports(filePath: string, rootDir: string): string[] {
+  try {
+    const content = readFile(filePath);
+    const imports: Set<string> = new Set();
+
+    // Comprehensive regex for all import styles
+    // Matches: import ... from '...', import '...', require('...'), import('...')
+    const importRegex = /(?:import\s+(?:.*?\s+from\s+)?['"]([^'"]+)['"]|require\s*\(\s*['"]([^'"]+)['"]\s*\)|import\s*\(\s*['"]([^'"]+)['"]\s*\))/g;
+
+    let match;
+    while ((match = importRegex.exec(content)) !== null) {
+      const importPath = match[1] || match[2] || match[3];
+
+      // Skip external packages (not relative or absolute paths)
+      if (!importPath.startsWith('.') && !importPath.startsWith('/')) {
+        continue;
+      }
+
+      // Resolve to actual file path
+      const resolved = resolveImportPath(importPath, filePath, rootDir);
+      if (resolved) {
+        imports.add(resolved);
+      }
+    }
+
+    return Array.from(imports);
+  } catch (error) {
+    logWarn('Failed to extract imports', {
+      file: filePath,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return [];
+  }
+}
+
+/**
+ * Resolve import path to actual file
+ * Tries extensions: .ts, .tsx, .js, .jsx, /index.{ext}
+ */
+function resolveImportPath(importPath: string, fromFile: string, rootDir: string): string | null {
+  const fromDir = path.dirname(fromFile);
+
+  // Resolve relative to importing file
+  let resolved = path.resolve(fromDir, importPath);
+
+  // Make relative to root directory
+  resolved = path.relative(rootDir, resolved);
+
+  // Try different extensions and index files
+  const extensions = [
+    '',           // Exact match
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '/index.ts',
+    '/index.tsx',
+    '/index.js',
+    '/index.jsx',
+  ];
+
+  for (const ext of extensions) {
+    const candidate = resolved + ext;
+    const candidatePath = path.join(rootDir, candidate);
+
+    if (fs.existsSync(candidatePath) && fs.statSync(candidatePath).isFile()) {
+      return candidate;
+    }
+  }
+
+  // Could not resolve
+  return null;
+}
+
+/**
+ * Find project root by looking for package.json
+ */
+function findProjectRoot(startPath: string): string {
+  let currentDir = path.dirname(startPath);
+
+  // Walk up until we find package.json or reach root
+  while (currentDir !== path.dirname(currentDir)) {
+    const packageJsonPath = path.join(currentDir, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+      return currentDir;
+    }
+    currentDir = path.dirname(currentDir);
+  }
+
+  // Fallback to starting directory
+  return path.dirname(startPath);
+}
+
+/**
+ * Get cached graph or build new one
+ */
+async function getOrBuildImportGraph(rootDir: string): Promise<ImportGraph> {
+  const now = Date.now();
+
+  // Check if cache is valid
+  if (cachedGraph && (now - cachedGraph.computedAt) < GRAPH_CACHE_TTL_MS) {
+    logDebug('Using cached import graph', {
+      age: Math.round((now - cachedGraph.computedAt) / 1000) + 's',
+    });
+    return cachedGraph.graph;
+  }
+
+  // Build new graph
+  logDebug('Cache expired or missing, building new import graph');
+  const graph = await buildImportGraph(rootDir);
+
+  // Update cache
+  cachedGraph = {
+    graph,
+    computedAt: now,
+  };
+
+  return graph;
+}
+
+/**
+ * Clear the import graph cache
+ * Useful for testing or when files change
+ */
+export function clearImportGraphCache(): void {
+  cachedGraph = null;
+  logDebug('Import graph cache cleared');
+}
+
+/**
+ * Batch calculate centrality for multiple files
+ * More efficient than individual calls when analyzing many files
+ */
+export async function calculateCentralityBatch(
+  filePaths: string[]
+): Promise<Map<string, CentralityResult>> {
+  const results = new Map<string, CentralityResult>();
+
+  // Find common root
+  if (filePaths.length === 0) {
+    return results;
+  }
+
+  const rootDir = findProjectRoot(filePaths[0]);
+
+  // Build graph once (ensures cache is populated)
+  const graph = await getOrBuildImportGraph(rootDir);
+  // Graph is used to populate cache for subsequent calculateCentrality calls
+  void graph;
+
+  // Calculate for each file
+  for (const filePath of filePaths) {
+    const result = await calculateCentrality(filePath);
+    results.set(filePath, result);
+  }
+
+  return results;
+}