repo-contract 0.1.0

package/src/presets/shared/terminal-status.ts

@@ -0,0 +1,70 @@
+import type { CheckEvidence, PolicyResult } from "../../types.js"
+import { combinedOutput } from "./exit-code-fail-rationale.js"
+
+/**
+ * The guard every preset needs immediately after `checkDependencyInstalled`
+ * and before its own pass/fail logic: a check whose process did not run to a
+ * normal exit on its own -- it timed out, was aborted via `options.signal`,
+ * was killed by a host `SIGINT`/`SIGTERM`, received an external signal, or
+ * failed to spawn for a reason other than a missing executable -- has a
+ * `null` `exitCode` and only whatever partial output the tool managed before
+ * termination. Interpreting that with an exit-code comparison or a JSON
+ * parse would present an operational failure to the consumer as a fabricated
+ * tool-specific verdict ("TypeScript reported type errors (exit code null)",
+ * "ESLint output could not be parsed as JSON"). This reports the real
+ * terminal cause instead.
+ *
+ * `"completed"` returns `undefined` -- the process reached its own exit and
+ * the preset interprets the (possibly non-zero) exit code itself. The
+ * ENOENT `"spawn_error"` case is already handled by `checkDependencyInstalled`;
+ * this catches the remaining spawn failures (`EACCES`, `ENOEXEC`) that
+ * `missing-dependency.ts` documents as falling through.
+ * @param result - the check's raw execution evidence to inspect.
+ * @param toolName - the tool's own display name for the rationale (e.g. "ESLint", "TypeScript").
+ * @returns a fail `PolicyResult` describing the abnormal termination, or `undefined` if the process ran to its own exit and the caller should proceed.
+ */
+export function checkTerminatedAbnormally(
+  result: CheckEvidence,
+  toolName: string,
+): PolicyResult | undefined {
+  if (result.status === "completed") {
+    return undefined
+  }
+
+  const detail = combinedOutput(result)
+  const suffix = detail.length > 0 ? `\n${detail}` : ""
+
+  switch (result.status) {
+    case "timed_out":
+      return {
+        outcome: "fail",
+        rationale: `${toolName} did not finish: its process exceeded the configured timeout and was terminated.${suffix}`,
+      }
+    case "aborted":
+      return {
+        outcome: "fail",
+        rationale: `${toolName} did not finish: the run was aborted before its process completed.${suffix}`,
+      }
+    case "host_terminated":
+      return {
+        outcome: "fail",
+        rationale: `${toolName} did not finish: the host process received a termination signal and killed it.${suffix}`,
+      }
+    case "signaled":
+      return {
+        outcome: "fail",
+        rationale: `${toolName} was terminated by signal ${result.signal ?? "unknown"} before it completed.${suffix}`,
+      }
+    case "spawn_error":
+      return {
+        outcome: "fail",
+        rationale: `${toolName} could not be started: ${result.spawnError ?? "the process failed to spawn"}.`,
+      }
+    default: {
+      // A newly added `CheckStatus` must be classified here deliberately, not
+      // silently fall through the switch and be read by callers as "proceed".
+      const unhandled: never = result.status
+      throw new Error(`checkTerminatedAbnormally: unhandled check status ${String(unhandled)}`)
+    }
+  }
+}

package/src/presets/shared/vitest-json-policy.ts

@@ -0,0 +1,95 @@
+import type { JsonAssertionResult, JsonTestResult, JsonTestResults } from "vitest/reporters"
+import type { ParsedOutput, PolicyResult } from "../../types.js"
+
+type VitestJsonReport = JsonTestResults
+type VitestJsonTestSuite = JsonTestResult
+type VitestJsonAssertion = JsonAssertionResult
+
+/**
+ * Interprets Vitest's own `--reporter=json` output shape -- and nothing
+ * else. Shared between the `test` preset (a single, un-categorized
+ * `vitest run --reporter=json`) and this repository's own
+ * `test-unit`/`test-integration`/`test-property`/`test-e2e` checks, whose
+ * `run` splits tests into four mutually exclusive categories via
+ * scripts/run-test-category.mjs -- a repository-specific concern this
+ * function knows nothing about. Each of those four checks owns its own
+ * category-specific semantics on top of this evaluator; this function must
+ * stay narrowly scoped to "parse Vitest's JSON reporter shape," never grow
+ * into a general "testing policy" abstraction. A category's own
+ * `output.success === false` (vitest crashed / produced unparseable output)
+ * is kept distinct from a substantive test failure, exactly as every other
+ * preset in this package already does via `ParsedOutput.success`.
+ * @param output - the vitest check's parsed `--reporter=json` output to evaluate.
+ * @returns the pass/fail outcome and its rationale.
+ */
+export function evaluateVitestJsonPolicy(output: ParsedOutput<unknown> | undefined): PolicyResult {
+  if (!output?.success) {
+    return { outcome: "fail", rationale: "Vitest output could not be parsed as JSON." }
+  }
+
+  // `output.value` is `unknown` -- valid JSON that isn't Vitest's reporter
+  // shape (`null`, a primitive, a wrapper that printed `{}`, a config dump, a
+  // future schema change) must produce a fail verdict, not a TypeError out of
+  // the policy that `runPolicies` rethrows as `PolicyThrewError` and rejects the
+  // whole `runRepoContract()` promise with. `numFailedTests`/
+  // `numFailedTestSuites` being `undefined` (not `0`) already falls through the
+  // pass branch below, so `testResults` must be guarded before it is walked.
+  const value: unknown = output.value
+  if (typeof value !== "object" || value === null) {
+    return { outcome: "fail", rationale: "Vitest produced invalid JSON report data." }
+  }
+
+  const report = value as VitestJsonReport
+
+  if (!Array.isArray(report.testResults)) {
+    return { outcome: "fail", rationale: "Vitest produced invalid JSON report data." }
+  }
+
+  if (report.numFailedTests === 0 && report.numFailedTestSuites === 0) {
+    return {
+      outcome: "pass",
+      rationale: `Vitest completed ${String(report.numTotalTests)} test(s) with 0 failures across ${String(report.numTotalTestSuites)} suite(s).`,
+    }
+  }
+
+  // `Partial<>` because the elements are untrusted parsed JSON, not a guaranteed
+  // `JsonTestResult` -- a suite missing `assertionResults` entirely (a partial or
+  // older reporter shape) must not throw out of the policy, just contribute no
+  // failure detail lines.
+  const failures = report.testResults.flatMap((suite: Partial<VitestJsonTestSuite>): string[] =>
+    (suite.assertionResults ?? [])
+      .filter((test: VitestJsonAssertion) => test.status === "failed")
+      .map((test: VitestJsonAssertion) => {
+        const location = test.location
+          ? `:${String(test.location.line)}:${String(test.location.column)}`
+          : ""
+
+        const messages = (test.failureMessages ?? [])
+          .map((message: string) => message.trim())
+          .filter(Boolean)
+          .join(" | ")
+
+        // This mutant (dropping .filter(Boolean).join(" — "), returning the bare array instead)
+        // is proven killed under direct, unmocked `vitest run` of
+        // test/unit/presets/shared/vitest-json-policy.test.ts -- applying this exact replacement
+        // by hand and re-running fails 4 of that file's tests, including two that assert the
+        // complete rationale string via `toBe` specifically to make this mutation observable --
+        // but it survives every `npx stryker run` against this file (scoped or full, reproduced
+        // three times, once with concurrency forced to 1): this mutant's own `coveredBy`/
+        // `testsCompleted` show only 6 of the file's 11 tests ever ran against it, never the two
+        // `toBe` tests that would kill it. See stryker.config.mjs's own comment for the identical
+        // "coverage-attribution quirk" already found and worked around for `perTest` mode -- this
+        // is the same class of bug surfacing under `"all"` mode too, for this one line.
+        // Stryker disable next-line MethodExpression -- proven killed under direct vitest execution but Stryker's own coverage attribution never runs the two tests that would kill it; see the comment above.
+        return [`${suite.name}${location}`, test.fullName, messages].filter(Boolean).join(" — ")
+      }),
+  )
+
+  return {
+    outcome: "fail",
+    rationale: [
+      `Vitest reported ${String(report.numFailedTests)} failing test(s) across ${String(report.numFailedTestSuites)} failing suite(s):`,
+      ...failures.map((failure: string) => `- ${failure}`),
+    ].join("\n"),
+  }
+}

package/src/presets/stylelint.ts

@@ -0,0 +1,101 @@
+import type { CheckDefinitionConfig } from "../types.js"
+import { combinedOutput } from "./shared/exit-code-fail-rationale.js"
+import { errorWarningPassPolicy } from "./shared/error-warning-pass-policy.js"
+import { checkDependencyInstalled } from "./shared/missing-dependency.js"
+import { checkTerminatedAbnormally } from "./shared/terminal-status.js"
+
+/** Stylelint's own `--formatter json` contract -- not published as a TypeScript type by the tool. */
+interface StylelintWarning {
+  readonly line: number
+  readonly column: number
+  readonly rule: string
+  readonly severity: "error" | "warning"
+  readonly text: string
+}
+
+interface StylelintResult {
+  readonly source?: string
+  readonly errored: boolean
+  readonly warnings: readonly StylelintWarning[]
+}
+
+/** Options accepted by {@link stylelint}. */
+interface StylelintOptions {
+  /** Glob passed straight through to stylelint as its positional target. Defaults to `"**\/*.{css,scss}"` -- adjust it for your own stylesheet file extensions (e.g. `.less`, `.vue`, `.svelte`). */
+  readonly glob?: string
+}
+
+/**
+ * CSS/SCSS lint via stylelint, using whatever stylelint config the
+ * consumer's own repository already has. `severity: "error"` blocks;
+ * `severity: "warning"` is reported but never blocks, matching how the
+ * `lint` preset treats ESLint's own severities.
+ * @param options - configuration for this check; see {@link StylelintOptions}.
+ * @returns the configured check.
+ */
+export function stylelint(options: StylelintOptions = {}): CheckDefinitionConfig {
+  const { glob = "**/*.{css,scss}" } = options
+
+  return {
+    run: ["stylelint", glob, "--formatter", "json"],
+    output: { format: "json" },
+    policy: ({ result }) => {
+      const missing = checkDependencyInstalled(result, "stylelint")
+      if (missing) return missing
+
+      const terminated = checkTerminatedAbnormally(result, "stylelint")
+      if (terminated) return terminated
+
+      if (!result.output?.success) {
+        // stylelint exits non-zero with no JSON on stdout when its glob
+        // matched no stylesheets or its config failed to load. Surface what
+        // it printed so a repo that legitimately has no CSS sees the real
+        // cause rather than an opaque parse failure.
+        const printed = combinedOutput(result)
+
+        return {
+          outcome: "fail",
+          rationale:
+            printed.length > 0
+              ? `stylelint output could not be parsed as JSON. stylelint printed:\n${printed}`
+              : "stylelint output could not be parsed as JSON.",
+        }
+      }
+
+      // Valid JSON of an unexpected shape (a stylelint formatter change, a
+      // primitive, an entry without a `warnings` array) must fail cleanly, not
+      // throw a TypeError out of the `flatMap` below.
+      const value: unknown = result.output.value
+      if (
+        !Array.isArray(value) ||
+        !value.every(
+          (entry): entry is StylelintResult =>
+            typeof entry === "object" &&
+            entry !== null &&
+            Array.isArray((entry as { warnings?: unknown }).warnings),
+        )
+      ) {
+        return { outcome: "fail", rationale: "stylelint output could not be parsed as JSON." }
+      }
+
+      const results: readonly StylelintResult[] = value
+
+      const render = (file: StylelintResult, warning: StylelintWarning): string =>
+        `${file.source ?? "<unknown file>"}:${String(warning.line)}:${String(warning.column)} [${warning.rule}]: ${warning.text}`
+
+      const errorDetails = results.flatMap((file: StylelintResult): string[] =>
+        file.warnings
+          .filter((warning: StylelintWarning) => warning.severity === "error")
+          .map((warning: StylelintWarning) => render(file, warning)),
+      )
+
+      const warningDetails = results.flatMap((file: StylelintResult): string[] =>
+        file.warnings
+          .filter((warning: StylelintWarning) => warning.severity === "warning")
+          .map((warning: StylelintWarning) => render(file, warning)),
+      )
+
+      return errorWarningPassPolicy("stylelint", errorDetails, warningDetails)
+    },
+  }
+}

package/src/presets/test.ts

@@ -0,0 +1,19 @@
+import type { CheckDefinitionConfig } from "../types.js"
+import { checkDependencyInstalled } from "./shared/missing-dependency.js"
+import { checkTerminatedAbnormally } from "./shared/terminal-status.js"
+import { evaluateVitestJsonPolicy } from "./shared/vitest-json-policy.js"
+
+/** Unit/integration test execution via Vitest, reading its JSON reporter output. */
+export const test: CheckDefinitionConfig = {
+  run: ["vitest", "run", "--reporter=json"],
+  output: { format: "json" },
+  policy: ({ result }) => {
+    const missing = checkDependencyInstalled(result, "vitest")
+    if (missing) return missing
+
+    const terminated = checkTerminatedAbnormally(result, "Vitest")
+    if (terminated) return terminated
+
+    return evaluateVitestJsonPolicy(result.output)
+  },
+}

package/src/presets/typecheck.ts

@@ -0,0 +1,25 @@
+import type { CheckDefinitionConfig } from "../types.js"
+import { checkDependencyInstalled } from "./shared/missing-dependency.js"
+import { checkTerminatedAbnormally } from "./shared/terminal-status.js"
+import { exitCodeFailRationale } from "./shared/exit-code-fail-rationale.js"
+
+/** Type checking via `tsc --noEmit`. */
+export const typecheck: CheckDefinitionConfig = {
+  run: ["tsc", "--noEmit", "-p", "tsconfig.json"],
+  policy: ({ result }) => {
+    const missing = checkDependencyInstalled(result, "typescript")
+    if (missing) return missing
+
+    const terminated = checkTerminatedAbnormally(result, "TypeScript")
+    if (terminated) return terminated
+
+    if (result.exitCode === 0) {
+      return { outcome: "pass", rationale: "tsc reported no type errors." }
+    }
+
+    return {
+      outcome: "fail",
+      rationale: exitCodeFailRationale(result, "TypeScript reported type errors"),
+    }
+  },
+}

package/src/run-repo-contract.ts

@@ -0,0 +1,80 @@
+import * as os from "node:os"
+import { validateRepoContractConfig } from "./config/validate-config.js"
+import { buildEvidence } from "./evidence/build-evidence.js"
+import { runChecks } from "./execution/run-checks.js"
+import { runPolicies } from "./policy/run-policies.js"
+import type {
+  CheckSchema,
+  Evidence,
+  RepoContractConfig,
+  RunRepoContractOptions,
+  Verdict,
+} from "./types.js"
+
+/**
+ * Executes every configured check, collects its evidence, optionally parses
+ * its output, evaluates every check's repository-owned policy against the
+ * complete evidence, and aggregates a verdict. Never calls `process.exit()`
+ * -- returns data; the caller decides what to do with `verdict.passed`.
+ *
+ * Structural configuration problems throw synchronously before any process
+ * spawns. Anything only discoverable by attempting execution (a missing
+ * binary, a bad `cwd`) becomes evidence on that check (`status:
+ * "spawn_error"`), never a throw. A policy function throwing or rejecting
+ * rejects this function's own returned promise (`PolicyThrewError`, or an
+ * `AggregateError` of them if more than one policy failed this way) --
+ * distinct from a policy that ran fine and simply returned a failure
+ * string. See `src/errors.ts` for the full distinction.
+ *
+ * Execution and policy evaluation are strictly phased: every check finishes
+ * running and every check's evidence is fully assembled before any policy
+ * is invoked (see specs/architecture.md) -- a policy can safely read
+ * `ctx.evidence` for any sibling check's result.
+ *
+ * Deliberately not declared `async`: validation runs and can throw before this function returns
+ * anything at all, so a config problem is a genuine synchronous exception to the caller (as
+ * documented above and on `InvalidRepoContractConfigError`/`InvalidCheckConfigError`/
+ * `DependencyDeclaredLaterError`) -- an `async function`'s body runs to its first `await` still
+ * inside the caller's own call stack, but any throw before that point is nonetheless converted by
+ * the language into a rejected `Promise`, never surfaced as a synchronous exception. Splitting
+ * validation out into this synchronous wrapper, with the rest of the work in the `async` function
+ * below, keeps the documented synchronous-throw guarantee actually true rather than aspirational.
+ * @param config - the repo-contract configuration to run: its checks, concurrency, and their policies
+ * @param options - run options; `options.checks` restricts execution to specific check ids, `options.signal` allows cancelling the run
+ * @returns the assembled `evidence` for every check together with the aggregated `verdict`
+ */
+export function runRepoContract<const TChecks extends CheckSchema>(
+  config: RepoContractConfig<TChecks>,
+  options?: RunRepoContractOptions,
+): Promise<{ evidence: Evidence<TChecks>; verdict: Verdict<TChecks> }> {
+  validateRepoContractConfig(config)
+  return runRepoContractAfterValidation(config, options)
+}
+
+/**
+ * The rest of `runRepoContract`'s work, once its config has already been validated -- see that
+ * function's own doc comment for why validation itself lives in a separate, non-`async` wrapper.
+ * @param config - the already-validated repo-contract configuration to run.
+ * @param options - run options; see `runRepoContract`.
+ * @returns the assembled `evidence` for every check together with the aggregated `verdict`
+ */
+async function runRepoContractAfterValidation<const TChecks extends CheckSchema>(
+  config: RepoContractConfig<TChecks>,
+  options: RunRepoContractOptions | undefined,
+): Promise<{ evidence: Evidence<TChecks>; verdict: Verdict<TChecks> }> {
+  // validateRepoContractConfig above already rejects any config.concurrency that is not a
+  // positive integer (>= 1, see validate-config.ts), so by the time this line runs
+  // config.concurrency is always either undefined or already truthy -- `??` and `&&` therefore
+  // select the identical branch for every value this parameter can actually hold here.
+  // Stryker disable next-line LogicalOperator -- validateRepoContractConfig above already rejects any config.concurrency that is not a positive integer (>= 1), so by the time this line runs config.concurrency is always either undefined or already truthy; `??` and `&&` therefore select the identical branch for every value this parameter can actually hold here, making them equivalent at this exact call site.
+  const concurrency = config.concurrency ?? os.availableParallelism()
+  const startedAt = new Date()
+
+  const results = await runChecks(config.checks, concurrency, options)
+  const completedAt = new Date()
+
+  const { evidence, entries } = await buildEvidence(results, startedAt, completedAt)
+  const verdict = await runPolicies(entries, evidence)
+
+  return { evidence, verdict } as { evidence: Evidence<TChecks>; verdict: Verdict<TChecks> }
+}