repo-contract 0.1.0

package/src/presets/dead-code.ts

@@ -0,0 +1,223 @@
+import type { CheckDefinitionConfig } from "../types.js"
+import { checkDependencyInstalled } from "./shared/missing-dependency.js"
+import { checkTerminatedAbnormally } from "./shared/terminal-status.js"
+
+/**
+ * Knip does not expose the serialized JSON reporter result as a public
+ * TypeScript type, so the local evidence type below intentionally models
+ * that JSON contract. This targets knip's `json` reporter as of knip 6:
+ * `{ issues: KnipIssue[] }`, one entry per file, each carrying an array per
+ * issue category (`knip 5` additionally had a top-level `files: string[]` for
+ * unused files; knip 6 folds those into `issues[].files`). The policy reports
+ * the actual issue category and name instead of only returning a count.
+ */
+interface KnipIssueEntry {
+  readonly name: string
+  readonly line?: number
+  readonly col?: number
+  readonly pos?: number
+}
+
+/** `duplicates`/`cycles` group several symbols together; every other category is a flat entry. */
+type KnipCategory = readonly (KnipIssueEntry | readonly KnipIssueEntry[])[]
+
+interface KnipIssue {
+  readonly file: string
+  readonly dependencies?: KnipCategory
+  readonly devDependencies?: KnipCategory
+  readonly optionalPeerDependencies?: KnipCategory
+  readonly unlisted?: KnipCategory
+  readonly unresolved?: KnipCategory
+  readonly exports?: KnipCategory
+  readonly types?: KnipCategory
+  readonly nsExports?: KnipCategory
+  readonly nsTypes?: KnipCategory
+  readonly namespaceMembers?: KnipCategory
+  readonly enumMembers?: KnipCategory
+  readonly binaries?: KnipCategory
+  readonly duplicates?: KnipCategory
+  readonly cycles?: KnipCategory
+  readonly files?: KnipCategory
+}
+
+interface KnipReport {
+  readonly issues: readonly KnipIssue[]
+}
+
+/** Options accepted by {@link deadCode}. */
+interface DeadCodeOptions {
+  /**
+   * devDependency names to exclude from the "unused devDependency" issue
+   * category -- e.g. CLI tools knip has no way to see are used, because
+   * nothing `import`s them. Round-tripped through knip's own
+   * `--reporter-options` flag (see `readReporterOptions`) rather than kept in
+   * a closure, so the exempt list this check actually ran with is visible on
+   * the recorded command line and in persisted evidence, not just in this
+   * file's source. Defaults to an empty list -- repo-contract ships no
+   * built-in exemptions; add your own repository's here.
+   */
+  readonly exemptUnusedDevDependencies?: readonly string[]
+}
+
+/**
+ * Recovers the JSON payload knip's own `--reporter-options` flag was invoked
+ * with, if any. This is how `deadCode`'s exempt list gets from `run` back
+ * into the policy purely via `result.args` -- see {@link DeadCodeOptions}.
+ * @param args - the exact argv the check's command was spawned with (`CheckEvidence.args`).
+ * @returns the parsed `--reporter-options` payload, or `undefined` if the flag is absent or its value isn't valid JSON.
+ */
+function readReporterOptions(args: readonly string[]): DeadCodeOptions | undefined {
+  const flagIndex = args.indexOf("--reporter-options")
+  const raw = flagIndex === -1 ? undefined : args[flagIndex + 1]
+
+  // Provably equivalent, not a coverage gap: `JSON.parse(undefined)` (what
+  // happens if this guard is removed or forced false) always throws
+  // ("undefined" is not valid JSON, confirmed empirically), which the catch
+  // block below already converts back to `undefined` -- the exact same
+  // observable result this early return produces. Kept for clarity (avoids
+  // relying on that throw-and-catch as the mechanism), not for behavior no
+  // test can otherwise reach.
+  // Stryker disable next-line ConditionalExpression,EqualityOperator,BlockStatement -- JSON.parse(undefined) always throws, and the catch block below already converts that back to undefined, the same result this early return produces
+  if (raw === undefined) {
+    return undefined
+  }
+
+  // Provably equivalent, not a coverage gap: the catch block below is the
+  // last statement in the function, so an empty block there falls off the
+  // end and implicitly returns `undefined` anyway -- identical to its
+  // explicit `return undefined`. Kept for clarity, not for behavior no
+  // test can otherwise reach.
+  // Stryker disable BlockStatement -- an empty catch block falls off the end of the function and implicitly returns undefined, identical to its explicit return
+  try {
+    return JSON.parse(raw) as DeadCodeOptions
+  } catch {
+    return undefined
+  }
+  // Stryker restore all
+}
+
+/**
+ * Renders one category entry as `{ name, location }`. `duplicates`/`cycles` entries are a
+ * group of symbols (knip pushes `symbols.map(...)`); every other category is a flat entry.
+ * @param entry - a single `KnipIssueEntry`, or a `duplicates`/`cycles` group of them.
+ * @returns the joined symbol name(s) and a `:line:col` suffix (empty for a group or a
+ *   location-less entry).
+ */
+function formatEntry(entry: KnipIssueEntry | readonly KnipIssueEntry[]): {
+  readonly name: string
+  readonly location: string
+} {
+  if (Array.isArray(entry)) {
+    const group = entry as readonly KnipIssueEntry[]
+    return { name: group.map((member) => member.name).join(", "), location: "" }
+  }
+
+  const single = entry as KnipIssueEntry
+  const location =
+    typeof single.line === "number" ? `:${String(single.line)}:${String(single.col ?? 1)}` : ""
+  return { name: single.name, location }
+}
+
+/**
+ * Dead/unused-code detection via knip.
+ * @param options - configuration for this check; see {@link DeadCodeOptions}.
+ * @returns the configured check.
+ */
+export function deadCode(options: DeadCodeOptions = {}): CheckDefinitionConfig {
+  const { exemptUnusedDevDependencies = [] } = options
+
+  return {
+    run: [
+      "knip",
+      "--reporter",
+      "json",
+      "--reporter-options",
+      JSON.stringify({ exemptUnusedDevDependencies } satisfies DeadCodeOptions),
+    ],
+    output: { format: "json" },
+    policy: ({ result }) => {
+      const missing = checkDependencyInstalled(result, "knip")
+      if (missing) return missing
+
+      const terminated = checkTerminatedAbnormally(result, "Knip")
+      if (terminated) return terminated
+
+      if (!result.output?.success) {
+        return { outcome: "fail", rationale: "Knip output could not be parsed as JSON." }
+      }
+
+      // `output.success` only means `JSON.parse` didn't throw -- `value` is `unknown` at
+      // runtime. Guard that it is a real object (not `null` / a primitive / an array) before
+      // trusting the `KnipReport` cast, so a policy TypeError never escapes into the run.
+      const value: unknown = result.output.value
+
+      if (typeof value !== "object" || value === null) {
+        return { outcome: "fail", rationale: "Knip produced invalid JSON report data." }
+      }
+
+      const report = value as KnipReport
+
+      if (!Array.isArray(report.issues)) {
+        return { outcome: "fail", rationale: "Knip produced invalid JSON report data." }
+      }
+
+      // Re-annotated rather than used directly: `Array.isArray` narrows its
+      // argument to `any[]` regardless of the checked value's declared type (a
+      // long-standing TypeScript limitation), so `report.issues` would
+      // otherwise silently lose its element type below.
+      const issues: readonly KnipIssue[] = report.issues
+
+      const exemptDevDependencies = new Set(
+        readReporterOptions(result.args)?.exemptUnusedDevDependencies ?? [],
+      )
+
+      const details: string[] = []
+
+      for (const issue of issues) {
+        const addEntries = (
+          label: string,
+          entries: KnipCategory | undefined,
+          ignored: ReadonlySet<string> = new Set(),
+        ): void => {
+          for (const entry of entries ?? []) {
+            const { name, location } = formatEntry(entry)
+
+            if (ignored.has(name)) {
+              continue
+            }
+
+            details.push(`${issue.file}${location} — ${label}: ${name}`)
+          }
+        }
+
+        addEntries("unused dependency", issue.dependencies)
+        addEntries("unused devDependency", issue.devDependencies, exemptDevDependencies)
+        addEntries("unused optional peer dependency", issue.optionalPeerDependencies)
+        addEntries("unlisted dependency", issue.unlisted)
+        addEntries("unresolved import", issue.unresolved)
+        addEntries("unused export", issue.exports)
+        addEntries("unused export (namespace)", issue.nsExports)
+        addEntries("unused type", issue.types)
+        addEntries("unused type (namespace)", issue.nsTypes)
+        addEntries("unused namespace member", issue.namespaceMembers)
+        addEntries("unused enum member", issue.enumMembers)
+        addEntries("unlisted binary", issue.binaries)
+        addEntries("duplicate export", issue.duplicates)
+        addEntries("circular dependency", issue.cycles)
+        addEntries("unused file", issue.files)
+      }
+
+      if (details.length === 0) {
+        return { outcome: "pass", rationale: "Knip reported 0 issues." }
+      }
+
+      return {
+        outcome: "fail",
+        rationale: [
+          `Knip reported ${String(details.length)} issue(s):`,
+          ...details.map((detail: string) => `- ${detail}`),
+        ].join("\n"),
+      }
+    },
+  }
+}

package/src/presets/duplication.ts

@@ -0,0 +1,137 @@
+import { readFile } from "node:fs/promises"
+import type { CheckDefinitionConfig } from "../types.js"
+import { checkDependencyInstalled } from "./shared/missing-dependency.js"
+import { readJsonReport } from "./shared/read-json-report.js"
+import { checkTerminatedAbnormally } from "./shared/terminal-status.js"
+
+interface JscpdFileSpan {
+  readonly name: string
+  readonly start: number
+  readonly end: number
+}
+
+interface JscpdDuplicate {
+  readonly format: string
+  readonly lines: number
+  readonly tokens: number
+  readonly firstFile: JscpdFileSpan
+  readonly secondFile: JscpdFileSpan
+}
+
+interface JscpdStatisticsTotal {
+  readonly clones: number
+  readonly duplicatedLines: number
+  readonly lines: number
+  readonly percentage: number
+  readonly sources: number
+}
+
+interface JscpdReport {
+  readonly duplicates?: readonly JscpdDuplicate[]
+  readonly statistics?: {
+    readonly total?: JscpdStatisticsTotal
+  }
+}
+
+/** Options accepted by {@link duplication}. */
+interface DuplicationOptions {
+  /** Directory to scan for duplicated code, passed straight through to jscpd as its positional target. Defaults to `"."` -- narrow it (e.g. `"src"`) to scope the scan to your own source tree. */
+  readonly path?: string
+}
+
+// Kept in lockstep with the `--output reports/jscpd` argument below. Both are
+// relative and resolve against the *host* process's cwd, not the check's own
+// `cwd` option: jscpd writes here and this policy's `readFile` reads from here,
+// so a check configured with a different `cwd` would look in the wrong place.
+// This preset does not expose an output-path option -- a consumer needing one
+// runs jscpd via a custom `run`/`policy` instead.
+const REPORT_PATH = "reports/jscpd/jscpd-report.json"
+
+// jscpd's JSON reporter writes its report to disk -- it never prints JSON to
+// stdout, which instead carries decorative progress/summary text -- so the
+// report is read from disk directly. jscpd's own `--threshold`/`--exit-code`
+// flags are deliberately not used: this preset reads the raw clone count
+// from evidence and owns the pass/fail decision itself, exactly as the
+// deadCode/securityDeps presets already do for their own tools.
+/**
+ * Duplicated-code detection via jscpd.
+ * @param options - configuration for this check; see {@link DuplicationOptions}.
+ * @returns the configured check.
+ */
+export function duplication(options: DuplicationOptions = {}): CheckDefinitionConfig {
+  const { path = "." } = options
+
+  return {
+    run: ["jscpd", path, "--reporters", "json", "--output", "reports/jscpd", "--silent"],
+    policy: async ({ result }) => {
+      const missing = checkDependencyInstalled(result, "jscpd")
+      if (missing) return missing
+
+      const terminated = checkTerminatedAbnormally(result, "jscpd")
+      if (terminated) return terminated
+
+      const parsed = await readJsonReport<JscpdReport>(
+        // Provably equivalent, not a coverage gap: `JSON.parse` coerces
+        // whatever `readFile` returns via that value's own `toString()`
+        // (confirmed empirically for a Buffer, which is what a mutated/
+        // unrecognized encoding argument produces here) -- and `Buffer`'s
+        // default `toString()` encoding is itself utf8, so parsing succeeds
+        // identically either way. No test can observe a difference through
+        // this policy's output.
+        // Stryker disable next-line StringLiteral -- JSON.parse coerces via toString(), which defaults to utf8 for a Buffer, so parsing succeeds identically either way
+        () => readFile(REPORT_PATH, "utf8"),
+        "jscpd did not produce its expected JSON report.",
+        "jscpd produced invalid JSON evidence.",
+      )
+      if (!parsed.ok) return parsed.result
+      // `readJsonReport<T>` narrows only at the type level -- the value is `unknown` at
+      // runtime. Guard it is a real object before trusting the cast, so `.statistics` /
+      // `.duplicates` never throw a TypeError out of the policy (matching markdownlint.ts).
+      const value: unknown = parsed.value
+
+      if (typeof value !== "object" || value === null) {
+        return { outcome: "fail", rationale: "jscpd produced invalid JSON report data." }
+      }
+
+      const report = value as JscpdReport
+      const total = report.statistics?.total
+
+      if (
+        !Array.isArray(report.duplicates) ||
+        !total ||
+        typeof total.percentage !== "number" ||
+        !Number.isFinite(total.percentage)
+      ) {
+        // `total.percentage` feeds `.toFixed(2)` below -- a missing or non-finite
+        // value would throw or render "NaN" instead of failing cleanly.
+        return { outcome: "fail", rationale: "jscpd produced invalid JSON report data." }
+      }
+
+      // Re-annotated rather than used directly: `Array.isArray` narrows its
+      // argument to `any[]` regardless of the checked value's declared type (a
+      // long-standing TypeScript limitation), so `report.duplicates` would
+      // otherwise silently lose its `JscpdDuplicate` element type below.
+      const duplicates: readonly JscpdDuplicate[] = report.duplicates
+
+      if (duplicates.length === 0) {
+        return {
+          outcome: "pass",
+          rationale: `jscpd found 0 duplicated block(s) across ${String(total.sources)} file(s) (${String(total.lines)} lines).`,
+        }
+      }
+
+      const details = duplicates.map(
+        (duplicate) =>
+          `${duplicate.firstFile.name}:${String(duplicate.firstFile.start)} duplicates ${duplicate.secondFile.name}:${String(duplicate.secondFile.start)} -- ${String(duplicate.lines)} lines / ${String(duplicate.tokens)} tokens`,
+      )
+
+      return {
+        outcome: "fail",
+        rationale: [
+          `jscpd found ${String(duplicates.length)} duplicated block(s) (${total.percentage.toFixed(2)}% of ${String(total.lines)} lines across ${String(total.sources)} file(s)):`,
+          ...details.map((detail) => `- ${detail}`),
+        ].join("\n"),
+      }
+    },
+  }
+}

package/src/presets/e2e.ts

@@ -0,0 +1,144 @@
+import type { CheckDefinitionConfig } from "../types.js"
+import { checkDependencyInstalled } from "./shared/missing-dependency.js"
+import { checkTerminatedAbnormally } from "./shared/terminal-status.js"
+
+/**
+ * Playwright's own `--reporter=json` contract -- not published as a
+ * TypeScript type by the tool. Suites nest (a project, then a file, then
+ * `describe` blocks), so failing specs are collected recursively.
+ */
+interface PlaywrightTestResult {
+  readonly status?: string
+  readonly error?: { readonly message?: string }
+}
+
+interface PlaywrightTest {
+  readonly results?: readonly PlaywrightTestResult[]
+}
+
+interface PlaywrightSpec {
+  readonly title: string
+  readonly file?: string
+  readonly line?: number
+  readonly ok: boolean
+  readonly tests?: readonly PlaywrightTest[]
+}
+
+interface PlaywrightSuite {
+  readonly title: string
+  readonly specs?: readonly PlaywrightSpec[]
+  readonly suites?: readonly PlaywrightSuite[]
+}
+
+interface PlaywrightStats {
+  readonly expected: number
+  readonly unexpected: number
+  readonly flaky: number
+  readonly skipped: number
+}
+
+interface PlaywrightReport {
+  readonly suites?: readonly PlaywrightSuite[]
+  readonly stats?: PlaywrightStats
+}
+
+/**
+ * Recursively collects one human-readable line per failing spec across a (possibly nested) suite tree.
+ * @param suites - the suite tree to walk, as `PlaywrightReport.suites` or a suite's own nested `suites`.
+ * @returns one rendered `file:line title -- message` line per failing spec, depth-first.
+ */
+function collectFailingSpecs(suites: readonly PlaywrightSuite[]): string[] {
+  const details: string[] = []
+
+  for (const suite of suites) {
+    for (const spec of suite.specs ?? []) {
+      if (spec.ok) continue
+
+      const location = spec.line !== undefined ? `:${String(spec.line)}` : ""
+      // Provably equivalent, not a coverage gap: whatever non-array/non-test
+      // garbage a mutated `?? []` fallback substitutes here, every field
+      // access on it below (`.results`, `.error`, `.message`) resolves
+      // safely to `undefined` via its own optional chaining -- confirmed by
+      // hand-tracing both fallback sites -- converging on the exact same
+      // `message: undefined` this line already produces for a genuinely
+      // empty `spec.tests`/`t.results`. No test can observe a difference.
+      // Stryker disable next-line ArrayDeclaration -- any fallback garbage here resolves safely to undefined via optional chaining below, same as a genuinely empty array
+      const lastResult = (spec.tests ?? []).flatMap((t) => t.results ?? []).at(-1)
+      const message = lastResult?.error?.message?.trim()
+
+      details.push(
+        `${spec.file ?? suite.title}${location} ${spec.title}${message ? ` — ${message}` : ""}`,
+      )
+    }
+
+    if (suite.suites) details.push(...collectFailingSpecs(suite.suites))
+  }
+
+  return details
+}
+
+/** End-to-end test execution via Playwright, reading its JSON reporter output. */
+export const e2e: CheckDefinitionConfig = {
+  run: ["playwright", "test", "--reporter=json"],
+  output: { format: "json" },
+  policy: ({ result }) => {
+    const missing = checkDependencyInstalled(result, "@playwright/test")
+    if (missing) return missing
+
+    const terminated = checkTerminatedAbnormally(result, "Playwright")
+    if (terminated) return terminated
+
+    if (!result.output?.success) {
+      return { outcome: "fail", rationale: "Playwright output could not be parsed as JSON." }
+    }
+
+    // `output.success` only means `JSON.parse` didn't throw -- `value` is `unknown` at
+    // runtime. Guard it is a real object before trusting the cast, matching how
+    // dead-code.ts / duplication.ts guard theirs, so `.stats` never throws out of the policy.
+    const value: unknown = result.output.value
+
+    if (typeof value !== "object" || value === null) {
+      return { outcome: "fail", rationale: "Playwright produced invalid JSON report data." }
+    }
+
+    const report = value as PlaywrightReport
+    const stats = report.stats
+
+    if (!stats || typeof stats.unexpected !== "number" || typeof stats.flaky !== "number") {
+      // The outcome checks below compare `unexpected`/`flaky` numerically -- a
+      // missing or non-numeric counter must fail cleanly, not slip through every
+      // comparison as `false`.
+      return { outcome: "fail", rationale: "Playwright produced invalid JSON report data." }
+    }
+
+    if (stats.unexpected === 0 && stats.flaky === 0) {
+      return {
+        outcome: "pass",
+        rationale: `Playwright completed ${String(stats.expected)} test(s) with 0 unexpected failures.`,
+      }
+    }
+
+    if (stats.unexpected > 0) {
+      // Provably equivalent, not a coverage gap: collectFailingSpecs itself
+      // only ever reads `.specs`/`.suites` off each element via safe
+      // optional chaining (see its own comment), so substituting any
+      // non-suite garbage for a genuinely absent `report.suites` still
+      // yields zero collected detail lines either way.
+      // Stryker disable next-line ArrayDeclaration -- collectFailingSpecs only reads .specs/.suites via safe optional chaining, so fallback garbage yields zero details either way
+      const details = collectFailingSpecs(report.suites ?? [])
+
+      return {
+        outcome: "fail",
+        rationale: [
+          `Playwright reported ${String(stats.unexpected)} unexpected failure(s):`,
+          ...details.map((detail) => `- ${detail}`),
+        ].join("\n"),
+      }
+    }
+
+    return {
+      outcome: "warn",
+      rationale: `Playwright completed with ${String(stats.flaky)} flaky test(s) that eventually passed on retry.`,
+    }
+  },
+}

package/src/presets/format.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"
+
+/** Code formatting via Prettier, applied in place. */
+export const format: CheckDefinitionConfig = {
+  run: ["prettier", "--write", "."],
+  policy: ({ result }) => {
+    const missing = checkDependencyInstalled(result, "prettier")
+    if (missing) return missing
+
+    const terminated = checkTerminatedAbnormally(result, "Prettier")
+    if (terminated) return terminated
+
+    if (result.exitCode === 0) {
+      return { outcome: "pass", rationale: "Prettier reported no formatting failures." }
+    }
+
+    return {
+      outcome: "fail",
+      rationale: exitCodeFailRationale(result, "Prettier reported formatting failures"),
+    }
+  },
+}

package/src/presets/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Curated, growing catalog of preset checks for tools common across
+ * TypeScript/JavaScript repositories -- each preset encodes how to execute
+ * and interpret a common tool, never a repository's definition of quality
+ * (see specs/decisions/0004-public-surface-stays-narrow-no-cli-experimental-presets.md). Import a preset,
+ * spread it into your own `checks` record, and override whatever you need
+ * -- most often `policy`; a factory preset's options are the preferred way
+ * to change what it executes, a direct `run` override is an escape hatch.
+ * Never re-exported from the package root (`src/index.ts`) -- presets are
+ * an opt-in extra, not part of the core execution/evidence/policy surface
+ * those exports describe, and this barrel never re-exports anything from
+ * there either; the two stay independent.
+ * @packageDocumentation
+ */
+export { arethetypeswrong } from "./arethetypeswrong.js"
+export { brokenLinks } from "./broken-links.js"
+export { commitlint } from "./commitlint.js"
+export { deadCode } from "./dead-code.js"
+export { duplication } from "./duplication.js"
+export { e2e } from "./e2e.js"
+export { format } from "./format.js"
+export { license } from "./license.js"
+export { lint } from "./lint.js"
+export { markdownlint } from "./markdownlint.js"
+export { publint } from "./publint.js"
+export { securityDeps } from "./security-deps.js"
+export { securitySecrets } from "./security-secrets.js"
+export { stylelint } from "./stylelint.js"
+export { test } from "./test.js"
+export { typecheck } from "./typecheck.js"

package/src/presets/license.ts

@@ -0,0 +1,90 @@
+import type { CheckDefinitionConfig } from "../types.js"
+import { exitCodeFailRationale } from "./shared/exit-code-fail-rationale.js"
+import { checkDependencyInstalled } from "./shared/missing-dependency.js"
+import { checkTerminatedAbnormally } from "./shared/terminal-status.js"
+
+interface LicenseeEntry {
+  readonly name: string
+  readonly version: string
+  readonly license?: string
+}
+
+// `--production` scopes evaluation to the dependency graph actually shipped
+// to consumers -- devDependencies never end up in a consumer's install, so
+// their licenses carry no obligation onto this package's own license. Same
+// runtime-only rationale the securityDeps preset already applies to `npm
+// audit --omit=dev`. `--osi` treats Open Source Initiative approval as the
+// approval criterion rather than a repository-maintained SPDX allowlist --
+// the same "policy is repository policy, not a repo-contract opinion"
+// stance securityDeps documents, just resolved to the broadest
+// widely-recognized standard instead of a bespoke list. `--errors-only`
+// keeps the ndjson evidence limited to the packages actually driving the
+// verdict, matching the deadCode/duplication presets' report-issues-only
+// shape.
+/** Dependency license compliance via licensee. */
+export const license: CheckDefinitionConfig = {
+  run: ["licensee", "--production", "--osi", "--errors-only", "--ndjson"],
+  policy: ({ result }) => {
+    const missing = checkDependencyInstalled(result, "licensee")
+    if (missing) return missing
+
+    const terminated = checkTerminatedAbnormally(result, "licensee")
+    if (terminated) return terminated
+
+    const trimmed = result.stdout.trim()
+
+    // `--errors-only` makes licensee exit non-zero *because* it found an
+    // offending dependency -- so a non-zero exit with ndjson on stdout is the
+    // expected failure path, handled below. But a non-zero exit with *empty*
+    // stdout means licensee never evaluated anything (node_modules not
+    // installed, an unreadable dependency tree, an internal `die()`): the
+    // error is on stderr and there is nothing to parse. Treating that as
+    // "found 0 offending dependencies" would let the compliance gate pass on
+    // a run that never actually ran. Only an empty stdout from a process that
+    // exited cleanly on its own is a genuine "nothing offending" pass.
+    if (trimmed.length === 0) {
+      if (result.status === "completed" && result.exitCode === 0) {
+        return {
+          outcome: "pass",
+          rationale: "licensee found 0 production dependencies with a non-OSI-approved license.",
+        }
+      }
+
+      return {
+        outcome: "fail",
+        rationale: exitCodeFailRationale(
+          result,
+          "licensee did not evaluate any dependency licenses (it produced no output)",
+        ),
+      }
+    }
+
+    let entries: readonly LicenseeEntry[]
+
+    try {
+      entries = trimmed
+        .split("\n")
+        // licensee emits one JSON object per line; a blank line between
+        // records (some versions/locales do this, as can a leading
+        // informational line) is not invalid evidence -- skip it rather than
+        // feeding "" to JSON.parse and discarding the real violation list.
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => JSON.parse(line) as LicenseeEntry)
+    } catch {
+      return { outcome: "fail", rationale: "licensee produced invalid JSON evidence." }
+    }
+
+    const details = entries
+      .map((entry) => `${entry.name}@${entry.version}: ${entry.license ?? "unknown license"}`)
+      .sort()
+
+    return {
+      outcome: "fail",
+      rationale: [
+        `licensee found ${String(details.length)} production dependency(ies) without an OSI-approved license:`,
+        ...details.map((detail) => `- ${detail}`),
+      ].join("\n"),
+    }
+  },
+}