coverage-check 0.1.1 → 0.2.1

package/README.md

@@ -22,46 +22,66 @@ coverage-check check \
 
 Exits `0` on pass, `1` on failure, `2` on configuration error.
 
-### Suite store (conditional CI)
+### Suite store with S3 (conditional CI)
 
-When only some CI suites run per PR (e.g. backend tests only when backend files change), store each suite's LCOV on every run and merge them when checking:
+When only some CI suites run per PR (e.g. backend tests only when backend files change), store each suite's LCOV in S3 and merge them during coverage checks:
 
 ```sh
-# After backend tests run — store this suite's coverage
+# After backend tests run on the main branch — store this suite's coverage
 coverage-check store-put \
   --suite backend \
-  --store ./coverage-store \
+  --store-s3 my-bucket/coverage-store \
   --artifacts ./coverage-artifacts \
   --sha "$GITHUB_SHA" \
-  --ref "$GITHUB_REF"
+  --branch main
 
-# Sync the store directory to persistent storage (e.g. S3, git orphan branch)
-aws s3 sync ./coverage-store s3://my-bucket/coverage-store/
+# On a PR that only runs frontend tests:
+coverage-check check \
+  --rules .coverage-rules.yml \
+  --artifacts ./coverage-artifacts \
+  --store-s3 my-bucket/coverage-store \
+  --suite frontend \
+  --branch main \
+  --base origin/main \
+  --head HEAD
+```
+
+The `--suite` flag on `check` tells the tool to use fresh `--artifacts` for the current suite and pull historical coverage from the store for all other suites. The `--branch` flag selects which branch pointer to follow when reading from the store.
+
+**S3 key layout:**
 
-# --- On the next PR that runs only frontend tests ---
+```text
+<prefix>/<suite>/sha/<sha>/lcov.info          # payload
+<prefix>/<suite>/branch/<branch>/latest.json  # pointer: { "sha": "...", "timestamp": "..." }
+```
 
-# Pull the store
-aws s3 sync s3://my-bucket/coverage-store/ ./coverage-store
+### Suite store with filesystem
 
-# Store-put the current suite
-coverage-check store-put --suite frontend --store ./coverage-store --artifacts ./coverage-artifacts
+For local development or simpler deployments:
+
+```sh
+coverage-check store-put \
+  --suite backend \
+  --store-fs ./coverage-store \
+  --artifacts ./coverage-artifacts \
+  --sha "$GITHUB_SHA" \
+  --branch main
 
-# Check: merges all stored suites (backend from baseline + frontend from this run)
 coverage-check check \
   --rules .coverage-rules.yml \
   --artifacts ./coverage-artifacts \
-  --store ./coverage-store \
+  --store-fs ./coverage-store \
   --suite frontend \
   --base origin/main \
   --head HEAD
 ```
 
-The `--suite` flag on `check` tells the tool to replace the same-named suite in the store with the fresh `--artifacts` (so you always see this PR's coverage for the suite that ran, and historical coverage for suites that didn't).
-
 ### GitHub PR sticky comment
 
 Pass `--pr` and `--repo` to post (or update) a sticky comment on a pull request. Requires the `gh` CLI and `GH_TOKEN`/`GITHUB_TOKEN`.
 
+On **failure**, the comment is created or updated with the list of uncovered lines. On **pass**, any existing failure comment is **deleted** — no new comment is posted.
+
 ```sh
 coverage-check check \
   --rules .coverage-rules.yml \
@@ -70,6 +90,10 @@ coverage-check check \
   --repo "${{ github.repository }}"
 ```
 
+### GitHub Actions step summary
+
+When `$GITHUB_STEP_SUMMARY` is set, a per-suite totals and per-rule patch-coverage table is appended to the job summary automatically.
+
 ## Rules file
 
 ```yaml
@@ -89,49 +113,47 @@ Rules are matched in order; the first match wins. Files in the diff not matched
 
 ### `coverage-check check`
 
-| Flag             | Default                | Description                                                                  |
-| ---------------- | ---------------------- | ---------------------------------------------------------------------------- |
-| `--rules`        | `.coverage-rules.yml`  | Path to YAML rules file                                                      |
-| `--artifacts`    | `./coverage-artifacts` | Directory to scan for `lcov.info` files                                      |
-| `--base`         | `origin/main`          | Base git ref for `git diff`                                                  |
-| `--head`         | `HEAD`                 | Head git ref for `git diff`                                                  |
-| `--store`        | —                      | Path to a suite store directory                                              |
-| `--suite`        | —                      | Name of the current suite (fresh artifacts override this suite in the store) |
-| `--strip-prefix` | —                      | Extra path prefix to strip from LCOV `SF:` lines (repeatable)                |
-| `--pr`           | —                      | Pull request number for sticky comment                                       |
-| `--repo`         | `$GITHUB_REPOSITORY`   | `owner/repo` for sticky comment                                              |
-| `--json`         | —                      | Write JSON result to this path                                               |
+| Flag             | Default                | Description                                                                                  |
+| ---------------- | ---------------------- | -------------------------------------------------------------------------------------------- |
+| `--rules`        | `.coverage-rules.yml`  | Path to YAML rules file                                                                      |
+| `--artifacts`    | `./coverage-artifacts` | Directory to scan for `lcov.info` files                                                      |
+| `--base`         | `origin/main`          | Base git ref for `git diff`                                                                  |
+| `--head`         | `HEAD`                 | Head git ref for `git diff`                                                                  |
+| `--store-fs`     | —                      | Path to a filesystem suite store directory                                                   |
+| `--store`        | —                      | Alias for `--store-fs`                                                                       |
+| `--store-s3`     | —                      | S3 suite store spec: `<bucket>[/<prefix>]`                                                   |
+| `--branch`       | `"main"`               | Branch pointer to follow when reading from the store (no `/` or `\\`)                        |
+| `--suite`        | —                      | Name of the current suite (no `/` or `\\`); fresh artifacts override this suite in the store |
+| `--strip-prefix` | —                      | Extra path prefix to strip from LCOV `SF:` lines (repeatable)                                |
+| `--pr`           | —                      | Pull request number for sticky comment                                                       |
+| `--repo`         | `$GITHUB_REPOSITORY`   | `owner/repo` for sticky comment                                                              |
+| `--json`         | —                      | Write JSON result to this path                                                               |
 
 ### `coverage-check store-put`
 
-| Flag             | Default                | Description                             |
-| ---------------- | ---------------------- | --------------------------------------- |
-| `--suite`        | required               | Suite name to store                     |
-| `--store`        | required               | Path to the suite store directory       |
-| `--artifacts`    | `./coverage-artifacts` | Directory to scan for `lcov.info` files |
-| `--strip-prefix` | —                      | Extra path prefix to strip (repeatable) |
-| `--sha`          | —                      | Git SHA to record in metadata           |
-| `--ref`          | —                      | Git ref to record in metadata           |
+| Flag             | Default                | Description                                                   |
+| ---------------- | ---------------------- | ------------------------------------------------------------- |
+| `--suite`        | required               | Suite name to store                                           |
+| `--store-fs`     | required\*             | Path to a filesystem suite store directory                    |
+| `--store`        | —                      | Alias for `--store-fs`                                        |
+| `--store-s3`     | required\*             | S3 suite store spec: `<bucket>[/<prefix>]`                    |
+| `--sha`          | required               | Git SHA to associate with this coverage payload               |
+| `--branch`       | required               | Branch name for the pointer (e.g. `main`)                     |
+| `--artifacts`    | `./coverage-artifacts` | Directory to scan for `lcov.info` files                       |
+| `--strip-prefix` | —                      | Extra path prefix to strip from LCOV `SF:` lines (repeatable) |
+
+\* Exactly one of `--store-fs` or `--store-s3` is required.
 
 ## Programmatic API
 
 ```ts
-import { runCheck, runStorePut, FileSystemSuiteStore } from "coverage-check";
+import { runCheck, runStorePut, FileSystemSuiteStore, S3SuiteStore } from "coverage-check";
 
-// Custom store adapter (e.g. S3)
-import { SuiteStore } from "coverage-check";
+// FileSystem store
+const fsStore = new FileSystemSuiteStore("/path/to/store");
 
-class S3SuiteStore implements SuiteStore {
-  async list() {
-    /* ... */
-  }
-  async get(suite: string) {
-    /* ... */
-  }
-  async put(suite: string, lcov: Buffer, meta?: SuiteMeta) {
-    /* ... */
-  }
-}
+// S3 store (requires AWS credentials — see https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html)
+const s3Store = new S3SuiteStore({ bucket: "my-bucket", prefix: "coverage" });
 
 await runCheck({
   rules: ".coverage-rules.yml",
@@ -142,9 +164,41 @@ await runCheck({
   repo: "",
   json: null,
   stripPrefixes: [],
-  store: new S3SuiteStore(),
+  store: s3Store,
   suite: "backend",
+  branch: "main",
 });
+
+await runStorePut({
+  suite: "backend",
+  store: s3Store,
+  artifacts: "./coverage",
+  stripPrefixes: [],
+  sha: "abc123",
+  branch: "main",
+});
+```
+
+You can also implement your own `SuiteStore`:
+
+```ts
+import type { SuiteStore } from "coverage-check";
+
+class MyCustomStore implements SuiteStore {
+  async list(): Promise<string[]> {
+    /* ... */
+  }
+  async get(suite: string, opts?: { sha?: string; branch?: string }): Promise<Buffer | null> {
+    /* ... */
+  }
+  async put(
+    suite: string,
+    lcov: Buffer,
+    meta: { sha: string; branch: string; timestamp?: string },
+  ): Promise<void> {
+    /* ... */
+  }
+}
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coverage-check",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Patch-coverage gate: checks that newly added lines meet per-path coverage thresholds. Supports per-suite LCOV accumulation for conditional CI.",
   "license": "MIT",
   "author": "Jonathan Ong",
@@ -18,6 +18,7 @@
     "node": ">=22.0.0"
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.1048.0",
     "js-yaml": "^4.1.1"
   },
   "devDependencies": {

package/src/commands/check-args.mts

@@ -0,0 +1,110 @@
+import { makeStore } from "../store-factory.mts";
+import { assertSafePathComponent } from "../suite-store.mts";
+import type { SuiteStore } from "../suite-store.mts";
+import type { GhRunner } from "../github-comment.mts";
+
+export type CheckArgs = {
+  rules: string;
+  artifacts: string;
+  base: string;
+  head: string;
+  pr: number | null;
+  repo: string;
+  json: string | null;
+  stripPrefixes: string[];
+  store: SuiteStore | null;
+  suite: string | null;
+  /** Branch used to resolve baseline from the store. Default: "main". */
+  branch?: string;
+  gh?: GhRunner;
+  /** Path to append the GitHub step summary. Default: $GITHUB_STEP_SUMMARY. */
+  summaryFile?: string | null;
+};
+
+export function parseCheckArgs(argv: string[]): CheckArgs {
+  let storeFs: string | null = null;
+  let storeS3: string | null = null;
+  const args: Omit<CheckArgs, "store"> & { store: SuiteStore | null } = {
+    rules: ".coverage-rules.yml",
+    artifacts: "./coverage-artifacts",
+    base: "origin/main",
+    head: "HEAD",
+    pr: null,
+    repo: process.env["GITHUB_REPOSITORY"] ?? "",
+    json: null,
+    stripPrefixes: [],
+    store: null,
+    suite: null,
+    branch: "main",
+    summaryFile: process.env["GITHUB_STEP_SUMMARY"] ?? null,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i]!;
+    const next = argv[i + 1];
+    const val = (): string => {
+      if (next === undefined || next.startsWith("--")) {
+        throw new Error(`${flag} requires a value`);
+      }
+      i++;
+      return next;
+    };
+    switch (flag) {
+      case "--rules":
+        args.rules = val();
+        break;
+      case "--artifacts":
+        args.artifacts = val();
+        break;
+      case "--base":
+        args.base = val();
+        break;
+      case "--head":
+        args.head = val();
+        break;
+      case "--repo":
+        args.repo = val();
+        break;
+      case "--json":
+        args.json = val();
+        break;
+      case "--suite": {
+        const s = val();
+        assertSafePathComponent(s, "suite");
+        args.suite = s;
+        break;
+      }
+      case "--strip-prefix":
+        args.stripPrefixes.push(val());
+        break;
+      case "--branch": {
+        const b = val();
+        assertSafePathComponent(b, "branch");
+        args.branch = b;
+        break;
+      }
+      case "--store":
+      case "--store-fs":
+        storeFs = val();
+        break;
+      case "--store-s3":
+        storeS3 = val();
+        break;
+      case "--pr": {
+        const raw = val();
+        if (!/^\d+$/.test(raw) || raw === "0")
+          throw new Error(`--pr must be a positive integer, got: ${JSON.stringify(raw)}`);
+        args.pr = parseInt(raw, 10);
+        break;
+      }
+      default:
+        throw new Error(`unknown flag: ${flag}`);
+    }
+  }
+
+  if (storeFs && storeS3) throw new Error("--store-fs and --store-s3 are mutually exclusive");
+  if (args.pr !== null && args.repo.trim() === "")
+    throw new Error("--repo is required when --pr is set (or define GITHUB_REPOSITORY)");
+  args.store = makeStore({ fs: storeFs, s3: storeS3 });
+  return args;
+}

package/src/commands/check.mts

@@ -4,103 +4,25 @@ import { mergeLcov } from "../lcov-merge.mts";
 import { getChangedLines } from "../diff-parser.mts";
 import { loadRules } from "../rules.mts";
 import { computePatchCoverage } from "../patch-coverage.mts";
-import { collapseRanges, renderFailureComment, renderPassComment } from "../report.mts";
+import { collapseRanges, renderFailureComment } from "../report.mts";
 import { upsertComment } from "../github-comment.mts";
 import { collectLcovFiles, buildStripPrefixes } from "../load-artifacts.mts";
-import { FileSystemSuiteStore } from "../suite-store.mts";
+import { writeSummary } from "../step-summary.mts";
+import { parseCheckArgs } from "./check-args.mts";
+import type { CheckArgs } from "./check-args.mts";
+import type { SuiteSource } from "../step-summary.mts";
 import type { LcovData } from "../types.mts";
-import type { SuiteStore } from "../suite-store.mts";
-import type { GhRunner } from "../github-comment.mts";
+export type { CheckArgs } from "./check-args.mts";
 
 const stdout = (msg: string) => process.stdout.write(`${msg}\n`);
 const stderr = (msg: string) => process.stderr.write(`${msg}\n`);
 
-export type CheckArgs = {
-  rules: string;
-  artifacts: string;
-  base: string;
-  head: string;
-  pr: number | null;
-  repo: string;
-  json: string | null;
-  stripPrefixes: string[];
-  store: SuiteStore | null;
-  suite: string | null;
-  gh?: GhRunner;
-};
-
-function parseArgs(argv: string[]): CheckArgs {
-  const args: CheckArgs = {
-    rules: ".coverage-rules.yml",
-    artifacts: "./coverage-artifacts",
-    base: "origin/main",
-    head: "HEAD",
-    pr: null,
-    repo: process.env["GITHUB_REPOSITORY"] ?? "",
-    json: null,
-    stripPrefixes: [],
-    store: null,
-    suite: null,
-  };
-
-  for (let i = 0; i < argv.length; i++) {
-    const flag = argv[i]!;
-    const next = argv[i + 1];
-    const val = (): string => {
-      if (next === undefined) throw new Error(`${flag} requires a value`);
-      i++;
-      return next;
-    };
-    switch (flag) {
-      case "--rules":
-        args.rules = val();
-        break;
-      case "--artifacts":
-        args.artifacts = val();
-        break;
-      case "--base":
-        args.base = val();
-        break;
-      case "--head":
-        args.head = val();
-        break;
-      case "--pr": {
-        const raw = val();
-        if (!/^\d+$/.test(raw) || raw === "0")
-          throw new Error(`--pr must be a positive integer, got: ${JSON.stringify(raw)}`);
-        args.pr = parseInt(raw, 10);
-        break;
-      }
-      case "--repo":
-        args.repo = val();
-        break;
-      case "--json":
-        args.json = val();
-        break;
-      case "--strip-prefix":
-        args.stripPrefixes.push(val());
-        break;
-      case "--store":
-        args.store = new FileSystemSuiteStore(val());
-        break;
-      case "--suite":
-        args.suite = val();
-        break;
-      default:
-        throw new Error(`unknown flag: ${flag}`);
-    }
-  }
-
-  return args;
-}
-
 export async function main(argv: string[]): Promise<number> {
   let args: CheckArgs;
   try {
-    args = parseArgs(argv);
+    args = parseCheckArgs(argv);
   } catch (err) {
-    /* c8 ignore next */
-    stderr(`coverage-check: ${err instanceof Error ? err.message : err}`);
+    stderr(`coverage-check: ${String(err)}`);
     return 2;
   }
   return runCheck(args);
@@ -115,25 +37,37 @@ export async function runCheck(args: CheckArgs): Promise<number> {
     return 2;
   }
 
+  const branch = args.branch ?? "main";
   const stripPrefixes = buildStripPrefixes(args.stripPrefixes);
   const reports: LcovData[] = [];
+  const suiteSources: SuiteSource[] = [];
 
-  // Merge in suites from the store (skip the current suite — fresh artifacts take precedence)
   if (args.store !== null) {
     const suites = await args.store.list();
     for (const suite of suites) {
       if (suite === args.suite) continue;
-      const buf = await args.store.get(suite);
+      const buf = await args.store.get(suite, { branch });
       if (buf !== null) {
-        reports.push(parseLcov(buf.toString("utf8"), stripPrefixes));
+        const lcov = parseLcov(buf.toString("utf8"), stripPrefixes);
+        reports.push(lcov);
+        suiteSources.push({ suite, source: "store", lcov });
       }
     }
   }
 
-  // Add current run's lcov files
   const lcovFiles = collectLcovFiles(args.artifacts);
+  const freshLcovs: LcovData[] = [];
   for (const f of lcovFiles) {
-    reports.push(parseLcov(readFileSync(f, "utf8"), stripPrefixes));
+    const lcov = parseLcov(readFileSync(f, "utf8"), stripPrefixes);
+    reports.push(lcov);
+    freshLcovs.push(lcov);
+  }
+  if (freshLcovs.length > 0) {
+    suiteSources.push({
+      suite: args.suite ?? "(current)",
+      source: "fresh",
+      lcov: mergeLcov(freshLcovs),
+    });
   }
 
   if (reports.length === 0) {
@@ -167,7 +101,7 @@ export async function runCheck(args: CheckArgs): Promise<number> {
   if (!passed) {
     stdout("\ncoverage-check: FAILED\n");
     for (const bucket of buckets.filter((b) => !b.passed)) {
-      /* c8 ignore next -- buckets always have coverable>0 by construction */
+      /* c8 ignore next -- bucket.coverable is always > 0 by patch-coverage.mts L36 guard */
       const pct =
         bucket.coverable > 0 ? `${((bucket.hit / bucket.coverable) * 100).toFixed(1)}%` : "—";
       stdout(
@@ -180,15 +114,28 @@ export async function runCheck(args: CheckArgs): Promise<number> {
   } else {
     stdout("\ncoverage-check: PASSED\n");
     for (const bucket of buckets) {
-      /* c8 ignore next -- buckets always have coverable>0 by construction */
+      /* c8 ignore next -- bucket.coverable is always > 0 by patch-coverage.mts L36 guard */
       const pct =
         bucket.coverable > 0 ? `${((bucket.hit / bucket.coverable) * 100).toFixed(1)}%` : "—";
       stdout(`  ${bucket.rule}: ${pct} ✓`);
     }
   }
 
+  const summaryFile =
+    args.summaryFile !== undefined
+      ? args.summaryFile
+      : (process.env["GITHUB_STEP_SUMMARY"] ?? null);
+  if (summaryFile) {
+    try {
+      writeSummary(summaryFile, suiteSources, result, runUrl, branch);
+    } catch (err) {
+      stderr(`coverage-check: failed to write step summary: ${err}`);
+      return 2;
+    }
+  }
+
   if (args.pr !== null && args.repo) {
-    const body = passed ? renderPassComment(runUrl) : renderFailureComment(result, runUrl);
+    const body = passed ? "" : renderFailureComment(result, runUrl);
     try {
       await upsertComment(body, args.repo, args.pr, passed, args.gh);
     } catch (err) {