agileflow 3.3.0 → 3.4.1

package/scripts/lib/ac-test-matcher.js

@@ -0,0 +1,452 @@
+/**
+ * ac-test-matcher.js - Automated Acceptance Criteria to Test Mapping
+ *
+ * Reads story AC from status.json, scans test files for keyword overlap,
+ * and returns matched/unmatched AC with confidence levels.
+ *
+ * Usage:
+ *   const { matchACToTests } = require('./lib/ac-test-matcher');
+ *
+ *   const result = matchACToTests('US-0042', projectRoot);
+ *   // result = {
+ *   //   storyId: 'US-0042',
+ *   //   total: 5,
+ *   //   matched: [{ index: 0, ac: '...', confidence: 'high', testFiles: [...] }],
+ *   //   unmatched: [{ index: 2, ac: '...' }],
+ *   //   coverage: 0.6
+ *   // }
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { getProjectRoot, getStatusPath } = require('../../lib/paths');
+const { safeReadJSON } = require('../../lib/errors');
+
+// ============================================================================
+// Keyword Extraction
+// ============================================================================
+
+/**
+ * Extract meaningful keywords from an AC string.
+ * Filters out stop words and short tokens.
+ */
+const STOP_WORDS = new Set([
+  'the',
+  'a',
+  'an',
+  'is',
+  'are',
+  'was',
+  'were',
+  'be',
+  'been',
+  'being',
+  'have',
+  'has',
+  'had',
+  'do',
+  'does',
+  'did',
+  'will',
+  'would',
+  'could',
+  'should',
+  'may',
+  'might',
+  'must',
+  'shall',
+  'can',
+  'need',
+  'dare',
+  'to',
+  'of',
+  'in',
+  'for',
+  'on',
+  'with',
+  'at',
+  'by',
+  'from',
+  'as',
+  'into',
+  'through',
+  'during',
+  'before',
+  'after',
+  'above',
+  'below',
+  'and',
+  'but',
+  'or',
+  'nor',
+  'not',
+  'so',
+  'yet',
+  'both',
+  'either',
+  'neither',
+  'each',
+  'every',
+  'all',
+  'any',
+  'few',
+  'more',
+  'most',
+  'other',
+  'some',
+  'such',
+  'no',
+  'only',
+  'own',
+  'same',
+  'than',
+  'too',
+  'very',
+  'just',
+  'that',
+  'this',
+  'these',
+  'those',
+  'it',
+  'its',
+  'when',
+  'where',
+  'how',
+  'what',
+  'which',
+  'who',
+  'whom',
+  'then',
+  'there',
+  'here',
+  'if',
+  'else',
+  'while',
+  'about',
+  'up',
+  'out',
+  'also',
+  'given',
+  'user',
+  'system',
+  'able',
+]);
+
+function extractKeywords(text) {
+  if (!text || typeof text !== 'string') return [];
+  // Split on non-alphanumeric (keep hyphenated words)
+  const tokens = text
+    .toLowerCase()
+    .replace(/[^a-z0-9-_]/g, ' ')
+    .split(/\s+/)
+    .filter(t => t.length >= 3 && !STOP_WORDS.has(t));
+
+  return [...new Set(tokens)];
+}
+
+// ============================================================================
+// Test File Discovery
+// ============================================================================
+
+/** Common test file patterns */
+const TEST_PATTERNS = [
+  /\.test\.[jt]sx?$/,
+  /\.spec\.[jt]sx?$/,
+  /_test\.[jt]sx?$/,
+  /_test\.go$/,
+  /test_.*\.py$/,
+  /.*_test\.py$/,
+  /\.test\.ts$/,
+];
+
+/**
+ * Recursively find test files under a directory.
+ * Skips node_modules, dist, .git, coverage, etc.
+ */
+function findTestFiles(dir, maxDepth = 5) {
+  const results = [];
+  const skipDirs = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    'coverage',
+    '.next',
+    '.nuxt',
+    '.agileflow',
+    '.claude',
+    'vendor',
+  ]);
+
+  function walk(currentDir, depth) {
+    if (depth > maxDepth) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (!skipDirs.has(entry.name)) {
+          walk(path.join(currentDir, entry.name), depth + 1);
+        }
+      } else if (entry.isFile()) {
+        if (TEST_PATTERNS.some(pat => pat.test(entry.name))) {
+          results.push(path.join(currentDir, entry.name));
+        }
+      }
+    }
+  }
+
+  walk(dir, 0);
+  return results;
+}
+
+// ============================================================================
+// Test Content Scanning
+// ============================================================================
+
+/**
+ * Read a test file and extract its content for keyword matching.
+ * Returns lowercased content (describe/it blocks, comments, etc.)
+ */
+function readTestContent(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    return content.toLowerCase();
+  } catch {
+    return '';
+  }
+}
+
+// ============================================================================
+// AC-to-Test Matching
+// ============================================================================
+
+/**
+ * Calculate keyword overlap between AC keywords and test file content.
+ * Returns a confidence score.
+ */
+function calculateConfidence(acKeywords, testContent) {
+  if (acKeywords.length === 0) return 0;
+  let matchCount = 0;
+  for (const kw of acKeywords) {
+    if (testContent.includes(kw)) {
+      matchCount++;
+    }
+  }
+  const ratio = matchCount / acKeywords.length;
+  return ratio;
+}
+
+/**
+ * Determine confidence level from ratio.
+ */
+function confidenceLevel(ratio) {
+  if (ratio >= 0.6) return 'high';
+  if (ratio >= 0.3) return 'medium';
+  if (ratio > 0) return 'low';
+  return 'none';
+}
+
+/**
+ * Match acceptance criteria to test files.
+ *
+ * @param {string} storyId - Story ID (e.g., 'US-0042')
+ * @param {string} [rootDir] - Project root (auto-detected if omitted)
+ * @returns {{ storyId, total, matched, unmatched, coverage, error? }}
+ */
+function matchACToTests(storyId, rootDir) {
+  rootDir = rootDir || getProjectRoot();
+
+  if (!rootDir) {
+    return {
+      storyId,
+      total: 0,
+      matched: [],
+      unmatched: [],
+      coverage: 0,
+      error: 'Project root not found',
+    };
+  }
+
+  // Load story from status.json
+  const statusPath = getStatusPath(rootDir);
+  const result = safeReadJSON(statusPath, { defaultValue: { stories: {} } });
+  const status = result.ok ? result.data : null;
+  if (!status || !status.stories) {
+    return {
+      storyId,
+      total: 0,
+      matched: [],
+      unmatched: [],
+      coverage: 0,
+      error: 'status.json not found or invalid',
+    };
+  }
+
+  const story = status.stories[storyId];
+  if (!story) {
+    return {
+      storyId,
+      total: 0,
+      matched: [],
+      unmatched: [],
+      coverage: 0,
+      error: `Story ${storyId} not found`,
+    };
+  }
+
+  const acList = story.acceptance_criteria || story.ac || [];
+  if (!Array.isArray(acList) || acList.length === 0) {
+    return {
+      storyId,
+      total: 0,
+      matched: [],
+      unmatched: [],
+      coverage: 0,
+      error: 'No acceptance criteria defined',
+    };
+  }
+
+  // Find test files
+  const testFiles = findTestFiles(rootDir);
+  if (testFiles.length === 0) {
+    return {
+      storyId,
+      total: acList.length,
+      matched: [],
+      unmatched: acList.map((ac, i) => ({
+        index: i,
+        ac: typeof ac === 'string' ? ac : ac.text || String(ac),
+      })),
+      coverage: 0,
+      error: 'No test files found',
+    };
+  }
+
+  // Read all test content (cached in memory for this run)
+  const testContentMap = {};
+  for (const tf of testFiles) {
+    testContentMap[tf] = readTestContent(tf);
+  }
+
+  // Match each AC against test files
+  const matched = [];
+  const unmatched = [];
+
+  for (let i = 0; i < acList.length; i++) {
+    const acText = typeof acList[i] === 'string' ? acList[i] : acList[i].text || String(acList[i]);
+    const keywords = extractKeywords(acText);
+
+    if (keywords.length === 0) {
+      unmatched.push({ index: i, ac: acText });
+      continue;
+    }
+
+    // Find best matching test files
+    const fileMatches = [];
+    for (const [filePath, content] of Object.entries(testContentMap)) {
+      const ratio = calculateConfidence(keywords, content);
+      if (ratio > 0) {
+        fileMatches.push({
+          file: path.relative(rootDir, filePath),
+          ratio,
+          confidence: confidenceLevel(ratio),
+        });
+      }
+    }
+
+    // Sort by match ratio descending
+    fileMatches.sort((a, b) => b.ratio - a.ratio);
+
+    // Take top 3 matches
+    const topMatches = fileMatches.slice(0, 3);
+    const bestConfidence = topMatches.length > 0 ? topMatches[0].confidence : 'none';
+
+    if (bestConfidence === 'high' || bestConfidence === 'medium') {
+      matched.push({
+        index: i,
+        ac: acText,
+        confidence: bestConfidence,
+        keywords,
+        testFiles: topMatches.map(m => ({ file: m.file, confidence: m.confidence })),
+      });
+    } else {
+      unmatched.push({
+        index: i,
+        ac: acText,
+        keywords,
+        testFiles:
+          topMatches.length > 0
+            ? topMatches.map(m => ({ file: m.file, confidence: m.confidence }))
+            : undefined,
+      });
+    }
+  }
+
+  return {
+    storyId,
+    total: acList.length,
+    matched,
+    unmatched,
+    coverage: acList.length > 0 ? matched.length / acList.length : 0,
+  };
+}
+
+/**
+ * Write ac_status to status.json for a story based on match results.
+ *
+ * @param {string} storyId - Story ID
+ * @param {Object} matchResult - Result from matchACToTests
+ * @param {Object} [manualOverrides] - Manual AC verification { index: 'verified' }
+ * @param {string} [rootDir] - Project root
+ */
+function writeACStatus(storyId, matchResult, manualOverrides = {}, rootDir) {
+  rootDir = rootDir || getProjectRoot();
+  const statusPath = getStatusPath(rootDir);
+  const result = safeReadJSON(statusPath);
+  if (!result.ok || !result.data || !result.data.stories || !result.data.stories[storyId]) return;
+  const status = result.data;
+
+  const acStatus = {};
+
+  // Auto-verified from high-confidence matches
+  for (const m of matchResult.matched) {
+    if (m.confidence === 'high') {
+      acStatus[m.index] = 'auto-verified';
+    } else {
+      acStatus[m.index] = 'likely-covered';
+    }
+  }
+
+  // Unmatched remain unverified
+  for (const u of matchResult.unmatched) {
+    acStatus[u.index] = 'unverified';
+  }
+
+  // Apply manual overrides
+  for (const [idx, val] of Object.entries(manualOverrides)) {
+    acStatus[idx] = val;
+  }
+
+  status.stories[storyId].ac_status = acStatus;
+  status.stories[storyId].ac_coverage = matchResult.coverage;
+
+  const { safeWriteJSON: writeJSON } = require('../../lib/errors');
+  writeJSON(statusPath, status);
+}
+
+module.exports = {
+  matchACToTests,
+  writeACStatus,
+  // Exported for testing
+  extractKeywords,
+  findTestFiles,
+  calculateConfidence,
+  confidenceLevel,
+};

package/scripts/lib/audit-cleanup.js

@@ -0,0 +1,250 @@
+/**
+ * audit-cleanup.js - Orphan cleanup for ULTRADEEP audit sessions
+ *
+ * Cleans up abandoned tmux sessions and incomplete sentinel directories
+ * from ULTRADEEP audit runs. Designed to be called from Stop hooks or
+ * manually for maintenance.
+ *
+ * Usage:
+ *   const { cleanupOrphanSessions } = require('./audit-cleanup');
+ *   cleanupOrphanSessions(rootDir);
+ *
+ * CLI:
+ *   node scripts/lib/audit-cleanup.js [--max-age=60] [--dry-run]
+ */
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const MAX_AGE_MINUTES = 60;
+
+/**
+ * Find all ultradeep trace directories.
+ * @param {string} rootDir - Project root
+ * @returns {Array<{ traceId: string, dir: string, status: object|null }>}
+ */
+function findTraceDirectories(rootDir) {
+  const ultradeepDir = path.join(rootDir, 'docs', '09-agents', 'ultradeep');
+
+  if (!fs.existsSync(ultradeepDir)) {
+    return [];
+  }
+
+  const traces = [];
+  try {
+    const entries = fs.readdirSync(ultradeepDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+
+      const traceDir = path.join(ultradeepDir, entry.name);
+      const statusFile = path.join(traceDir, '_status.json');
+      let status = null;
+
+      try {
+        if (fs.existsSync(statusFile)) {
+          status = JSON.parse(fs.readFileSync(statusFile, 'utf8'));
+        }
+      } catch (_) {
+        // Corrupt status file
+      }
+
+      traces.push({
+        traceId: entry.name,
+        dir: traceDir,
+        status,
+      });
+    }
+  } catch (_) {
+    // Directory read failure
+  }
+
+  return traces;
+}
+
+/**
+ * Check if a trace is stale (older than maxAge).
+ * @param {object} trace - Trace info from findTraceDirectories
+ * @param {number} maxAgeMinutes - Maximum age in minutes
+ * @returns {boolean}
+ */
+function isStaleTrace(trace, maxAgeMinutes) {
+  if (!trace.status || !trace.status.started_at) {
+    // No status = assume stale
+    return true;
+  }
+
+  const startedAt = new Date(trace.status.started_at).getTime();
+  if (isNaN(startedAt)) return true; // Invalid date = treat as stale
+  const age = Date.now() - startedAt;
+  return age > maxAgeMinutes * 60 * 1000;
+}
+
+/**
+ * Check if a trace is incomplete (not all analyzers have findings).
+ * @param {object} trace - Trace info from findTraceDirectories
+ * @returns {boolean}
+ */
+function isIncompleteTrace(trace) {
+  if (!trace.status || !trace.status.analyzers) return true;
+
+  const expected = trace.status.analyzers;
+  const completed = trace.status.completed || [];
+
+  return completed.length < expected.length;
+}
+
+/**
+ * Find orphaned tmux sessions matching audit pattern.
+ * @returns {string[]} Array of session names
+ */
+function findOrphanedTmuxSessions() {
+  try {
+    const output = execFileSync('tmux', ['list-sessions', '-F', '#{session_name}'], {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+
+    if (!output) return [];
+
+    return output.split('\n').filter(name => name.startsWith('audit-'));
+  } catch (_) {
+    return [];
+  }
+}
+
+/**
+ * Kill a tmux session by name.
+ * @param {string} sessionName - Session name to kill
+ * @returns {boolean} True if killed successfully
+ */
+function killTmuxSession(sessionName) {
+  try {
+    execFileSync('tmux', ['kill-session', '-t', sessionName], {
+      stdio: 'pipe',
+    });
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Remove a sentinel directory.
+ * @param {string} dir - Directory to remove
+ * @returns {boolean} True if removed successfully
+ */
+function removeSentinelDir(dir) {
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Clean up orphaned ULTRADEEP audit sessions and stale sentinel dirs.
+ *
+ * @param {string} rootDir - Project root directory
+ * @param {object} [options] - Options
+ * @param {number} [options.maxAgeMinutes] - Max age for stale traces (default: 60)
+ * @param {boolean} [options.dryRun] - If true, report but don't delete
+ * @returns {{ sessionsKilled: string[], tracesRemoved: string[], errors: string[] }}
+ */
+function cleanupOrphanSessions(rootDir, options) {
+  const maxAge = (options && options.maxAgeMinutes) || MAX_AGE_MINUTES;
+  const dryRun = (options && options.dryRun) || false;
+
+  const result = {
+    sessionsKilled: [],
+    tracesRemoved: [],
+    errors: [],
+  };
+
+  // 1. Find and kill orphaned tmux sessions
+  const orphanedSessions = findOrphanedTmuxSessions();
+  for (const session of orphanedSessions) {
+    // Extract trace ID from session name: audit-{type}-{traceId}
+    const parts = session.split('-');
+    if (parts.length < 3) continue; // Malformed session name, skip
+    const traceId = parts.slice(2).join('-');
+
+    if (dryRun) {
+      result.sessionsKilled.push(`${session} (dry-run)`);
+      continue;
+    }
+
+    if (killTmuxSession(session)) {
+      result.sessionsKilled.push(session);
+    } else {
+      result.errors.push(`Failed to kill session: ${session}`);
+    }
+  }
+
+  // 2. Clean up stale sentinel directories
+  const traces = findTraceDirectories(rootDir);
+  for (const trace of traces) {
+    if (isStaleTrace(trace, maxAge) && isIncompleteTrace(trace)) {
+      if (dryRun) {
+        result.tracesRemoved.push(`${trace.traceId} (dry-run)`);
+        continue;
+      }
+
+      if (removeSentinelDir(trace.dir)) {
+        result.tracesRemoved.push(trace.traceId);
+      } else {
+        result.errors.push(`Failed to remove trace dir: ${trace.traceId}`);
+      }
+    }
+  }
+
+  return result;
+}
+
+// CLI
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  let maxAge = MAX_AGE_MINUTES;
+  let dryRun = false;
+
+  for (const arg of args) {
+    if (arg.startsWith('--max-age=')) {
+      const parsed = parseInt(arg.split('=')[1], 10);
+      maxAge = isNaN(parsed) ? MAX_AGE_MINUTES : parsed;
+    }
+    if (arg === '--dry-run') dryRun = true;
+  }
+
+  const rootDir = process.cwd();
+  const result = cleanupOrphanSessions(rootDir, { maxAgeMinutes: maxAge, dryRun });
+
+  if (result.sessionsKilled.length > 0) {
+    console.log(`Killed ${result.sessionsKilled.length} orphaned session(s):`);
+    result.sessionsKilled.forEach(s => console.log(`  - ${s}`));
+  }
+
+  if (result.tracesRemoved.length > 0) {
+    console.log(`Removed ${result.tracesRemoved.length} stale trace(s):`);
+    result.tracesRemoved.forEach(t => console.log(`  - ${t}`));
+  }
+
+  if (result.errors.length > 0) {
+    console.error(`${result.errors.length} error(s):`);
+    result.errors.forEach(e => console.error(`  - ${e}`));
+  }
+
+  if (result.sessionsKilled.length === 0 && result.tracesRemoved.length === 0) {
+    console.log('No orphaned sessions or stale traces found.');
+  }
+}
+
+module.exports = {
+  findTraceDirectories,
+  isStaleTrace,
+  isIncompleteTrace,
+  findOrphanedTmuxSessions,
+  killTmuxSession,
+  removeSentinelDir,
+  cleanupOrphanSessions,
+};