repo-contract 0.1.0

package/src/presets/lint.ts

@@ -0,0 +1,116 @@
+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"
+
+/**
+ * ESLint does not expose its JSON formatter result as a public LintResult
+ * export -- these types describe the JSON formatter contract rather than
+ * ESLint's internal Linter types.
+ */
+interface EslintMessage {
+  readonly ruleId: string | null
+  readonly severity: 0 | 1 | 2
+  readonly message: string
+  readonly line: number
+  readonly column: number
+}
+
+interface EslintResult {
+  readonly filePath: string
+  readonly messages: readonly EslintMessage[]
+  readonly errorCount: number
+  readonly warningCount: number
+}
+
+/** Options accepted by {@link lint}. */
+interface LintOptions {
+  /** Path (or glob) passed straight through to ESLint as its positional target. Defaults to `"."` -- narrow it (e.g. `"src"`) to scope linting to your own source tree. */
+  readonly path?: string
+}
+
+/**
+ * Renders every message at the given severity across all files as one `file:line:column [rule]: message` line each.
+ * @param results - the full ESLint JSON formatter result to filter and render.
+ * @param severity - which severity to render (`2` for errors, `1` for warnings).
+ * @returns one rendered line per matching message, across every file.
+ */
+function renderMessages(results: readonly EslintResult[], severity: 1 | 2): string[] {
+  return results.flatMap((file: EslintResult): string[] =>
+    file.messages
+      .filter((message: EslintMessage) => message.severity === severity)
+      .map((message: EslintMessage) => {
+        const rule = message.ruleId ? ` [${message.ruleId}]` : ""
+
+        return `${file.filePath}:${String(message.line)}:${String(message.column)}${rule}: ${message.message}`
+      }),
+  )
+}
+
+/**
+ * Static analysis via ESLint, using whatever `eslint.config.js` the
+ * consumer's own repository already has -- this preset makes no assumption
+ * about rule configuration, only about how to run the tool and interpret
+ * its JSON output. Severity `2` (error) blocks; severity `1` (warning) is
+ * reported but never blocks -- ESLint's own severities already encode that
+ * distinction, so this preset just respects it rather than treating every
+ * finding as equally blocking.
+ * @param options - configuration for this check; see {@link LintOptions}.
+ * @returns the configured check.
+ */
+export function lint(options: LintOptions = {}): CheckDefinitionConfig {
+  const { path = "." } = options
+
+  return {
+    run: ["eslint", path, "--format", "json"],
+    output: { format: "json" },
+    policy: ({ result }) => {
+      const missing = checkDependencyInstalled(result, "eslint")
+      if (missing) return missing
+
+      const terminated = checkTerminatedAbnormally(result, "ESLint")
+      if (terminated) return terminated
+
+      if (!result.output?.success) {
+        // ESLint exits non-zero with no JSON on stdout both for a flat-config
+        // load error and for a glob that matched no lintable files. Surface
+        // whatever it printed so the consumer sees the real cause instead of
+        // only "could not be parsed as JSON".
+        const printed = combinedOutput(result)
+
+        return {
+          outcome: "fail",
+          rationale:
+            printed.length > 0
+              ? `ESLint output could not be parsed as JSON. ESLint printed:\n${printed}`
+              : "ESLint output could not be parsed as JSON.",
+        }
+      }
+
+      // Valid JSON of an unexpected shape (an ESLint formatter change, a
+      // primitive, an entry without a `messages` array) must fail cleanly, not
+      // throw a TypeError out of `renderMessages` -- matching the other JSON
+      // presets' guards.
+      const value: unknown = result.output.value
+      if (
+        !Array.isArray(value) ||
+        !value.every(
+          (file): file is EslintResult =>
+            typeof file === "object" &&
+            file !== null &&
+            Array.isArray((file as { messages?: unknown }).messages),
+        )
+      ) {
+        return { outcome: "fail", rationale: "ESLint output could not be parsed as JSON." }
+      }
+
+      const results: readonly EslintResult[] = value
+
+      const errorDetails = renderMessages(results, 2)
+      const warningDetails = renderMessages(results, 1)
+
+      return errorWarningPassPolicy("ESLint", errorDetails, warningDetails)
+    },
+  }
+}

package/src/presets/markdownlint.ts

@@ -0,0 +1,105 @@
+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"
+
+/**
+ * markdownlint-cli2 has no stdout JSON mode -- this describes its own JSON
+ * output-formatter contract (markdownlint-cli2-formatter-json), read back
+ * from disk. Not published as a TypeScript type by either package.
+ */
+interface MarkdownlintFinding {
+  readonly fileName: string
+  readonly lineNumber: number
+  readonly ruleNames: readonly string[]
+  readonly ruleDescription: string
+  readonly errorDetail: string | null
+  readonly severity: "error" | "warning"
+}
+
+/** Options accepted by {@link markdownlint}. */
+interface MarkdownlintOptions {
+  /** Glob passed straight through to markdownlint-cli2 as its positional target. Defaults to `"**\/*.md"`. */
+  readonly glob?: string
+}
+
+const REPORT_PATH = "reports/markdownlint.json"
+
+/**
+ * @param finding One markdownlint-cli2 finding.
+ * @returns A single-line `file:line [rule]: description (detail)` summary.
+ */
+function formatFinding(finding: MarkdownlintFinding): string {
+  const rule = finding.ruleNames.join("/")
+  const detail = finding.errorDetail ? ` (${finding.errorDetail})` : ""
+
+  return `${finding.fileName}:${String(finding.lineNumber)} [${rule}]: ${finding.ruleDescription}${detail}`
+}
+
+/**
+ * Markdown structure/style lint via markdownlint-cli2. Unlike this
+ * package's other file-based-report presets, the report path is
+ * config-driven rather than a CLI flag -- markdownlint-cli2 only writes
+ * JSON when its own config file requests it. This preset assumes the
+ * consumer's `.markdownlint-cli2.jsonc` includes:
+ * ```jsonc
+ * "outputFormatters": [["markdownlint-cli2-formatter-json", { "name": "reports/markdownlint.json" }]]
+ * ```
+ * which also requires the `markdownlint-cli2-formatter-json` package
+ * alongside `markdownlint-cli2` itself.
+ * @param options - configuration for this check; see {@link MarkdownlintOptions}.
+ * @returns the configured check.
+ */
+export function markdownlint(options: MarkdownlintOptions = {}): CheckDefinitionConfig {
+  const { glob = "**/*.md" } = options
+
+  return {
+    run: ["markdownlint-cli2", glob],
+    policy: async ({ result }) => {
+      const missing = checkDependencyInstalled(result, "markdownlint-cli2")
+      if (missing) return missing
+
+      const terminated = checkTerminatedAbnormally(result, "markdownlint-cli2")
+      if (terminated) return terminated
+
+      const parsed = await readJsonReport<readonly MarkdownlintFinding[]>(
+        // Provably equivalent, not a coverage gap -- see the identical
+        // comment in src/presets/duplication.ts for why.
+        // 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"),
+        "markdownlint-cli2 did not produce its expected JSON report -- confirm your " +
+          ".markdownlint-cli2.jsonc configures outputFormatters to write " +
+          `"${REPORT_PATH}" (requires the markdownlint-cli2-formatter-json package).`,
+        "markdownlint-cli2 produced invalid JSON evidence.",
+      )
+      if (!parsed.ok) return parsed.result
+
+      // `readJsonReport<T>` narrows only at the type level -- the parsed
+      // value is `unknown` at runtime. Valid JSON that isn't an array (an
+      // object from a different/older formatter, `null`) must fail cleanly
+      // rather than throw `.length`/`.map` out of the policy and crash the
+      // run, matching duplication.ts's `Array.isArray` guard.
+      if (!Array.isArray(parsed.value)) {
+        return {
+          outcome: "fail",
+          rationale: "markdownlint-cli2 produced invalid JSON report data.",
+        }
+      }
+
+      const findings: readonly MarkdownlintFinding[] = parsed.value
+
+      if (findings.length === 0) {
+        return { outcome: "pass", rationale: "markdownlint-cli2 reported 0 issues." }
+      }
+
+      return {
+        outcome: "fail",
+        rationale: [
+          `markdownlint-cli2 reported ${String(findings.length)} issue(s):`,
+          ...findings.map((finding) => `- ${formatFinding(finding)}`),
+        ].join("\n"),
+      }
+    },
+  }
+}

package/src/presets/publint.ts

@@ -0,0 +1,38 @@
+import type { CheckDefinitionConfig } from "../types.js"
+import { combinedOutput, exitCodeFailRationale } from "./shared/exit-code-fail-rationale.js"
+import { checkDependencyInstalled } from "./shared/missing-dependency.js"
+import { checkTerminatedAbnormally } from "./shared/terminal-status.js"
+
+/**
+ * publint has no machine-readable output mode -- only a plain-text CLI
+ * reporter (see its own `src/cli.js` `formatMessages`). Its process exit
+ * code reflects only 'error'-level findings; 'warning'/'suggestion'-level
+ * findings never affect it. This preset reads the same three section
+ * headers publint's own CLI writes ("Errors:", "Warnings:", "Suggestions:")
+ * to distinguish blocking findings from non-blocking ones, without
+ * depending on any per-message structure publint doesn't expose. Relevant
+ * only to repositories that publish an npm package.
+ */
+export const publint: CheckDefinitionConfig = {
+  run: ["publint", "run"],
+  policy: ({ result }) => {
+    const missing = checkDependencyInstalled(result, "publint")
+    if (missing) return missing
+
+    const terminated = checkTerminatedAbnormally(result, "publint")
+    if (terminated) return terminated
+
+    const output = combinedOutput(result)
+
+    if (result.exitCode === 0) {
+      return output.includes("Warnings:") || output.includes("Suggestions:")
+        ? { outcome: "warn", rationale: `publint reported non-blocking finding(s):\n${output}` }
+        : { outcome: "pass", rationale: "publint reported no packaging errors." }
+    }
+
+    return {
+      outcome: "fail",
+      rationale: exitCodeFailRationale(result, "publint reported packaging error(s)"),
+    }
+  },
+}

package/src/presets/security-deps.ts

@@ -0,0 +1,142 @@
+import type { CheckDefinitionConfig } from "../types.js"
+import { checkTerminatedAbnormally } from "./shared/terminal-status.js"
+
+interface NpmAuditVulnerabilityCounts {
+  readonly info: number
+  readonly low: number
+  readonly moderate: number
+  readonly high: number
+  readonly critical: number
+}
+
+interface NpmAuditAdvisory {
+  readonly severity?: string
+  readonly range?: string
+  readonly isDirect?: boolean
+  readonly via?: readonly unknown[]
+  readonly fixAvailable?:
+    | boolean
+    | {
+        readonly name?: string
+        readonly version?: string
+        readonly isSemVerMajor?: boolean
+      }
+}
+
+interface NpmAuditReport {
+  readonly auditReportVersion?: number
+  readonly vulnerabilities?: Record<string, NpmAuditAdvisory>
+  readonly metadata?: {
+    readonly vulnerabilities?: NpmAuditVulnerabilityCounts
+  }
+}
+
+// --omit=dev evaluates only the dependency graph shipped to consumers.
+// Development dependency vulnerabilities remain evidence but do not block
+// this runtime security contract. The blocking threshold is repository
+// policy rather than an opinion imposed by repo-contract.
+//
+// No missing-dependency check here (see shared/missing-dependency.ts's own
+// doc comment): this preset shells out to `npm` itself, which cannot be
+// "missing" in any environment capable of running `npm run <script>` at
+// all -- the exception is intentional, not an oversight.
+/** Dependency vulnerability scanning via `npm audit`. */
+export const securityDeps: CheckDefinitionConfig = {
+  run: ["npm", "audit", "--omit=dev", "--json"],
+  output: { format: "json" },
+  policy: ({ result }) => {
+    const terminated = checkTerminatedAbnormally(result, "npm audit")
+    if (terminated) return terminated
+
+    if (!result.output?.success) {
+      return { outcome: "fail", rationale: "npm audit output could not be parsed as JSON." }
+    }
+
+    // `output.success` only means `JSON.parse` didn't throw -- valid JSON of an
+    // unexpected shape (`null`, a primitive) must fail cleanly, not throw
+    // `.metadata` out of the policy.
+    const value: unknown = result.output.value
+    if (typeof value !== "object" || value === null) {
+      return { outcome: "fail", rationale: "npm audit produced invalid JSON report data." }
+    }
+
+    const report = value as NpmAuditReport
+    const vulnerabilities = report.metadata?.vulnerabilities
+
+    if (!vulnerabilities) {
+      return {
+        outcome: "fail",
+        rationale: "npm audit produced no vulnerability summary.",
+      }
+    }
+
+    // Every count is cast from untrusted parsed JSON. A proxy registry, a
+    // future npm format, or a truncated report can omit a severity field --
+    // `undefined + n` is `NaN`, and both `NaN > 0` and `undefined > 0` are
+    // false, which would silently turn real reported vulnerabilities into a
+    // "0 of everything" pass. Require every severity count to be a finite
+    // number before trusting the summary at all.
+    const severities = ["info", "low", "moderate", "high", "critical"] as const
+    const missingCount = severities.find((severity) => !Number.isFinite(vulnerabilities[severity]))
+
+    if (missingCount !== undefined) {
+      return {
+        outcome: "fail",
+        rationale: `npm audit's vulnerability summary is missing a numeric "${missingCount}" count -- the report could not be evaluated.`,
+      }
+    }
+
+    const blocking =
+      vulnerabilities.low +
+      vulnerabilities.moderate +
+      vulnerabilities.high +
+      vulnerabilities.critical
+
+    if (blocking > 0) {
+      const details = Object.entries(report.vulnerabilities ?? {})
+        .map(([name, vulnerability]: [string, NpmAuditAdvisory]) => {
+          const severity = vulnerability.severity ?? "unknown"
+
+          const dependencyType = vulnerability.isDirect === true ? "direct" : "transitive"
+
+          const range = vulnerability.range ? ` range=${vulnerability.range}` : ""
+
+          const fix =
+            vulnerability.fixAvailable === true
+              ? " fix available"
+              : vulnerability.fixAvailable
+                ? " remediation available"
+                : " no automatic fix available"
+
+          return `${name}: ${severity} (${dependencyType})${range};${fix}`
+        })
+        .sort()
+
+      return {
+        outcome: "fail",
+        rationale: [
+          `npm audit found ${String(blocking)} runtime vulnerability(ies):`,
+          ...details.map((detail: string) => `- ${detail}`),
+        ].join("\n"),
+      }
+    }
+
+    // `info`-severity findings are excluded from the blocking count above
+    // (they were never part of this policy's pass/fail contract), but a pass
+    // built on top of some unresolved info-level findings is still worth
+    // surfacing explicitly rather than silently folding into an unqualified
+    // pass.
+    if (vulnerabilities.info > 0) {
+      return {
+        outcome: "warn",
+        rationale: `Runtime dependency policy passed. 0 critical, 0 high, 0 moderate, and 0 low vulnerabilities were found. ${String(vulnerabilities.info)} info-severity finding(s) remain and are non-blocking under repository policy.`,
+      }
+    }
+
+    return {
+      outcome: "pass",
+      rationale:
+        "Runtime dependency policy passed. 0 critical, 0 high, 0 moderate, and 0 low vulnerabilities were found.",
+    }
+  },
+}

package/src/presets/security-secrets.ts

@@ -0,0 +1,93 @@
+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 SecretlintMessage {
+  readonly message: string
+  readonly line: number
+  readonly column: number
+  readonly ruleId?: string
+  readonly severity?: number
+}
+
+interface SecretlintResult {
+  readonly filePath: string
+  readonly messages: readonly SecretlintMessage[]
+}
+
+// Secret values are deliberately excluded from the policy output. The
+// location and rule identify the remediation target without turning the
+// contract result itself into another secret-disclosure channel. Requires
+// the consumer's own secretlint config (secretlint has no built-in rules).
+/** Secret-leak scanning via secretlint. */
+export const securitySecrets: CheckDefinitionConfig = {
+  run: ["secretlint", "--format", "json", "--output", "reports/secretlint.json", "**/*"],
+  policy: async ({ result }) => {
+    const missing = checkDependencyInstalled(result, "secretlint")
+    if (missing) return missing
+
+    const terminated = checkTerminatedAbnormally(result, "Secretlint")
+    if (terminated) return terminated
+
+    const parsed = await readJsonReport<readonly SecretlintResult[]>(
+      // Provably equivalent, not a coverage gap -- see the identical
+      // comment in src/presets/duplication.ts for why.
+      // Stryker disable next-line StringLiteral -- JSON.parse coerces via toString(), which defaults to utf8 for a Buffer, so parsing succeeds identically either way
+      () => readFile("reports/secretlint.json", "utf8"),
+      "Secretlint did not produce its expected JSON report.",
+      "Secretlint produced invalid JSON evidence.",
+    )
+    if (!parsed.ok) return parsed.result
+
+    // `readJsonReport<T>` narrows only at the type level; valid JSON that
+    // isn't an array must fail cleanly rather than throw `.flatMap` out of
+    // the policy and crash the run.
+    if (!Array.isArray(parsed.value)) {
+      return { outcome: "fail", rationale: "Secretlint produced invalid JSON report data." }
+    }
+
+    const results: readonly SecretlintResult[] = parsed.value
+
+    const findings = results.flatMap((file: unknown) => {
+      // A single malformed array element (not an object, or missing its
+      // `messages` array) must not throw `.map` out of the policy -- skip it,
+      // exactly as the top-level non-array guard fails cleanly.
+      if (
+        typeof file !== "object" ||
+        file === null ||
+        !Array.isArray((file as { messages?: unknown }).messages)
+      ) {
+        return []
+      }
+
+      const typedFile = file as SecretlintResult
+      return typedFile.messages.map((message: SecretlintMessage) => ({
+        file: typedFile.filePath,
+        line: message.line,
+        column: message.column,
+        ruleId: message.ruleId,
+      }))
+    })
+
+    if (findings.length === 0) {
+      return { outcome: "pass", rationale: "Secretlint found 0 potential secrets." }
+    }
+
+    const details = findings.map((finding) => {
+      const rule = finding.ruleId ? ` [${finding.ruleId}]` : ""
+
+      return `${finding.file}:${String(finding.line)}:${String(finding.column)}${rule}`
+    })
+
+    return {
+      outcome: "fail",
+      rationale: [
+        `Secretlint found ${String(findings.length)} potential secret(s):`,
+        ...details.map((detail: string) => `- ${detail}`),
+        "Potential secret values are intentionally omitted. Remove the secret, replace it with an appropriate secret-management mechanism, and rotate any credential that may already have been exposed.",
+      ].join("\n"),
+    }
+  },
+}

package/src/presets/shared/error-warning-pass-policy.ts

@@ -0,0 +1,39 @@
+import type { PolicyResult } from "../../types.js"
+
+/**
+ * The shared three-branch shape behind every lint-style preset's pass/warn/fail decision: fail,
+ * listing every error, if there are any; else warn, listing every warning, if there are any; else
+ * pass -- shared by `lint` (ESLint) and `stylelint`, whose only difference was the tool name
+ * substituted into each rationale string.
+ * @param toolName - the tool's own display name, substituted into every rationale (e.g. "ESLint", "stylelint").
+ * @param errorDetails - one rendered line per error-severity finding.
+ * @param warningDetails - one rendered line per warning-severity finding.
+ * @returns the fail/warn/pass `PolicyResult`.
+ */
+export function errorWarningPassPolicy(
+  toolName: string,
+  errorDetails: readonly string[],
+  warningDetails: readonly string[],
+): PolicyResult {
+  if (errorDetails.length > 0) {
+    return {
+      outcome: "fail",
+      rationale: [
+        `${toolName} reported ${String(errorDetails.length)} error(s):`,
+        ...errorDetails.map((detail) => `- ${detail}`),
+      ].join("\n"),
+    }
+  }
+
+  if (warningDetails.length > 0) {
+    return {
+      outcome: "warn",
+      rationale: [
+        `${toolName} reported 0 errors but ${String(warningDetails.length)} warning(s):`,
+        ...warningDetails.map((detail) => `- ${detail}`),
+      ].join("\n"),
+    }
+  }
+
+  return { outcome: "pass", rationale: `${toolName} reported 0 errors and 0 warnings.` }
+}

package/src/presets/shared/exit-code-fail-rationale.ts

@@ -0,0 +1,34 @@
+import type { CheckEvidence } from "../../types.js"
+
+/**
+ * A check's captured stdout and stderr, trimmed and joined into one block -- either stream may be
+ * empty and is dropped rather than contributing a blank line. Shared by `exitCodeFailRationale`
+ * below and by `publint` (which needs the combined text itself, not just a rendered failure
+ * message, to detect its own "Warnings:"/"Suggestions:" section headers).
+ * @param result - the check's execution evidence (only `stdout`/`stderr` are read).
+ * @returns the combined, trimmed stdout+stderr text, or `""` if the tool produced neither.
+ */
+export function combinedOutput(result: CheckEvidence): string {
+  return [result.stdout.trim(), result.stderr.trim()]
+    .filter((value): value is string => Boolean(value))
+    .join("\n")
+}
+
+/**
+ * Shared by every preset whose policy is a plain "exitCode 0 = pass, else
+ * render captured stdout/stderr (or fall back to an exit-code-only message
+ * if the tool produced neither)" -- `format`, `typecheck`, `commitlint`.
+ * Each preset still owns its own pass rationale and its own description of
+ * what failed; this only renders the shared "here's what the tool printed"
+ * half.
+ * @param result - the check's execution evidence (only `stdout`/`stderr`/`exitCode` are read).
+ * @param description - a present-tense description of the failure, e.g. "Prettier reported formatting failures".
+ * @returns `"{description}:\n{output}"` when the tool produced output, or `"{description} (exit code {N})."` otherwise.
+ */
+export function exitCodeFailRationale(result: CheckEvidence, description: string): string {
+  const output = combinedOutput(result)
+
+  return output.length > 0
+    ? `${description}:\n${output}`
+    : `${description} (exit code ${String(result.exitCode)}).`
+}

package/src/presets/shared/missing-dependency.ts

@@ -0,0 +1,31 @@
+import type { CheckEvidence, PolicyResult } from "../../types.js"
+
+/**
+ * Every preset in `src/presets/*.ts` (except `securityDeps`, which shells out
+ * to `npm` itself -- something that cannot be "missing" in any environment
+ * capable of running `npm run <script>` at all) calls this first, before its
+ * own pass/fail/warn logic. `CheckEvidence.status === "spawn_error"` already
+ * distinguishes "the OS couldn't even launch the executable" from "the tool
+ * ran and exited non-zero" -- but not every spawn failure means the package
+ * is missing (a permission error or an invalid executable format lands here
+ * too), so this checks the structured `spawnErrorCode` for `"ENOENT"`
+ * specifically rather than treating every spawn error as "not installed."
+ * A non-ENOENT spawn error falls through to the preset's normal handling,
+ * unchanged, rather than getting a misleading "not installed" message.
+ * @param result - the check's raw execution evidence to inspect.
+ * @param packageName - the npm package a consumer would install to fix this (may differ from the binary name, e.g. `tsc` comes from `typescript`).
+ * @returns an actionable, package-manager-neutral `PolicyResult` if the tool appears to be missing, or `undefined` if the caller should proceed with its own interpretation.
+ */
+export function checkDependencyInstalled(
+  result: CheckEvidence,
+  packageName: string,
+): PolicyResult | undefined {
+  if (result.status !== "spawn_error" || result.spawnErrorCode !== "ENOENT") {
+    return undefined
+  }
+
+  return {
+    outcome: "fail",
+    rationale: `\`${packageName}\` is required by this preset but was not found. Install \`${packageName}\` as a development dependency and run the contract again.`,
+  }
+}

package/src/presets/shared/read-json-report.ts

@@ -0,0 +1,46 @@
+import type { PolicyResult } from "../../types.js"
+
+/** The report, already JSON-parsed and narrowed to `T`, or the fail `PolicyResult` to return verbatim when reading or parsing it failed. See `readJsonReport`. */
+type ReadJsonReportResult<T> =
+  { readonly ok: true; readonly value: T } | { readonly ok: false; readonly result: PolicyResult }
+
+/**
+ * Reads and JSON-parses a report a tool wrote to disk rather than printing to stdout -- the "read,
+ * fail with one rationale if the read itself fails, fail with a different rationale if the JSON is
+ * invalid" shape shared by every preset whose tool has no stdout JSON mode (jscpd,
+ * markdownlint-cli2, secretlint). Each failure takes its own caller-supplied rationale rather than a
+ * generic shared message, since a missing report and invalid JSON usually point a consumer at a
+ * different fix (a misconfigured reporter/output flag vs. a genuinely broken tool run), and each
+ * tool's own advice differs (markdownlint's own read-failure rationale, for instance, names the
+ * specific config field to check).
+ *
+ * Takes the read itself as a thunk (`readRaw`), rather than a `path` this function reads from
+ * directly, so every call site's own `readFile(LITERAL_PATH, "utf8")` stays written as a literal
+ * argument in the caller's own file -- required by this repo's `security/detect-non-literal-fs-filename`
+ * policy, which forbids suppressing that rule outright (see policy-config.ts's `eslint.rules["security/*"]`)
+ * and would otherwise flag a `path: string` function parameter threaded into `readFile` here as
+ * non-literal.
+ * @param readRaw - reads the report's raw text (typically `() => readFile(REPORT_PATH, "utf8")`).
+ * @param onReadFailed - the rationale to fail with if `readRaw` rejects.
+ * @param onParseFailed - the rationale to fail with if the read text isn't valid JSON.
+ * @returns `{ ok: true, value }` with the parsed JSON narrowed to `T`, or `{ ok: false, result }` with the fail `PolicyResult` to return verbatim.
+ */
+export async function readJsonReport<T>(
+  readRaw: () => Promise<string>,
+  onReadFailed: string,
+  onParseFailed: string,
+): Promise<ReadJsonReportResult<T>> {
+  let raw: string
+
+  try {
+    raw = await readRaw()
+  } catch {
+    return { ok: false, result: { outcome: "fail", rationale: onReadFailed } }
+  }
+
+  try {
+    return { ok: true, value: JSON.parse(raw) as T }
+  } catch {
+    return { ok: false, result: { outcome: "fail", rationale: onParseFailed } }
+  }
+}