coverage-check 0.7.0 → 0.8.0

package/README.md

@@ -51,12 +51,29 @@ The `--suite` flag on `check` tells the tool to use fresh `--artifacts` for the
 **S3 key layout:**
 
 ```text
-<prefix>/<suite>/sha/<sha>/lcov.info          # payload
-<prefix>/<suite>/branch/<encoded-branch>/latest.json  # pointer: { "sha": "...", "timestamp": "..." }
+<prefix>/<suite>/sha/<sha>/lcov.info.gz       # gzip payload for new versioned writes
+<prefix>/<suite>/branch/<encoded-branch>/latest.json  # pointer with sha, payloadKey, encoding, byte counts, timestamp
 ```
 
 S3-backed stores need `s3:PutObject` for writes and `s3:GetObject` for reading branch pointers and baselines. The pointer reader also checks the previous unencoded pointer key (for example `branch/main/latest.json`) so stores written before branch-name encoding remain readable.
 
+Versioned S3 writes (`store-put --sha ... --branch ...`) gzip the LCOV payload and write pointer
+metadata with `payloadKey`, `encoding`, `rawBytes`, and `storedBytes`. Existing raw
+`sha/<sha>/lcov.info` payloads and legacy `<suite>/lcov.info` payloads remain readable. Legacy
+writes without `--sha`/`--branch` keep the old raw `<suite>/lcov.info` layout.
+
+Every S3 operation logs a concise diagnostic line to stderr with the operation name, bucket, key,
+elapsed time, and byte counts where applicable. Use these lines to distinguish payload writes,
+branch-pointer reads, and branch-pointer writes when CI storage stalls.
+
+S3 request bounds are configurable with environment variables:
+
+| Variable                                  | Default | Purpose                                  |
+| ----------------------------------------- | ------- | ---------------------------------------- |
+| `COVERAGE_CHECK_S3_CONNECTION_TIMEOUT_MS` | `5000`  | Socket connection timeout for S3 calls   |
+| `COVERAGE_CHECK_S3_REQUEST_TIMEOUT_MS`    | `30000` | Whole-request timeout for S3 calls       |
+| `COVERAGE_CHECK_S3_MAX_ATTEMPTS`          | `2`     | AWS SDK attempt count, including retries |
+
 ### Suite store with filesystem
 
 For local development or simpler deployments:
@@ -145,6 +162,22 @@ coverage-check check \
   --advisory
 ```
 
+For wrappers that need machine-readable advisory results without a temp file, pass `--json -`.
+This writes JSON-only output to stdout and suppresses the human report:
+
+```sh
+coverage-check check \
+  --rules .coverage-rules.yml \
+  --artifacts ./coverage-artifacts \
+  --base origin/main \
+  --head HEAD \
+  --advisory \
+  --json -
+```
+
+JSON output keeps the normal check result fields (`passed`, `buckets`, `drops`, `informational`) and
+adds `exitCode`, `advisory`, and `skipped`.
+
 ### PR-scoped regression gate
 
 By default, `no_coverage_drop` applies to every rule area regardless of what changed. Pass `--drop-only-changed-areas` to restrict the drop gate to rule areas that contain at least one changed file in the PR diff. Areas with no changed files are reported as `skipped` — they pass non-blockingly:
@@ -174,6 +207,24 @@ coverage-check check \
 
 `--require-artifact` is also accepted by `coverage-check merge`.
 
+### Preparing fan-in artifacts
+
+Use `prepare-artifacts` before a fan-in coverage check when downloaded artifacts may be either
+nested as `coverage-<suite>/lcov.info` or flattened to a root-level `lcov.info`. Pass one
+`--expect-suite <job>=<suite>` for each successful coverage producer. The command normalizes a
+single flat LCOV into the expected suite directory and fails if any expected LCOV is missing:
+
+```sh
+coverage-check prepare-artifacts \
+  --artifacts ./coverage-artifacts \
+  --expect-suite test-backend=backend \
+  --expect-suite test-web=web
+```
+
+For local or fan-in wrappers, `check --aggregate-artifacts` treats all fresh LCOV files as one source
+for diagnostics, `check --fail-on-empty` exits `1` instead of skipping when no LCOV exists, and
+`check --ignore-path <glob>` prepends a zero-threshold override for CI-only paths in that run.
+
 ## Rules file
 
 ```yaml
@@ -218,6 +269,8 @@ First-match-wins means that if you have a more specific rule before a broader on
 
 ## CLI reference
 
+Run `coverage-check --help` or `coverage-check check --help` to print the available commands and check flags.
+
 ### `coverage-check check`
 
 | Flag                        | Default                | Description                                                                                                |
@@ -234,11 +287,14 @@ First-match-wins means that if you have a more specific rule before a broader on
 | `--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                                                                             |
+| `--json`                    | —                      | Write JSON result to this path; use `-` for JSON-only stdout                                               |
 | `--annotate-source`         | —                      | Print the trimmed source text of each uncovered line in stdout (does not alter PR comment or step summary) |
 | `--advisory`                | —                      | Exit `0` even on shortfall; still prints, writes JSON, and posts PR comment                                |
 | `--drop-only-changed-areas` | —                      | Restrict `no_coverage_drop` to rule areas that have ≥1 changed file; others are reported as skipped        |
 | `--require-artifact`        | —                      | Fail (exit `2`) if this relative path is absent under `--artifacts` (repeatable)                           |
+| `--fail-on-empty`           | —                      | Exit `1` when no coverage data is found instead of skipping                                                |
+| `--aggregate-artifacts`     | —                      | Treat fresh LCOV files as one source for diagnostics and summaries                                         |
+| `--ignore-path`             | —                      | Prepend a zero-threshold override glob for this run (repeatable)                                           |
 
 ### `coverage-check merge`
 
@@ -251,6 +307,13 @@ First-match-wins means that if you have a more specific rule before a broader on
 
 Hit counts are summed across all inputs. Function (`FN`/`FNDA`) and branch (`BRDA`) records are preserved; summary counters (`LF/LH/FNF/FNH/BRF/BRH`) are recomputed from the merged data.
 
+### `coverage-check prepare-artifacts`
+
+| Flag             | Default                | Description                                    |
+| ---------------- | ---------------------- | ---------------------------------------------- |
+| `--artifacts`    | `./coverage-artifacts` | Coverage artifact directory to normalize/check |
+| `--expect-suite` | —                      | Expected producer and suite as `<job>=<suite>` |
+
 ### `coverage-check store-put`
 
 | Flag             | Default                | Description                                                   |
@@ -272,10 +335,15 @@ When `--sha` and `--branch` are both provided, `store-put` writes a SHA-addresse
 
 ```ts
 import {
+  checkCoverage,
+  evaluateCheck,
   runCheck,
   runMerge,
   runStorePut,
+  prepareCoverageArtifacts,
   collapseRanges,
+  collectLcovFiles,
+  zeroThresholdGlobs,
   parseLcovFull,
   mergeLcovFull,
   toLcovFull,
@@ -289,6 +357,27 @@ const fsStore = new FileSystemSuiteStore("/path/to/store");
 // 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" });
 
+const check = await checkCoverage({
+  rules: ".coverage-rules.yml",
+  artifacts: "./coverage",
+  base: "origin/main",
+  head: "HEAD",
+  pr: null,
+  repo: "",
+  json: null,
+  stripPrefixes: [],
+  store: s3Store,
+  suite: "backend",
+  branch: "main",
+  advisory: true,
+  dropOnlyChangedAreas: false,
+  requireArtifacts: [],
+});
+
+if (!check.result?.passed) {
+  console.log(check.exitCode, check.advisory, check.result);
+}
+
 await runCheck({
   rules: ".coverage-rules.yml",
   artifacts: "./coverage",
@@ -304,7 +393,34 @@ await runCheck({
   advisory: false,
   dropOnlyChangedAreas: false,
   requireArtifacts: [],
+  failOnEmpty: false,
+  aggregateArtifacts: false,
+  ignorePaths: [],
+});
+
+const evaluated = await evaluateCheck({
+  rules: ".coverage-rules.yml",
+  artifacts: "./coverage",
+  base: "origin/main",
+  head: "HEAD",
+  pr: null,
+  repo: "",
+  json: null,
+  stripPrefixes: [],
+  store: null,
+  suite: null,
 });
+if (evaluated.result?.passed === false) {
+  // Integrations can render their own advisory output from the typed result.
+}
+
+prepareCoverageArtifacts({
+  artifacts: "./coverage-artifacts",
+  expectedSuites: [{ job: "test-backend", suite: "backend" }],
+});
+
+collectLcovFiles("./coverage-artifacts");
+zeroThresholdGlobs(".coverage-rules.yml");
 
 await runMerge({
   artifacts: "./coverage-artifacts",

package/dist/src/cli.mjs

@@ -1,11 +1,18 @@
 import { main as checkMain } from "./commands/check.mjs";
+import { checkHelp } from "./commands/check-render.mjs";
 import { main as storePutMain } from "./commands/store-put.mjs";
 import { main as htmlMain } from "./commands/html.mjs";
 import { main as mergeMain } from "./commands/merge.mjs";
 import { main as summaryMain } from "./commands/summary.mjs";
+import { main as prepareArtifactsMain } from "./commands/prepare-artifacts.mjs";
 const stderr = (msg) => process.stderr.write(`${msg}\n`);
+const stdout = (msg) => process.stdout.write(`${msg}\n`);
 export async function main(argv) {
     const sub = argv[0];
+    if (sub === "--help" || sub === "-h") {
+        stdout(help());
+        return 0;
+    }
     if (!sub || sub.startsWith("-"))
         return checkMain(argv);
     if (sub === "check")
@@ -18,6 +25,24 @@ export async function main(argv) {
         return htmlMain(argv.slice(1));
     if (sub === "summary")
         return summaryMain(argv.slice(1));
+    if (sub === "prepare-artifacts")
+        return prepareArtifactsMain(argv.slice(1));
     stderr(`coverage-check: unknown subcommand: ${JSON.stringify(sub)}`);
     return 2;
 }
+function help() {
+    return `coverage-check
+
+Usage:
+  coverage-check <command> [options]
+  coverage-check [check options]
+
+Commands:
+  check       Check patch coverage (default)
+  store-put   Store suite LCOV data
+  merge       Merge lcov.info files
+  html        Generate HTML coverage reports
+  summary     Generate a coverage summary
+
+${checkHelp()}`;
+}

package/dist/src/commands/check-args.d.mts

@@ -24,5 +24,11 @@ export type CheckArgs = {
     dropOnlyChangedAreas?: boolean;
     /** Relative paths under --artifacts that must exist before the check runs (repeatable). */
     requireArtifacts?: string[];
+    /** Exit non-zero when no LCOV data is available instead of treating the check as skipped. */
+    failOnEmpty?: boolean;
+    /** Merge fresh LCOV artifacts before evaluating, so fan-in artifacts are treated as one source. */
+    aggregateArtifacts?: boolean;
+    /** Path globs to exempt by prepending zero-threshold override rules (repeatable). */
+    ignorePaths?: string[];
 };
 export declare function parseCheckArgs(argv: string[]): CheckArgs;

package/dist/src/commands/check-args.mjs

@@ -1,5 +1,5 @@
 import { makeStore } from "../store-factory.mjs";
-import { assertSafePathComponent } from "../suite-store.mjs";
+import { assertSafePathComponent, assertValidRepo } from "../suite-store.mjs";
 export function parseCheckArgs(argv) {
     let storeFs = null;
     let storeS3 = null;
@@ -20,6 +20,9 @@ export function parseCheckArgs(argv) {
         advisory: false,
         dropOnlyChangedAreas: false,
         requireArtifacts: [],
+        failOnEmpty: false,
+        aggregateArtifacts: false,
+        ignorePaths: [],
     };
     for (let i = 0; i < argv.length; i++) {
         const flag = argv[i];
@@ -92,14 +95,29 @@ export function parseCheckArgs(argv) {
             case "--require-artifact":
                 args.requireArtifacts.push(val());
                 break;
+            case "--fail-on-empty":
+                args.failOnEmpty = true;
+                break;
+            case "--aggregate-artifacts":
+                args.aggregateArtifacts = true;
+                break;
+            case "--ignore-path":
+                args.ignorePaths.push(val());
+                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() === "")
+    const repo = args.repo.trim();
+    args.repo = repo;
+    if (args.pr !== null && repo.length === 0) {
         throw new Error("--repo is required when --pr is set (or define GITHUB_REPOSITORY)");
+    }
+    if (repo !== "") {
+        args.repo = assertValidRepo(repo);
+    }
     args.store = makeStore({ fs: storeFs, s3: storeS3 });
     return args;
 }

package/dist/src/commands/check-output.d.mts

@@ -4,8 +4,13 @@ import type { DropResult, DiffLines, LcovData } from "../types.mts";
  * Prints `::error::` to stderr for each missing file and returns false if any are absent.
  */
 export declare function checkRequiredArtifacts(artifactsDir: string, requireArtifacts: string[]): boolean;
+export declare function missingRequiredArtifacts(artifactsDir: string, requireArtifacts: string[]): string[];
 export declare function warnNonContributing(parsedSources: {
     name: string;
     lcov: LcovData;
 }[], diff: DiffLines): void;
+export declare function nonContributingWarnings(parsedSources: {
+    name: string;
+    lcov: LcovData;
+}[], diff: DiffLines): string[];
 export declare function printDropOutput(drops: DropResult[]): void;

package/dist/src/commands/check-output.mjs

@@ -26,23 +26,28 @@ function lcovContributesToDiff(sourceLcov, diff) {
  * Prints `::error::` to stderr for each missing file and returns false if any are absent.
  */
 export function checkRequiredArtifacts(artifactsDir, requireArtifacts) {
-    let ok = true;
-    for (const rel of requireArtifacts) {
-        if (!existsSync(join(artifactsDir, rel))) {
-            stderr(`::error:: missing expected coverage artifact: ${rel}`);
-            ok = false;
-        }
-    }
-    return ok;
+    const missing = missingRequiredArtifacts(artifactsDir, requireArtifacts);
+    for (const rel of missing)
+        stderr(`::error:: missing expected coverage artifact: ${rel}`);
+    return missing.length === 0;
+}
+export function missingRequiredArtifacts(artifactsDir, requireArtifacts) {
+    return requireArtifacts.filter((rel) => !existsSync(join(artifactsDir, rel)));
 }
 export function warnNonContributing(parsedSources, diff) {
+    for (const warning of nonContributingWarnings(parsedSources, diff))
+        stderr(warning);
+}
+export function nonContributingWarnings(parsedSources, diff) {
     if (diff.size === 0)
-        return;
+        return [];
+    const warnings = [];
     for (const { name, lcov: sourceLcov } of parsedSources) {
         if (!lcovContributesToDiff(sourceLcov, diff)) {
-            stderr(`coverage-check: warning: coverage from ${name} contributed 0 coverable lines to the patch result. This may indicate a path prefix mismatch.`);
+            warnings.push(`coverage-check: warning: coverage from ${name} contributed 0 coverable lines to the patch result. This may indicate a path prefix mismatch.`);
         }
     }
+    return warnings;
 }
 export function printDropOutput(drops) {
     if (drops.length === 0)

package/dist/src/commands/check-render.d.mts

@@ -0,0 +1 @@
+export declare function checkHelp(): string;

package/dist/src/commands/check-render.mjs

@@ -0,0 +1,27 @@
+export function checkHelp() {
+    return `coverage-check check
+
+Usage:
+  coverage-check check [options]
+  coverage-check [options]
+
+Options:
+  --rules <path>                 Path to YAML rules file (default: .coverage-rules.yml)
+  --artifacts <dir>              Directory to scan for lcov.info files (default: ./coverage-artifacts)
+  --base <ref>                   Base git ref for git diff (default: origin/main)
+  --head <ref>                   Head git ref for git diff (default: HEAD)
+  --store-fs <path>              Path to a filesystem suite store directory
+  --store <path>                 Alias for --store-fs
+  --store-s3 <bucket[/prefix]>   S3 suite store
+  --branch <name>                Branch pointer to follow when reading from the store (default: main)
+  --suite <name>                 Name of the current suite
+  --strip-prefix <prefix>        Extra path prefix to strip from LCOV SF: lines (repeatable)
+  --pr <number>                  Pull request number for sticky comment
+  --repo <owner/repo>            Repository for sticky comment (default: $GITHUB_REPOSITORY)
+  --json <path|->                Write JSON result to a path, or JSON-only stdout with -
+  --annotate-source              Print trimmed source text for each uncovered line
+  --advisory                     Exit 0 even on coverage shortfall
+  --drop-only-changed-areas      Restrict no_coverage_drop to changed rule areas
+  --require-artifact <relpath>   Fail if this path is absent under --artifacts (repeatable)
+  -h, --help                     Show this help`;
+}

package/dist/src/commands/check-result.d.mts

@@ -0,0 +1,17 @@
+import type { CoverageCheckResult } from "../types.mts";
+export type CheckRunResult = {
+    result: CoverageCheckResult | null;
+    exitCode: 0 | 1 | 2;
+    advisory: boolean;
+    skipped: boolean;
+    error: string | null;
+    warnings: string[];
+};
+export type CheckJsonPayload = CoverageCheckResult & {
+    exitCode: 0 | 1 | 2;
+    advisory: boolean;
+    skipped: boolean;
+    error?: string;
+};
+export declare function emptyResult(passed: boolean): CoverageCheckResult;
+export declare function toJsonPayload(check: CheckRunResult): CheckJsonPayload;

package/dist/src/commands/check-result.mjs

@@ -0,0 +1,12 @@
+export function emptyResult(passed) {
+    return { buckets: [], drops: [], informational: [], passed };
+}
+export function toJsonPayload(check) {
+    return {
+        ...(check.result ?? emptyResult(false)),
+        exitCode: check.exitCode,
+        advisory: check.advisory,
+        skipped: check.skipped,
+        ...(check.error === null ? {} : { error: check.error }),
+    };
+}

package/dist/src/commands/check.d.mts

@@ -1,4 +1,25 @@
 import type { CheckArgs } from "./check-args.mts";
+import type { CheckRunResult } from "./check-result.mts";
+import type { SuiteSource } from "../step-summary.mts";
+import type { DiffLineContent, LcovData } from "../types.mts";
+import type { CoverageCheckResult } from "../types.mts";
 export type { CheckArgs } from "./check-args.mts";
+export type { CheckRunResult } from "./check-result.mts";
+export type EvaluatedCheck = {
+    exitCode: number;
+    result: CoverageCheckResult | null;
+    suiteSources: SuiteSource[];
+    runUrl: string;
+    branch: string;
+    diffContent: DiffLineContent | null;
+    skippedReason?: string;
+    parsedSources: {
+        name: string;
+        lcov: LcovData;
+    }[];
+    warnings: string[];
+};
 export declare function main(argv: string[]): Promise<number>;
+export declare function checkCoverage(args: CheckArgs): Promise<CheckRunResult>;
+export declare function evaluateCheck(args: CheckArgs): Promise<EvaluatedCheck>;
 export declare function runCheck(args: CheckArgs): Promise<number>;