@boyingliu01/xp-gate 0.33.0 → 0.33.2

package/gate-3.sh

@@ -172,8 +172,19 @@ elif [ "$PROJECT_LANG" = "powershell" ]; then
                   const entries = baseline.functions || baseline.entries || baseline;
                   if (Array.isArray(entries)) {
                     for (const e of entries) {
-                      if (!e || !e.file || !e.name) continue;
-                      known.set(norm(e.file) + "::" + e.name, Number(e.ccn) || 0);
+                      // #632: accept the key the baseline WRITER actually emits.
+                      // tools/Update-ComplexityBaseline.ps1 (the tool this gate
+                      // points at in its own fix-it message) writes "function",
+                      // while this reader only knew "name" -- so every entry was
+                      // dropped, "known" stayed empty, and every function above
+                      // the threshold became a brand-new function. The ratchet
+                      // could never pass. Both spellings are read: this is a
+                      // reader, and the writer vocabulary is not ours to
+                      // redefine from here.
+                      if (!e || !e.file) continue;
+                      const fnName = e.name || e.function;
+                      if (!fnName) continue;
+                      known.set(norm(e.file) + "::" + fnName, Number(e.ccn) || 0);
                     }
                   }
                   // The measurement emits ABSOLUTE paths (pwsh resolved them), while
@@ -529,13 +540,43 @@ else
       # this, a crashing or mis-invoked lizard yields 0 warnings and the gate
       # reports PASSED on zero analysed functions -- the same silent-success
       # failure this issue is about.
+      #
+      # #666: "no rows" has TWO causes and they must not share a verdict. A
+      # module of pure constants legitimately has zero functions, and lizard
+      # emits no row for it at all (measured: `lizard pure_data.py --csv` prints
+      # nothing and exits 0). That was reported as `lizard_output_unparsable`
+      # /WARN, which is the message for a BROKEN lizard -- so a healthy run on a
+      # data-only diff was indistinguishable from a tooling fault. The two are
+      # separated by a POSITIVE probe: ask lizard to describe a fixture known to
+      # contain a function. If it produces rows, lizard works and the input
+      # simply had no functions (SKIP, `no_functions_in_input`); if it does not,
+      # the tool really is broken (WARN, `lizard_output_unparsable`).
       if ! printf '%s\n' "$CC_CSV_FLAT" | awk -F, 'NF > 1 && $2 ~ /^[0-9]+$/ { found = 1; exit }
                                                  END { exit(found ? 0 : 1) }'; then
-        echo "⚠️  WARN - lizard produced no parsable results; complexity not verified"
-        GATE_3_STATUS="WARN"
-        # Consumed by the sourcing parent (pre-commit report JSON), not here.
-        # shellcheck disable=SC2034
-        GATE_3_REASON="lizard_output_unparsable"
+        _lizard_probe_dir=$(mktemp -d 2>/dev/null || echo "${TMPDIR:-/tmp}")
+        _lizard_probe_file="$_lizard_probe_dir/xp-gate-lizard-probe.py"
+        printf 'def _xp_gate_probe(x):\n    if x:\n        return 1\n    return 0\n' > "$_lizard_probe_file" 2>/dev/null
+        _lizard_probe_rows=0
+        if [ -f "$_lizard_probe_file" ]; then
+          _lizard_probe_rows=$(printf '%s\n' "$_lizard_probe_file" \
+            | lizard_batches --csv 2>/dev/null \
+            | awk -F, 'NF > 1 && $2 ~ /^[0-9]+$/ { c++ } END { print c + 0 }')
+        fi
+        rm -rf "$_lizard_probe_dir" 2>/dev/null || true
+        if [ "${_lizard_probe_rows:-0}" -gt 0 ]; then
+          echo "⏭️  SKIPPED - Complexity: the changed source files define no functions (pure data module)."
+          echo "   Verified: lizard parsed a probe fixture normally, so this is an empty result set, not a broken tool."
+          GATE_3_STATUS="SKIP"
+          # Consumed by the sourcing parent (pre-commit report JSON), not here.
+          # shellcheck disable=SC2034
+          GATE_3_REASON="no_functions_in_input"
+        else
+          echo "⚠️  WARN - lizard produced no parsable results; complexity not verified"
+          GATE_3_STATUS="WARN"
+          # Consumed by the sourcing parent (pre-commit report JSON), not here.
+          # shellcheck disable=SC2034
+          GATE_3_REASON="lizard_output_unparsable"
+        fi
       elif [ "$CC_WARNINGS" -gt 0 ]; then
         echo "$CC_OUTPUT"
         echo ""

package/gate-8.sh

@@ -59,10 +59,24 @@ fi
 # revisions and reports "0 commits scanned" on a pre-commit run -- so a staged
 # secret was never seen and Gate 8 always passed. `git --staged` scans
 # `git diff --cached`, which is exactly the pre-commit payload (#449).
+#
+# #616: `--all` is a different question, and the index is the wrong place to ask
+# it. Under `xp-gate check . --all` the user asked "is the whole tree clean", the
+# index is usually empty, `git --staged` legitimately found nothing, and that
+# nothing was counted as PASSED -- a secret sitting in a tracked file was
+# invisible to the one command meant to find it. The runner already exports
+# GATE_SCOPE (#589); this fragment just has to read it. `dir --no-git` scans the
+# filesystem so tracked-but-unmodified files are covered.
 GITLEAKS_REPORT="${TMPDIR:-/tmp}/gitleaks-report.json"
 rm -f "$GITLEAKS_REPORT"
-GITLEAKS_OUTPUT=$($GITLEAKS_CMD git --staged --redact --no-banner $GITLEAKS_CONFIG --report-format=json --report-path="$GITLEAKS_REPORT" 2>&1)
-GITLEAKS_EXIT=$?
+if [ "${GATE_SCOPE:-diff}" = "all" ]; then
+  echo "     Scope: --all (scanning the working tree, not the index)"
+  GITLEAKS_OUTPUT=$($GITLEAKS_CMD dir --no-git --redact --no-banner $GITLEAKS_CONFIG --report-format=json --report-path="$GITLEAKS_REPORT" 2>&1)
+  GITLEAKS_EXIT=$?
+else
+  GITLEAKS_OUTPUT=$($GITLEAKS_CMD git --staged --redact --no-banner $GITLEAKS_CONFIG --report-format=json --report-path="$GITLEAKS_REPORT" 2>&1)
+  GITLEAKS_EXIT=$?
+fi
 
 if [ "$GITLEAKS_EXIT" -eq 0 ]; then
   # Decide SKIP from the REPORT ARTIFACT, not from log wording. Parsing stdout
@@ -183,7 +197,22 @@ fi
 # if-condition (errexit-exempt); a non-zero hook exit lands in the else branch.
 if command -v detect-secrets-hook >/dev/null 2>&1 && [ -f ".secrets.baseline" ]; then
   DS_TMP="$(dirname "$(mktemp -u)")/ds-output.$$"
-  if git diff --cached --name-only --diff-filter=ACM -z \
+  # #616: same scope split as the gitleaks call above. Under `--all` the index is
+  # usually empty, so piping `git diff --cached -z` into xargs fed the hook zero
+  # files and it reported success without reading anything.
+  if [ "${GATE_SCOPE:-diff}" = "all" ]; then
+    if git ls-files -z | xargs -0 detect-secrets-hook --baseline .secrets.baseline > "$DS_TMP" 2>&1; then
+      echo "     ✅ detect-secrets PASSED - no new secrets beyond baseline (scope: --all)."
+    else
+      cat "$DS_TMP"
+      echo ""
+      echo "     ❌ BLOCKED - detect-secrets found secrets not in .secrets.baseline."
+      echo "   If these are false positives, regenerate the baseline (cross-platform):"
+      echo "     detect-secrets scan --update .secrets.baseline && git add .secrets.baseline"
+      rm -f "$DS_TMP"
+      exit 1
+    fi
+  elif git diff --cached --name-only --diff-filter=ACM -z \
       | xargs -0 detect-secrets-hook --baseline .secrets.baseline > "$DS_TMP" 2>&1; then
     echo "     ✅ detect-secrets PASSED - no new secrets beyond baseline."
   else

package/gate-9.sh

@@ -32,8 +32,20 @@ if [ -z "$SEMGREP_CMD" ]; then
   echo "     Gate 9: SAST Security (WARN, semgrep not installed)"
   GATE_9_STATUS="WARN"
 else
-  # Get staged files filtered to Semgrep-supported languages
-  SEMGREP_FILES=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null | grep -E '\.(ts|tsx|js|jsx|py|go|java|c|cpp|cs|rb|php|scala|swift)$' || true)
+  # Get staged files filtered to Semgrep-supported languages.
+  #
+  # #616: under `--all` the index is usually empty, so the staged diff yielded no
+  # files and the gate reported SKIPPED -- "no supported language files changed"
+  # -- for a run whose whole purpose was to scan the tree. Same fail-open shape
+  # #589 fixed in Gate 3, one layer down: the CLI says the tree was checked and
+  # the fragment checks a diff that does not exist. The runner exports GATE_SCOPE;
+  # read it and enumerate tracked files instead.
+  if [ "${GATE_SCOPE:-diff}" = "all" ]; then
+    echo "     Scope: --all (scanning tracked files, not the index)"
+    SEMGREP_FILES=$(git ls-files 2>/dev/null | grep -E '\.(ts|tsx|js|jsx|py|go|java|c|cpp|cs|rb|php|scala|swift)$' || true)
+  else
+    SEMGREP_FILES=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null | grep -E '\.(ts|tsx|js|jsx|py|go|java|c|cpp|cs|rb|php|scala|swift)$' || true)
+  fi
 
   if [ -z "$SEMGREP_FILES" ]; then
     echo "     ⏭️  SKIPPED - SAST (no supported language files changed)"

package/gates/common-process.ts

@@ -0,0 +1,178 @@
+/**
+ * Process-execution and tool-detection primitives shared by the gates.
+ * Split out of common.ts (Boy Scout: many-exports); re-exported there so
+ * every existing `from '../common'` import keeps working unchanged.
+ */
+import { spawnSync, SpawnSyncReturns } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+export interface ToolAvailability {
+  available: boolean;
+  path: string;
+  via: 'path' | 'npx' | 'custom' | 'none';
+}
+
+export interface ToolResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  timedOut: boolean;
+}
+
+export interface PowerShellInfo {
+  available: boolean;
+  exe: string;
+  version: string;
+}
+
+// ── Tool Detection ──
+
+/**
+ * Cross-platform tool detection with 3-tier fallback:
+ * 1. PATH lookup (command -v equivalent)
+ * 2. npx fallback (for npm-installed tools)
+ * 3. Custom path (~/.local/bin/ on Unix)
+ */
+/** Tier 1: PATH lookup. */
+function probeToolPath(tool: string): ToolAvailability {
+  const whichCmd = process.platform === 'win32' ? 'where' : 'which';
+  try {
+    const pathCheck = spawnSync(whichCmd, [tool], { encoding: 'utf-8', timeout: 5000 });
+    if (pathCheck.status === 0 && pathCheck.stdout.trim()) {
+      return { available: true, path: pathCheck.stdout.trim().split('\n')[0], via: 'path' };
+    }
+  } catch { /* probe failed → not on PATH */ }
+  return { available: false, path: '', via: 'none' };
+}
+
+/** Tier 2: npx fallback (check if tool is available via npx). */
+function probeToolNpx(tool: string, cwd?: string): ToolAvailability {
+  try {
+    const npxCheck = spawnSync('npx', ['--yes', tool, '--version'], {
+      encoding: 'utf-8',
+      timeout: 15000,
+      shell: process.platform === 'win32',
+      cwd,
+    });
+    if (npxCheck.status === 0) {
+      return { available: true, path: `npx ${tool}`, via: 'npx' };
+    }
+  } catch { /* probe failed → not reachable via npx */ }
+  return { available: false, path: '', via: 'none' };
+}
+
+export function isToolAvailable(tool: string, cwd?: string): ToolAvailability {
+  // Tier 1: PATH lookup
+  const pathProbe = probeToolPath(tool);
+  if (pathProbe.available) return pathProbe;
+
+  // Tier 2: npx fallback
+  const npxProbe = probeToolNpx(tool, cwd);
+  if (npxProbe.available) return npxProbe;
+
+  // Tier 3: Custom path (~/.local/bin/)
+  if (process.platform !== 'win32') {
+    const customPath = path.join(os.homedir(), '.local', 'bin', tool);
+    if (fs.existsSync(customPath)) {
+      return { available: true, path: customPath, via: 'custom' };
+    }
+  }
+
+  return { available: false, path: '', via: 'none' };
+}
+
+// ── Process Execution ──
+
+/**
+ * Cross-platform spawnSync wrapper with timeout and error handling.
+ * Uses spawnSync (not execSync) to avoid shell injection.
+ */
+export function runTool(
+  cmd: string,
+  args: string[],
+  opts?: { cwd?: string; env?: Record<string, string>; timeoutMs?: number; shell?: boolean }
+): ToolResult {
+  try {
+    const result: SpawnSyncReturns<string> = spawnSync(cmd, args, {
+      encoding: 'utf-8',
+      cwd: opts?.cwd || process.cwd(),
+      env: { ...process.env, ...opts?.env },
+      timeout: opts?.timeoutMs || 120_000,
+      maxBuffer: 10 * 1024 * 1024,
+      shell: opts?.shell || process.platform === 'win32',
+    });
+
+    return {
+      stdout: result.stdout || '',
+      stderr: result.stderr || '',
+      exitCode: result.status ?? -1,
+      timedOut: result.signal === 'SIGTERM' || (result.error as NodeJS.ErrnoException | undefined)?.code === 'ETIMEDOUT',
+    };
+  } catch (err) {
+    // spawnSync throws on ENOENT-class failures; report them as a failed run
+    // with the message on stderr instead of crashing every caller.
+    return { stdout: '', stderr: err instanceof Error ? err.message : String(err), exitCode: -1, timedOut: false };
+  }
+}
+
+// ── Git Helpers ──
+
+/**
+ * Get list of changed (staged) files via git diff --cached.
+ * Equivalent to adapter-common.sh's git diff --cached --name-only.
+ */
+export function getChangedFiles(cwd?: string): string[] {
+  try {
+    const result = spawnSync('git', ['diff', '--cached', '--name-only', '--diff-filter=ACM'], {
+      encoding: 'utf-8',
+      cwd: cwd || process.cwd(),
+      timeout: 10000,
+    });
+    if (result.status !== 0) return [];
+    return result.stdout
+      .split('\n')
+      .map(f => f.trim())
+      .filter(Boolean);
+  } catch {
+    // No git / unreadable repo → no changed files, same as a failed status.
+    return [];
+  }
+}
+
+// ── PowerShell Support ──
+
+/**
+ * Detect PowerShell executable (prefer pwsh 7+, fallback to powershell.exe 5.1).
+ * Mirrors powershell.sh's _detect_pwsh() pattern.
+ */
+/** Probe one candidate executable; null when it is not on PATH. */
+function probePowerShellCandidate(exe: string): PowerShellInfo | null {
+  const whichCmd = process.platform === 'win32' ? 'where' : 'which';
+  try {
+    const check = spawnSync(whichCmd, [exe], { encoding: 'utf-8', timeout: 5000 });
+    if (check.status !== 0 || !check.stdout.trim()) return null;
+    const exePath = check.stdout.trim().split('\n')[0];
+    // Get version
+    const verResult = spawnSync(exe, ['-Command', '$PSVersionTable.PSVersion.ToString()'], {
+      encoding: 'utf-8',
+      timeout: 10000,
+      shell: process.platform === 'win32',
+    });
+    const version = verResult.status === 0 ? verResult.stdout.trim() : 'unknown';
+    return { available: true, exe: exePath, version };
+  } catch { /* probe failed → this candidate is not usable */ }
+  return null;
+}
+
+export function detectPowerShell(): PowerShellInfo {
+  const candidates = ['pwsh', 'powershell.exe', 'powershell'];
+
+  for (const exe of candidates) {
+    const found = probePowerShellCandidate(exe);
+    if (found) return found;
+  }
+
+  return { available: false, exe: '', version: '' };
+}

package/gates/common.ts

@@ -0,0 +1,208 @@
+/**
+ * Shared infrastructure for TypeScript gate modules.
+ * Provides cross-platform tool detection, process execution, audit logging,
+ * project language detection, and PowerShell project support.
+ */
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+// ── Types ──
+
+export interface GateInput {
+  changedFiles: string[];
+  projectLang: string;
+  cwd?: string;
+}
+
+export interface GateOutput {
+  status: 'PASS' | 'FAIL' | 'SKIP' | 'WARN';
+  messages: string[];
+  exitCode: number;
+}
+
+// ── Process & tool primitives (split to common-process.ts for module size) ──
+
+import { runTool, type PowerShellInfo, type ToolResult } from './common-process';
+
+export {
+  type ToolAvailability,
+  type ToolResult,
+  type PowerShellInfo,
+  isToolAvailable,
+  runTool,
+  getChangedFiles,
+  detectPowerShell,
+} from './common-process';
+
+// ── Audit Logging ──
+
+const AUDIT_DIR = '.xp-gate';
+const AUDIT_FILE = 'audit.jsonl';
+
+/**
+ * Record gate execution to .xp-gate/audit.jsonl.
+ * Schema must match bash version's record_gate_audit() output.
+ */
+export function recordAudit(
+  gateId: string,
+  gateName: string,
+  status: string,
+  details: string | number,
+  startMs: number
+): void {
+  const durationMs = Date.now() - startMs;
+  const entry = {
+    timestamp: new Date().toISOString(),
+    gate: gateId,
+    name: gateName,
+    status,
+    details: String(details),
+    duration_ms: durationMs,
+  };
+
+  try {
+    if (!fs.existsSync(AUDIT_DIR)) {
+      fs.mkdirSync(AUDIT_DIR, { recursive: true });
+    }
+    fs.appendFileSync(path.join(AUDIT_DIR, AUDIT_FILE), JSON.stringify(entry) + '\n');
+  } catch {
+    // Audit logging failure should not block the gate
+  }
+}
+
+// ── Language Detection ──
+
+/** Any file in `dir` (non-recursive) matching one of the extensions. */
+function hasFileWithExtension(dir: string, extensions: string[]): boolean {
+  try {
+    const files = fs.readdirSync(dir);
+    return files.some((f) => extensions.some((ext) => f.endsWith(ext)));
+  } catch { /* unreadable dir counts as absent — same as before */ }
+  return false;
+}
+
+/** Java/Kotlin from Gradle markers: any .kt anywhere tips it to Kotlin. */
+function detectJvmLanguage(dir: string): string {
+  try {
+    const files = fs.readdirSync(dir, { recursive: true }) as string[];
+    if (files.some(f => typeof f === 'string' && f.endsWith('.kt'))) return 'kotlin';
+  } catch { /* ignore */ }
+  return 'java';
+}
+
+/** Marker-file language probes, tried in order; first hit wins. */
+const LANG_MARKERS: Array<{ lang: string; files: string[] }> = [
+  { lang: 'typescript', files: ['tsconfig.json'] },
+  { lang: 'python', files: ['pyproject.toml', 'requirements.txt', 'setup.py'] },
+  { lang: 'go', files: ['go.mod'] },
+];
+
+/** Dart vs Flutter, or null when there is no pubspec.yaml. */
+function detectDartFlutter(dir: string): string | null {
+  const pubspec = path.join(dir, 'pubspec.yaml');
+  if (!fs.existsSync(pubspec)) return null;
+  try {
+    const content = fs.readFileSync(pubspec, 'utf-8');
+    if (content.includes('flutter:') || fs.existsSync(path.join(dir, '.metadata'))) return 'flutter';
+  } catch { /* A pubspec we cannot read is still a Dart project. */ }
+  return 'dart';
+}
+
+/** JVM build files: Gradle wins over Maven, matching the original order. */
+function detectJvm(dir: string): string | null {
+  const hasGradle = fs.existsSync(path.join(dir, 'build.gradle'))
+    || fs.existsSync(path.join(dir, 'build.gradle.kts'));
+  if (hasGradle) return detectJvmLanguage(dir);
+  if (fs.existsSync(path.join(dir, 'pom.xml'))) return 'java';
+  return null;
+}
+
+/** Infrastructure-as-code by file extension, or null. */
+function detectIac(dir: string): string | null {
+  try {
+    const files = fs.readdirSync(dir);
+    if (files.some((f) => f.endsWith('.tf') || f === 'Dockerfile')) return 'iac';
+  } catch { /* An unreadable directory proves nothing. */ }
+  return null;
+}
+
+export function detectProjectLang(cwd?: string): string {
+  const dir = cwd || process.cwd();
+
+  for (const marker of LANG_MARKERS) {
+    if (marker.files.some((f) => fs.existsSync(path.join(dir, f)))) return marker.lang;
+  }
+
+  const candidates = [
+    detectJvm(dir),
+    detectDartFlutter(dir),
+    hasFileWithExtension(dir, ['.psd1', '.psm1', '.ps1']) ? 'powershell' : null,
+    hasFileWithExtension(dir, ['.sh', '.bash']) ? 'shell' : null,
+    detectIac(dir),
+  ];
+  return candidates.find((lang) => lang !== null) ?? 'unknown';
+}
+
+// ── PowerShell Support ──
+
+/**
+ * Detect PowerShell executable (prefer pwsh 7+, fallback to powershell.exe 5.1).
+/**
+ * Check if the project language is PowerShell.
+ */
+export function isPowerShellProject(projectLang: string): boolean {
+  return projectLang === 'powershell';
+}
+
+/**
+ * Run a PowerShell tool/script via the detected PowerShell executable.
+ */
+export function runPowerShellTool(
+  psInfo: PowerShellInfo,
+  command: string,
+  opts?: { cwd?: string; timeoutMs?: number }
+): ToolResult {
+  if (!psInfo.available) {
+    return { stdout: '', stderr: 'PowerShell not available', exitCode: -1, timedOut: false };
+  }
+  return runTool(psInfo.exe, ['-NoProfile', '-NonInteractive', '-Command', command], {
+    cwd: opts?.cwd,
+    timeoutMs: opts?.timeoutMs,
+  });
+}
+
+// ── Temp Directory ──
+
+/**
+ * Cross-platform temp directory (Windows: %TEMP%, Linux/macOS: /tmp).
+ */
+export function getTempDir(): string {
+  return os.tmpdir();
+}
+
+// ── File Filtering Helpers ──
+
+/** Source file extensions that lizard can analyze. */
+const LIZARD_EXTENSIONS = /\.(ts|tsx|js|jsx|py|go|java|swift|cpp|c|hpp|h|m|mm|kt)$/;
+
+/** File extensions that semgrep supports. */
+const SEMGREP_EXTENSIONS = /\.(ts|tsx|js|jsx|py|go|java|c|cpp|cs|rb|php|scala|swift)$/;
+
+/** IaC file patterns. */
+const IAC_PATTERN = /\.(tf|yaml|yml)$|Dockerfile/;
+
+/** PowerShell DSC file patterns. */
+const PS_DSC_PATTERN = /\.configuration\.ps1$|\.mof$/;
+
+export function filterSourceFiles(files: string[]): string[] {
+  return files.filter(f => LIZARD_EXTENSIONS.test(f));
+}
+
+export function filterSemgrepFiles(files: string[]): string[] {
+  return files.filter(f => SEMGREP_EXTENSIONS.test(f));
+}
+
+export function filterIaCFiles(files: string[]): string[] {
+  return files.filter(f => IAC_PATTERN.test(f) || PS_DSC_PATTERN.test(f));
+}

package/gates/gate-3.ts

@@ -0,0 +1,144 @@
+/**
+ * Gate 3: Cyclomatic Complexity Check
+ * Uses lizard for source files; PSScriptAnalyzer for PowerShell projects.
+ * TypeScript rewrite of githooks/adapters/gate-3.sh for cross-platform Node.js CLI.
+ */
+import {
+  GateInput, GateOutput, isToolAvailable, runTool, recordAudit,
+  filterSourceFiles, detectPowerShell, isPowerShellProject, runPowerShellTool,
+  getChangedFiles, detectProjectLang,
+} from './common';
+
+const CCN_THRESHOLD = 5;
+
+export function runGate3(input: GateInput): GateOutput {
+  const startMs = Date.now();
+  const messages: string[] = [];
+
+  messages.push('');
+  messages.push('→ Gate 3: Cyclomatic complexity...');
+
+  // Documentation-only projects: skip
+  if (input.projectLang === 'documentation-only') {
+    messages.push('⏭️  SKIPPED - Complexity (documentation project).');
+    recordAudit('gate-3', 'complexity', 'SKIP', 0, startMs);
+    return { status: 'SKIP', messages, exitCode: 0 };
+  }
+
+  // PowerShell project: use PSScriptAnalyzer as alternative
+  if (isPowerShellProject(input.projectLang)) {
+    return runPowerShellComplexity(input, startMs, messages);
+  }
+
+  // Standard path: lizard
+  const tool = isToolAvailable('lizard', input.cwd);
+  if (!tool.available) {
+    messages.push('⚠️  WARN - lizard not installed, complexity check not performed');
+    messages.push('   Install with: pip install --user lizard');
+    messages.push('   Gate 3: Complexity check (WARN, tool not available)');
+    recordAudit('gate-3', 'complexity', 'WARN', 0, startMs);
+    return { status: 'WARN', messages, exitCode: 0 };
+  }
+
+  const lizardCmd = tool.via === 'npx' ? 'npx' : tool.path;
+  const lizardArgs = tool.via === 'npx' ? ['-y', 'lizard'] : [];
+
+  // Filter to source files lizard can analyze
+  const ccFiles = filterSourceFiles(input.changedFiles);
+  if (ccFiles.length === 0) {
+    messages.push('⏭️  SKIPPED - Complexity (no source files to check).');
+    recordAudit('gate-3', 'complexity', 'SKIP', 0, startMs);
+    return { status: 'SKIP', messages, exitCode: 0 };
+  }
+
+  messages.push('Checking complexity for source files...');
+
+  // Run lizard with CCN threshold
+  const result = runTool(lizardCmd, [...lizardArgs, '-C', String(CCN_THRESHOLD), ...ccFiles], {
+    cwd: input.cwd,
+  });
+
+  const combinedOutput = result.stdout + result.stderr;
+
+  // Parse warning count from summary table: "Warning cnt   8"
+  const warningMatch = combinedOutput.match(/^Warning cnt\s+(\d+)/m);
+  const warnings = warningMatch ? parseInt(warningMatch[1], 10) : 0;
+
+  if (warnings > 0) {
+    messages.push(combinedOutput);
+    messages.push('');
+    messages.push(`❌ BLOCKED - ${warnings} functions with CCN > ${CCN_THRESHOLD} found.`);
+    messages.push(`Refactor high-complexity functions to keep below ${CCN_THRESHOLD} complexity.`);
+    recordAudit('gate-3', 'complexity', 'FAIL', warnings, startMs);
+    return { status: 'FAIL', messages, exitCode: 1 };
+  }
+
+  messages.push(`✅ PASSED - All functions within complexity threshold (${CCN_THRESHOLD}).`);
+  recordAudit('gate-3', 'complexity', '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 = runGate3({ changedFiles, projectLang, cwd });
+  result.messages.forEach(m => console.log(m));
+  process.exit(result.exitCode);
+}
+
+/**
+ * PowerShell project complexity check using PSScriptAnalyzer.
+ * Uses PSAvoid* rules as approximate complexity indicators.
+ */
+function runPowerShellComplexity(
+  input: GateInput,
+  startMs: number,
+  messages: string[]
+): GateOutput {
+  const ps = detectPowerShell();
+  if (!ps.available) {
+    messages.push('ℹ️  No PowerShell Clean Code / SOLID tool available');
+    messages.push('⏭️  SKIPPED - Complexity (no PowerShell tool)');
+    recordAudit('gate-3', 'complexity', 'SKIP', 0, startMs);
+    return { status: 'SKIP', messages, exitCode: 0 };
+  }
+
+  // Filter to .ps1 files
+  const psFiles = input.changedFiles.filter(f => f.endsWith('.ps1') || f.endsWith('.psm1'));
+  if (psFiles.length === 0) {
+    messages.push('⏭️  SKIPPED - Complexity (no PowerShell files to check).');
+    recordAudit('gate-3', 'complexity', 'SKIP', 0, startMs);
+    return { status: 'SKIP', messages, exitCode: 0 };
+  }
+
+  messages.push('Checking PowerShell code quality via PSScriptAnalyzer...');
+
+  const fileList = psFiles.map(f => `'${f}'`).join(',');
+  const command = `Invoke-ScriptAnalyzer -Path ${fileList} -IncludeRule PSAvoidUsingInvokeExpression,PSAvoidGlobalAliases -ErrorAction SilentlyContinue | ConvertTo-Json`;
+  const result = runPowerShellTool(ps, command, { cwd: input.cwd });
+
+  if (result.exitCode !== 0) {
+    messages.push('⚠️  PSScriptAnalyzer check failed, skipping');
+    recordAudit('gate-3', 'complexity', 'WARN', 0, startMs);
+    return { status: 'WARN', messages, exitCode: 0 };
+  }
+
+  try {
+    const findings = result.stdout.trim() ? JSON.parse(result.stdout.trim()) : [];
+    const count = Array.isArray(findings) ? findings.length : 0;
+    if (count > 0) {
+      messages.push(`⚠️  ${count} PSScriptAnalyzer findings (warnings only for PowerShell projects)`);
+      recordAudit('gate-3', 'complexity', 'WARN', count, startMs);
+      return { status: 'WARN', messages, exitCode: 0 };
+    }
+  } catch {
+    // JSON parse failure — not a gate failure
+  }
+
+  messages.push('✅ PASSED - PowerShell code quality check passed.');
+  recordAudit('gate-3', 'complexity', 'PASS', 0, startMs);
+  return { status: 'PASS', messages, exitCode: 0 };
+}