@deployanyway/ship-it-meter 0.4.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.0.0
+
+- Show Your Receipts: release policies from actual reports.
+- Typed API, CLI integration, runnable codebase example and meaningful workflow tests.
+- Stable contracts and migration guidance; original humor stays around accurate facts.
+
 ## 0.4.0
 
 Twelve named demonstration scenarios show passing evidence, Friday releases, missing evidence, failed builds, failing tests, low coverage, critical issues, lint failures, dirty worktrees, feature branches, zero tests and weekend incidents. These are examples, never evidence about your real project.

package/MIGRATION.md

@@ -9,3 +9,9 @@ Install 0.3.0 with npm. Seeds and exact humorous wording are version-specific. D
 12 discoverable evidence scenarios and releasePlan with ordered blocker/review/release tasks and observable completion criteria; API and CLI scenarios/plans; passing/blocked gate exit codes preserved.
 
 Existing defaults and entry points remain available. The new release plan and demonstration scenarios are opt-in; the original scoring and gate rules are retained.
+
+## 0.4.0 to stable 1.0.0
+
+Report APIs and CLI receipt mode are additive. Existing supplied-evidence scoring remains a heuristic and named scenarios remain examples. Use report policies for actual CI gating; do not confuse demonstration scenarios with measured artifacts.
+
+See README for exact contracts, bounds and failure behavior.

package/README.md

@@ -1,5 +1,55 @@
 # ship-it-meter
 
+## Show Your Receipts: release policies from actual reports (1.0.0)
+
+evaluateReports(bundle, policy) turns actual test, coverage and build receipts into a release gate and prioritized repair tasks. parseTestReport supports completed Node TAP v13 and Jest JSON. parseCoverageReport supports c8/Istanbul coverage-summary.json. Skipped/todo tests are excluded from executed evidence; failed/cancelled tests, unsuccessful Jest suites and collected-only/interrupted runs do not count as successful execution. Coverage counts must reconcile; empty lines/statements are not measured evidence.
+
+```js
+import { evaluateReports } from "@deployanyway/ship-it-meter";
+const result = evaluateReports(
+  {
+    commit: "abc123",
+    tests: {
+      commit: "abc123",
+      capturedAt: "2026-10-09T02:00:00Z",
+      format: "node-tap",
+      data: tapOutput,
+    },
+    coverage: {
+      commit: "abc123",
+      capturedAt: "2026-10-09T02:00:00Z",
+      format: "istanbul-summary",
+      data: coverageSummary,
+    },
+    build: {
+      commit: "abc123",
+      capturedAt: "2026-10-09T02:00:00Z",
+      exitCode: buildExitCode,
+    },
+  },
+  { minTests: 1, minCoverage: 80, minScore: 80, maxAgeMs: 3600000 },
+);
+if (!result.passed) console.error(result.blockers);
+```
+
+All three receipts are required, must identify the same nonempty bundle commit, and use valid UTC ISO capturedAt timestamps. Future/stale receipts block. Default policy: at least one executed test, all four coverage percentages >=80, passing build and score >=80, max age one hour. now can be supplied for deterministic evaluation. Unknown policy keys throw, so misspelled thresholds do not silently apply defaults. The policy is configurable; it does not alter your artifacts.
+
+Result adds evidence, receipts, commit, policy and evaluatedAt to a release plan. Each receipt exposes acceptance and issues; rejected receipts add blocker tasks with verification criteria. The final summary/passed value follows receipt blockers, even when the heuristic score looks good. Parse helpers throw on malformed reports; evaluateReports converts report problems into blockers. Invalid policy/bundle configuration throws.
+
+```sh
+ship-it-meter --report-file receipts.json --policy '{"minCoverage":90,"maxAgeMs":1800000}' --json
+cat receipts.json | ship-it-meter --reports --json
+node node_modules/@deployanyway/ship-it-meter/examples/report-gate.mjs receipts.json
+```
+
+Report CLI input is bounded to 10 MiB and exits 1 when blocked, 2 for invalid arguments/configuration. Receipt mode rejects manual evidence overrides and conflicting gate/scenario flags. The browser demo uses pure parsers; file reading and CI collection happen in Node. Metadata is a claim from your trusted pipeline, not a cryptographic attestation; do not relabel old reports or trust arbitrary submitted bundles. The gate neither runs your CI nor deploys anything. See examples/collect-receipts.mjs for collecting new Node test and c8 coverage reports together, followed by your actual npm build, inside an npm script. It requires c8 as a project dev dependency, Node-discoverable tests (or explicit test file arguments), npm run build, an unchanged Git commit and clean tracked source. Generated/untracked files must be excluded from your test configuration; receipt metadata remains a trusted pipeline claim.
+
+## Stable v1 contract
+
+Node 22.13+ or Node 24. MIT licensed. CLI flags, structured fields, ESM/CommonJS exports and declarations are covered by tests and installed-package checks. Existing 0.4 APIs remain available except the explicitly documented doggo-log redaction/text-context changes. Future incompatible public API changes require a major release; callers should consume structured fields rather than parse jokes. Exact humorous wording and seeded catalog choices are version-specific. No telemetry, external API keys or network service is needed for core use.
+
+Run npm test, npm run lint, npm run format:check, npm run coverage, npm run test:types and npm run verify:package from a source checkout. Runnable examples are shipped under examples/. The root demo is https://deployanyway.github.io/.
+
 ## Evidence into an actual release plan (0.4.0)
 
 Twelve named demonstration scenarios show passing evidence, Friday releases, missing evidence, failed builds, failing tests, low coverage, critical issues, lint failures, dirty worktrees, feature branches, zero tests and weekend incidents. These are examples, never evidence about your real project.

package/dist/index.cjs

@@ -20,6 +20,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.js
 var index_exports = {};
 __export(index_exports, {
+  evaluateReports: () => evaluateReports,
+  parseCoverageReport: () => parseCoverageReport,
+  parseTestReport: () => parseTestReport,
   preflight: () => preflight,
   releaseGate: () => releaseGate,
   releasePlan: () => releasePlan,
@@ -151,6 +154,214 @@ function scenarioEvidence(name) {
   return { ...scenarios[name].evidence };
 }
 
+// src/reports.js
+var object = (value, label) => {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new TypeError(`${label} must be an object.`);
+  return value;
+};
+var count = (value, label) => {
+  if (!Number.isSafeInteger(value) || value < 0)
+    throw new TypeError(`${label} must be a nonnegative safe integer.`);
+  return value;
+};
+var json = (value) => typeof value === "string" ? JSON.parse(value) : value;
+var date = (value, label) => {
+  if (typeof value !== "string" || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,3})?Z$/.test(value) || !Number.isFinite(Date.parse(value)) || new Date(value).toISOString().slice(0, 19) !== value.slice(0, 19))
+    throw new TypeError(`${label} must be a UTC ISO timestamp.`);
+  return Date.parse(value);
+};
+function parseTestReport(data, format = "node-tap") {
+  if (format === "node-tap") {
+    if (typeof data !== "string" || !data.startsWith("TAP version 13") || /^Bail out!/m.test(data))
+      throw new TypeError("Expected a completed Node TAP v13 report.");
+    const values = {};
+    for (const key of [
+      "tests",
+      "pass",
+      "fail",
+      "cancelled",
+      "skipped",
+      "todo"
+    ]) {
+      const matches = [
+        ...data.matchAll(new RegExp(`^# ${key} (\\d+)\\r?$`, "gm"))
+      ];
+      if (matches.length !== 1)
+        throw new TypeError(`TAP requires one ${key} summary.`);
+      values[key] = count(Number(matches[0][1]), key);
+    }
+    if (values.pass + values.fail + values.cancelled + values.skipped + values.todo !== values.tests)
+      throw new TypeError("TAP counts do not reconcile.");
+    return {
+      tests: values.tests - values.skipped - values.todo,
+      passedTests: values.pass,
+      failingTests: values.fail + values.cancelled,
+      skippedTests: values.skipped,
+      todoTests: values.todo,
+      successful: values.fail + values.cancelled === 0
+    };
+  }
+  if (format === "jest") {
+    const report = object(json(data), "Jest report");
+    const total = count(report.numTotalTests, "numTotalTests"), passed = count(report.numPassedTests, "numPassedTests"), failed = count(report.numFailedTests, "numFailedTests"), pending = count(report.numPendingTests, "numPendingTests"), todo = count(report.numTodoTests ?? 0, "numTodoTests");
+    if (total !== passed + failed + pending + todo || typeof report.success !== "boolean")
+      throw new TypeError("Jest counts/success do not reconcile.");
+    if (report.wasInterrupted || report.testResults?.some(
+      (result) => result.assertionResults?.some(
+        (assertion) => assertion.wouldRun === true
+      )
+    ))
+      throw new TypeError(
+        "Interrupted or collected-only Jest output is not executed evidence."
+      );
+    const failedSuites = count(
+      report.numFailedTestSuites ?? 0,
+      "numFailedTestSuites"
+    );
+    return {
+      tests: total - pending - todo,
+      passedTests: passed,
+      failingTests: failed,
+      skippedTests: pending,
+      todoTests: todo,
+      successful: report.success && failed === 0 && failedSuites === 0
+    };
+  }
+  throw new RangeError("Supported test formats: node-tap, jest.");
+}
+function parseCoverageReport(data) {
+  const total = object(
+    object(json(data), "Coverage report").total,
+    "Coverage total"
+  ), result = {};
+  for (const key of ["lines", "statements", "functions", "branches"]) {
+    const metric = object(total[key], `Coverage ${key}`), all = count(metric.total, `${key}.total`), covered = count(metric.covered, `${key}.covered`);
+    if (all === 0 && ["lines", "statements"].includes(key) || covered > all || typeof metric.pct !== "number" || !Number.isFinite(metric.pct) || metric.pct < 0 || metric.pct > 100)
+      throw new TypeError(
+        `Coverage ${key} must contain measured code and a percentage.`
+      );
+    const computed = all === 0 ? 100 : covered / all * 100;
+    if (Math.abs(computed - metric.pct) > 0.02)
+      throw new TypeError(`Coverage ${key} percentage disagrees with counts.`);
+    result[key] = metric.pct;
+  }
+  return result;
+}
+function evaluateReports(bundle, options = {}) {
+  object(bundle, "Report bundle");
+  object(options, "Policy");
+  for (const key of Object.keys(options))
+    if (!["minTests", "minCoverage", "minScore", "maxAgeMs", "now"].includes(key))
+      throw new TypeError(`Unknown policy option: ${key}.`);
+  if (typeof bundle.commit !== "string" || !bundle.commit.trim())
+    throw new TypeError("Report bundle requires a nonempty commit.");
+  const policy = {
+    minTests: 1,
+    minCoverage: 80,
+    minScore: 80,
+    maxAgeMs: 36e5,
+    ...options
+  };
+  for (const [key, value] of Object.entries({
+    minTests: 1,
+    minCoverage: 80,
+    minScore: 80,
+    maxAgeMs: 36e5
+  }))
+    if (policy[key] === void 0) policy[key] = value;
+  count(policy.minTests, "minTests");
+  if (policy.minTests < 1) throw new RangeError("minTests must be positive.");
+  for (const key of ["minCoverage", "minScore"])
+    if (typeof policy[key] !== "number" || !Number.isFinite(policy[key]) || policy[key] < 0 || policy[key] > 100)
+      throw new RangeError(`${key} must be from 0 to 100.`);
+  if (!Number.isSafeInteger(policy.maxAgeMs) || policy.maxAgeMs < 1)
+    throw new RangeError("maxAgeMs must be a positive safe integer.");
+  const now = options.now ?? (/* @__PURE__ */ new Date()).toISOString();
+  const nowMs = date(now, "now");
+  const evidence = {}, receipts = [], blockers = [];
+  for (const kind of ["tests", "coverage", "build"]) {
+    const issues = [], report = bundle[kind];
+    if (!report) {
+      issues.push(`${kind}: report is missing.`);
+    } else
+      try {
+        object(report, kind);
+        const captured = date(report.capturedAt, `${kind}.capturedAt`);
+        if (report.commit !== bundle.commit)
+          issues.push(`${kind}: commit does not match ${bundle.commit}.`);
+        if (captured > nowMs)
+          issues.push(`${kind}: timestamp is in the future.`);
+        if (nowMs - captured > policy.maxAgeMs)
+          issues.push(`${kind}: report is stale.`);
+        if (kind === "tests") {
+          if (!["node-tap", "jest"].includes(report.format))
+            throw new RangeError("Test format must be node-tap or jest.");
+          const parsed = parseTestReport(report.data, report.format);
+          evidence.tests = parsed.tests;
+          evidence.failingTests = parsed.failingTests;
+          if (!parsed.successful)
+            issues.push("tests: test execution was unsuccessful.");
+          if (parsed.tests < policy.minTests)
+            issues.push(
+              `tests: ${parsed.tests} executed tests is below ${policy.minTests}.`
+            );
+        } else if (kind === "coverage") {
+          if (report.format !== "istanbul-summary")
+            throw new RangeError("Coverage format must be istanbul-summary.");
+          const coverage = parseCoverageReport(report.data);
+          evidence.coverage = coverage.lines;
+          for (const [metric, value] of Object.entries(coverage))
+            if (value < policy.minCoverage)
+              issues.push(
+                `coverage: ${metric} ${value}% is below ${policy.minCoverage}%.`
+              );
+        } else {
+          count(report.exitCode, "build.exitCode");
+          evidence.build = report.exitCode === 0;
+          if (report.exitCode !== 0)
+            issues.push(`build: command exited ${report.exitCode}.`);
+        }
+      } catch (error) {
+        issues.push(`${kind}: ${error.message}`);
+      }
+    receipts.push({
+      kind,
+      format: kind === "build" ? "exit-code" : report?.format ?? "missing",
+      commit: typeof report?.commit === "string" ? report.commit : null,
+      capturedAt: typeof report?.capturedAt === "string" ? report.capturedAt : null,
+      accepted: issues.length === 0,
+      issues
+    });
+    blockers.push(...issues);
+  }
+  const plan = releasePlan(evidence, { minScore: policy.minScore });
+  const combined = [.../* @__PURE__ */ new Set([...blockers, ...plan.blockers])];
+  const receiptTasks = receipts.filter((item) => !item.accepted).map((item) => ({
+    id: "receipt-" + item.kind,
+    priority: "blocker",
+    title: "Repair " + item.kind + " evidence",
+    verify: `Generate a completed ${item.kind} report for ${bundle.commit} with a current UTC timestamp; resolve: ${item.issues.join(" ")}`
+  }));
+  return {
+    ...plan,
+    summary: combined.length ? "The receipts say stop. Confidence must wait." : plan.summary,
+    tasks: [...receiptTasks, ...plan.tasks],
+    passed: combined.length === 0,
+    blockers: combined,
+    evidence,
+    receipts,
+    commit: bundle.commit,
+    policy: {
+      minTests: policy.minTests,
+      minCoverage: policy.minCoverage,
+      minScore: policy.minScore,
+      maxAgeMs: policy.maxAgeMs
+    },
+    evaluatedAt: now
+  };
+}
+
 // src/index.js
 var days = [
   "monday",
@@ -408,6 +619,9 @@ function releasePlan(input = {}, options = {}) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  evaluateReports,
+  parseCoverageReport,
+  parseTestReport,
   preflight,
   releaseGate,
   releasePlan,

package/examples/basic.js

@@ -0,0 +1,12 @@
+import { shipIt } from "@deployanyway/ship-it-meter";
+
+console.log(
+  shipIt({
+    tests: 125,
+    failingTests: 2,
+    coverage: 82,
+    day: "Friday",
+    branch: "main",
+    build: true,
+  }),
+);

package/examples/collect-receipts.mjs

@@ -0,0 +1,85 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync, writeFileSync, mkdtempSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { evaluateReports } from "@deployanyway/ship-it-meter";
+// Configure in your project: "release:receipts": "node node_modules/@deployanyway/ship-it-meter/examples/collect-receipts.mjs"
+// Requires your project's c8 dev dependency, Node tests using Node test discovery, and npm run build.
+const run = (args) =>
+  spawnSync(process.execPath, args, {
+    encoding: "utf8",
+    maxBuffer: 10 * 1024 * 1024,
+  });
+const git = (args) => spawnSync("git", args, { encoding: "utf8" });
+let temp;
+try {
+  if (!process.env.npm_execpath)
+    throw new Error(
+      "Run through an npm script so the build uses the current npm CLI.",
+    );
+  const head = git(["rev-parse", "HEAD"]);
+  if (head.status !== 0)
+    throw new Error("Cannot identify the exact Git commit.");
+  const commit = head.stdout.trim();
+  const clean = () => {
+    const status = git(["status", "--porcelain", "--untracked-files=no"]);
+    if (status.status !== 0 || status.stdout.trim())
+      throw new Error(
+        "Tracked source changes must be committed before collecting receipts.",
+      );
+  };
+  clean();
+  temp = mkdtempSync(join(tmpdir(), "deployanyway-receipts-"));
+  const tests = run([
+    resolve("node_modules/c8/bin/c8.js"),
+    "--reporter=json-summary",
+    "--reports-dir",
+    temp,
+    "--temp-directory",
+    join(temp, "v8"),
+    process.execPath,
+    "--test",
+    "--test-reporter=tap",
+    ...process.argv.slice(2),
+  ]);
+  if (tests.error) throw tests.error;
+  const testTime = new Date().toISOString(),
+    coverage = JSON.parse(
+      readFileSync(join(temp, "coverage-summary.json"), "utf8"),
+    );
+  const build = run([process.env.npm_execpath, "run", "build"]);
+  if (build.error) throw build.error;
+  const after = git(["rev-parse", "HEAD"]);
+  if (after.status !== 0 || after.stdout.trim() !== commit)
+    throw new Error("Commit changed during collection.");
+  clean();
+  const bundle = {
+    commit,
+    tests: {
+      commit,
+      capturedAt: testTime,
+      format: "node-tap",
+      data: tests.stdout,
+    },
+    coverage: {
+      commit,
+      capturedAt: testTime,
+      format: "istanbul-summary",
+      data: coverage,
+    },
+    build: {
+      commit,
+      capturedAt: new Date().toISOString(),
+      exitCode: build.status,
+    },
+  };
+  writeFileSync("receipts.json", JSON.stringify(bundle, null, 2));
+  const result = evaluateReports(bundle);
+  console.log(JSON.stringify(result, null, 2));
+  process.exitCode = result.passed ? 0 : 1;
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 2;
+} finally {
+  if (temp) rmSync(temp, { recursive: true, force: true });
+}

package/examples/report-gate.mjs

@@ -0,0 +1,13 @@
+import { readFileSync } from "node:fs";
+import { evaluateReports } from "@deployanyway/ship-it-meter";
+try {
+  if (!process.argv[2]) throw new TypeError("Provide receipts.json.");
+  const result = evaluateReports(
+    JSON.parse(readFileSync(process.argv[2], "utf8")),
+  );
+  console.log(JSON.stringify(result, null, 2));
+  process.exitCode = result.passed ? 0 : 1;
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 2;
+}

package/index.d.cts

@@ -63,3 +63,55 @@ export function releasePlan(
   input?: Evidence,
   options?: { minScore?: number },
 ): ReleasePlan;
+export type TestReportFormat = "node-tap" | "jest";
+export interface TestReportSummary {
+  tests: number;
+  passedTests: number;
+  failingTests: number;
+  skippedTests: number;
+  todoTests: number;
+  successful: boolean;
+}
+export function parseTestReport(
+  data: unknown,
+  format?: TestReportFormat,
+): TestReportSummary;
+export function parseCoverageReport(
+  data: unknown,
+): Record<"lines" | "statements" | "functions" | "branches", number>;
+export interface ReportMetadata {
+  commit: string;
+  capturedAt: string;
+}
+export interface ReportBundle {
+  commit: string;
+  tests?: ReportMetadata & { format: TestReportFormat; data: unknown };
+  coverage?: ReportMetadata & { format: "istanbul-summary"; data: unknown };
+  build?: ReportMetadata & { exitCode: number };
+}
+export interface ReportPolicy {
+  minTests?: number;
+  minCoverage?: number;
+  minScore?: number;
+  maxAgeMs?: number;
+  now?: string;
+}
+export interface ReportReceipt {
+  kind: "tests" | "coverage" | "build";
+  format: string;
+  commit: string | null;
+  capturedAt: string | null;
+  accepted: boolean;
+  issues: string[];
+}
+export interface ReportEvaluation extends ReleasePlan {
+  evidence: Evidence;
+  receipts: ReportReceipt[];
+  commit: string;
+  policy: Required<Omit<ReportPolicy, "now">>;
+  evaluatedAt: string;
+}
+export function evaluateReports(
+  bundle: ReportBundle,
+  options?: ReportPolicy,
+): ReportEvaluation;

package/index.d.ts

@@ -63,3 +63,55 @@ export function releasePlan(
   input?: Evidence,
   options?: { minScore?: number },
 ): ReleasePlan;
+export type TestReportFormat = "node-tap" | "jest";
+export interface TestReportSummary {
+  tests: number;
+  passedTests: number;
+  failingTests: number;
+  skippedTests: number;
+  todoTests: number;
+  successful: boolean;
+}
+export function parseTestReport(
+  data: unknown,
+  format?: TestReportFormat,
+): TestReportSummary;
+export function parseCoverageReport(
+  data: unknown,
+): Record<"lines" | "statements" | "functions" | "branches", number>;
+export interface ReportMetadata {
+  commit: string;
+  capturedAt: string;
+}
+export interface ReportBundle {
+  commit: string;
+  tests?: ReportMetadata & { format: TestReportFormat; data: unknown };
+  coverage?: ReportMetadata & { format: "istanbul-summary"; data: unknown };
+  build?: ReportMetadata & { exitCode: number };
+}
+export interface ReportPolicy {
+  minTests?: number;
+  minCoverage?: number;
+  minScore?: number;
+  maxAgeMs?: number;
+  now?: string;
+}
+export interface ReportReceipt {
+  kind: "tests" | "coverage" | "build";
+  format: string;
+  commit: string | null;
+  capturedAt: string | null;
+  accepted: boolean;
+  issues: string[];
+}
+export interface ReportEvaluation extends ReleasePlan {
+  evidence: Evidence;
+  receipts: ReportReceipt[];
+  commit: string;
+  policy: Required<Omit<ReportPolicy, "now">>;
+  evaluatedAt: string;
+}
+export function evaluateReports(
+  bundle: ReportBundle,
+  options?: ReportPolicy,
+): ReportEvaluation;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deployanyway/ship-it-meter",
-  "version": "0.4.0",
-  "description": "Explainable deployment readiness scoring for tests, coverage, and builds. Turns questionable confidence into a number.",
+  "version": "1.0.0",
+  "description": "Report-backed release policies, prioritized plans and explainable readiness scores. Confidence is not a build artifact; bring your receipts.",
   "type": "module",
   "exports": {
     ".": {
@@ -27,7 +27,8 @@
     "dist",
     "index.d.ts",
     "index.d.cts",
-    "MIGRATION.md"
+    "MIGRATION.md",
+    "examples"
   ],
   "engines": {
     "node": ">=22.13"
@@ -75,7 +76,11 @@
     "scoring",
     "typescript",
     "humor",
-    "deployanyway"
+    "deployanyway",
+    "ci",
+    "release-policy",
+    "test-reports",
+    "istanbul"
   ],
   "main": "./dist/index.cjs",
   "types": "./index.d.ts",

package/src/cli.js

@@ -1,5 +1,5 @@
 import { parseArgs } from "node:util";
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { URL } from "node:url";
 import {
   shipIt,
@@ -8,6 +8,7 @@ import {
   releasePlan,
   releaseScenarios,
   scenarioEvidence,
+  evaluateReports,
 } from "./index.js";
 
 import { readStdin } from "./input.js";
@@ -19,6 +20,9 @@ try {
       version: { type: "boolean", short: "v" },
       json: { type: "boolean" },
       stdin: { type: "boolean" },
+      reports: { type: "boolean" },
+      "report-file": { type: "string" },
+      policy: { type: "string" },
       gate: { type: "boolean" },
       plan: { type: "boolean" },
       scenario: { type: "string" },
@@ -38,7 +42,7 @@ try {
   });
   if (values.help) {
     console.log(
-      "Usage: ship-it-meter [options]\n\nOptions:\n  --tests number    Total tests\n  --failing number  Failing tests\n  --coverage number Coverage percent\n  --build pass|fail Build result\n  --critical number Open critical issues\n  --lint number     Lint failures\n  --dirty           Uncommitted changes\n  --branch name     Branch name\n  --day weekday     Full weekday name\n  --scenario name   Explore a named evidence scenario\n  --list-scenarios  List sample scenarios\n  --plan            Gate plus prioritized tasks and verification criteria\n  --checklist       Actionable, mildly concerned preflight\n  --json            Structured output\n  -h, --help        Help\n  -v, --version     Version\n\n--stdin reads a JSON evidence object (256 KiB); explicit flags override it. --gate requires passing evidence; --min-score 80 selects its threshold. A blocked gate exits 1. Missing test, coverage, and build evidence reduces readiness.\nExit codes: 0 scored successfully; 2 invalid arguments.",
+      "Usage: ship-it-meter [options]\n\nOptions:\n  --reports         Read report bundle JSON from stdin (10 MiB)\n  --report-file path Read report bundle JSON file\n  --policy JSON      Receipt thresholds/freshness; receipt mode only\n  --tests number    Total tests\n  --failing number  Failing tests\n  --coverage number Coverage percent\n  --build pass|fail Build result\n  --critical number Open critical issues\n  --lint number     Lint failures\n  --dirty           Uncommitted changes\n  --branch name     Branch name\n  --day weekday     Full weekday name\n  --scenario name   Explore a named evidence scenario\n  --list-scenarios  List sample scenarios\n  --plan            Gate plus prioritized tasks and verification criteria\n  --checklist       Actionable, mildly concerned preflight\n  --json            Structured output\n  -h, --help        Help\n  -v, --version     Version\n\n--stdin reads a JSON evidence object (256 KiB); explicit flags override it. --gate requires passing evidence; --min-score 80 selects its threshold. A blocked gate exits 1. Missing test, coverage, and build evidence reduces readiness.\nExit codes: 0 scored successfully; 2 invalid arguments.",
     );
   } else if (values.version) {
     console.log(
@@ -52,6 +56,42 @@ try {
         .map((item) => item.name + " — " + item.description)
         .join("\n"),
     );
+  } else if (values.reports || values["report-file"] !== undefined) {
+    if (values.reports && values["report-file"] !== undefined)
+      throw new TypeError("Choose --reports stdin or --report-file.");
+    const allowed = new Set(["reports", "report-file", "policy", "json"]);
+    for (const [key, value] of Object.entries(values))
+      if (value !== undefined && !allowed.has(key))
+        throw new TypeError(`--${key} cannot combine with report evaluation.`);
+    if (
+      values["report-file"] !== undefined &&
+      statSync(values["report-file"]).size > 10485760
+    )
+      throw new RangeError("Report bundle exceeds 10 MiB.");
+    const text =
+      values["report-file"] !== undefined
+        ? readFileSync(values["report-file"], "utf8")
+        : await readStdin(process.stdin, 10485760);
+    if (Buffer.byteLength(text) > 10485760)
+      throw new RangeError("Report bundle exceeds 10 MiB.");
+    const policy = values.policy === undefined ? {} : JSON.parse(values.policy);
+    const result = evaluateReports(JSON.parse(text), policy);
+    if (!result.passed) process.exitCode = 1;
+    console.log(
+      values.json
+        ? JSON.stringify(result, null, 2)
+        : `Receipt gate: ${result.passed ? "PASS" : "BLOCKED"} for ${result.commit}\n` +
+            result.receipts
+              .map(
+                (item) =>
+                  `${item.kind}: ${item.accepted ? "accepted" : "rejected"}`,
+              )
+              .join("\n") +
+            "\n" +
+            result.blockers.map((item) => "- " + item).join("\n"),
+    );
+  } else if (values.policy !== undefined) {
+    throw new TypeError("--policy requires --reports or --report-file.");
   } else {
     const input = values.stdin
       ? JSON.parse(await readStdin())

package/src/index.js

@@ -297,3 +297,8 @@ export function releasePlan(input = {}, options = {}) {
   tasks.sort((a, b) => rank[a.priority] - rank[b.priority]);
   return { ...gate, summary: summaries[gate.verdict], tasks };
 }
+export {
+  parseTestReport,
+  parseCoverageReport,
+  evaluateReports,
+} from "./reports.js";

package/src/input.js

@@ -1,12 +1,19 @@
 /** Read bounded UTF-8 stdin without swallowing upstream failures. */
-export async function readStdin(stream = process.stdin) {
+export async function readStdin(stream = process.stdin, maxBytes = 262144) {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)
+    throw new RangeError("Input limit must be a positive safe integer.");
   if (stream.isTTY) throw new TypeError("Pipe or redirect input.");
   let size = 0;
   const chunks = [];
   for await (const chunk of stream) {
     const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
     size += buffer.length;
-    if (size > 262144) throw new RangeError("stdin exceeds 256 KiB.");
+    if (size > maxBytes)
+      throw new RangeError(
+        maxBytes === 262144
+          ? "stdin exceeds 256 KiB."
+          : `stdin exceeds ${maxBytes} bytes.`,
+      );
     chunks.push(buffer);
   }
   const text = Buffer.concat(chunks).toString("utf8").trim();

package/src/reports.js

@@ -0,0 +1,262 @@
+import { releasePlan } from "./index.js";
+const object = (value, label) => {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new TypeError(`${label} must be an object.`);
+  return value;
+};
+const count = (value, label) => {
+  if (!Number.isSafeInteger(value) || value < 0)
+    throw new TypeError(`${label} must be a nonnegative safe integer.`);
+  return value;
+};
+const json = (value) => (typeof value === "string" ? JSON.parse(value) : value);
+const date = (value, label) => {
+  if (
+    typeof value !== "string" ||
+    !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,3})?Z$/.test(value) ||
+    !Number.isFinite(Date.parse(value)) ||
+    new Date(value).toISOString().slice(0, 19) !== value.slice(0, 19)
+  )
+    throw new TypeError(`${label} must be a UTC ISO timestamp.`);
+  return Date.parse(value);
+};
+
+/** Parse completed Node TAP or Jest JSON test results; skipped/todo tests are not passing evidence. */
+export function parseTestReport(data, format = "node-tap") {
+  if (format === "node-tap") {
+    if (
+      typeof data !== "string" ||
+      !data.startsWith("TAP version 13") ||
+      /^Bail out!/m.test(data)
+    )
+      throw new TypeError("Expected a completed Node TAP v13 report.");
+    const values = {};
+    for (const key of [
+      "tests",
+      "pass",
+      "fail",
+      "cancelled",
+      "skipped",
+      "todo",
+    ]) {
+      const matches = [
+        ...data.matchAll(new RegExp(`^# ${key} (\\d+)\\r?$`, "gm")),
+      ];
+      if (matches.length !== 1)
+        throw new TypeError(`TAP requires one ${key} summary.`);
+      values[key] = count(Number(matches[0][1]), key);
+    }
+    if (
+      values.pass +
+        values.fail +
+        values.cancelled +
+        values.skipped +
+        values.todo !==
+      values.tests
+    )
+      throw new TypeError("TAP counts do not reconcile.");
+    return {
+      tests: values.tests - values.skipped - values.todo,
+      passedTests: values.pass,
+      failingTests: values.fail + values.cancelled,
+      skippedTests: values.skipped,
+      todoTests: values.todo,
+      successful: values.fail + values.cancelled === 0,
+    };
+  }
+  if (format === "jest") {
+    const report = object(json(data), "Jest report");
+    const total = count(report.numTotalTests, "numTotalTests"),
+      passed = count(report.numPassedTests, "numPassedTests"),
+      failed = count(report.numFailedTests, "numFailedTests"),
+      pending = count(report.numPendingTests, "numPendingTests"),
+      todo = count(report.numTodoTests ?? 0, "numTodoTests");
+    if (
+      total !== passed + failed + pending + todo ||
+      typeof report.success !== "boolean"
+    )
+      throw new TypeError("Jest counts/success do not reconcile.");
+    if (
+      report.wasInterrupted ||
+      report.testResults?.some((result) =>
+        result.assertionResults?.some(
+          (assertion) => assertion.wouldRun === true,
+        ),
+      )
+    )
+      throw new TypeError(
+        "Interrupted or collected-only Jest output is not executed evidence.",
+      );
+    const failedSuites = count(
+      report.numFailedTestSuites ?? 0,
+      "numFailedTestSuites",
+    );
+    return {
+      tests: total - pending - todo,
+      passedTests: passed,
+      failingTests: failed,
+      skippedTests: pending,
+      todoTests: todo,
+      successful: report.success && failed === 0 && failedSuites === 0,
+    };
+  }
+  throw new RangeError("Supported test formats: node-tap, jest.");
+}
+/** Read Istanbul/c8 coverage-summary.json. Empty instrumented code is not evidence. */
+export function parseCoverageReport(data) {
+  const total = object(
+      object(json(data), "Coverage report").total,
+      "Coverage total",
+    ),
+    result = {};
+  for (const key of ["lines", "statements", "functions", "branches"]) {
+    const metric = object(total[key], `Coverage ${key}`),
+      all = count(metric.total, `${key}.total`),
+      covered = count(metric.covered, `${key}.covered`);
+    if (
+      (all === 0 && ["lines", "statements"].includes(key)) ||
+      covered > all ||
+      typeof metric.pct !== "number" ||
+      !Number.isFinite(metric.pct) ||
+      metric.pct < 0 ||
+      metric.pct > 100
+    )
+      throw new TypeError(
+        `Coverage ${key} must contain measured code and a percentage.`,
+      );
+    const computed = all === 0 ? 100 : (covered / all) * 100;
+    if (Math.abs(computed - metric.pct) > 0.02)
+      throw new TypeError(`Coverage ${key} percentage disagrees with counts.`);
+    result[key] = metric.pct;
+  }
+  return result;
+}
+/** Gate real report envelopes. Caller-supplied commit/timestamps are provenance claims, not signatures. */
+export function evaluateReports(bundle, options = {}) {
+  object(bundle, "Report bundle");
+  object(options, "Policy");
+  for (const key of Object.keys(options))
+    if (
+      !["minTests", "minCoverage", "minScore", "maxAgeMs", "now"].includes(key)
+    )
+      throw new TypeError(`Unknown policy option: ${key}.`);
+  if (typeof bundle.commit !== "string" || !bundle.commit.trim())
+    throw new TypeError("Report bundle requires a nonempty commit.");
+  const policy = {
+    minTests: 1,
+    minCoverage: 80,
+    minScore: 80,
+    maxAgeMs: 3600000,
+    ...options,
+  };
+  for (const [key, value] of Object.entries({
+    minTests: 1,
+    minCoverage: 80,
+    minScore: 80,
+    maxAgeMs: 3600000,
+  }))
+    if (policy[key] === undefined) policy[key] = value;
+  count(policy.minTests, "minTests");
+  if (policy.minTests < 1) throw new RangeError("minTests must be positive.");
+  for (const key of ["minCoverage", "minScore"])
+    if (
+      typeof policy[key] !== "number" ||
+      !Number.isFinite(policy[key]) ||
+      policy[key] < 0 ||
+      policy[key] > 100
+    )
+      throw new RangeError(`${key} must be from 0 to 100.`);
+  if (!Number.isSafeInteger(policy.maxAgeMs) || policy.maxAgeMs < 1)
+    throw new RangeError("maxAgeMs must be a positive safe integer.");
+  const now = options.now ?? new Date().toISOString();
+  const nowMs = date(now, "now");
+  const evidence = {},
+    receipts = [],
+    blockers = [];
+  for (const kind of ["tests", "coverage", "build"]) {
+    const issues = [],
+      report = bundle[kind];
+    if (!report) {
+      issues.push(`${kind}: report is missing.`);
+    } else
+      try {
+        object(report, kind);
+        const captured = date(report.capturedAt, `${kind}.capturedAt`);
+        if (report.commit !== bundle.commit)
+          issues.push(`${kind}: commit does not match ${bundle.commit}.`);
+        if (captured > nowMs)
+          issues.push(`${kind}: timestamp is in the future.`);
+        if (nowMs - captured > policy.maxAgeMs)
+          issues.push(`${kind}: report is stale.`);
+        if (kind === "tests") {
+          if (!["node-tap", "jest"].includes(report.format))
+            throw new RangeError("Test format must be node-tap or jest.");
+          const parsed = parseTestReport(report.data, report.format);
+          evidence.tests = parsed.tests;
+          evidence.failingTests = parsed.failingTests;
+          if (!parsed.successful)
+            issues.push("tests: test execution was unsuccessful.");
+          if (parsed.tests < policy.minTests)
+            issues.push(
+              `tests: ${parsed.tests} executed tests is below ${policy.minTests}.`,
+            );
+        } else if (kind === "coverage") {
+          if (report.format !== "istanbul-summary")
+            throw new RangeError("Coverage format must be istanbul-summary.");
+          const coverage = parseCoverageReport(report.data);
+          evidence.coverage = coverage.lines;
+          for (const [metric, value] of Object.entries(coverage))
+            if (value < policy.minCoverage)
+              issues.push(
+                `coverage: ${metric} ${value}% is below ${policy.minCoverage}%.`,
+              );
+        } else {
+          count(report.exitCode, "build.exitCode");
+          evidence.build = report.exitCode === 0;
+          if (report.exitCode !== 0)
+            issues.push(`build: command exited ${report.exitCode}.`);
+        }
+      } catch (error) {
+        issues.push(`${kind}: ${error.message}`);
+      }
+    receipts.push({
+      kind,
+      format: kind === "build" ? "exit-code" : (report?.format ?? "missing"),
+      commit: typeof report?.commit === "string" ? report.commit : null,
+      capturedAt:
+        typeof report?.capturedAt === "string" ? report.capturedAt : null,
+      accepted: issues.length === 0,
+      issues,
+    });
+    blockers.push(...issues);
+  }
+  const plan = releasePlan(evidence, { minScore: policy.minScore });
+  const combined = [...new Set([...blockers, ...plan.blockers])];
+  const receiptTasks = receipts
+    .filter((item) => !item.accepted)
+    .map((item) => ({
+      id: "receipt-" + item.kind,
+      priority: "blocker",
+      title: "Repair " + item.kind + " evidence",
+      verify: `Generate a completed ${item.kind} report for ${bundle.commit} with a current UTC timestamp; resolve: ${item.issues.join(" ")}`,
+    }));
+  return {
+    ...plan,
+    summary: combined.length
+      ? "The receipts say stop. Confidence must wait."
+      : plan.summary,
+    tasks: [...receiptTasks, ...plan.tasks],
+    passed: combined.length === 0,
+    blockers: combined,
+    evidence,
+    receipts,
+    commit: bundle.commit,
+    policy: {
+      minTests: policy.minTests,
+      minCoverage: policy.minCoverage,
+      minScore: policy.minScore,
+      maxAgeMs: policy.maxAgeMs,
+    },
+    evaluatedAt: now,
+  };
+}