@boyingliu01/xp-gate 0.33.0 → 0.33.2

package/gates/gate-7.ts

@@ -0,0 +1,147 @@
+/**
+ * Gate 7: IaC Security Scanning (Terraform, Kubernetes, Docker, PowerShell DSC)
+ * Detects security issues in Infrastructure as Code files.
+ * TypeScript rewrite of githooks/adapters/gate-7.sh for cross-platform Node.js CLI.
+ */
+import path from 'path';
+import fs from 'fs';
+import {
+  GateInput, GateOutput, isToolAvailable, runTool, recordAudit, filterIaCFiles,
+  getChangedFiles, detectProjectLang,
+} from './common';
+
+export function runGate7(input: GateInput): GateOutput {
+  const startMs = Date.now();
+  const cwd = input.cwd || process.cwd();
+  const messages: string[] = [];
+
+  messages.push('');
+  messages.push('→ Gate 7: IaC Security Scanning (Terraform, Kubernetes, Docker)...');
+
+  // Filter to IaC files (includes PowerShell DSC per design)
+  const iacFiles = filterIaCFiles(input.changedFiles);
+
+  if (iacFiles.length === 0) {
+    messages.push('✅ PASSED - No IaC files detected in changes.');
+    recordAudit('gate-7', 'iac-security', 'PASS', 0, startMs);
+    return { status: 'PASS', messages, exitCode: 0 };
+  }
+
+  // checkov is the PREFERRED engine (see the module header and the fallback
+  // message below), so it is tried FIRST. #650: the adapter lookup used to run
+  // before this and SKIP the gate whenever a consumer project had no vendored
+  // `githooks/adapters/iac.sh` -- even with checkov installed and on PATH. A
+  // security gate that skips because an optional helper script is absent, while
+  // the real scanner is available, reports "nothing to check" about code that was
+  // never checked. The bash adapter is the FALLBACK, so it is consulted after.
+  const checkov = isToolAvailable('checkov', cwd);
+  if (checkov.available) {
+    return runCheckov(checkov.path, checkov.via, iacFiles, cwd, startMs, messages);
+  }
+
+  // Fallback: run the bash IaC adapter via bash
+  messages.push('⚠️  checkov not installed — falling back to bash IaC adapter');
+  messages.push('   Install: pip install checkov');
+
+  return runBashAdapter(iacFiles, cwd, startMs, messages);
+}
+
+/**
+ * Fallback path: hand the IaC files to the project's bash adapter.
+ *
+ * Extracted from `runGate7` so the primary (checkov) path stays readable and the
+ * entry point stays inside the long-function limit. A missing adapter is a SKIP,
+ * never a PASS: no scan ran, so there is no evidence to report as clean.
+ */
+function runBashAdapter(
+  iacFiles: string[],
+  cwd: string,
+  startMs: number,
+  messages: string[]
+): GateOutput {
+  const adapterPath = findIaCAdapter(cwd);
+  if (!adapterPath) {
+    messages.push('ℹ️  SKIP - IaC adapter not found');
+    messages.push('⏭️  SKIPPED - IaC security (no IaC adapter found)');
+    recordAudit('gate-7', 'iac-security', 'SKIP', 0, startMs);
+    return { status: 'SKIP', messages, exitCode: 0 };
+  }
+
+  const result = runTool('bash', [adapterPath, ...iacFiles], { cwd });
+  const combinedOutput = result.stdout + result.stderr;
+
+  if (result.exitCode === 0) {
+    messages.push(combinedOutput);
+    messages.push('✅ PASSED - IaC security scan.');
+    recordAudit('gate-7', 'iac-security', 'PASS', 0, startMs);
+    return { status: 'PASS', messages, exitCode: 0 };
+  }
+
+  messages.push(combinedOutput);
+  messages.push('');
+  messages.push('❌ BLOCKED - IaC security issues detected');
+  messages.push('Fix the security issues above before committing.');
+  messages.push('Tip: Install checkov for comprehensive IaC scanning: pip install checkov');
+  recordAudit('gate-7', 'iac-security', 'FAIL', result.exitCode, startMs);
+  return { status: 'FAIL', messages, exitCode: 1 };
+}
+
+function runCheckov(
+  cmdPath: string,
+  via: string,
+  files: string[],
+  cwd: string,
+  startMs: number,
+  messages: string[]
+): GateOutput {
+  const checkovCmd = via === 'npx' ? 'npx' : cmdPath;
+  const checkovArgs = via === 'npx' ? ['-y', 'checkov'] : [];
+
+  // Detect config file
+  const configPath = path.join(cwd, '.checkov.yaml');
+  if (fs.existsSync(configPath)) {
+    checkovArgs.push('--config-file', configPath);
+  }
+
+  // Run checkov on the changed IaC files
+  checkovArgs.push('--file', ...files, '--quiet', '--compact');
+
+  const result = runTool(checkovCmd, checkovArgs, { cwd });
+  const combinedOutput = result.stdout + result.stderr;
+
+  if (result.exitCode === 0) {
+    messages.push(combinedOutput);
+    messages.push('✅ PASSED - IaC security scan.');
+    recordAudit('gate-7', 'iac-security', 'PASS', 0, startMs);
+    return { status: 'PASS', messages, exitCode: 0 };
+  }
+
+  messages.push(combinedOutput);
+  messages.push('');
+  messages.push('❌ BLOCKED - IaC security issues detected');
+  messages.push('Fix the security issues above before committing.');
+  recordAudit('gate-7', 'iac-security', 'FAIL', result.exitCode, startMs);
+  return { status: 'FAIL', messages, exitCode: 1 };
+}
+
+function findIaCAdapter(cwd: string): string | null {
+  const candidates = [
+    path.join(cwd, 'githooks', 'adapters', 'iac.sh'),
+    path.join(cwd, 'githooks', 'adapters', 'iac', 'iac.sh'),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  return null;
+}
+
+// ── CLI Entry Point ──
+if (process.argv.includes('--run')) {
+  const cwdIdx = process.argv.indexOf('--cwd');
+  const cwd = cwdIdx >= 0 ? process.argv[cwdIdx + 1] : process.cwd();
+  const changedFiles = getChangedFiles(cwd);
+  const projectLang = detectProjectLang(cwd);
+  const result = runGate7({ changedFiles, projectLang, cwd });
+  result.messages.forEach(m => console.log(m));
+  process.exit(result.exitCode);
+}

package/gates/gate-8.ts

@@ -0,0 +1,92 @@
+/**
+ * Gate 8: Secret Scanning (gitleaks)
+ * Detects secrets (API keys, passwords, tokens) in staged files.
+ * TypeScript rewrite of githooks/adapters/gate-8.sh for cross-platform Node.js CLI.
+ */
+import path from 'path';
+import fs from 'fs';
+import {
+  GateInput, GateOutput, isToolAvailable, runTool, recordAudit, getTempDir,
+  getChangedFiles, detectProjectLang,
+} from './common';
+
+export function runGate8(input: GateInput): GateOutput {
+  const startMs = Date.now();
+  const cwd = input.cwd || process.cwd();
+  const messages: string[] = [];
+
+  messages.push('');
+  messages.push('→ Gate 8: Secret scanning (gitleaks)...');
+
+  // Tool detection
+  const tool = isToolAvailable('gitleaks', cwd);
+  if (!tool.available) {
+    messages.push('     ℹ️  gitleaks not installed — secret scanning unavailable');
+    messages.push('     Install: brew install gitleaks (macOS) | winget install gitleaks (Windows)');
+    messages.push('     ⏭️  SKIPPED - Secret scanning (gitleaks not installed)');
+    recordAudit('gate-8', 'secret-scanning', 'SKIP', 0, startMs);
+    return { status: 'SKIP', messages, exitCode: 0 };
+  }
+
+  const gitleaksCmd = tool.via === 'npx' ? 'npx' : tool.path;
+  const gitleaksArgs = tool.via === 'npx' ? ['-y', 'gitleaks'] : [];
+
+  // Config detection
+  const configPath = findGitleaksConfig(cwd);
+  if (configPath) {
+    gitleaksArgs.push(`--config=${configPath}`);
+  }
+
+  // Cross-platform temp path (fixes /tmp issue on Windows)
+  const reportPath = path.join(getTempDir(), 'gitleaks-report.json');
+
+  // Run gitleaks on staged changes
+  gitleaksArgs.push('git', '--pre-commit', '--redact', '--no-banner',
+    '--report-format=json', `--report-path=${reportPath}`);
+
+  const result = runTool(gitleaksCmd, gitleaksArgs, { cwd });
+
+  if (result.exitCode === 0) {
+    messages.push('     ✅ PASSED - No secrets detected.');
+    recordAudit('gate-8', 'secret-scanning', 'PASS', 0, startMs);
+    return { status: 'PASS', messages, exitCode: 0 };
+  }
+
+  if (result.exitCode === 1) {
+    // Secrets found
+    messages.push(result.stdout);
+    messages.push('');
+    messages.push('❌ BLOCKED - Secrets detected in staged files.');
+    messages.push('');
+    messages.push('Remediation options:');
+    messages.push('  1. Remove the secret and use environment variables instead');
+    messages.push('  2. Add a false positive to .gitleaks.toml allowlist');
+    messages.push('  3. Use git secret or vault for sensitive data');
+    messages.push('');
+    messages.push('See: https://github.com/gitleaks/gitleaks');
+    recordAudit('gate-8', 'secret-scanning', 'FAIL', 1, startMs);
+    return { status: 'FAIL', messages, exitCode: 1 };
+  }
+
+  // Runtime error
+  messages.push(`     ⚠️  gitleaks exited with code ${result.exitCode} - skipping gate`);
+  messages.push('     ✅ Secret Scanning (SKIP, gitleaks error)');
+  recordAudit('gate-8', 'secret-scanning', 'SKIP', result.exitCode, startMs);
+  return { status: 'SKIP', messages, exitCode: 0 };
+}
+
+function findGitleaksConfig(cwd: string): string | null {
+  const configPath = path.join(cwd, '.gitleaks.toml');
+  return fs.existsSync(configPath) ? configPath : null;
+}
+
+// ── CLI Entry Point ──
+if (process.argv.includes('--run')) {
+  const cwdIdx = process.argv.indexOf('--cwd');
+  const cwd = cwdIdx >= 0 ? process.argv[cwdIdx + 1] : process.cwd();
+  const changedFiles = getChangedFiles(cwd);
+  const projectLang = detectProjectLang(cwd);
+  const result = runGate8({ changedFiles, projectLang, cwd });
+  result.messages.forEach(m => console.log(m));
+  process.exit(result.exitCode);
+}

package/gates/gate-9.ts

@@ -0,0 +1,269 @@
+/**
+ * Gate 9: Semgrep SAST Security Scan
+ * Detects security vulnerabilities in staged files.
+ * For PowerShell projects: uses PSScriptAnalyzer security rules as alternative.
+ * TypeScript rewrite of githooks/adapters/gate-9.sh for cross-platform Node.js CLI.
+ */
+import {
+  GateInput, GateOutput, isToolAvailable, runTool, recordAudit,
+  filterSemgrepFiles, detectPowerShell, isPowerShellProject, runPowerShellTool,
+  getChangedFiles, detectProjectLang,
+} from './common';
+
+export function runGate9(input: GateInput): GateOutput {
+  const startMs = Date.now();
+  const messages: string[] = [];
+
+  messages.push('');
+  messages.push('→ Gate 9: Semgrep SAST Security Scan...');
+
+  // PowerShell project: use PSScriptAnalyzer security rules
+  if (isPowerShellProject(input.projectLang)) {
+    return runPowerShellSAST(input, startMs, messages);
+  }
+
+  // Standard path: semgrep
+  const tool = isToolAvailable('semgrep', input.cwd);
+  if (!tool.available) {
+    messages.push('     ⚠️  WARN - semgrep not installed — SAST scanning unavailable');
+    messages.push('     Install: brew install semgrep (macOS) | pip install semgrep (Linux/Windows)');
+    messages.push('     Pre-cache rules: semgrep --config=p/security-audit');
+    messages.push('     Gate 9: SAST Security (WARN, semgrep not installed)');
+    recordAudit('gate-9', 'sast-security', 'WARN', 0, startMs);
+    return { status: 'WARN', messages, exitCode: 0 };
+  }
+
+  const semgrepCmd = tool.via === 'npx' ? 'npx' : tool.path;
+  const semgrepArgs = tool.via === 'npx' ? ['-y', 'semgrep'] : [];
+
+  // Filter to semgrep-supported language files
+  const semgrepFiles = filterSemgrepFiles(input.changedFiles);
+  if (semgrepFiles.length === 0) {
+    messages.push('     ⏭️  SKIPPED - SAST (no supported language files changed)');
+    recordAudit('gate-9', 'sast-security', 'SKIP', 0, startMs);
+    return { status: 'SKIP', messages, exitCode: 0 };
+  }
+
+  // Run semgrep with JSON output
+  semgrepArgs.push('scan', '--config=p/security-audit', '--json', '--disable-version-check', ...semgrepFiles);
+
+  const result = runTool(semgrepCmd, semgrepArgs, { cwd: input.cwd });
+
+  // #518 (same defect class as the bash gate-10.sh fix): the exit code does NOT
+  // carry the verdict. semgrep exits 0 even with ERROR-severity findings, and
+  // its exit-code semantics drift across versions/platforms. The verdict comes
+  // from the JSON; the exit code only tells whether the tool itself ran.
+  return parseSemgrepResults(result.stdout, result.exitCode, result.stderr, startMs, messages);
+}
+
+// #518: warnings-only vocabulary. Everything OUTSIDE this list — including
+// semgrep's ERROR tier, the legacy CRITICAL/HIGH tiers, and any unknown or
+// missing severity — counts as BLOCKING: a security gate must fail closed on
+// tiers it does not recognize.
+const NONBLOCKING_SEVERITIES = ['WARNING', 'INFO', 'MEDIUM', 'LOW'];
+const MAX_DETAIL_FINDINGS = 5;
+const MAX_FINDING_MESSAGE_LENGTH = 80;
+
+interface SemgrepFinding {
+  check_id?: string;
+  path?: string;
+  start?: { line?: number };
+  extra?: { severity?: string; message?: string };
+}
+
+function pushStderrDiagnostics(messages: string[], stderr: string): void {
+  if (!stderr) {
+    return;
+  }
+  messages.push('     ── what semgrep reported ──');
+  messages.push(...stderr.split('\n').slice(-10).map(l => `     ${l}`));
+}
+
+function countBySeverity(results: SemgrepFinding[]): { blocking: number; warnings: number } {
+  let blocking = 0;
+  let warnings = 0;
+  results.forEach(r => {
+    const s = (r.extra?.severity || '').toUpperCase();
+    if (NONBLOCKING_SEVERITIES.includes(s)) {
+      warnings++;
+    } else {
+      blocking++;
+    }
+  });
+  return { blocking, warnings };
+}
+
+function findingDetailLines(results: SemgrepFinding[]): string[] {
+  const lines: string[] = [];
+  results.slice(0, MAX_DETAIL_FINDINGS).forEach(r => {
+    const severity = (r.extra?.severity || 'UNKNOWN').toUpperCase();
+    const ruleId = r.check_id || 'unknown';
+    const filePath = r.path || 'unknown';
+    const line = r.start?.line || '?';
+    const msg = (r.extra?.message || '').slice(0, MAX_FINDING_MESSAGE_LENGTH);
+    lines.push(`  [${severity}] ${ruleId}`);
+    lines.push(`  ${filePath}:${line} → ${msg}`);
+    lines.push('');
+  });
+  return lines;
+}
+
+function renderSemgrepBlock(
+  blocking: number,
+  warnings: number,
+  findingLines: string[],
+  startMs: number,
+  messages: string[]
+): GateOutput {
+  messages.push('');
+  messages.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  messages.push('   GATE 9: Semgrep Security Gate');
+  messages.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  messages.push(`  CRITICAL/HIGH/ERROR:     ${blocking}  ❌ BLOCKED`);
+  messages.push(`  MEDIUM/LOW/WARNING/INFO: ${warnings}  ⚠️  warning`);
+  messages.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  messages.push('  ❌ BLOCKED — blocking-severity vulnerability found');
+  messages.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  messages.push(...findingLines);
+  messages.push("  Run 'semgrep scan --config=p/security-audit' to review all findings.");
+  recordAudit('gate-9', 'sast-security', 'FAIL', blocking, startMs);
+  return { status: 'FAIL', messages, exitCode: 1 };
+}
+
+function parseSemgrepResults(
+  jsonOutput: string,
+  exitCode: number,
+  stderr: string,
+  startMs: number,
+  messages: string[]
+): GateOutput {
+  let data: { results?: SemgrepFinding[]; errors?: Array<{ message?: string }> };
+  try {
+    data = JSON.parse(jsonOutput);
+  } catch {
+    // Fail closed (#518): unparseable output cannot be judged — SKIP, never PASS.
+    messages.push('     ⚠️  semgrep output unparseable or verdict fields missing — cannot determine verdict');
+    pushStderrDiagnostics(messages, stderr);
+    messages.push('     ⏭️  SKIPPED - SAST (semgrep output unparseable)');
+    recordAudit('gate-9', 'sast-security', 'SKIP', exitCode, startMs);
+    return { status: 'SKIP', messages, exitCode: 0 };
+  }
+
+  const results: SemgrepFinding[] = data.results || [];
+  const scanErrors = data.errors || [];
+
+  // Nothing scanned to a verdict: tool failure (nonzero exit) or scan errors on
+  // every input. Must neither block nor claim a pass (#475 contract, #518 R2:
+  // exit 0 + results:[] + errors:[{...}] used to fall through to PASS).
+  if (results.length === 0 && (scanErrors.length > 0 || exitCode !== 0)) {
+    messages.push(`     ⚠️  semgrep exit=${exitCode}, scan errors=${scanErrors.length}, findings=${results.length} — nothing to judge`);
+    pushStderrDiagnostics(messages, stderr);
+    messages.push('     ⏭️  SKIPPED - SAST (semgrep runtime error)');
+    recordAudit('gate-9', 'sast-security', 'SKIP', exitCode, startMs);
+    return { status: 'SKIP', messages, exitCode: 0 };
+  }
+
+  const { blocking, warnings } = countBySeverity(results);
+  const findingLines = findingDetailLines(results);
+
+  if (blocking > 0) {
+    return renderSemgrepBlock(blocking, warnings, findingLines, startMs, messages);
+  }
+
+  messages.push('');
+  messages.push('     ✅ PASSED - No blocking vulnerabilities');
+  if (warnings > 0) {
+    messages.push(`     ⚠️  ${warnings} non-blocking findings (warnings only)`);
+    messages.push(...findingLines);
+  }
+  recordAudit('gate-9', 'sast-security', 'PASS', 0, startMs);
+  return { status: 'PASS', messages, exitCode: 0 };
+}
+
+const PSSCRIPTANALYZER_SECURITY_RULES = [
+  'PSAvoidUsingInvokeExpression',
+  'PSAvoidUsingConvertToSecureStringWithPlainText',
+  'PSAvoidUsingPlainTextForPassword',
+  'PSAvoidUsingUserNameAndPasswordParams',
+  'PSAvoidUsingWMICmdlet',
+  'PSAvoidUsingWriteHost',
+].join(',');
+
+function buildPSScriptAnalyzerCommand(psFiles: string[]): string {
+  const fileList = psFiles.map(f => `'${f}'`).join(',');
+  return `Invoke-ScriptAnalyzer -Path ${fileList} -IncludeRule ${PSSCRIPTANALYZER_SECURITY_RULES} -ErrorAction SilentlyContinue | ConvertTo-Json`;
+}
+
+function renderPowerShellFindings(
+  findings: Array<{ RuleName?: string; ScriptName?: string; Line?: number; Message?: string }>,
+  startMs: number,
+  messages: string[]
+): GateOutput {
+  messages.push('');
+  messages.push('❌ BLOCKED - PSScriptAnalyzer security findings:');
+  findings.slice(0, MAX_DETAIL_FINDINGS).forEach(f => {
+    messages.push(`  [${f.RuleName || 'UNKNOWN'}] ${f.ScriptName || '?'}:${f.Line || '?'} → ${(f.Message || '').slice(0, MAX_FINDING_MESSAGE_LENGTH)}`);
+  });
+  recordAudit('gate-9', 'sast-security', 'FAIL', findings.length, startMs);
+  return { status: 'FAIL', messages, exitCode: 1 };
+}
+
+/**
+ * PowerShell project SAST using PSScriptAnalyzer security rules.
+ * Replaces semgrep which doesn't support .ps1 files.
+ */
+function runPowerShellSAST(
+  input: GateInput,
+  startMs: number,
+  messages: string[]
+): GateOutput {
+  const ps = detectPowerShell();
+  if (!ps.available) {
+    messages.push('     ⚠️  WARN - PowerShell not available — SAST scanning unavailable');
+    messages.push('     Gate 9: SAST Security (WARN, PowerShell not installed)');
+    recordAudit('gate-9', 'sast-security', 'WARN', 0, startMs);
+    return { status: 'WARN', messages, exitCode: 0 };
+  }
+
+  const psFiles = input.changedFiles.filter(f => f.endsWith('.ps1') || f.endsWith('.psm1'));
+  if (psFiles.length === 0) {
+    messages.push('     ⏭️  SKIPPED - SAST (no PowerShell files changed)');
+    recordAudit('gate-9', 'sast-security', 'SKIP', 0, startMs);
+    return { status: 'SKIP', messages, exitCode: 0 };
+  }
+
+  messages.push('     Running PSScriptAnalyzer security rules...');
+
+  const result = runPowerShellTool(ps, buildPSScriptAnalyzerCommand(psFiles), { cwd: input.cwd });
+
+  if (result.exitCode !== 0) {
+    messages.push('     ⚠️  PSScriptAnalyzer security check failed, skipping');
+    recordAudit('gate-9', 'sast-security', 'WARN', 0, startMs);
+    return { status: 'WARN', messages, exitCode: 0 };
+  }
+
+  try {
+    const findings = result.stdout.trim() ? JSON.parse(result.stdout.trim()) : [];
+    const arr = Array.isArray(findings) ? findings : [findings];
+    if (arr.length > 0) {
+      return renderPowerShellFindings(arr, startMs, messages);
+    }
+  } catch {
+    // JSON parse failure
+  }
+
+  messages.push('     ✅ PASSED - No PowerShell security vulnerabilities found.');
+  recordAudit('gate-9', 'sast-security', 'PASS', 0, startMs);
+  return { status: 'PASS', messages, exitCode: 0 };
+}
+
+// ── CLI Entry Point ──
+if (process.argv.includes('--run')) {
+  const cwdIdx = process.argv.indexOf('--cwd');
+  const cwd = cwdIdx >= 0 ? process.argv[cwdIdx + 1] : process.cwd();
+  const changedFiles = getChangedFiles(cwd);
+  const projectLang = detectProjectLang(cwd);
+  const result = runGate9({ changedFiles, projectLang, cwd });
+  result.messages.forEach(m => console.log(m));
+  process.exit(result.exitCode);
+}

package/gates/pbt-detect.ts

@@ -0,0 +1,163 @@
+/**
+ * Property-Based Testing Detection — reports PBT framework usage in the project.
+ * Implements #337: PBT analytics (report mode, does NOT block).
+ */
+import fs from 'fs';
+import path from 'path';
+
+// ── Types ──
+
+export interface PBTReport {
+  detected: boolean;
+  frameworks: string[];
+  testFiles: string[];
+  pbtTestFiles: string[];
+  coverage: number;
+  messages: string[];
+}
+
+// ── PBT Framework Patterns ──
+
+/** Import patterns that indicate PBT usage. */
+const PBT_IMPORT_PATTERNS = [
+  { name: 'fast-check', patterns: [/from\s+['"]fast-check['"]/, /require\(['"]fast-check['"]\)/, /import.*fc.*from/] },
+  { name: 'jsverify', patterns: [/from\s+['"]jsverify['"]/, /require\(['"]jsverify['"]\)/] },
+  { name: 'jest-property', patterns: [/expect\(\)\.property/, /jest-property/] },
+  { name: 'ava-fast-check', patterns: [/ava.*fast-check/, /test\.property/] },
+];
+
+/** PBT API usage patterns (even without explicit import). */
+const PBT_API_PATTERNS = [
+  /fc\.property\(/,
+  /fc\.assert\(/,
+  /fc\.check\(/,
+  /fc\.sample\(/,
+  /fc\.quickcheck\(/,
+  /jsc\.property\(/,
+  /\.forAll\(/,
+  /property\(.*arb/,
+];
+
+// ── Scanner ──
+
+/** Directories that never hold test sources worth scanning. */
+const SKIPPED_DIRS = new Set(['node_modules', '.git', 'dist']);
+
+/** Test-file suffixes recognised by the PBT scanner. */
+const TEST_SUFFIXES = ['.test.ts', '.test.js', '.spec.ts', '.spec.js'];
+
+function isTestFileName(name: string): boolean {
+  return TEST_SUFFIXES.some(suffix => name.endsWith(suffix));
+}
+
+/** Collect test files under `dir`, descending into subdirectories. */
+function scanDirectory(dir: string, basePath?: string): string[] {
+  if (!fs.existsSync(dir)) return [];
+
+  const results: string[] = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!SKIPPED_DIRS.has(entry.name)) {
+        results.push(...scanDirectory(path.join(dir, entry.name), basePath ?? dir));
+      }
+      continue;
+    }
+    if (isTestFileName(entry.name)) results.push(path.join(dir, entry.name));
+  }
+  return results;
+}
+
+function detectPBTInFile(filePath: string): { hasPBT: boolean; frameworks: string[] } {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const foundFrameworks: string[] = [];
+
+    // Check import patterns
+    for (const fw of PBT_IMPORT_PATTERNS) {
+      if (fw.patterns.some(p => p.test(content))) {
+        foundFrameworks.push(fw.name);
+      }
+    }
+
+    // Check API usage patterns
+    if (foundFrameworks.length === 0) {
+      for (const pattern of PBT_API_PATTERNS) {
+        if (pattern.test(content)) {
+          foundFrameworks.push('unknown-pbt');
+          break;
+        }
+      }
+    }
+
+    return { hasPBT: foundFrameworks.length > 0, frameworks: [...new Set(foundFrameworks)] };
+  } catch {
+    return { hasPBT: false, frameworks: [] };
+  }
+}
+
+// ── Main Analysis ──
+
+/**
+ * Analyze PBT usage in the project.
+ */
+export function detectPBT(cwd?: string): PBTReport {
+  const dir = cwd || process.cwd();
+  const srcDir = path.join(dir, 'src');
+  const messages: string[] = [];
+
+  // Find all test files
+  const testFiles = scanDirectory(srcDir);
+  const pbtTestFiles: string[] = [];
+  const allFrameworks = new Set<string>();
+
+  for (const testFile of testFiles) {
+    const result = detectPBTInFile(testFile);
+    if (result.hasPBT) {
+      pbtTestFiles.push(path.relative(dir, testFile).replace(/\\/g, '/'));
+      result.frameworks.forEach(fw => allFrameworks.add(fw));
+    }
+  }
+
+  const totalTests = testFiles.length;
+  const coverage = totalTests > 0 ? Math.round((pbtTestFiles.length / totalTests) * 100) : 0;
+  const detected = pbtTestFiles.length > 0;
+
+  // Build messages
+  messages.push('');
+  messages.push('━━━ Property-Based Testing Report ━━━');
+  messages.push('');
+  messages.push(`  Test files:    ${totalTests}`);
+  messages.push(`  PBT files:     ${pbtTestFiles.length} (${coverage}%)`);
+  messages.push(`  Frameworks:    ${detected ? [...allFrameworks].join(', ') : 'none detected'}`);
+  messages.push('');
+
+  if (detected) {
+    messages.push('  ✅ PBT usage detected:');
+    pbtTestFiles.forEach(f => messages.push(`    - ${f}`));
+  } else if (totalTests > 0) {
+    messages.push('  ℹ️  No property-based testing detected.');
+    messages.push('  Consider adding fast-check for boundary condition coverage:');
+    messages.push('    npm install -D fast-check');
+    messages.push('    import fc from "fast-check";');
+    messages.push('    test("property: reverse is idempotent", () => {');
+    messages.push('      fc.assert(fc.property(fc.array(fc.integer()), arr => {');
+    messages.push('        expect(arr.reverse().reverse()).toEqual(arr);');
+    messages.push('      }));');
+    messages.push('    });');
+  } else {
+    messages.push('  ℹ️  No test files found.');
+  }
+  messages.push('');
+
+  return { detected, frameworks: [...allFrameworks], testFiles, pbtTestFiles, coverage, messages };
+}
+
+// ── CLI Entry Point ──
+
+if (process.argv.includes('--run')) {
+  const cwdIdx = process.argv.indexOf('--cwd');
+  const cwd = cwdIdx >= 0 ? process.argv[cwdIdx + 1] : process.cwd();
+  const report = detectPBT(cwd);
+  report.messages.forEach(m => console.log(m));
+  process.exit(0);
+}