@deployanyway/ship-it-meter 0.3.0 → 1.0.0

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

@@ -41,3 +41,77 @@ export function releaseGate(
   input?: Evidence,
   options?: { minScore?: number },
 ): Gate;
+
+export interface ReleaseTask {
+  id: string;
+  priority: "blocker" | "review" | "release";
+  title: string;
+  verify: string;
+}
+export interface ReleasePlan extends Gate {
+  summary: string;
+  tasks: ReleaseTask[];
+}
+export interface ReleaseScenario {
+  name: string;
+  description: string;
+  evidence: Evidence;
+}
+export function releaseScenarios(): ReleaseScenario[];
+export function scenarioEvidence(name: string): Evidence;
+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

@@ -41,3 +41,77 @@ export function releaseGate(
   input?: Evidence,
   options?: { minScore?: number },
 ): Gate;
+
+export interface ReleaseTask {
+  id: string;
+  priority: "blocker" | "review" | "release";
+  title: string;
+  verify: string;
+}
+export interface ReleasePlan extends Gate {
+  summary: string;
+  tasks: ReleaseTask[];
+}
+export interface ReleaseScenario {
+  name: string;
+  description: string;
+  evidence: Evidence;
+}
+export function releaseScenarios(): ReleaseScenario[];
+export function scenarioEvidence(name: string): Evidence;
+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.3.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,7 +1,15 @@
 import { parseArgs } from "node:util";
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { URL } from "node:url";
-import { shipIt, preflight, releaseGate } from "./index.js";
+import {
+  shipIt,
+  preflight,
+  releaseGate,
+  releasePlan,
+  releaseScenarios,
+  scenarioEvidence,
+  evaluateReports,
+} from "./index.js";
 
 import { readStdin } from "./input.js";
 
@@ -12,7 +20,13 @@ 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" },
+      "list-scenarios": { type: "boolean" },
       "min-score": { type: "string" },
       checklist: { type: "boolean" },
       tests: { type: "string" },
@@ -28,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  --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(
@@ -36,15 +50,68 @@ try {
         readFileSync(new URL("../package.json", import.meta.url), "utf8"),
       ).version,
     );
+  } else if (values["list-scenarios"]) {
+    console.log(
+      releaseScenarios()
+        .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()) : {};
+    const input = values.stdin
+      ? JSON.parse(await readStdin())
+      : values.scenario !== undefined
+        ? scenarioEvidence(values.scenario)
+        : {};
+    if (values.stdin && values.scenario !== undefined)
+      throw new TypeError("Choose --stdin or --scenario, not both.");
+    if ([values.gate, values.plan, values.checklist].filter(Boolean).length > 1)
+      throw new TypeError("Choose one of --gate, --plan or --checklist.");
     if (!input || typeof input !== "object" || Array.isArray(input))
       throw new TypeError("stdin must contain an evidence object.");
     if (
       values["min-score"] !== undefined &&
-      (!values.gate || !/^\d+(?:\.\d+)?$/.test(values["min-score"]))
+      (!(values.gate || values.plan) ||
+        !/^\d+(?:\.\d+)?$/.test(values["min-score"]))
     )
-      throw new TypeError("--min-score requires --gate and a decimal number.");
+      throw new TypeError(
+        "--min-score requires --gate or --plan and a decimal number.",
+      );
     for (const [flag, key] of Object.entries({
       tests: "tests",
       failing: "failingTests",
@@ -66,21 +133,34 @@ try {
     for (const key of ["day", "branch"])
       if (values[key] !== undefined) input[key] = values[key];
     if (values.dirty) input.uncommittedChanges = true;
-    const result = values.gate
-      ? releaseGate(input, {
-          minScore:
-            values["min-score"] === undefined
-              ? undefined
-              : Number(values["min-score"]),
-        })
-      : values.checklist
-        ? preflight(input)
-        : shipIt(input);
-    if (values.gate && !result.passed) process.exitCode = 1;
+    const result =
+      values.gate || values.plan
+        ? (values.plan ? releasePlan : releaseGate)(input, {
+            minScore:
+              values["min-score"] === undefined
+                ? undefined
+                : Number(values["min-score"]),
+          })
+        : values.checklist
+          ? preflight(input)
+          : shipIt(input);
+    if ((values.gate || values.plan) && !result.passed) process.exitCode = 1;
+    if (values.plan && !values.json)
+      console.log(
+        result.summary +
+          "\n" +
+          result.tasks
+            .map(
+              (task) =>
+                `[${task.priority}] ${task.title}\n  Verify: ${task.verify}`,
+            )
+            .join("\n") +
+          "\n",
+      );
     console.log(
       values.json
         ? JSON.stringify(result, null, 2)
-        : `${result.score}/100 — ${result.verdict}${values.gate ? (result.passed ? " — gate passed" : " — gate blocked") : ""}\n${result.reasons.map((reason) => `- ${reason}`).join("\n")}${result.actions ? "\n\nBefore you ship:\n" + result.actions.map((action) => `[ ] ${action}`).join("\n") : ""}`,
+        : `${result.score}/100 — ${result.verdict}${values.gate || values.plan ? (result.passed ? " — gate passed" : " — gate blocked") : ""}\n${result.reasons.map((reason) => `- ${reason}`).join("\n")}${result.actions ? "\n\nBefore you ship:\n" + result.actions.map((action) => `[ ] ${action}`).join("\n") : ""}`,
     );
   }
 } catch (error) {

package/src/index.js

@@ -187,3 +187,118 @@ export function preflight(input = {}) {
     );
   return { ...result, actions };
 }
+
+export { releaseScenarios, scenarioEvidence } from "./scenarios.js";
+/** Explain the gate as ordered work with observable completion criteria. */
+export function releasePlan(input = {}, options = {}) {
+  const gate = releaseGate(input, options);
+  const tasks = [];
+  const add = (id, priority, title, verify) =>
+    tasks.push({ id, priority, title, verify });
+  if (input.build !== true)
+    add(
+      "build",
+      "blocker",
+      "Get a passing build",
+      "Run the release build for the exact commit and record its successful result.",
+    );
+  if (!input.tests)
+    add(
+      "tests",
+      "blocker",
+      "Run a nonempty test suite",
+      "Record the test count and outcome for the release commit.",
+    );
+  if (input.failingTests)
+    add(
+      "failing-tests",
+      "blocker",
+      "Repair failing tests",
+      "Reproduce each failure, fix its cause and rerun the suite.",
+    );
+  if (input.coverage === undefined)
+    add(
+      "coverage-evidence",
+      "blocker",
+      "Measure coverage",
+      "Generate coverage for the release commit and record the percentage.",
+    );
+  else if (input.coverage < 80)
+    add(
+      "coverage-review",
+      "review",
+      "Review untested paths",
+      "Inspect uncovered critical paths and add meaningful tests where needed.",
+    );
+  if (input.criticalIssues)
+    add(
+      "critical-issues",
+      "blocker",
+      "Resolve critical issues",
+      "Record the resolution and verify the affected behavior.",
+    );
+  if (input.lintFailures)
+    add(
+      "lint",
+      "blocker",
+      "Fix lint failures",
+      "Run the configured lint checks successfully.",
+    );
+  if (input.uncommittedChanges)
+    add(
+      "worktree",
+      "blocker",
+      "Reconcile local changes",
+      "Commit or stash intentionally and verify the exact release source.",
+    );
+  if (input.branch && !["main", "master"].includes(input.branch.trim()))
+    add(
+      "branch",
+      "review",
+      "Confirm release branch",
+      "Verify that this branch is the intended release source and that its CI passed.",
+    );
+  if (input.day?.trim().toLowerCase() === "friday")
+    add(
+      "friday",
+      "review",
+      "Confirm weekend support",
+      "Identify monitoring ownership and a tested rollback path.",
+    );
+  if (gate.score < gate.minScore)
+    add(
+      "score",
+      "blocker",
+      "Improve evidence to the configured threshold",
+      "Address score deductions, rerun the checks and reevaluate the gate.",
+    );
+  add(
+    "rollback",
+    "release",
+    "Prepare the return route",
+    "Verify the rollback artifact and procedure before deployment.",
+  );
+  add(
+    "monitoring",
+    "release",
+    "Watch the actual release",
+    "Check health and error metrics after deployment and name an owner.",
+  );
+  const summaries = {
+    "Absolutely Not": "The evidence says stop. The confidence hat can wait.",
+    Questionable:
+      "The release has questions. Answer them before adding confetti.",
+    "Probably Fine": "Close is a useful direction, not a deployment receipt.",
+    "Ship It": "Good evidence. Keep the parachute and watch the landing.",
+    "Suspiciously Ready":
+      "Boring, verified readiness. Give the checks their share of the applause.",
+  };
+  const rank = { blocker: 0, review: 1, release: 2 };
+  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();