@comity-dev/validate 0.2.0 → 0.2.1

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,40 @@
 import type { Repository } from "../discover.js";
 import type { EngineResult } from "./types.js";
+/**
+ * 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 resolvePythonForSemgrep(env?: NodeJS.ProcessEnv, binPath?: string): string | null;
 export declare function runSemgrep(repo: Repository): Promise<EngineResult>;

package/dist/engines/semgrep.js

@@ -1,41 +1,121 @@
 import { buildSemgrepConfig } from "@comity-dev/semgrep-rules";
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, mkdtempSync, openSync, readSync, rmSync, writeFileSync, } from "node:fs";
 import { relative, resolve } from "node:path";
+/**
+ * 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) {
@@ -140,10 +220,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 +239,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
@@ -229,6 +311,7 @@ export async function runSemgrep(repo) {
             duration: Date.now() - start,
             status: "EXECUTION-ERROR",
             tool: "semgrep",
+            reason: `semgrep exited with code ${proc.status} before producing findings (stderr: ${stderrHead}); this is a tool execution failure, not a rule match — see the SEM-CRASH finding`,
         };
     }
     return {

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,
@@ -142,3 +143,17 @@ 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)
+        return 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.1",
   "description": "Thin orchestrator over Comity shared validation tooling. Development tooling.",
   "type": "module",
   "private": false,
@@ -37,7 +37,7 @@
     "@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/semgrep-rules": "0.2.1"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",