@claudemini/shit-cli 1.4.0 → 1.6.0

package/lib/review.js

@@ -0,0 +1,728 @@
+/**
+ * Structured code review over session artifacts.
+ * Inspired by mco's findings model:
+ * - fixed findings schema
+ * - evidence-grounded findings
+ * - deterministic severity/confidence
+ * - dedup + aggregation for CI/PR workflows
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import { createHash } from 'crypto';
+import { getLogDir, getProjectRoot, SESSION_ID_REGEX } from './config.js';
+import { redactSecrets } from './redact.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', // text | json | markdown
+    strict: false,
+    minSeverity: 'info',
+    failOn: 'high',
+    sessionId: null,
+    recent: 1,
+    all: false,
+    help: false,
+  };
+
+  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 === '--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('-') && !options.sessionId) {
+      options.sessionId = arg;
+    }
+  }
+
+  return options;
+}
+
+function printUsage() {
+  console.log('Usage: shit 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('  --strict                      Exit non-zero when findings hit fail-on threshold');
+}
+
+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 loadJsonIfExists(filePath, fallback = null) {
+  if (!existsSync(filePath)) {
+    return fallback;
+  }
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function normalizeEvidence(evidence) {
+  return evidence
+    .filter(Boolean)
+    .map(item => String(item).trim())
+    .filter(Boolean);
+}
+
+function normalizeFinding(input) {
+  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: input.location || null,
+    evidence: normalizeEvidence(input.evidence || []),
+    sessions: Array.isArray(input.sessions) ? [...new Set(input.sessions)] : [],
+  };
+}
+
+function normalizeLocation(location) {
+  if (!location || typeof location !== 'object') {
+    return '';
+  }
+  const file = location.file || '';
+  const line = location.line || '';
+  const column = location.column || '';
+  return `${file}:${line}:${column}`;
+}
+
+function canonicalFindingKey(finding) {
+  return [
+    String(finding.rule_id || '').trim().toLowerCase(),
+    String(finding.category || '').trim().toLowerCase(),
+    normalizeLocation(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 getAllCommands(summary) {
+  const commandGroups = summary?.activity?.commands || {};
+  return Object.values(commandGroups).flatMap(list => Array.isArray(list) ? list : []);
+}
+
+const WINDOWS_ABS_PATH_REGEX = /(^|[\s([{:="'`])([A-Za-z]:\\(?:[^\\\s"'`|<>]+\\){1,}[^\\\s"'`|<>]+)/g;
+const UNIX_SENSITIVE_ROOT_PATH_REGEX = /(^|[\s([{:="'`])(\/(?:Users|home|var|tmp|opt|etc|private|Volumes|workspace|workspaces|usr)(?:\/[^\s"'`|<>]+){2,})/g;
+const UNIX_FILE_PATH_WITH_EXT_REGEX = /(^|[\s([{:="'`])(\/(?:[^\/\s"'`|<>]+\/){2,}[^\/\s"'`|<>]*\.[A-Za-z0-9]{1,10})/g;
+
+function sanitizeErrorDetails(message) {
+  const text = String(message || 'Tool returned an error');
+  const redacted = redactSecrets(text)
+    .replace(WINDOWS_ABS_PATH_REGEX, '$1[PATH]')
+    .replace(UNIX_SENSITIVE_ROOT_PATH_REGEX, '$1[PATH]')
+    .replace(UNIX_FILE_PATH_WITH_EXT_REGEX, '$1[PATH]')
+    .replace(/\b[A-Z_]{2,}=[^\s"'`|<>]+/g, '[ENV_REDACTED]');
+  return redacted.slice(0, 200);
+}
+
+function generateFindings(summary, state, sessionId) {
+  const findings = [];
+  const reviewHints = summary?.review_hints || {};
+  const changes = summary?.changes?.files || [];
+  const activity = summary?.activity || {};
+  const errors = Array.isArray(activity.errors) ? activity.errors : [];
+  const commands = getAllCommands(summary);
+  const modifiedSourceFiles = changes.filter(file =>
+    file.category === 'source' &&
+    Array.isArray(file.operations) &&
+    file.operations.some(op => op !== 'read')
+  );
+
+  if (modifiedSourceFiles.length > 0 && !reviewHints.tests_run) {
+    findings.push({
+      rule_id: 'testing.no_tests_after_source_changes',
+      category: 'testing',
+      severity: modifiedSourceFiles.length >= 5 ? 'high' : 'medium',
+      confidence: 'high',
+      summary: 'Source code changed without test execution evidence',
+      details: `Detected ${modifiedSourceFiles.length} modified source file(s), but no test command was recorded.`,
+      suggestion: 'Run targeted tests for changed modules and attach the command/output in the session.',
+      evidence: [
+        `session_id=${sessionId}`,
+        `review_hints.tests_run=${Boolean(reviewHints.tests_run)}`,
+        `modified_source_files=${modifiedSourceFiles.length}`,
+      ],
+      sessions: [sessionId],
+    });
+  }
+
+  if (reviewHints.migration_added && !reviewHints.tests_run) {
+    findings.push({
+      rule_id: 'correctness.migration_without_tests',
+      category: 'correctness',
+      severity: 'high',
+      confidence: 'high',
+      summary: 'Database migration changed without test validation',
+      details: 'Migration-related changes are present and no test run was captured.',
+      suggestion: 'Run migration verification and regression tests before merge.',
+      evidence: [
+        `session_id=${sessionId}`,
+        `review_hints.migration_added=${Boolean(reviewHints.migration_added)}`,
+        `review_hints.tests_run=${Boolean(reviewHints.tests_run)}`,
+      ],
+      sessions: [sessionId],
+    });
+  }
+
+  if (reviewHints.config_changed && !reviewHints.build_verified) {
+    findings.push({
+      rule_id: 'reliability.config_without_build',
+      category: 'reliability',
+      severity: 'medium',
+      confidence: 'high',
+      summary: 'Configuration changed without build verification',
+      details: 'Config-level edits were detected, but no build/compile command was recorded.',
+      suggestion: 'Run a full build/compile and include output to reduce deployment risk.',
+      evidence: [
+        `session_id=${sessionId}`,
+        `review_hints.config_changed=${Boolean(reviewHints.config_changed)}`,
+        `review_hints.build_verified=${Boolean(reviewHints.build_verified)}`,
+      ],
+      sessions: [sessionId],
+    });
+  }
+
+  if (reviewHints.large_change && !reviewHints.tests_run && !reviewHints.build_verified) {
+    findings.push({
+      rule_id: 'maintainability.large_change_without_validation',
+      category: 'maintainability',
+      severity: 'high',
+      confidence: 'medium',
+      summary: 'Large change set lacks both test and build signals',
+      details: 'A large multi-file change was made without recorded test/build validation.',
+      suggestion: 'Split change into smaller PRs or provide CI/local validation evidence.',
+      evidence: [
+        `session_id=${sessionId}`,
+        `review_hints.large_change=${Boolean(reviewHints.large_change)}`,
+        `review_hints.tests_run=${Boolean(reviewHints.tests_run)}`,
+        `review_hints.build_verified=${Boolean(reviewHints.build_verified)}`,
+      ],
+      sessions: [sessionId],
+    });
+  }
+
+  if (Array.isArray(reviewHints.files_without_tests) && reviewHints.files_without_tests.length > 0) {
+    const sample = reviewHints.files_without_tests.slice(0, 3);
+    findings.push({
+      rule_id: 'testing.files_without_tests',
+      category: 'testing',
+      severity: reviewHints.files_without_tests.length > 5 ? 'high' : 'medium',
+      confidence: 'medium',
+      summary: 'Modified source files have no corresponding test changes',
+      details: `Detected ${reviewHints.files_without_tests.length} file(s) without related test updates.`,
+      suggestion: 'Add/adjust tests for changed source files or document why tests are not needed.',
+      location: { file: sample[0] },
+      evidence: [
+        `session_id=${sessionId}`,
+        `review_hints.files_without_tests_count=${reviewHints.files_without_tests.length}`,
+        ...sample.map(file => `file_without_test=${file}`),
+      ],
+      sessions: [sessionId],
+    });
+  }
+
+  for (const error of errors.slice(-3)) {
+    findings.push({
+      rule_id: 'reliability.tool_error',
+      category: 'reliability',
+      severity: 'medium',
+      confidence: 'high',
+      summary: `Tool error detected: ${error.tool || 'unknown tool'}`,
+      details: sanitizeErrorDetails(error.message),
+      suggestion: 'Confirm the error is resolved and include successful rerun evidence.',
+      evidence: [
+        `session_id=${sessionId}`,
+        'activity.errors_present=true',
+        `error_tool=${error.tool || 'unknown'}`,
+      ],
+      sessions: [sessionId],
+    });
+  }
+
+  const rollbackCommands = commands.filter(cmd =>
+    /\bgit\s+(reset|restore|revert)\b/i.test(cmd) ||
+    /\bgit\s+checkout\s+--\b/i.test(cmd) ||
+    /\bundo\b/i.test(cmd)
+  );
+  if (rollbackCommands.length >= 2) {
+    findings.push({
+      rule_id: 'maintainability.frequent_rollback_commands',
+      category: 'maintainability',
+      severity: rollbackCommands.length >= 4 ? 'high' : 'medium',
+      confidence: 'medium',
+      summary: 'Frequent rollback/undo commands detected in one session',
+      details: `Detected ${rollbackCommands.length} rollback-style command(s), which may indicate unstable iteration.`,
+      suggestion: 'Split the change and validate each step to reduce back-and-forth edits.',
+      evidence: [
+        `session_id=${sessionId}`,
+        `rollback_command_count=${rollbackCommands.length}`,
+        ...rollbackCommands.slice(0, 3).map(cmd => `rollback_cmd=${cmd.slice(0, 80)}`),
+      ],
+      sessions: [sessionId],
+    });
+  }
+
+  if ((summary?.session?.risk || '') === 'high') {
+    findings.push({
+      rule_id: 'maintainability.high_risk_session',
+      category: 'maintainability',
+      severity: 'medium',
+      confidence: 'medium',
+      summary: 'Session-level risk was classified as high',
+      details: 'The extraction engine labeled this session as high risk based on change shape.',
+      suggestion: 'Require manual reviewer sign-off and verify rollback/checkpoint strategy.',
+      evidence: [
+        `session_id=${sessionId}`,
+        `summary.session.risk=${summary.session.risk}`,
+      ],
+      sessions: [sessionId],
+    });
+  }
+
+  if (state?.checkpoints && state.checkpoints.length > 0) {
+    findings.push({
+      rule_id: 'maintainability.checkpoints_present',
+      category: 'maintainability',
+      severity: 'info',
+      confidence: 'high',
+      summary: 'Checkpoint chain exists for this session',
+      details: `Detected ${state.checkpoints.length} checkpoint commit(s), enabling safer rollback.`,
+      suggestion: 'Use "shit rewind <checkpoint>" if post-merge regression appears.',
+      evidence: [
+        `session_id=${sessionId}`,
+        `state.checkpoints_count=${state.checkpoints.length}`,
+      ],
+      sessions: [sessionId],
+    });
+  }
+
+  return findings;
+}
+
+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 files = Array.isArray(snap.summary?.changes?.files) ? snap.summary.changes.files : [];
+    for (const file of files) {
+      if (file.category !== 'source') {
+        continue;
+      }
+      if (!fileToSessions.has(file.path)) {
+        fileToSessions.set(file.path, new Set());
+      }
+      fileToSessions.get(file.path).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 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 buildReport(selectedSessions, options) {
+  const snapshots = selectedSessions.map(buildSessionSnapshot);
+  const rawFindings = [];
+
+  for (const snap of snapshots) {
+    if (!snap.summary) {
+      rawFindings.push(generateSummaryMissingFinding(snap.id));
+      continue;
+    }
+    rawFindings.push(...generateFindings(snap.summary, snap.state, snap.id));
+  }
+  rawFindings.push(...generateCrossSessionFindings(snapshots.filter(snap => snap.summary)));
+
+  const deduped = dedupeFindings(rawFindings);
+  const filteredFindings = filterBySeverity(deduped, options.minSeverity);
+  const verdict = computeVerdict(filteredFindings, options.failOn);
+
+  return {
+    schema_version: '1.1',
+    generated_at: new Date().toISOString(),
+    policy: {
+      min_severity: options.minSeverity,
+      fail_on: options.failOn,
+      strict: options.strict,
+      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: 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 printMarkdownReport(report) {
+  const lines = [];
+  lines.push('# Code Review Report');
+  lines.push('');
+  lines.push(`- Verdict: **${report.verdict.toUpperCase()}**`);
+  lines.push(`- Sessions: **${report.stats.reviewed_sessions}**`);
+  lines.push(`- Findings: **${report.findings.length}**`);
+  lines.push(`- Policy: \`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.');
+    console.log(lines.join('\n'));
+    return;
+  }
+
+  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('');
+  }
+
+  console.log(lines.join('\n'));
+}
+
+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;
+    }
+
+    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 report = buildReport(selectedSessions, options);
+
+    if (options.format === 'json') {
+      console.log(JSON.stringify(report, null, 2));
+    } else if (options.format === 'markdown') {
+      printMarkdownReport(report);
+    } else {
+      printHumanReport(report);
+      console.log('Options: --json --markdown --recent=<n> --all --strict --min-severity=<...> --fail-on=<...>');
+    }
+
+    if (options.strict && shouldFailByThreshold(report.findings, options.failOn)) {
+      return 1;
+    }
+    return 0;
+  } catch (error) {
+    console.error('❌ Failed to run review:', error.message);
+    return 1;
+  }
+}