@claudemini/ses-cli 1.4.3

package/lib/review.js

@@ -0,0 +1,652 @@
+/**
+ * Structured code review over session artifacts.
+ * Uses goatchain agent output and keeps the existing findings/report schema.
+ */
+
+import { existsSync, readdirSync, statSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { createHash } from 'crypto';
+import { getLogDir, getProjectRoot, SESSION_ID_REGEX } from './config.js';
+import { dispatchWebhook } from './webhook.js';
+import {
+  loadJsonIfExists,
+  normalizeEvidence,
+  normalizeLocation,
+  normalizeLocationKey,
+} from './review-common.js';
+
+const SEVERITY_SCORE = {
+  info: 1,
+  low: 2,
+  medium: 3,
+  high: 4,
+  critical: 5,
+};
+
+const CONFIDENCE_SCORE = {
+  low: 1,
+  medium: 2,
+  high: 3,
+};
+
+function parseArgs(args) {
+  const options = {
+    format: 'text',
+    strict: false,
+    minSeverity: 'info',
+    failOn: 'high',
+    sessionId: null,
+    recent: 1,
+    all: false,
+    help: false,
+    engine: 'agent',
+    agentTimeoutMs: null,
+    allowWorktreeDiff: false,
+    agentAutoApprove: true,
+    deprecatedFlags: [],
+    deprecatedEngineValue: null,
+  };
+
+  for (const arg of args) {
+    if (arg === '--json') {
+      options.format = 'json';
+      continue;
+    }
+    if (arg === '--markdown' || arg === '--md') {
+      options.format = 'markdown';
+      continue;
+    }
+    if (arg === '--strict') {
+      options.strict = true;
+      continue;
+    }
+    if (arg === '--all') {
+      options.all = true;
+      continue;
+    }
+    if (arg === '--agent') {
+      options.deprecatedFlags.push('--agent');
+      continue;
+    }
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+      continue;
+    }
+    if (arg.startsWith('--recent=')) {
+      const value = Number.parseInt(arg.split('=')[1], 10);
+      if (Number.isFinite(value) && value > 0) {
+        options.recent = value;
+      }
+      continue;
+    }
+    if (arg.startsWith('--min-severity=')) {
+      const value = (arg.split('=')[1] || '').toLowerCase();
+      if (SEVERITY_SCORE[value]) {
+        options.minSeverity = value;
+      }
+      continue;
+    }
+    if (arg.startsWith('--fail-on=')) {
+      const value = (arg.split('=')[1] || '').toLowerCase();
+      if (SEVERITY_SCORE[value]) {
+        options.failOn = value;
+      }
+      continue;
+    }
+    if (arg.startsWith('--engine=')) {
+      const value = (arg.split('=')[1] || '').toLowerCase();
+      options.deprecatedFlags.push('--engine');
+      options.deprecatedEngineValue = value || null;
+      continue;
+    }
+    if (arg.startsWith('--agent-timeout-ms=')) {
+      const value = Number.parseInt(arg.split('=')[1], 10);
+      if (Number.isFinite(value) && value > 0) {
+        options.agentTimeoutMs = value;
+      }
+      continue;
+    }
+    if (arg === '--allow-worktree-diff') {
+      options.allowWorktreeDiff = true;
+      continue;
+    }
+    if (arg === '--agent-auto-approve') {
+      options.agentAutoApprove = true;
+      continue;
+    }
+    if (arg === '--no-agent-auto-approve') {
+      options.agentAutoApprove = false;
+      continue;
+    }
+    if (arg.startsWith('--agent-auto-approve=')) {
+      const value = (arg.split('=')[1] || '').toLowerCase();
+      if (value === 'true' || value === '1' || value === 'yes') {
+        options.agentAutoApprove = true;
+      }
+      if (value === 'false' || value === '0' || value === 'no') {
+        options.agentAutoApprove = false;
+      }
+      continue;
+    }
+    if (!arg.startsWith('-') && !options.sessionId) {
+      options.sessionId = arg;
+    }
+  }
+
+  return options;
+}
+
+function printUsage() {
+  console.log('Usage: ses review [session-id] [options]');
+  console.log('');
+  console.log('Options:');
+  console.log('  --json                         Output JSON report');
+  console.log('  --markdown, --md              Output Markdown report');
+  console.log('  --recent=<n>                  Review latest n sessions (default: 1)');
+  console.log('  --all                         Review all sessions');
+  console.log('  --min-severity=<level>        Filter findings below severity');
+  console.log('  --fail-on=<level>             Strict mode failure threshold (default: high)');
+  console.log('  --agent-timeout-ms=<ms>       Agent timeout (default: 60s base + 30s/session)');
+  console.log('  --allow-worktree-diff         Allow worktree diff fallback without checkpoint commits');
+  console.log('  --agent-auto-approve=<bool>   Auto approve agent tool calls (default: true)');
+  console.log('  --no-agent-auto-approve       Disable auto approval for agent tool calls');
+  console.log('  --strict                      Exit non-zero when findings hit fail-on threshold');
+  console.log('');
+  console.log('Deprecated options (accepted but ignored):');
+  console.log('  --agent');
+  console.log('  --engine=<name>');
+}
+
+function getSessionDirs(logDir) {
+  if (!existsSync(logDir)) {
+    return [];
+  }
+
+  const sessions = [];
+  for (const name of readdirSync(logDir)) {
+    if (!SESSION_ID_REGEX.test(name)) {
+      continue;
+    }
+
+    const fullPath = join(logDir, name);
+    let stat;
+    try {
+      stat = statSync(fullPath);
+    } catch {
+      continue;
+    }
+
+    if (!stat.isDirectory()) {
+      continue;
+    }
+
+    sessions.push({
+      id: name,
+      dir: fullPath,
+      mtime: stat.mtime.getTime(),
+    });
+  }
+
+  return sessions.sort((a, b) => b.mtime - a.mtime);
+}
+
+function normalizeFinding(input) {
+  const sessions = Array.isArray(input.sessions) ? [...new Set(input.sessions)] : [];
+  return {
+    id: input.id || '',
+    rule_id: input.rule_id || 'review.generic',
+    category: input.category || 'maintainability',
+    severity: input.severity || 'low',
+    confidence: input.confidence || 'medium',
+    summary: input.summary || '',
+    details: input.details || '',
+    suggestion: input.suggestion || '',
+    location: normalizeLocation(input.location),
+    evidence: normalizeEvidence(input.evidence, {
+      fallbackItems: sessions.length > 0 ? sessions.map(id => `session_id=${id}`) : ['evidence_missing=true'],
+    }),
+    sessions,
+  };
+}
+
+function canonicalFindingKey(finding) {
+  return [
+    String(finding.rule_id || '').trim().toLowerCase(),
+    String(finding.category || '').trim().toLowerCase(),
+    normalizeLocationKey(finding.location),
+    String(finding.summary || '').trim().toLowerCase(),
+  ].join('|');
+}
+
+function buildFindingId(finding) {
+  const canonical = canonicalFindingKey(finding);
+  const digest = createHash('sha256').update(canonical).digest('hex');
+  return `f_${digest.slice(0, 16)}`;
+}
+
+function dedupeFindings(findings) {
+  const map = new Map();
+
+  for (const candidate of findings) {
+    const finding = normalizeFinding(candidate);
+    const key = canonicalFindingKey(finding);
+    finding.id = buildFindingId(finding);
+
+    if (!map.has(key)) {
+      map.set(key, finding);
+      continue;
+    }
+
+    const prev = map.get(key);
+    const merged = {
+      ...prev,
+      severity: SEVERITY_SCORE[finding.severity] > SEVERITY_SCORE[prev.severity] ? finding.severity : prev.severity,
+      confidence: (CONFIDENCE_SCORE[finding.confidence] || 0) > (CONFIDENCE_SCORE[prev.confidence] || 0)
+        ? finding.confidence
+        : prev.confidence,
+      details: prev.details.length >= finding.details.length ? prev.details : finding.details,
+      suggestion: prev.suggestion || finding.suggestion,
+      evidence: [...new Set([...prev.evidence, ...finding.evidence])],
+      sessions: [...new Set([...(prev.sessions || []), ...(finding.sessions || [])])],
+    };
+
+    merged.id = prev.id;
+    map.set(key, merged);
+  }
+
+  return [...map.values()].sort((a, b) => SEVERITY_SCORE[b.severity] - SEVERITY_SCORE[a.severity]);
+}
+
+function generateSummaryMissingFinding(sessionId) {
+  return {
+    rule_id: 'integrity.missing_summary',
+    category: 'correctness',
+    severity: 'high',
+    confidence: 'high',
+    summary: 'Session summary artifact is missing or invalid',
+    details: `summary.json was missing/corrupted for session ${sessionId}, review confidence is degraded.`,
+    suggestion: 'Re-run session processing or inspect raw events to reconstruct summary artifacts.',
+    evidence: [`session_id=${sessionId}`],
+    sessions: [sessionId],
+  };
+}
+
+function generateCrossSessionFindings(snapshots) {
+  if (snapshots.length < 2) {
+    return [];
+  }
+
+  const fileToSessions = new Map();
+
+  for (const snap of snapshots) {
+    const sourcePaths = collectSessionSourcePaths(snap);
+    for (const sourcePath of sourcePaths) {
+      if (!fileToSessions.has(sourcePath)) {
+        fileToSessions.set(sourcePath, new Set());
+      }
+      fileToSessions.get(sourcePath).add(snap.id);
+    }
+  }
+
+  const hotFiles = [...fileToSessions.entries()]
+    .filter(([, sessions]) => sessions.size >= 2)
+    .sort((a, b) => b[1].size - a[1].size);
+
+  if (hotFiles.length === 0) {
+    return [];
+  }
+
+  const HOT_FILE_LIMIT = 3;
+  return hotFiles.slice(0, HOT_FILE_LIMIT).map(([filePath, sessionSet], idx) => ({
+    rule_id: 'maintainability.hot_file_across_sessions',
+    category: 'maintainability',
+    severity: sessionSet.size >= 4 ? 'high' : 'medium',
+    confidence: 'medium',
+    summary: 'Same source file modified across multiple reviewed sessions',
+    details: `File "${filePath}" was modified in ${sessionSet.size} reviewed sessions, which may signal unresolved churn.`,
+    suggestion: 'Investigate root cause and consolidate related changes into a single reviewed thread.',
+    location: { file: filePath },
+    evidence: [
+      `hot_file=${filePath}`,
+      `session_count=${sessionSet.size}`,
+      `hot_file_rank=${idx + 1}`,
+      ...[...sessionSet].slice(0, 5).map(id => `session_id=${id}`),
+    ],
+    sessions: [...sessionSet],
+  }));
+}
+
+function collectSessionSourcePaths(snapshot) {
+  const pathsFromSummary = Array.isArray(snapshot.summary?.changes?.files)
+    ? snapshot.summary.changes.files
+      .filter(file => file?.category === 'source')
+      .map(file => String(file.path || '').trim())
+      .filter(Boolean)
+    : [];
+
+  if (pathsFromSummary.length > 0) {
+    return [...new Set(pathsFromSummary)];
+  }
+
+  const statePaths = new Set();
+  collectPathCandidates(snapshot.state?.edits, statePaths);
+  collectPathCandidates(snapshot.state?.file_ops, statePaths);
+  return [...statePaths];
+}
+
+function collectPathCandidates(entries, outputSet) {
+  if (!Array.isArray(entries)) {
+    return;
+  }
+
+  for (const entry of entries) {
+    if (typeof entry === 'string') {
+      addPathCandidate(entry, outputSet);
+      continue;
+    }
+    if (!entry || typeof entry !== 'object') {
+      continue;
+    }
+
+    addPathCandidate(entry.path, outputSet);
+    addPathCandidate(entry.file, outputSet);
+    addPathCandidate(entry.target, outputSet);
+    addPathCandidate(entry.source, outputSet);
+    addPathCandidate(entry.from, outputSet);
+    addPathCandidate(entry.to, outputSet);
+  }
+}
+
+function addPathCandidate(pathValue, outputSet) {
+  const path = String(pathValue || '').trim();
+  if (!path) {
+    return;
+  }
+  if (path.startsWith('.git/') || path.startsWith('.ses-logs/') || path.includes('/.git/')) {
+    return;
+  }
+  outputSet.add(path);
+}
+
+function filterBySeverity(findings, minSeverity) {
+  const threshold = SEVERITY_SCORE[minSeverity] || SEVERITY_SCORE.info;
+  return findings.filter(f => (SEVERITY_SCORE[f.severity] || 0) >= threshold);
+}
+
+function shouldFailByThreshold(findings, failOn) {
+  const threshold = SEVERITY_SCORE[failOn] || SEVERITY_SCORE.high;
+  return findings.some(f => (SEVERITY_SCORE[f.severity] || 0) >= threshold);
+}
+
+function computeVerdict(findings, failOn) {
+  if (shouldFailByThreshold(findings, failOn)) {
+    return 'fail';
+  }
+  if (findings.length > 0) {
+    return 'warn';
+  }
+  return 'pass';
+}
+
+function buildSessionSnapshot(sessionEntry) {
+  const summaryPath = join(sessionEntry.dir, 'summary.json');
+  const statePath = join(sessionEntry.dir, 'state.json');
+  const metadataPath = join(sessionEntry.dir, 'metadata.json');
+
+  const summary = loadJsonIfExists(summaryPath);
+  const state = loadJsonIfExists(statePath, {});
+  const metadata = loadJsonIfExists(metadataPath, {});
+
+  return {
+    id: sessionEntry.id,
+    summary,
+    state,
+    metadata,
+    source: {
+      summary_file: summaryPath,
+      state_file: statePath,
+    },
+  };
+}
+
+function buildReportFromRawFindings(snapshots, rawFindings, options) {
+  const deduped = dedupeFindings(rawFindings);
+  const filteredFindings = filterBySeverity(deduped, options.minSeverity);
+  const verdict = computeVerdict(filteredFindings, options.failOn);
+
+  return {
+    schema_version: '1.2',
+    generated_at: new Date().toISOString(),
+    policy: {
+      min_severity: options.minSeverity,
+      fail_on: options.failOn,
+      strict: options.strict,
+      engine: options.engine,
+      recent: options.all ? 'all' : options.recent,
+      session_filter: options.sessionId || null,
+    },
+    verdict,
+    sessions: snapshots.map(snap => ({
+      id: snap.id,
+      type: snap.summary?.session?.type || snap.metadata?.type || 'unknown',
+      risk: snap.summary?.session?.risk || snap.metadata?.risk || 'unknown',
+      duration_minutes: snap.summary?.session?.duration_minutes ?? snap.metadata?.duration_minutes ?? 0,
+      source: snap.source,
+    })),
+    findings: filteredFindings,
+    stats: {
+      reviewed_sessions: snapshots.length,
+      total_findings: filteredFindings.length,
+      by_severity: Object.keys(SEVERITY_SCORE).reduce((acc, key) => {
+        acc[key] = filteredFindings.filter(f => f.severity === key).length;
+        return acc;
+      }, {}),
+    },
+  };
+}
+
+function printHumanReport(report) {
+  console.log(`🧪 Code Review`);
+  console.log(`   Sessions: ${report.stats.reviewed_sessions}`);
+  console.log(`   Verdict: ${report.verdict.toUpperCase()} | Findings: ${report.findings.length}`);
+  console.log(`   Policy: engine=${report.policy.engine}, min=${report.policy.min_severity}, fail-on=${report.policy.fail_on}`);
+  console.log();
+
+  if (report.sessions.length === 1) {
+    const session = report.sessions[0];
+    console.log(`📦 Session: ${session.id}`);
+    console.log(`   Type: ${session.type} | Risk: ${session.risk} | Duration: ${session.duration_minutes}m`);
+    console.log();
+  }
+
+  if (report.findings.length === 0) {
+    console.log('✅ No findings above current severity threshold.');
+    return;
+  }
+
+  for (const [idx, finding] of report.findings.entries()) {
+    console.log(`${idx + 1}. [${finding.severity.toUpperCase()}][${finding.category}] ${finding.summary}`);
+    console.log(`   Rule: ${finding.rule_id} | Confidence: ${finding.confidence}`);
+    if (finding.details) {
+      console.log(`   Detail: ${finding.details}`);
+    }
+    if (finding.location?.file) {
+      console.log(`   Location: ${finding.location.file}`);
+    }
+    if (finding.sessions?.length > 0) {
+      console.log(`   Sessions: ${finding.sessions.slice(0, 3).join(', ')}${finding.sessions.length > 3 ? ` (+${finding.sessions.length - 3})` : ''}`);
+    }
+    if (finding.evidence.length > 0) {
+      console.log(`   Evidence: ${finding.evidence.slice(0, 3).join(' | ')}`);
+    }
+    if (finding.suggestion) {
+      console.log(`   Suggestion: ${finding.suggestion}`);
+    }
+    console.log();
+  }
+}
+
+function buildMarkdownReport(report) {
+  const lines = [];
+  lines.push('# Code Review Report');
+  lines.push('');
+  lines.push(`- Generated: **${report.generated_at}**`);
+  lines.push(`- Verdict: **${report.verdict.toUpperCase()}**`);
+  lines.push(`- Sessions: **${report.stats.reviewed_sessions}**`);
+  lines.push(`- Findings: **${report.findings.length}**`);
+  lines.push(`- Policy: \`engine=${report.policy.engine}, min=${report.policy.min_severity}, fail-on=${report.policy.fail_on}\``);
+  lines.push('');
+
+  lines.push('## Findings');
+  lines.push('');
+
+  if (report.findings.length === 0) {
+    lines.push('No findings above threshold.');
+    return lines.join('\n');
+  }
+
+  lines.push('| Severity | Category | Rule | Summary | Sessions |');
+  lines.push('|---|---|---|---|---|');
+  for (const finding of report.findings) {
+    const sessions = finding.sessions?.length || 0;
+    const summary = finding.summary.replace(/\|/g, '\\|');
+    lines.push(`| ${finding.severity.toUpperCase()} | ${finding.category} | \`${finding.rule_id}\` | ${summary} | ${sessions} |`);
+  }
+
+  lines.push('');
+  lines.push('## Details');
+  lines.push('');
+
+  for (const finding of report.findings) {
+    lines.push(`### [${finding.severity.toUpperCase()}] ${finding.summary}`);
+    lines.push(`- Rule: \`${finding.rule_id}\``);
+    lines.push(`- Confidence: \`${finding.confidence}\``);
+    if (finding.sessions?.length > 0) {
+      lines.push(`- Sessions: ${finding.sessions.join(', ')}`);
+    }
+    if (finding.location?.file) {
+      lines.push(`- Location: \`${finding.location.file}\``);
+    }
+    if (finding.details) {
+      lines.push(`- Detail: ${finding.details}`);
+    }
+    if (finding.suggestion) {
+      lines.push(`- Suggestion: ${finding.suggestion}`);
+    }
+    if (finding.evidence.length > 0) {
+      lines.push(`- Evidence: ${finding.evidence.slice(0, 5).join(' | ')}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function saveReviewArtifacts(logDir, report, markdown) {
+  const sessionIds = report.sessions.map(s => s.id);
+
+  for (const sessionId of sessionIds) {
+    const sessionDir = join(logDir, sessionId);
+    if (!existsSync(sessionDir)) {
+      continue;
+    }
+    try {
+      writeFileSync(join(sessionDir, 'review.md'), markdown, 'utf8');
+      writeFileSync(join(sessionDir, 'review.json'), JSON.stringify(report, null, 2), 'utf8');
+    } catch {
+      // Best-effort, don't fail review.
+    }
+  }
+
+  const savedBoth = sessionIds.filter((id) => {
+    const sessionDir = join(logDir, id);
+    return existsSync(join(sessionDir, 'review.md')) && existsSync(join(sessionDir, 'review.json'));
+  });
+  if (savedBoth.length > 0) {
+    console.error(`📝 Review saved to ${savedBoth.length} session(s): review.md, review.json`);
+  }
+}
+
+function selectSessions(allSessions, options) {
+  if (options.sessionId) {
+    const matched = allSessions.find(s => s.id === options.sessionId || s.id.startsWith(options.sessionId));
+    return matched ? [matched] : [];
+  }
+
+  if (options.all) {
+    return allSessions;
+  }
+
+  return allSessions.slice(0, options.recent);
+}
+
+export default async function review(args) {
+  try {
+    const options = parseArgs(args);
+    if (options.help) {
+      printUsage();
+      return 0;
+    }
+
+    if (options.deprecatedFlags.length > 0) {
+      console.error(`⚠️  Deprecated review flags are ignored: ${[...new Set(options.deprecatedFlags)].join(', ')}.`);
+      if (options.deprecatedEngineValue && options.deprecatedEngineValue !== 'agent') {
+        console.error(`⚠️  --engine=${options.deprecatedEngineValue} is unsupported. Using goatchain agent review.`);
+      }
+    }
+
+    const projectRoot = getProjectRoot();
+    const logDir = getLogDir(projectRoot);
+    const sessions = getSessionDirs(logDir);
+
+    if (sessions.length === 0) {
+      console.error('❌ No sessions found for review.');
+      return 1;
+    }
+
+    const selectedSessions = selectSessions(sessions, options);
+    if (selectedSessions.length === 0) {
+      console.error(`❌ Session not found: ${options.sessionId}`);
+      return 1;
+    }
+
+    const snapshots = selectedSessions.map(buildSessionSnapshot);
+    const rawFindings = [];
+
+    for (const snap of snapshots) {
+      if (!snap.summary) {
+        rawFindings.push(generateSummaryMissingFinding(snap.id));
+      }
+    }
+
+    const { runAgentReview } = await import('./agent-review.js');
+    const agentFindings = await runAgentReview(projectRoot, selectedSessions, options);
+    rawFindings.push(...agentFindings);
+    // Intentional: include snapshots without summary and fallback to state paths when available.
+    rawFindings.push(...generateCrossSessionFindings(snapshots));
+
+    const report = buildReportFromRawFindings(snapshots, rawFindings, options);
+    const markdown = buildMarkdownReport(report);
+
+    saveReviewArtifacts(logDir, report, markdown);
+    await dispatchWebhook(projectRoot, 'review.completed', report);
+
+    if (options.format === 'json') {
+      console.log(JSON.stringify(report, null, 2));
+    } else if (options.format === 'markdown') {
+      console.log(markdown);
+    } else {
+      printHumanReport(report);
+      console.log('Options: --json --markdown --recent=<n> --all --strict --min-severity=<...> --fail-on=<...> --agent-timeout-ms=<...>');
+    }
+
+    if (options.strict && shouldFailByThreshold(report.findings, options.failOn)) {
+      return 1;
+    }
+
+    return 0;
+  } catch (error) {
+    console.error('❌ Failed to run review:', error.message);
+    return 1;
+  }
+}