repo-contract 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [0.3.0](https://github.com/MaverickCER/repo-contract/compare/repo-contract-v0.2.1...repo-contract-v0.3.0) (2026-09-03)
+
+
+### ⚠ BREAKING CHANGES
+
+* defineRepoContract/runRepoContract now require spawn and env on the config (e.g. spawn: child_process.spawn, env: process.env). See ADR 0011 and README's "Supplying spawn/env" section for migration.
+
+### Features
+
+* contract engine, self-hosting checks and CI workflows ([97ae128](https://github.com/MaverickCER/repo-contract/commit/97ae128bd96f2c631057f1150068af58cc66b224))
+* contract engine, self-hosting checks and CI workflows ([22b2a3b](https://github.com/MaverickCER/repo-contract/commit/22b2a3b03fe4e44ad7a01b82342d86583926416a))
+* make process spawning and env access consumer-supplied capabilities ([640a961](https://github.com/MaverickCER/repo-contract/commit/640a961b65fd73511586c3b4f6274284bf5172a9))
+
+
+### Bug Fixes
+
+* clear Socket supply-chain alerts (unminified dist, no prepare script) ([71c9230](https://github.com/MaverickCER/repo-contract/commit/71c92306fcf00e3858f0596c2d56f3272199339d))
+* publish the dist bundle unminified ([266ae47](https://github.com/MaverickCER/repo-contract/commit/266ae47919753c55f10364713fe0c7c5876815b7))
+* remove the prepare install script from the published package ([9153540](https://github.com/MaverickCER/repo-contract/commit/9153540e4f0f1a069e07c12ddfee8ba62827ce5b))
+
+## [0.2.1](https://github.com/MaverickCER/repo-contract/compare/repo-contract-v0.2.0...repo-contract-v0.2.1) (2026-09-03)
+
+
+### Documentation
+
+* add Socket security badge to README
+
+## [0.2.0](https://github.com/MaverickCER/repo-contract/compare/repo-contract-v0.1.1...repo-contract-v0.2.0) (2026-09-03)
+
+
+### ⚠ BREAKING CHANGES
+
+* defineRepoContract/runRepoContract now require spawn and env on the config (e.g. spawn: child_process.spawn, env: process.env). See ADR 0011 and README's "Supplying spawn/env" section for migration.
+
+### Features
+
+* make process spawning and env access consumer-supplied capabilities ([640a961](https://github.com/MaverickCER/repo-contract/commit/640a961b65fd73511586c3b4f6274284bf5172a9))
+
 ## [0.1.1](https://github.com/MaverickCER/repo-contract/compare/repo-contract-v0.1.0...repo-contract-v0.1.1) (2026-09-01)
 
 

package/README.md

@@ -6,6 +6,7 @@
 [![Coverage](https://img.shields.io/badge/coverage-%E2%89%A585%25-brightgreen)](scripts/coverage-thresholds.mjs)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](tsconfig.json)
 [![Node](https://img.shields.io/node/v/repo-contract.svg)](package.json)
+[![Socket Badge](https://badge.socket.dev/npm/package/repo-contract/latest)](https://badge.socket.dev/npm/package/repo-contract/latest)
 
 **Turn your repository's engineering standards into enforceable contracts.**
 
@@ -92,7 +93,7 @@ npm install --save-dev yaml
 
 ### Runtime support matrix
 
-repo-contract spawns processes and reads `process.env` — it is server/CLI-only by design, not an isomorphic/browser package.
+repo-contract's checks run as spawned processes and read the ambient environment — but repo-contract never imports a process-spawning implementation or reads `process.env` itself (see [Supplying `spawn`/`env`](#supplying-spawnenv) below); it is server/CLI-only by design regardless, not an isomorphic/browser package, since the capability a consumer supplies is itself always a real Node-only spawning mechanism.
 
 | Environment                                | Supported                                                                                                                                                                                                    |
 | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -113,9 +114,14 @@ Define your repository's standards as checks:
 
 ```ts
 // repo-contract.config.ts
+import { spawn } from "node:child_process"
 import { defineRepoContract } from "repo-contract"
 
 export default defineRepoContract({
+  // repo-contract never spawns a process or reads process.env itself -- see
+  // "Supplying spawn/env" below for why, and what to pass on Windows.
+  spawn,
+  env: process.env,
   checks: {
     tests: {
       run: "npm test",
@@ -179,6 +185,49 @@ process.exitCode = verdict.passed ? 0 : 1
 
 There is no CLI, no config-file discovery magic, and no hidden state.
 
+### Supplying `spawn`/`env`
+
+`spawn` and `env` are required fields on the config — repo-contract never imports a process-spawning implementation or reads `process.env` internally (see [ADR 0011](specs/decisions/0011-process-spawning-and-ambient-environment-access-are-consumer-supplied-capabilities-not-package-owned.md)). You supply both, as trusted capabilities repo-contract calls with a resolved command/argv/options — it does not inspect, wrap, or sanitize them.
+
+**macOS/Linux** — plain `node:child_process` is enough:
+
+```ts
+import { spawn } from "node:child_process"
+
+export default defineRepoContract({
+  spawn,
+  env: process.env,
+  checks: {/* ... */},
+})
+```
+
+**Windows** — most npm-installed CLI tools (`eslint`, `prettier`, `tsc`, …) resolve to `.cmd` shims, and plain `node:child_process.spawn` refuses to run those at all without `shell: true` (Node's own CVE-2024-27980 mitigation). Install [`cross-spawn`](https://www.npmjs.com/package/cross-spawn) and pass it instead — it resolves `.cmd`/`.bat` shims and quotes arguments safely for `cmd.exe`, **without** turning on shell metacharacter interpretation:
+
+```ts
+import crossSpawn, { sync as crossSpawnSync } from "cross-spawn"
+
+export default defineRepoContract({
+  spawn: crossSpawn,
+  env: process.env,
+  // Optional: lets a timed-out/aborted/Ctrl+C-killed check's full process
+  // tree (not just its immediate process) get cleaned up on Windows too.
+  killProcessTree: crossSpawnSync,
+  checks: {/* ... */},
+})
+```
+
+**`cross-spawn` does not mean "shell execution."** These are two independent choices:
+
+| `Spawner` choice | `shell` option    | Result                                                                                                                               |
+| ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| native `spawn`   | `false` (default) | argv-only, no shell interpretation                                                                                                   |
+| `cross-spawn`    | `false` (default) | Windows `.cmd`/`.bat` resolution + safe `cmd.exe` quoting, still argv-only                                                           |
+| either           | `true`            | shell metacharacters (`&&`, `\|`, …) interpreted — a per-check or global opt-in, see [`shell`](docs/api-report/repo-contract.api.md) |
+
+Passing `cross-spawn` fixes Windows command resolution; it does not by itself enable shell metacharacter interpretation. `check.shell` (or the config-level `shell` default) is the separate, explicit opt-in for that — see `SECURITY.md` before enabling it.
+
+`repo-contract` doesn't ship a ready-made spawner of its own, on purpose (see ADR 0011's Alternatives) — the two snippets above are the whole integration.
+
 ## The model
 
 ```text
@@ -641,10 +690,13 @@ It does **not** encode your repository's definition of quality.
 Import a preset, spread it into your own `checks` record, and override whatever you need — most often `policy`:
 
 ```ts
+import { spawn } from "node:child_process"
 import { defineRepoContract } from "repo-contract"
 import { format, typecheck, license } from "repo-contract/presets"
 
 export default defineRepoContract({
+  spawn,
+  env: process.env,
   checks: {
     format,
     typecheck: {
@@ -662,10 +714,13 @@ export default defineRepoContract({
 Some presets are factories because they expose options that change what gets executed:
 
 ```ts
+import { spawn } from "node:child_process"
 import { defineRepoContract } from "repo-contract"
 import { lint, deadCode } from "repo-contract/presets"
 
 export default defineRepoContract({
+  spawn,
+  env: process.env,
   checks: {
     lint: lint({ path: "src" }),
     deadCode: deadCode({

package/dist/index.cjs

@@ -1,11 +1,7 @@
 'use strict';
 
 var os = require('os');
-var crossSpawn = require('cross-spawn');
 var string_decoder = require('string_decoder');
-var child_process = require('child_process');
-
-function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 function _interopNamespace(e) {
   if (e && e.__esModule) return e;
@@ -26,7 +22,6 @@ function _interopNamespace(e) {
 }
 
 var os__namespace = /*#__PURE__*/_interopNamespace(os);
-var crossSpawn__default = /*#__PURE__*/_interopDefault(crossSpawn);
 
 // src/config/define-repo-contract.ts
 function defineRepoContract(config) {
@@ -236,7 +231,7 @@ function validateRepoContractConfig(config) {
   if (untrusted === null || typeof untrusted !== "object") {
     throw new InvalidRepoContractConfigError("config must be an object.");
   }
-  const { checks, concurrency } = untrusted;
+  const { checks, concurrency, spawn, env, shell, killProcessTree } = untrusted;
   if (checks === null || typeof checks !== "object" || Array.isArray(checks)) {
     throw new InvalidRepoContractConfigError(
       "checks must be an object mapping check id to check definition."
@@ -249,12 +244,35 @@ function validateRepoContractConfig(config) {
       );
     }
   }
+  if (typeof spawn !== "function") {
+    throw new InvalidRepoContractConfigError("spawn must be a function.");
+  }
+  validateConfigEnv(env);
+  if (shell !== void 0 && typeof shell !== "boolean") {
+    throw new InvalidRepoContractConfigError("shell must be a boolean when provided.");
+  }
+  const globalShell = shell === true;
+  if (killProcessTree !== void 0 && typeof killProcessTree !== "function") {
+    throw new InvalidRepoContractConfigError("killProcessTree must be a function when provided.");
+  }
   for (const [checkId, check] of Object.entries(checks)) {
-    validateCheckDefinition(checkId, check);
+    validateCheckDefinition(checkId, check, globalShell);
   }
   validateDependencyGraph(checks);
 }
-function validateCheckDefinition(checkId, check) {
+function validateConfigEnv(env) {
+  if (env === null || typeof env !== "object" || Array.isArray(env)) {
+    throw new InvalidRepoContractConfigError(
+      "env must be an object mapping variable name to value."
+    );
+  }
+  for (const [key, value] of Object.entries(env)) {
+    if (typeof value !== "string" && value !== void 0) {
+      throw new InvalidRepoContractConfigError(`env["${key}"] must be a string or undefined.`);
+    }
+  }
+}
+function validateCheckDefinition(checkId, check, globalShell) {
   if (/^(?:0|[1-9]\d*)$/.test(checkId)) {
     throw new InvalidCheckConfigError(
       checkId,
@@ -265,7 +283,7 @@ function validateCheckDefinition(checkId, check) {
     throw new InvalidCheckConfigError(checkId, "check definition must be an object.");
   }
   const fields = check;
-  const usesShell = validateShell(checkId, fields.shell);
+  const usesShell = validateShell(checkId, fields.shell, globalShell);
   validateRun(checkId, fields.run, usesShell);
   validateCwd(checkId, fields.cwd);
   validateEnv(checkId, fields.env);
@@ -276,11 +294,11 @@ function validateCheckDefinition(checkId, check) {
   validateIsolated(checkId, fields.isolated);
   validatePolicy(checkId, fields.policy);
 }
-function validateShell(checkId, shell) {
+function validateShell(checkId, shell, globalShell) {
   if (shell !== void 0 && typeof shell !== "boolean") {
     throw new InvalidCheckConfigError(checkId, "shell must be a boolean when provided.");
   }
-  return shell === true;
+  return typeof shell === "boolean" ? shell : globalShell;
 }
 function validateRun(checkId, run, usesShell) {
   if (typeof run !== "string" && !Array.isArray(run)) {
@@ -627,18 +645,23 @@ async function runWithConcurrencyGraph(items, concurrency, dependencyIndexes, wo
     launchNext();
   });
 }
+
+// src/execution/process-tree.ts
 function shouldSpawnDetached() {
   return process.platform !== "win32";
 }
 function isErrnoException(error) {
   return error instanceof Error && "code" in error;
 }
-function killTree(pid, signal) {
+function killTree(pid, signal, killProcessTree) {
   if (!Number.isInteger(pid) || pid <= 0) {
     return;
   }
   if (process.platform === "win32") {
-    const result = child_process.spawnSync("taskkill", ["/pid", String(pid), "/t", "/f"], { stdio: "ignore" });
+    if (killProcessTree === void 0) return;
+    const result = killProcessTree("taskkill", ["/pid", String(pid), "/t", "/f"], {
+      stdio: "ignore"
+    });
     if (result.error !== void 0) throw result.error;
     return;
   }
@@ -672,7 +695,7 @@ function createBoundedCollector() {
     value: () => value
   };
 }
-function resolveCommand(checkId, check) {
+function resolveCommand(checkId, check, effectiveShell) {
   const run = check.run;
   if (typeof run !== "string") {
     const [command2, ...args2] = run;
@@ -681,7 +704,7 @@ function resolveCommand(checkId, check) {
     }
     return { command: command2, args: args2 };
   }
-  if (check.shell === true) {
+  if (effectiveShell) {
     return { command: run, args: [] };
   }
   const [command, ...args] = tokenizeRunString(run, checkId);
@@ -690,10 +713,10 @@ function resolveCommand(checkId, check) {
   }
   return { command, args };
 }
-function buildEnv(check) {
+function buildEnv(check, ambientEnv) {
   const base = {};
   if (check.inheritEnv !== false) {
-    for (const [key, value] of Object.entries(process.env)) {
+    for (const [key, value] of Object.entries(ambientEnv)) {
       if (value !== void 0) base[key] = value;
     }
   }
@@ -716,13 +739,14 @@ function terminalEvidence(command, args, startedAt, status, exitCode, signal, st
     ...spawnErrorCode !== void 0 ? { spawnErrorCode } : {}
   };
 }
-async function spawnCheck(checkId, check, runSignal, activeHandles) {
+async function spawnCheck(checkId, check, runSignal, activeHandles, execution) {
   const startedAt = /* @__PURE__ */ new Date();
-  const { command, args } = resolveCommand(checkId, check);
+  const effectiveShell = check.shell ?? execution.shell;
+  const { command, args } = resolveCommand(checkId, check, effectiveShell);
   if (runSignal?.aborted === true) {
     return terminalEvidence(command, args, startedAt, "aborted", null, null);
   }
-  const env = buildEnv(check);
+  const env = buildEnv(check, execution.env);
   let terminationReason = null;
   let timeoutHandle;
   const timeoutController = new AbortController();
@@ -737,10 +761,10 @@ async function spawnCheck(checkId, check, runSignal, activeHandles) {
     runSignal !== void 0 ? [runSignal, timeoutController.signal] : [timeoutController.signal]
   );
   return new Promise((resolve) => {
-    const child = crossSpawn__default.default(command, args, {
+    const child = execution.spawn(command, args, {
       cwd: check.cwd,
       env,
-      shell: check.shell === true,
+      shell: effectiveShell,
       detached: shouldSpawnDetached(),
       // Windows-only cosmetic behavior (suppresses a console window flash)
       // with no effect on stdout/stderr/exitCode/signal on any platform, and
@@ -755,7 +779,11 @@ async function spawnCheck(checkId, check, runSignal, activeHandles) {
     let hostTerminated = false;
     const bestEffortKillTree = (pid, signal) => {
       try {
-        killTree(pid, signal);
+        killTree(pid, signal, execution.killProcessTree);
+      } catch {
+      }
+      try {
+        child.kill(signal);
       } catch {
       }
     };
@@ -894,7 +922,7 @@ function resolveCheckDependencies(checks, requestedChecks) {
   for (const checkId of requestedChecks) visit(checkId);
   return Object.entries(checks).filter(([checkId]) => required.has(checkId));
 }
-async function runChecks(checks, concurrency, options) {
+async function runChecks(checks, concurrency, execution, options) {
   const entries = options?.checks ? resolveCheckDependencies(checks, options.checks) : Object.entries(checks);
   const activeHandles = /* @__PURE__ */ new Set();
   const hostAbortController = new AbortController();
@@ -915,7 +943,7 @@ async function runChecks(checks, concurrency, options) {
     )
   );
   const worker = async ([checkId, check]) => {
-    const evidence = await spawnCheck(checkId, check, runSignal, activeHandles);
+    const evidence = await spawnCheck(checkId, check, runSignal, activeHandles, execution);
     return [checkId, check, evidence];
   };
   try {
@@ -1047,7 +1075,13 @@ function runRepoContract(config, options) {
 async function runRepoContractAfterValidation(config, options) {
   const concurrency = config.concurrency ?? os__namespace.availableParallelism();
   const startedAt = /* @__PURE__ */ new Date();
-  const results = await runChecks(config.checks, concurrency, options);
+  const execution = {
+    spawn: config.spawn,
+    killProcessTree: config.killProcessTree,
+    env: config.env,
+    shell: config.shell ?? false
+  };
+  const results = await runChecks(config.checks, concurrency, execution, options);
   const completedAt = /* @__PURE__ */ new Date();
   const { evidence, entries } = await buildEvidence(results, startedAt, completedAt);
   const verdict = await runPolicies(entries, evidence);