@comity-dev/validate 0.2.0 → 0.2.2

package/README.md

@@ -50,6 +50,11 @@ comity-validate --only=schema        # one engine only
 comity-validate --only=eslint --verbose
 ```
 
+`--only <category>` runs a single engine. Policies owned by another engine are
+not evaluated: `--only semgrep` does not check ESLint-owned policy, including
+the required `@internal` marker rule (`@comity-dev/require-internal-marker`).
+Use the default run (no `--only`) for full policy coverage.
+
 Exit codes:
 
 - `0` — validation passed
@@ -61,10 +66,11 @@ Exit codes:
 
 The Semgrep engine shells out to a local Semgrep installation:
 
-| Variable         | Purpose                                                                                          |
-| ---------------- | ------------------------------------------------------------------------------------------------ |
-| `SEMGREP_BIN`    | Path to the `semgrep` executable. Used as-is when it exists; otherwise resolved from PATH.       |
-| `SEMGREP_PYTHON` | Path to the Python interpreter that ships the `semgrep` module. The scan is executed with it.    |
+| Variable                    | Purpose                                                                                          |
+| --------------------------- | ------------------------------------------------------------------------------------------------ |
+| `SEMGREP_BIN`               | Path to the `semgrep` executable. Used as-is when it exists; otherwise resolved from PATH.       |
+| `SEMGREP_PYTHON`            | Path to the Python interpreter that ships the `semgrep` module. The scan is executed with it.    |
+| `COMITY_SEMGREP_TIMEOUT_MS` | Overall scan timeout in milliseconds. Defaults to `300000` (five minutes). Must be an integer between `1` and `2147483647`; invalid or oversized values are reported as `CONFIGURATION-ERROR`. |
 
 Rules:
 
@@ -77,6 +83,17 @@ Rules:
   then `python3` on PATH).
 - The scan `PATH` is prefixed with the directories of the resolved
   `SEMGREP_BIN` and interpreter so Semgrep finds its sibling `pysemgrep`.
+- Every scan has an overall liveness bound (`COMITY_SEMGREP_TIMEOUT_MS`). A
+  timeout is reported as `EXECUTION-ERROR`, never as PASS. On POSIX the
+  scanner's process group is terminated so Semgrep's Python and `semgrep-core`
+  descendants do not remain running; on Windows only the immediate child can
+  be signalled, so descendant termination is best-effort.
+- `--verbose` emits a stderr heartbeat every ten seconds while a scan is
+  running; the final summary remains on stdout.
+- A file Semgrep could not fully parse (`PartialParsing`) is reported as
+  `EXECUTION-ERROR` with a `SEM-PARTIAL-PARSE` finding naming the file, never
+  as PASS: a partially parsed file may have been skipped by AST-based rules,
+  so the scan is incomplete rather than clean.
 
 ```bash
 SEMGREP_BIN=~/.local/bin/semgrep SEMGREP_PYTHON=/opt/homebrew/bin/python3 \

package/dist/bin/comity-validate.js

@@ -26,7 +26,7 @@
 import { resolve } from "node:path";
 import { ExitCode } from "../exit-codes.js";
 import { formatSummary, formatViolations } from "../format.js";
-import { runValidation } from "../run.js";
+import { exitCodeForResult, runValidation } from "../run.js";
 function parseArgs(argv) {
     const args = {
         root: process.cwd(),
@@ -88,7 +88,10 @@ async function main() {
             console.log("");
             console.log(formatViolations(result.violations));
         }
-        process.exit(result.passed ? ExitCode.PASS : ExitCode.FAIL);
+        // A required tool that could not run must never surface as PASS:
+        // report it with the documented TOOL_MISSING exit code instead of
+        // fabricating a passing result.
+        process.exit(exitCodeForResult(result));
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);

package/dist/engines/semgrep.d.ts

@@ -1,18 +1,72 @@
 import type { Repository } from "../discover.js";
 import type { EngineResult } from "./types.js";
+/** Default overall Semgrep scan timeout: five minutes. */
+export declare const DEFAULT_SEMGREP_TIMEOUT_MS = 300000;
+/** Maximum single Node.js timer value, in milliseconds (2^31 - 1). */
+export declare const MAX_SEMGREP_TIMEOUT_MS = 2147483647;
+export interface SemgrepOptions {
+    /** Overall scan timeout in milliseconds; overrides COMITY_SEMGREP_TIMEOUT_MS. */
+    readonly timeoutMs?: number;
+    /** Emit a heartbeat on stderr while the scan is running. */
+    readonly verbose?: boolean;
+}
+export interface SemgrepTimeoutResolution {
+    /** Validated timeout in milliseconds. */
+    readonly timeoutMs: number;
+    /** Configuration error, if the configured timeout is invalid. */
+    readonly error?: string;
+}
+/**
+ * Resolve the overall Semgrep timeout from an explicit override or the
+ * `COMITY_SEMGREP_TIMEOUT_MS` environment variable.
+ *
+ * @param env - Environment to read
+ * @param override - Test/embedding override; when supplied, it wins
+ *
+ * @returns A supported timeout in milliseconds, or a configuration error
+ *
+ * @remarks
+ * The timeout is deliberately bounded. A value of zero would disable the
+ * liveness guarantee, and values above Node's 32-bit timer limit would be
+ * clamped to 1 ms, so both are rejected. Invalid values are reported as
+ * configuration errors and never fall back silently.
+ */
+export declare function resolveSemgrepTimeout(env?: NodeJS.ProcessEnv, override?: number): SemgrepTimeoutResolution;
+/**
+ * Derive the Python interpreter from a semgrep executable's shebang
+ * line. Shim installs (Homebrew, pipx, venv) point `#!` at the
+ * interpreter that ships the `semgrep` module; resolving it keeps the
+ * scan on a working interpreter instead of an unrelated system python
+ * that merely exists on PATH.
+ *
+ * @param binPath - Path to the semgrep executable.
+ * @param env - Environment to read for `/usr/bin/env` resolution.
+ *
+ * @returns The interpreter path when the file starts with a usable
+ * `#!` line naming an existing executable, otherwise `null`.
+ */
+export declare function resolveInterpreterFromBin(binPath: string, env?: NodeJS.ProcessEnv): string | null;
 /**
  * Discover the Python interpreter that ships the `semgrep` module.
  *
  * Selection order:
  * 1. `SEMGREP_PYTHON` when set to an existing path — explicit operator
  *    configuration always wins and is never silently overridden.
- * 2. Well-known absolute paths, then `python3` on PATH (historic default).
+ * 2. The interpreter named by the semgrep executable's shebang line
+ *    (shim installs point at the interpreter that ships the module).
+ * 3. Well-known absolute paths, then `python3` on PATH (historic default).
+ *
+ * Every auto-discovered candidate (steps 2-3) must both exist and
+ * successfully `import semgrep`; the first candidate that does wins.
+ * An explicit `SEMGREP_PYTHON` is honored as-is for backwards
+ * compatibility.
  *
  * @param env - Environment to read. Defaults to the process environment.
+ * @param binPath - Resolved semgrep executable used for step 2.
  *
  * @returns The selected interpreter path, or `null` when none is available.
  * A set-but-missing `SEMGREP_PYTHON` also yields `null` so the caller can
  * report it as invalid configuration rather than falling back silently.
  */
-export declare function resolvePythonForSemgrep(env?: NodeJS.ProcessEnv): string | null;
-export declare function runSemgrep(repo: Repository): Promise<EngineResult>;
+export declare function resolvePythonForSemgrep(env?: NodeJS.ProcessEnv, binPath?: string): string | null;
+export declare function runSemgrep(repo: Repository, options?: SemgrepOptions): Promise<EngineResult>;

package/dist/engines/semgrep.js

@@ -1,41 +1,336 @@
 import { buildSemgrepConfig } from "@comity-dev/semgrep-rules";
-import { spawnSync } from "node:child_process";
-import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { closeSync, existsSync, mkdtempSync, openSync, readSync, rmSync, writeFileSync, } from "node:fs";
 import { relative, resolve } from "node:path";
+/** Default overall Semgrep scan timeout: five minutes. */
+export const DEFAULT_SEMGREP_TIMEOUT_MS = 300_000;
+/** Maximum single Node.js timer value, in milliseconds (2^31 - 1). */
+export const MAX_SEMGREP_TIMEOUT_MS = 2_147_483_647;
+/** Time allowed for a timed-out process group to exit before SIGKILL. */
+const SEMGREP_TERMINATION_GRACE_MS = 2_000;
+/** Frequency of optional verbose heartbeats. */
+const SEMGREP_HEARTBEAT_MS = 10_000;
+/** Preserve the previous spawnSync maxBuffer ceiling for the async scanner. */
+const MAX_SEMGREP_OUTPUT_BYTES = 16 * 1024 * 1024;
+/**
+ * Resolve the overall Semgrep timeout from an explicit override or the
+ * `COMITY_SEMGREP_TIMEOUT_MS` environment variable.
+ *
+ * @param env - Environment to read
+ * @param override - Test/embedding override; when supplied, it wins
+ *
+ * @returns A supported timeout in milliseconds, or a configuration error
+ *
+ * @remarks
+ * The timeout is deliberately bounded. A value of zero would disable the
+ * liveness guarantee, and values above Node's 32-bit timer limit would be
+ * clamped to 1 ms, so both are rejected. Invalid values are reported as
+ * configuration errors and never fall back silently.
+ */
+export function resolveSemgrepTimeout(env = process.env, override) {
+    if (override !== undefined) {
+        if (!Number.isSafeInteger(override) ||
+            override <= 0 ||
+            override > MAX_SEMGREP_TIMEOUT_MS) {
+            return {
+                timeoutMs: DEFAULT_SEMGREP_TIMEOUT_MS,
+                error: `timeoutMs must be an integer between 1 and ${MAX_SEMGREP_TIMEOUT_MS}; received ${String(override)}`,
+            };
+        }
+        return { timeoutMs: override };
+    }
+    const raw = env["COMITY_SEMGREP_TIMEOUT_MS"];
+    if (raw === undefined) {
+        return { timeoutMs: DEFAULT_SEMGREP_TIMEOUT_MS };
+    }
+    const trimmed = raw.trim();
+    if (!/^\d+$/.test(trimmed)) {
+        return {
+            timeoutMs: DEFAULT_SEMGREP_TIMEOUT_MS,
+            error: `COMITY_SEMGREP_TIMEOUT_MS must be an integer between 1 and ${MAX_SEMGREP_TIMEOUT_MS}; received "${raw}"`,
+        };
+    }
+    const parsed = Number(trimmed);
+    if (!Number.isSafeInteger(parsed) ||
+        parsed <= 0 ||
+        parsed > MAX_SEMGREP_TIMEOUT_MS) {
+        return {
+            timeoutMs: DEFAULT_SEMGREP_TIMEOUT_MS,
+            error: `COMITY_SEMGREP_TIMEOUT_MS must be an integer between 1 and ${MAX_SEMGREP_TIMEOUT_MS}; received "${raw}"`,
+        };
+    }
+    return { timeoutMs: parsed };
+}
+/**
+ * Terminate a Semgrep child process and, on POSIX, its process group.
+ *
+ * @param child - Child process started by the scanner
+ * @param signal - Signal to send
+ *
+ * @remarks
+ * The scanner is started with `detached: true` on POSIX so its Python and
+ * semgrep-core descendants share a process group. Killing the group prevents
+ * orphaned semgrep-core processes after a timeout. Windows has no equivalent
+ * process-group primitive in Node; there only the immediate child is signalled.
+ */
+function terminateSemgrepProcess(child, signal) {
+    if (child.pid === undefined)
+        return;
+    if (process.platform === "win32") {
+        try {
+            child.kill(signal);
+        }
+        catch {
+            // The child may already have exited.
+        }
+        return;
+    }
+    try {
+        process.kill(-child.pid, signal);
+    }
+    catch {
+        try {
+            child.kill(signal);
+        }
+        catch {
+            // The process group may already have exited.
+        }
+    }
+}
+/**
+ * Run the Semgrep subprocess with an overall timeout and bounded output.
+ *
+ * @param command - Interpreter to execute
+ * @param args - Interpreter arguments
+ * @param options - Working directory, environment, timeout, and verbosity
+ *
+ * @returns Captured output and termination details
+ *
+ * @remarks
+ * A timeout sends SIGTERM to the process group, then SIGKILL after a short
+ * grace period. The promise always settles; a close event normally does so
+ * sooner, while the grace timer is a hard ceiling. On Windows only the direct
+ * child can be signalled, so descendant termination is best-effort there.
+ */
+function runSemgrepProcess(command, args, options) {
+    return new Promise((resolvePromise) => {
+        let child;
+        try {
+            child = spawn(command, args, {
+                cwd: options.cwd,
+                env: options.env,
+                detached: process.platform !== "win32",
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        }
+        catch (error) {
+            resolvePromise({
+                stdout: "",
+                stderr: "",
+                status: null,
+                signal: null,
+                timedOut: false,
+                spawnError: error instanceof Error ? error : new Error(String(error)),
+                outputLimitExceeded: false,
+            });
+            return;
+        }
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let spawnError = null;
+        let outputLimitExceeded = false;
+        let settled = false;
+        let timeoutTimer;
+        let forceTimer;
+        let heartbeatTimer;
+        const started = Date.now();
+        const clearTimers = () => {
+            if (timeoutTimer !== undefined)
+                clearTimeout(timeoutTimer);
+            if (forceTimer !== undefined)
+                clearTimeout(forceTimer);
+            if (heartbeatTimer !== undefined)
+                clearInterval(heartbeatTimer);
+        };
+        const finish = (status, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimers();
+            resolvePromise({
+                stdout,
+                stderr,
+                status,
+                signal,
+                timedOut,
+                spawnError,
+                outputLimitExceeded,
+            });
+        };
+        const terminate = () => {
+            terminateSemgrepProcess(child, "SIGTERM");
+            // A process that ignores SIGTERM must not hold validation open. The
+            // hard timer also guarantees the promise settles if no close event
+            // arrives; killing the process group is the primary termination path.
+            forceTimer = setTimeout(() => {
+                terminateSemgrepProcess(child, "SIGKILL");
+                finish(null, "SIGKILL");
+            }, SEMGREP_TERMINATION_GRACE_MS);
+        };
+        const appendOutput = (target, chunk) => {
+            const text = chunk.toString();
+            if (target === "stdout")
+                stdout += text;
+            else
+                stderr += text;
+            if (!outputLimitExceeded &&
+                Buffer.byteLength(stdout, "utf8") + Buffer.byteLength(stderr, "utf8") >
+                    MAX_SEMGREP_OUTPUT_BYTES) {
+                outputLimitExceeded = true;
+                terminate();
+            }
+        };
+        child.stdout?.on("data", (chunk) => appendOutput("stdout", chunk));
+        child.stderr?.on("data", (chunk) => appendOutput("stderr", chunk));
+        child.on("error", (error) => {
+            spawnError = error;
+            finish(null, null);
+        });
+        child.on("close", (status, signal) => {
+            finish(status, signal);
+        });
+        timeoutTimer = setTimeout(() => {
+            timedOut = true;
+            terminate();
+        }, options.timeoutMs);
+        if (options.verbose) {
+            heartbeatTimer = setInterval(() => {
+                const elapsedSeconds = Math.round((Date.now() - started) / 1000);
+                try {
+                    process.stderr.write(`comity-validate: semgrep scan still running after ${elapsedSeconds}s (timeout ${Math.round(options.timeoutMs / 1000)}s)\n`);
+                }
+                catch {
+                    // Diagnostics must never change the validation result.
+                }
+            }, SEMGREP_HEARTBEAT_MS);
+        }
+    });
+}
+/**
+ * Derive the Python interpreter from a semgrep executable's shebang
+ * line. Shim installs (Homebrew, pipx, venv) point `#!` at the
+ * interpreter that ships the `semgrep` module; resolving it keeps the
+ * scan on a working interpreter instead of an unrelated system python
+ * that merely exists on PATH.
+ *
+ * @param binPath - Path to the semgrep executable.
+ * @param env - Environment to read for `/usr/bin/env` resolution.
+ *
+ * @returns The interpreter path when the file starts with a usable
+ * `#!` line naming an existing executable, otherwise `null`.
+ */
+export function resolveInterpreterFromBin(binPath, env = process.env) {
+    let head;
+    try {
+        const fd = openSync(binPath, "r");
+        try {
+            const buf = Buffer.alloc(2048);
+            const read = readSync(fd, buf, 0, buf.length, 0);
+            head = buf.subarray(0, read).toString("utf8").split("\n")[0] ?? "";
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return null;
+    }
+    if (!head.startsWith("#!"))
+        return null;
+    const parts = head.slice(2).trim().split(/\s+/).filter(Boolean);
+    const [first, second] = parts;
+    if (!first)
+        return null;
+    // `#!/usr/bin/env python3 ...` form: resolve the named interpreter
+    // against PATH the same way a shell would.
+    if (first === "env" || first.endsWith("/env")) {
+        if (!second)
+            return null;
+        const probe = spawnSync("which", [second], {
+            encoding: "utf8",
+            env: { ...env, PATH: env["PATH"] ?? "" },
+        });
+        if (probe.status === 0 && probe.stdout?.trim()) {
+            return probe.stdout.trim();
+        }
+        return null;
+    }
+    return existsSync(first) ? first : null;
+}
+/**
+ * Probe whether an interpreter ships the `semgrep` module, so a
+ * resolved python is never assumed to work by mere existence.
+ */
+function interpreterShipsSemgrep(interpreter) {
+    try {
+        const probe = spawnSync(interpreter, ["-c", "import semgrep"], {
+            encoding: "utf8",
+            timeout: 30000,
+        });
+        return probe.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Discover the Python interpreter that ships the `semgrep` module.
  *
  * Selection order:
  * 1. `SEMGREP_PYTHON` when set to an existing path — explicit operator
  *    configuration always wins and is never silently overridden.
- * 2. Well-known absolute paths, then `python3` on PATH (historic default).
+ * 2. The interpreter named by the semgrep executable's shebang line
+ *    (shim installs point at the interpreter that ships the module).
+ * 3. Well-known absolute paths, then `python3` on PATH (historic default).
+ *
+ * Every auto-discovered candidate (steps 2-3) must both exist and
+ * successfully `import semgrep`; the first candidate that does wins.
+ * An explicit `SEMGREP_PYTHON` is honored as-is for backwards
+ * compatibility.
  *
  * @param env - Environment to read. Defaults to the process environment.
+ * @param binPath - Resolved semgrep executable used for step 2.
  *
  * @returns The selected interpreter path, or `null` when none is available.
  * A set-but-missing `SEMGREP_PYTHON` also yields `null` so the caller can
  * report it as invalid configuration rather than falling back silently.
  */
-export function resolvePythonForSemgrep(env = process.env) {
+export function resolvePythonForSemgrep(env = process.env, binPath) {
     const explicit = env["SEMGREP_PYTHON"];
     if (explicit) {
         return existsSync(explicit) ? explicit : null;
     }
-    const candidates = [
-        "/usr/bin/python3",
-        "/usr/local/bin/python3",
-        "/opt/homebrew/bin/python3",
-    ];
+    const candidates = [];
+    if (binPath) {
+        const fromBin = resolveInterpreterFromBin(binPath, env);
+        if (fromBin)
+            candidates.push(fromBin);
+    }
+    candidates.push("/usr/bin/python3", "/usr/local/bin/python3", "/opt/homebrew/bin/python3");
     for (const c of candidates) {
-        if (existsSync(c))
+        if (existsSync(c) && interpreterShipsSemgrep(c))
             return c;
     }
     const probe = spawnSync("which", ["python3"], {
         encoding: "utf8",
         env: { ...env, PATH: env["PATH"] ?? "" },
     });
-    if (probe.status === 0 && probe.stdout?.trim())
-        return probe.stdout.trim();
+    if (probe.status === 0 && probe.stdout?.trim()) {
+        const viaPath = probe.stdout.trim();
+        if (interpreterShipsSemgrep(viaPath))
+            return viaPath;
+    }
     return null;
 }
 function findSemgrepBin(fallbackDirs) {
@@ -106,8 +401,21 @@ function buildSemgrepArgs(configPath, target, excludedDirs) {
     }
     return args;
 }
-export async function runSemgrep(repo) {
+export async function runSemgrep(repo, options = {}) {
     const start = Date.now();
+    const timeout = resolveSemgrepTimeout(process.env, options.timeoutMs);
+    if (timeout.error !== undefined) {
+        return {
+            executed: false,
+            exitCode: null,
+            passed: false,
+            findings: [],
+            duration: Date.now() - start,
+            status: "CONFIGURATION-ERROR",
+            tool: "semgrep",
+            reason: `${timeout.error}; the Semgrep scan was not started`,
+        };
+    }
     // Build the combined Semgrep config. Semgrep's CLI accepts a single
     // --config path, so we concatenate all canonical rule files into one
     // synthesized config.
@@ -140,10 +448,12 @@ export async function runSemgrep(repo) {
             reason: "semgrep binary not found on PATH; install semgrep or set SEMGREP_BIN",
         };
     }
-    // Locate the Python interpreter that ships the semgrep module.
-    // An explicit SEMGREP_PYTHON is honored as-is; a set-but-missing value
-    // is invalid configuration, never a reason to silently fall back.
-    const pythonBin = resolvePythonForSemgrep();
+    // Locate the Python interpreter that ships the semgrep module,
+    // preferring the interpreter named by the semgrep executable's own
+    // shebang line. An explicit SEMGREP_PYTHON is honored as-is; a
+    // set-but-missing value is invalid configuration, never a reason to
+    // silently fall back.
+    const pythonBin = resolvePythonForSemgrep(process.env, semgrepBin ?? undefined);
     if (!pythonBin) {
         cleanup();
         const explicitPython = process.env["SEMGREP_PYTHON"];
@@ -157,7 +467,7 @@ export async function runSemgrep(repo) {
             tool: "semgrep",
             reason: explicitPython
                 ? `SEMGREP_PYTHON is set to "${explicitPython}" but that path does not exist; set SEMGREP_PYTHON to a Python interpreter that ships the semgrep module`
-                : "Python interpreter not found; semgrep requires Python on PATH",
+                : `No Python interpreter shipping the semgrep module was found (semgrep binary: "${semgrepBin}"); install semgrep so its executable resolves to a working interpreter, or set SEMGREP_PYTHON to a Python interpreter that ships the semgrep module`,
         };
     }
     // Augment PATH so the inner Python process can find semgrep's
@@ -199,72 +509,334 @@ export async function runSemgrep(repo) {
         };
     }
     const args = buildSemgrepArgs(configPath, target, excludedDirs);
-    const proc = spawnSync(pythonBin, args, {
+    const outcome = await runSemgrepProcess(pythonBin, args, {
         cwd: repo.root,
         env: { ...process.env, PATH: envPath },
-        maxBuffer: 16 * 1024 * 1024,
-        encoding: "utf8",
+        timeoutMs: timeout.timeoutMs,
+        verbose: options.verbose === true,
     });
     cleanup();
-    const stdout = proc.stdout ?? "";
-    const stderr = proc.stderr ?? "";
-    const findings = parseSemgrepOutput(stdout, stderr);
+    const { stdout, stderr } = outcome;
+    const parsed = parseSemgrepOutput(stdout, stderr);
+    const findings = [...parsed.findings];
+    const duration = Date.now() - start;
+    if (outcome.spawnError !== null) {
+        const message = `semgrep could not be started: ${outcome.spawnError.message}; this is a tool execution failure, not a rule match`;
+        findings.push({
+            tool: "semgrep",
+            rule: "SEM-SPAWN",
+            message,
+            severity: "error",
+        });
+        return {
+            executed: true,
+            exitCode: null,
+            passed: false,
+            findings,
+            duration,
+            status: "EXECUTION-ERROR",
+            tool: "semgrep",
+            reason: message,
+        };
+    }
+    if (outcome.timedOut) {
+        const message = `semgrep exceeded the ${timeout.timeoutMs} ms timeout after ${duration} ms during structural-pattern validation; the process group was terminated. This is a tool execution failure, not a rule match.`;
+        findings.push({
+            tool: "semgrep",
+            rule: "SEM-TIMEOUT",
+            message,
+            severity: "error",
+        });
+        return {
+            executed: true,
+            exitCode: null,
+            passed: false,
+            findings,
+            duration,
+            status: "EXECUTION-ERROR",
+            tool: "semgrep",
+            reason: message,
+        };
+    }
+    if (outcome.outputLimitExceeded) {
+        const message = `semgrep output exceeded ${MAX_SEMGREP_OUTPUT_BYTES} bytes; the process group was terminated. This is a tool execution failure, not a rule match.`;
+        findings.push({
+            tool: "semgrep",
+            rule: "SEM-OUTPUT",
+            message,
+            severity: "error",
+        });
+        return {
+            executed: true,
+            exitCode: null,
+            passed: false,
+            findings,
+            duration,
+            status: "EXECUTION-ERROR",
+            tool: "semgrep",
+            reason: message,
+        };
+    }
+    if (outcome.signal !== null) {
+        const message = `semgrep was terminated by ${outcome.signal}; this is a tool execution failure, not a rule match.`;
+        findings.push({
+            tool: "semgrep",
+            rule: "SEM-SIGNAL",
+            message,
+            severity: "error",
+        });
+        return {
+            executed: true,
+            exitCode: null,
+            passed: false,
+            findings,
+            duration,
+            status: "EXECUTION-ERROR",
+            tool: "semgrep",
+            reason: message,
+        };
+    }
+    // Incomplete analysis takes precedence over the policy verdict. Semgrep
+    // reports a partially parsed file as a `level: "warn"` error and still
+    // exits 0, so the exit code alone would report a clean pass even though
+    // AST-based rules may never have analysed that file. This check runs before
+    // the crash/exit-code checks so the affected file is always surfaced.
+    if (parsed.partialParsing.length > 0) {
+        const first = parsed.partialParsing[0];
+        for (const diagnostic of parsed.partialParsing) {
+            findings.push({
+                tool: "semgrep",
+                rule: "SEM-PARTIAL-PARSE",
+                message: `semgrep could not fully parse ${diagnostic.path}: ${diagnostic.message}. AST-based rules may not have analysed this file, so the result is incomplete.`,
+                file: diagnostic.path,
+                severity: "error",
+            });
+        }
+        const exitNote = outcome.status !== null && outcome.status !== 0
+            ? `; semgrep exited with code ${outcome.status}`
+            : "";
+        const message = `semgrep could not fully parse ${parsed.partialParsing.length} file(s) (first: ${first?.path ?? "<unknown file>"}); the scan is incomplete, so this category cannot report PASS${exitNote}. This is an incomplete-analysis failure, not a rule match.`;
+        return {
+            executed: true,
+            exitCode: outcome.status,
+            passed: false,
+            findings,
+            duration,
+            status: "EXECUTION-ERROR",
+            tool: "semgrep",
+            reason: message,
+        };
+    }
     // If semgrep exited non-zero but produced no parseable findings, this
     // is an EXECUTION-ERROR (configuration, rule-parse, internal crash),
     // not a policy violation.
-    if (proc.status !== null && proc.status !== 0 && findings.length === 0) {
+    if (outcome.status !== null && outcome.status !== 0 && findings.length === 0) {
         const stderrHead = stderr.split("\n")[0] ?? "";
         const stdoutHead = stdout.slice(0, 500);
         findings.push({
             tool: "semgrep",
             rule: "SEM-CRASH",
-            message: `semgrep exited with code ${proc.status}; stderr: ${stderrHead}; stdout (first 500): ${stdoutHead}`,
+            message: `semgrep exited with code ${outcome.status}; stderr: ${stderrHead}; stdout (first 500): ${stdoutHead}`,
             severity: "error",
         });
         return {
             executed: true,
-            exitCode: proc.status,
+            exitCode: outcome.status,
             passed: false,
             findings,
-            duration: Date.now() - start,
+            duration,
+            status: "EXECUTION-ERROR",
+            tool: "semgrep",
+            reason: `semgrep exited with code ${outcome.status} before producing findings (stderr: ${stderrHead}); this is a tool execution failure, not a rule match — see the SEM-CRASH finding`,
+        };
+    }
+    if (outcome.status === null) {
+        const message = "semgrep terminated without an exit code; this is a tool execution failure, not a rule match.";
+        findings.push({
+            tool: "semgrep",
+            rule: "SEM-CRASH",
+            message,
+            severity: "error",
+        });
+        return {
+            executed: true,
+            exitCode: null,
+            passed: false,
+            findings,
+            duration,
+            status: "EXECUTION-ERROR",
+            tool: "semgrep",
+            reason: message,
+        };
+    }
+    if (parsed.malformed) {
+        const stdoutHead = stdout.slice(0, 500);
+        const message = `semgrep produced malformed JSON output (first 500 chars: ${stdoutHead}); this is a tool execution failure, not a rule match.`;
+        findings.push({
+            tool: "semgrep",
+            rule: "SEM-MALFORMED",
+            message,
+            severity: "error",
+        });
+        return {
+            executed: true,
+            exitCode: outcome.status,
+            passed: false,
+            findings,
+            duration,
             status: "EXECUTION-ERROR",
             tool: "semgrep",
+            reason: message,
         };
     }
     return {
         executed: true,
-        exitCode: proc.status,
-        passed: proc.status === 0 && findings.length === 0,
+        exitCode: outcome.status,
+        passed: outcome.status === 0 && findings.length === 0,
         findings,
-        duration: Date.now() - start,
-        status: proc.status === 0 ? "PASS" : "FAIL",
+        duration,
+        status: outcome.status === 0 && findings.length === 0 ? "PASS" : "FAIL",
         tool: "semgrep",
     };
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Validate the result fields consumed by this validator. */
+function isSemgrepResult(value) {
+    if (!isRecord(value))
+        return false;
+    const start = value["start"];
+    return (typeof value["check_id"] === "string" &&
+        typeof value["path"] === "string" &&
+        isRecord(start) &&
+        typeof start["line"] === "number" &&
+        typeof start["col"] === "number");
+}
+/** Validate the error fields consumed by this validator. */
+function isSemgrepError(value) {
+    if (!isRecord(value))
+        return false;
+    if (typeof value["level"] !== "string")
+        return false;
+    if ("rule_id" in value && typeof value["rule_id"] !== "string")
+        return false;
+    if ("message" in value && typeof value["message"] !== "string")
+        return false;
+    // Semgrep encodes `type` as a tag name or a `[tagName, ...]` tuple; this
+    // validator now reads it to detect partial parsing, so anything else is
+    // treated as malformed rather than silently ignored.
+    if ("type" in value && !isSemgrepErrorType(value["type"]))
+        return false;
+    return true;
+}
+/** Whether a Semgrep error `type` field has a supported shape. */
+function isSemgrepErrorType(value) {
+    if (typeof value === "string")
+        return true;
+    return Array.isArray(value) && typeof value[0] === "string";
+}
+/** The tag name of a Semgrep error `type` field, when it is well formed. */
+function semgrepErrorTypeName(value) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value) && typeof value[0] === "string")
+        return value[0];
+    return null;
+}
+/**
+ * Whether an error entry reports a file Semgrep could not fully parse.
+ *
+ * @remarks
+ * Semgrep 1.180.0 reports partial parsing at `level: "warn"` with the
+ * `PartialParsing` tag name while still exiting `0`, so the exit code alone
+ * cannot detect it. The tag name is the primary signal; a warning that names
+ * a syntax error is treated the same way so Semgrep versions that omit the
+ * tag name cannot silently skip a file. Warnings that do not indicate
+ * incomplete analysis keep their existing (non-fatal) treatment.
+ */
+function isIncompleteAnalysisError(entry) {
+    const type = semgrepErrorTypeName(entry["type"]);
+    if (type !== null && /partialparsing/i.test(type))
+        return true;
+    const message = entry["message"];
+    return typeof message === "string" && /\bsyntax error\b/i.test(message);
+}
+/** The file an error entry refers to, when Semgrep reports one. */
+function errorEntryPath(entry) {
+    const direct = entry["path"];
+    if (typeof direct === "string" && direct.length > 0)
+        return direct;
+    const spans = entry["spans"];
+    if (Array.isArray(spans)) {
+        for (const span of spans) {
+            if (isRecord(span) && typeof span["file"] === "string") {
+                return span["file"];
+            }
+        }
+    }
+    const locations = Array.isArray(entry["type"]) ? entry["type"][1] : undefined;
+    if (Array.isArray(locations)) {
+        for (const location of locations) {
+            if (isRecord(location) && typeof location["path"] === "string") {
+                return location["path"];
+            }
+        }
+    }
+    return "<unknown file>";
+}
 function parseSemgrepOutput(stdout, stderr) {
-    const out = stdout ?? stderr ?? "";
+    const out = stdout?.trim() ? stdout : (stderr ?? "");
     if (!out.trim())
-        return [];
-    let parsed = null;
+        return { findings: [], malformed: true, partialParsing: [] };
+    let parsedValue;
     try {
-        parsed = JSON.parse(out);
+        parsedValue = JSON.parse(out);
     }
     catch {
-        return [];
+        return { findings: [], malformed: true, partialParsing: [] };
+    }
+    if (!isRecord(parsedValue)) {
+        return { findings: [], malformed: true, partialParsing: [] };
+    }
+    const rawResults = parsedValue["results"];
+    const rawErrors = parsedValue["errors"];
+    if (!Array.isArray(rawResults)) {
+        return { findings: [], malformed: true, partialParsing: [] };
+    }
+    if (rawErrors !== undefined && !Array.isArray(rawErrors)) {
+        return { findings: [], malformed: true, partialParsing: [] };
+    }
+    if (!rawResults.every(isSemgrepResult)) {
+        return { findings: [], malformed: true, partialParsing: [] };
+    }
+    if (rawErrors !== undefined && !rawErrors.every(isSemgrepError)) {
+        return { findings: [], malformed: true, partialParsing: [] };
     }
     const findings = [];
-    for (const e of parsed?.errors ?? []) {
-        if (e.level === "error") {
+    const partialParsing = [];
+    for (const e of (rawErrors ?? [])) {
+        if (e["level"] === "error") {
             findings.push({
                 tool: "semgrep",
-                rule: `SEM-PARSE-${e.rule_id ?? "UNKNOWN"}`,
-                message: e.message ?? "semgrep rule parse error",
+                rule: `SEM-PARSE-${typeof e["rule_id"] === "string" ? e["rule_id"] : "UNKNOWN"}`,
+                message: typeof e["message"] === "string"
+                    ? e["message"]
+                    : "semgrep rule parse error",
                 severity: "error",
             });
+            continue;
+        }
+        if (isIncompleteAnalysisError(e)) {
+            partialParsing.push({
+                path: errorEntryPath(e),
+                message: typeof e["message"] === "string"
+                    ? e["message"]
+                    : "semgrep reported a file it could not fully parse",
+            });
         }
     }
-    const results = parsed?.results ?? [];
-    for (const r of results) {
+    for (const r of rawResults) {
         const start = r["start"];
         const extra = r["extra"];
         findings.push({
@@ -277,5 +849,5 @@ function parseSemgrepOutput(stdout, stderr) {
             severity: extra?.severity === "ERROR" ? "error" : "warning",
         });
     }
-    return findings;
+    return { findings, malformed: false, partialParsing };
 }

package/dist/format.js

@@ -27,6 +27,19 @@ function statusBadge(cat) {
             return cat.executed ? (cat.passed ? "PASS" : "FAIL") : "NOT-RUN";
     }
 }
+/**
+ * The overall result line. A run that found no violations but could not
+ * execute a required stage is neither a pass nor a failure: it is
+ * incomplete. In particular the summary must never claim PASS while a
+ * category reports TOOL-UNAVAILABLE (the process exit code already
+ * distinguishes that case as TOOL_MISSING).
+ */
+function overallResult(result) {
+    if (!result.passed)
+        return "FAIL";
+    const toolUnavailable = Object.values(result.categories).some((cat) => cat.status === "TOOL-UNAVAILABLE");
+    return toolUnavailable ? "INCOMPLETE" : "PASS";
+}
 /**
  * Format a unified summary for the terminal.
  */
@@ -56,7 +69,7 @@ export function formatSummary(result) {
         }
     }
     lines.push("");
-    lines.push(`Result: ${result.passed ? "PASS" : "FAIL"}`);
+    lines.push(`Result: ${overallResult(result)}`);
     return lines.join("\n");
 }
 /**

package/dist/index.d.ts

@@ -6,4 +6,4 @@ export type { CategoryResult, RunOptions, RunResult } from "./run.js";
 export { discoverRepository } from "./discover.js";
 export { ExitCode } from "./exit-codes.js";
 export { formatSummary, formatViolations } from "./format.js";
-export { runValidation } from "./run.js";
+export { exitCodeForResult, runValidation } from "./run.js";

package/dist/index.js

@@ -1,4 +1,4 @@
 export { discoverRepository } from "./discover.js";
 export { ExitCode } from "./exit-codes.js";
 export { formatSummary, formatViolations } from "./format.js";
-export { runValidation } from "./run.js";
+export { exitCodeForResult, runValidation } from "./run.js";

package/dist/run.d.ts

@@ -1,4 +1,5 @@
 import type { EngineResult, Finding } from "./engines/types.js";
+import type { ExitCodeValue } from "./exit-codes.js";
 export interface RunOptions {
     /** The root directory of the repository to validate */
     root: string;
@@ -54,3 +55,12 @@ export interface RunResult {
  * state. PASS without execution is impossible.
  */
 export declare function runValidation(options: RunOptions): Promise<RunResult>;
+/**
+ * Map a validation result to the documented process exit code.
+ *
+ * A required tool that could not run must never surface as PASS: when
+ * every executed engine passed but at least one category reports
+ * `TOOL-UNAVAILABLE`, the result exits `TOOL_MISSING` (3) instead of
+ * fabricating a passing result.
+ */
+export declare function exitCodeForResult(result: RunResult): ExitCodeValue;

package/dist/run.js

@@ -6,6 +6,7 @@ import { runDepcruise } from "./engines/depcruise.js";
 import { runEslint } from "./engines/eslint.js";
 import { runSchema } from "./engines/schema.js";
 import { runSemgrep } from "./engines/semgrep.js";
+import { ExitCode } from "./exit-codes.js";
 function categoryOf(result) {
     return {
         status: result.status,
@@ -17,6 +18,21 @@ function categoryOf(result) {
         reason: result.reason,
     };
 }
+/**
+ * Whether a category is acceptable for the overall validation result.
+ *
+ * A skipped category is acceptable only when it is explicitly NOT-RUN or
+ * NOT-APPLICABLE, or when a required tool is unavailable (which the exit-code
+ * mapping reports separately). Configuration and execution errors are never
+ * acceptable merely because they did not execute.
+ */
+function categoryIsAcceptable(result) {
+    if (result.executed)
+        return result.passed;
+    return (result.status === "NOT-RUN" ||
+        result.status === "NOT-APPLICABLE" ||
+        result.status === "TOOL-UNAVAILABLE");
+}
 function emptyCategory(reason) {
     return {
         status: "NOT-RUN",
@@ -87,7 +103,7 @@ export async function runValidation(options) {
     }
     let semgrepResult;
     if (!only || only === "semgrep") {
-        semgrepResult = await runSemgrep(repo);
+        semgrepResult = await runSemgrep(repo, { verbose: options.verbose === true });
     }
     else {
         semgrepResult = emptyEngineResult("semgrep engine skipped");
@@ -112,11 +128,9 @@ export async function runValidation(options) {
         }
     }
     const allExecuted = [depResult, eslintResult, semgrepResult, adapterResult];
-    const allPassed = allExecuted.every((r) => (r.executed ? r.passed : r.status !== "FAIL")) &&
-        (metaResult.executed ? metaResult.passed : metaResult.status !== "FAIL") &&
-        (configResult.executed
-            ? configResult.passed
-            : configResult.status !== "FAIL");
+    const allPassed = allExecuted.every(categoryIsAcceptable) &&
+        categoryIsAcceptable(metaResult) &&
+        categoryIsAcceptable(configResult);
     return {
         passed: allPassed,
         violations,
@@ -142,3 +156,19 @@ function emptyEngineResult(reason) {
         reason,
     };
 }
+/**
+ * Map a validation result to the documented process exit code.
+ *
+ * A required tool that could not run must never surface as PASS: when
+ * every executed engine passed but at least one category reports
+ * `TOOL-UNAVAILABLE`, the result exits `TOOL_MISSING` (3) instead of
+ * fabricating a passing result.
+ */
+export function exitCodeForResult(result) {
+    if (!result.passed) {
+        const configurationError = Object.values(result.categories).some((category) => category.status === "CONFIGURATION-ERROR");
+        return configurationError ? ExitCode.CONFIG_ERROR : ExitCode.FAIL;
+    }
+    const toolUnavailable = Object.values(result.categories).some((c) => c.status === "TOOL-UNAVAILABLE");
+    return toolUnavailable ? ExitCode.TOOL_MISSING : ExitCode.PASS;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comity-dev/validate",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Thin orchestrator over Comity shared validation tooling. Development tooling.",
   "type": "module",
   "private": false,
@@ -36,8 +36,8 @@
     "eslint": "^9.39.5",
     "@comity-dev/schemas": "0.2.0",
     "@comity-dev/dependency-rules": "0.2.0",
-    "@comity-dev/eslint-plugin": "0.2.0",
-    "@comity-dev/semgrep-rules": "0.2.0"
+    "@comity-dev/eslint-plugin": "0.3.0",
+    "@comity-dev/semgrep-rules": "0.2.2"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",