coverage-check 0.7.1 → 0.8.0

package/README.md

@@ -162,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:
@@ -191,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
@@ -235,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                                                                                                |
@@ -251,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`
 
@@ -268,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                                                   |
@@ -289,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,
@@ -306,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",
@@ -321,8 +393,35 @@ 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",
   output: "./coverage-merged/lcov.info",

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>;

package/dist/src/commands/check.mjs

@@ -1,9 +1,10 @@
+// oxlint-disable max-lines -- check evaluation and CLI rendering share one pipeline
 import { readFileSync, writeFileSync } from "node:fs";
 import { parseLcov } from "../lcov-parser.mjs";
 import { mergeLcov } from "../lcov-merge.mjs";
 import { getChangedLines } from "../diff-parser.mjs";
 import { getChangedLineContent } from "../diff-parser-content.mjs";
-import { loadRules, buildChangedRules } from "../rules.mjs";
+import { loadRules, buildChangedRules, withIgnoredPaths } from "../rules.mjs";
 import { computePatchCoverage } from "../patch-coverage.mjs";
 import { computeCoverageDrop } from "../coverage-drop.mjs";
 import { collapseRanges, renderFailureComment } from "../report.mjs";
@@ -11,10 +12,16 @@ import { upsertComment } from "../github-comment.mjs";
 import { collectLcovFiles, buildStripPrefixes } from "../load-artifacts.mjs";
 import { writeSummary } from "../step-summary.mjs";
 import { parseCheckArgs } from "./check-args.mjs";
-import { warnNonContributing, printDropOutput, checkRequiredArtifacts } from "./check-output.mjs";
+import { checkHelp } from "./check-render.mjs";
+import { emptyResult, toJsonPayload } from "./check-result.mjs";
+import { missingRequiredArtifacts, nonContributingWarnings, printDropOutput, checkRequiredArtifacts, } from "./check-output.mjs";
 const stdout = (msg) => process.stdout.write(`${msg}\n`);
 const stderr = (msg) => process.stderr.write(`${msg}\n`);
 export async function main(argv) {
+    if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) {
+        stdout(checkHelp());
+        return 0;
+    }
     let args;
     try {
         args = parseCheckArgs(argv);
@@ -25,18 +32,50 @@ export async function main(argv) {
     }
     return runCheck(args);
 }
-export async function runCheck(args) {
+export async function checkCoverage(args) {
+    return toCheckRunResult(args, await evaluateCheck(args));
+}
+function toCheckRunResult(args, evaluated) {
+    const skippedReason = evaluated.skippedReason ?? null;
+    const skipped = evaluated.result === null &&
+        skippedReason !== null &&
+        skippedReason.startsWith("no coverage data found") &&
+        !(args.failOnEmpty ?? false);
+    return {
+        result: evaluated.result ?? (skipped ? emptyResult(true) : null),
+        exitCode: evaluated.exitCode,
+        advisory: args.advisory ?? false,
+        skipped,
+        error: skipped ? null : skippedReason,
+        warnings: skipped ? [`coverage-check: ${skippedReason}`] : evaluated.warnings,
+    };
+}
+export async function evaluateCheck(args) {
+    const branch = args.branch ?? "main";
+    const runUrl = process.env["GITHUB_SERVER_URL"] && process.env["GITHUB_RUN_ID"]
+        ? `${process.env["GITHUB_SERVER_URL"]}/${args.repo}/actions/runs/${process.env["GITHUB_RUN_ID"]}`
+        : "N/A";
+    const emptyEvaluation = (exitCode, skippedReason) => ({
+        exitCode,
+        result: null,
+        suiteSources: [],
+        runUrl,
+        branch,
+        diffContent: null,
+        skippedReason,
+        parsedSources: [],
+        warnings: [],
+    });
     let rules;
     try {
-        rules = loadRules(args.rules);
+        rules = withIgnoredPaths(loadRules(args.rules), args.ignorePaths);
     }
     catch (err) {
-        stderr(`coverage-check: failed to load rules: ${err}`);
-        return 2;
+        return emptyEvaluation(2, `failed to load rules: ${err}`);
+    }
+    if (missingRequiredArtifacts(args.artifacts, args.requireArtifacts ?? []).length > 0) {
+        return emptyEvaluation(2, "missing required coverage artifact");
     }
-    if (!checkRequiredArtifacts(args.artifacts, args.requireArtifacts ?? []))
-        return 2;
-    const branch = args.branch ?? "main";
     const stripPrefixes = buildStripPrefixes(args.stripPrefixes);
     const reports = [];
     const suiteSources = [];
@@ -59,20 +98,31 @@ export async function runCheck(args) {
     const freshLcovs = [];
     for (const f of lcovFiles) {
         const lcov = parseLcov(readFileSync(f, "utf8"), stripPrefixes);
-        reports.push(lcov);
         freshLcovs.push(lcov);
-        parsedSources.push({ name: `file '${f}'`, lcov });
+        if (!(args.aggregateArtifacts ?? false)) {
+            reports.push(lcov);
+            parsedSources.push({ name: `file '${f}'`, lcov });
+        }
     }
     if (freshLcovs.length > 0) {
+        const freshMerged = mergeLcov(freshLcovs);
+        if (args.aggregateArtifacts ?? false) {
+            reports.push(freshMerged);
+            parsedSources.push({
+                name: `aggregated artifacts under '${args.artifacts}'`,
+                lcov: freshMerged,
+            });
+        }
         suiteSources.push({
             suite: args.suite ?? "(current)",
             source: "fresh",
-            lcov: mergeLcov(freshLcovs),
+            lcov: freshMerged,
         });
     }
     if (reports.length === 0) {
-        stderr(`coverage-check: no coverage data found — skipping`);
-        return 0;
+        return emptyEvaluation(args.failOnEmpty ? 1 : 0, args.failOnEmpty
+            ? `no coverage data found under ${args.artifacts}`
+            : "no coverage data found — skipping");
     }
     const lcov = mergeLcov(reports);
     let diff;
@@ -87,10 +137,19 @@ export async function runCheck(args) {
         }
     }
     catch (err) {
-        stderr(`coverage-check: git diff failed: ${err}`);
-        return 2;
+        return {
+            exitCode: 2,
+            result: null,
+            suiteSources,
+            runUrl,
+            branch,
+            diffContent: null,
+            skippedReason: `git diff failed: ${err}`,
+            parsedSources,
+            warnings: [],
+        };
     }
-    warnNonContributing(parsedSources, diff);
+    const warnings = nonContributingWarnings(parsedSources, diff);
     let baseline = null;
     if (args.store !== null) {
         try {
@@ -104,7 +163,7 @@ export async function runCheck(args) {
             }
         }
         catch (err) {
-            stderr(`coverage-check: warning: failed to load baseline from store: ${String(err)}`);
+            warnings.push(`coverage-check: warning: failed to load baseline from store: ${String(err)}`);
         }
     }
     const { buckets, informational } = computePatchCoverage(diff, lcov, rules);
@@ -112,15 +171,79 @@ export async function runCheck(args) {
     const drops = computeCoverageDrop(lcov, baseline, rules, changedRules);
     const passed = buckets.every((b) => b.passed) && drops.every((d) => d.passed || d.skipped);
     const result = { buckets, drops, informational, passed };
-    if (args.json) {
-        writeFileSync(args.json, JSON.stringify(result, null, 2));
+    return {
+        exitCode: (args.advisory ?? false) || passed ? 0 : 1,
+        result,
+        suiteSources,
+        runUrl,
+        branch,
+        diffContent,
+        parsedSources,
+        warnings,
+    };
+}
+export async function runCheck(args) {
+    const evaluated = await evaluateCheck(args);
+    const check = toCheckRunResult(args, evaluated);
+    const jsonToStdout = args.json === "-";
+    if (evaluated.result === null) {
+        if (evaluated.skippedReason === "missing required coverage artifact") {
+            if (args.json)
+                writeJson(args.json, check);
+            checkRequiredArtifacts(args.artifacts, args.requireArtifacts);
+            return evaluated.exitCode;
+        }
+        if (args.json)
+            writeJson(args.json, check);
+        if (check.error !== null)
+            stderr(`coverage-check: ${check.error}`);
+        for (const warning of check.warnings)
+            stderr(warning);
+        return evaluated.exitCode;
     }
-    const runUrl = process.env["GITHUB_SERVER_URL"] && process.env["GITHUB_RUN_ID"]
-        ? `${process.env["GITHUB_SERVER_URL"]}/${args.repo}/actions/runs/${process.env["GITHUB_RUN_ID"]}`
-        : "N/A";
-    if (!passed) {
+    for (const warning of evaluated.warnings)
+        stderr(warning);
+    const result = evaluated.result;
+    const diffContent = evaluated.diffContent;
+    const passed = result.passed;
+    if (args.json)
+        writeJson(args.json, check);
+    if (!jsonToStdout)
+        printHumanResult(result, diffContent);
+    const summaryFile = args.summaryFile !== undefined
+        ? args.summaryFile
+        : (process.env["GITHUB_STEP_SUMMARY"] ?? null);
+    if (summaryFile) {
+        try {
+            writeSummary(summaryFile, evaluated.suiteSources, result, evaluated.runUrl, evaluated.branch);
+        }
+        catch (err) {
+            stderr(`coverage-check: failed to write step summary: ${err}`);
+            return 2;
+        }
+    }
+    if (args.pr !== null && args.repo) {
+        const body = passed ? "" : renderFailureComment(result, evaluated.runUrl);
+        try {
+            await upsertComment(body, args.repo, args.pr, passed, args.gh);
+        }
+        catch (err) {
+            stderr(`coverage-check: failed to post PR comment: ${err}`);
+        }
+    }
+    return evaluated.exitCode;
+}
+function writeJson(path, check) {
+    const json = `${JSON.stringify(toJsonPayload(check), null, 2)}\n`;
+    if (path === "-")
+        process.stdout.write(json);
+    else
+        writeFileSync(path, json);
+}
+function printHumanResult(result, diffContent) {
+    if (!result.passed) {
         stdout("\ncoverage-check: FAILED\n");
-        for (const bucket of buckets.filter((b) => !b.passed)) {
+        for (const bucket of result.buckets.filter((b) => !b.passed)) {
             /* 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} (${bucket.hit}/${bucket.coverable}) — threshold ${bucket.threshold}%`);
@@ -141,33 +264,11 @@ export async function runCheck(args) {
     }
     else {
         stdout("\ncoverage-check: PASSED\n");
-        for (const bucket of buckets) {
+        for (const bucket of result.buckets) {
             /* 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} ✓`);
         }
     }
-    printDropOutput(drops);
-    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 ? "" : renderFailureComment(result, runUrl);
-        try {
-            await upsertComment(body, args.repo, args.pr, passed, args.gh);
-        }
-        catch (err) {
-            stderr(`coverage-check: failed to post PR comment: ${err}`);
-        }
-    }
-    return (args.advisory ?? false) || passed ? 0 : 1;
+    printDropOutput(result.drops);
 }

package/dist/src/commands/prepare-artifacts.d.mts

@@ -0,0 +1,18 @@
+export type ExpectedSuite = {
+    job: string;
+    suite: string;
+};
+export type PrepareArtifactsArgs = {
+    artifacts: string;
+    expectedSuites: ExpectedSuite[];
+};
+export type PrepareArtifactsResult = {
+    message: string;
+    missing: string[];
+};
+export declare function parsePrepareArtifactsArgs(argv: string[]): PrepareArtifactsArgs;
+export declare function missingCoverageArtifacts(artifactsDir: string, expectedSuites: ExpectedSuite[]): string[];
+export declare function normalizeCoverageArtifacts(artifactsDir: string, expectedSuites: ExpectedSuite[]): string;
+export declare function prepareCoverageArtifacts(args: PrepareArtifactsArgs): PrepareArtifactsResult;
+export declare function runPrepareArtifacts(args: PrepareArtifactsArgs): number;
+export declare function main(argv: string[]): number;

package/dist/src/commands/prepare-artifacts.mjs

@@ -0,0 +1,105 @@
+import { existsSync, mkdirSync, renameSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+const stdout = (msg) => process.stdout.write(`${msg}\n`);
+const stderr = (msg) => process.stderr.write(`${msg}\n`);
+export function parsePrepareArtifactsArgs(argv) {
+    const args = {
+        artifacts: "./coverage-artifacts",
+        expectedSuites: [],
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const flag = argv[i];
+        const next = argv[i + 1];
+        const val = () => {
+            if (next === undefined || next.startsWith("--")) {
+                throw new Error(`${flag} requires a value`);
+            }
+            i++;
+            return next;
+        };
+        switch (flag) {
+            case "--artifacts":
+                args.artifacts = val();
+                break;
+            case "--expect-suite": {
+                const raw = val();
+                const eq = raw.indexOf("=");
+                if (eq <= 0 || eq === raw.length - 1) {
+                    throw new Error(`--expect-suite must be formatted as <job>=<suite>, got ${JSON.stringify(raw)}`);
+                }
+                args.expectedSuites.push({ job: raw.slice(0, eq), suite: raw.slice(eq + 1) });
+                break;
+            }
+            default:
+                throw new Error(`unknown flag: ${flag}`);
+        }
+    }
+    return args;
+}
+function expectedLcovPath(artifactsDir, suite) {
+    return join(artifactsDir, `coverage-${suite}`, "lcov.info");
+}
+export function missingCoverageArtifacts(artifactsDir, expectedSuites) {
+    const errors = [];
+    for (const { job, suite } of expectedSuites) {
+        if (!existsSync(expectedLcovPath(artifactsDir, suite))) {
+            errors.push(`Missing coverage artifact for ${job}: coverage-${suite}/lcov.info`);
+        }
+    }
+    return errors;
+}
+export function normalizeCoverageArtifacts(artifactsDir, expectedSuites) {
+    const rootLcovPath = join(artifactsDir, "lcov.info");
+    if (!existsSync(rootLcovPath))
+        return "Coverage artifact layout already uses named directories.";
+    if (expectedSuites.length === 0) {
+        return "No expected coverage suites configured; leaving root-level lcov.info unchanged.";
+    }
+    if (expectedSuites.length !== 1) {
+        const missingNamedSuites = missingCoverageArtifacts(artifactsDir, expectedSuites);
+        if (missingNamedSuites.length === 0) {
+            unlinkSync(rootLcovPath);
+            return "Removed duplicate root-level lcov.info (all expected named coverage artifacts already exist).";
+        }
+        throw new Error(`Root-level lcov.info is only valid for exactly one expected coverage suite; got ${expectedSuites.length}.`);
+    }
+    const suite = expectedSuites[0].suite;
+    const targetDir = join(artifactsDir, `coverage-${suite}`);
+    const targetPath = join(targetDir, "lcov.info");
+    if (existsSync(targetPath)) {
+        unlinkSync(rootLcovPath);
+        return `Removed duplicate root-level lcov.info (coverage-${suite}/lcov.info already present).`;
+    }
+    mkdirSync(targetDir, { recursive: true });
+    renameSync(rootLcovPath, targetPath);
+    return `Normalized root-level lcov.info to coverage-${suite}/lcov.info.`;
+}
+export function prepareCoverageArtifacts(args) {
+    const message = normalizeCoverageArtifacts(args.artifacts, args.expectedSuites);
+    return {
+        message,
+        missing: missingCoverageArtifacts(args.artifacts, args.expectedSuites),
+    };
+}
+export function runPrepareArtifacts(args) {
+    const result = prepareCoverageArtifacts(args);
+    stdout(result.message);
+    if (result.missing.length === 0) {
+        stdout("Coverage artifacts are complete.");
+        return 0;
+    }
+    for (const error of result.missing)
+        stderr(`::error::${error}`);
+    return 1;
+}
+export function main(argv) {
+    try {
+        return runPrepareArtifacts(parsePrepareArtifactsArgs(argv));
+    }
+    catch (error) {
+        /* c8 ignore next -- defensive fallback; local command errors throw Error instances */
+        const message = error instanceof Error ? error.message : String(error);
+        stderr(`coverage-check prepare-artifacts: ${message}`);
+        return 2;
+    }
+}

package/dist/src/coverage-check.d.mts

@@ -1,14 +1,18 @@
-export { runCheck } from "./commands/check.mts";
+export { checkCoverage, evaluateCheck, runCheck } from "./commands/check.mts";
 export { runStorePut } from "./commands/store-put.mts";
 export { runMerge } from "./commands/merge.mts";
+export { missingCoverageArtifacts, normalizeCoverageArtifacts, prepareCoverageArtifacts, runPrepareArtifacts, } from "./commands/prepare-artifacts.mts";
 export { FileSystemSuiteStore } from "./suite-store.mts";
 export { S3SuiteStore } from "./s3-suite-store.mts";
 export { parseDiffWithContent, getChangedLineContent } from "./diff-parser-content.mts";
 export { collapseRanges } from "./report.mts";
 export { parseLcovFull, mergeLcovFull, toLcovFull } from "./lcov-records.mts";
-export type { CheckArgs } from "./commands/check.mts";
+export { collectLcovFiles } from "./load-artifacts.mts";
+export { loadRules, zeroThresholdGlobs } from "./rules.mts";
+export type { CheckArgs, CheckRunResult, EvaluatedCheck } from "./commands/check.mts";
 export type { StorePutArgs } from "./commands/store-put.mts";
 export type { MergeArgs } from "./commands/merge.mts";
+export type { ExpectedSuite, PrepareArtifactsArgs, PrepareArtifactsResult, } from "./commands/prepare-artifacts.mts";
 export type { SuiteStore, SuiteMeta } from "./suite-store.mts";
 export type { S3SuiteStoreOptions } from "./s3-suite-store.mts";
 export { computeCoverageDrop } from "./coverage-drop.mts";

package/dist/src/coverage-check.mjs

@@ -1,9 +1,12 @@
-export { runCheck } from "./commands/check.mjs";
+export { checkCoverage, evaluateCheck, runCheck } from "./commands/check.mjs";
 export { runStorePut } from "./commands/store-put.mjs";
 export { runMerge } from "./commands/merge.mjs";
+export { missingCoverageArtifacts, normalizeCoverageArtifacts, prepareCoverageArtifacts, runPrepareArtifacts, } from "./commands/prepare-artifacts.mjs";
 export { FileSystemSuiteStore } from "./suite-store.mjs";
 export { S3SuiteStore } from "./s3-suite-store.mjs";
 export { parseDiffWithContent, getChangedLineContent } from "./diff-parser-content.mjs";
 export { collapseRanges } from "./report.mjs";
 export { parseLcovFull, mergeLcovFull, toLcovFull } from "./lcov-records.mjs";
+export { collectLcovFiles } from "./load-artifacts.mjs";
+export { loadRules, zeroThresholdGlobs } from "./rules.mjs";
 export { computeCoverageDrop } from "./coverage-drop.mjs";

package/dist/src/github-comment.mjs

@@ -1,4 +1,5 @@
 import { COMMENT_MARKER } from "./report.mjs";
+import { assertValidRepo } from "./suite-store.mjs";
 /* c8 ignore start */
 async function defaultGhRunner(args) {
     const { spawn } = await import("node:child_process");
@@ -43,17 +44,18 @@ async function findExistingComment(repo, pr, gh) {
  * - On pass with no prior comment: stays silent.
  */
 export async function upsertComment(body, repo, pr, passed, gh = defaultGhRunner) {
-    const existingId = await findExistingComment(repo, pr, gh);
+    const normalizedRepo = assertValidRepo(repo);
+    const existingId = await findExistingComment(normalizedRepo, pr, gh);
     if (passed && existingId === null)
         return;
     if (passed && existingId !== null) {
-        await gh(["api", `repos/${repo}/issues/comments/${existingId}`, "-X", "DELETE"]);
+        await gh(["api", `repos/${normalizedRepo}/issues/comments/${existingId}`, "-X", "DELETE"]);
         return;
     }
     if (existingId !== null) {
         await gh([
             "api",
-            `repos/${repo}/issues/comments/${existingId}`,
+            `repos/${normalizedRepo}/issues/comments/${existingId}`,
             "-X",
             "PATCH",
             "-f",
@@ -61,6 +63,6 @@ export async function upsertComment(body, repo, pr, passed, gh = defaultGhRunner
         ]);
     }
     else {
-        await gh(["api", `repos/${repo}/issues/${pr}/comments`, "-f", `body=${body}`]);
+        await gh(["api", `repos/${normalizedRepo}/issues/${pr}/comments`, "-f", `body=${body}`]);
     }
 }

package/dist/src/lcov-records.mjs

@@ -39,11 +39,20 @@ function applyRecord(line, cov) {
             cov.functionHits.set(name, (cov.functionHits.get(name) ?? 0) + hits);
     }
     else if (line.startsWith("BRDA:")) {
-        const parts = line.slice(5).split(",");
-        if (parts.length !== 4)
+        // Optimization: Instead of using `split(",")` which allocates an array, manually find commas
+        const c1 = line.indexOf(",", 5);
+        if (c1 === -1)
             return;
-        const key = `${parts[0]},${parts[1]},${parts[2]}`;
-        const raw = parts[3];
+        const c2 = line.indexOf(",", c1 + 1);
+        if (c2 === -1)
+            return;
+        const c3 = line.indexOf(",", c2 + 1);
+        if (c3 === -1)
+            return;
+        if (line.indexOf(",", c3 + 1) !== -1)
+            return;
+        const key = line.slice(5, c3);
+        const raw = line.slice(c3 + 1);
         const hits = raw === "-" ? 0 : parseInt(raw, 10);
         if (Number.isFinite(hits))
             cov.branches.set(key, (cov.branches.get(key) ?? 0) + hits);

package/dist/src/rules.d.mts

@@ -1,5 +1,9 @@
 import type { CoverageRule, DiffLines } from "./types.mts";
 export declare function loadRules(rulesPath: string): CoverageRule[];
+/** Returns path globs whose patch coverage threshold is exactly zero. */
+export declare function zeroThresholdGlobs(rulesPath: string): string[];
+/** Prepends zero-threshold rules for paths that should be ignored by this run. */
+export declare function withIgnoredPaths(rules: CoverageRule[], ignorePaths?: string[]): CoverageRule[];
 /** Returns the first matching rule for a repo-root-relative file path, or null. */
 export declare function matchRule(file: string, rules: CoverageRule[]): CoverageRule | null;
 /**

package/dist/src/rules.mjs

@@ -36,6 +36,16 @@ export function loadRules(rulesPath) {
     }
     return parsed.rules;
 }
+/** Returns path globs whose patch coverage threshold is exactly zero. */
+export function zeroThresholdGlobs(rulesPath) {
+    return loadRules(rulesPath).flatMap((rule) => rule.patch_coverage_min === 0 ? [rule.paths] : []);
+}
+/** Prepends zero-threshold rules for paths that should be ignored by this run. */
+export function withIgnoredPaths(rules, ignorePaths = []) {
+    if (ignorePaths.length === 0)
+        return rules;
+    return [...ignorePaths.map((paths) => ({ paths, patch_coverage_min: 0 })), ...rules];
+}
 /** Returns the first matching rule for a repo-root-relative file path, or null. */
 export function matchRule(file, rules) {
     for (const rule of rules) {

package/dist/src/s3-suite-store-reads.d.mts

@@ -12,6 +12,6 @@ type ReadContext = {
     sendS3(operation: string, key: string, command: object): Promise<unknown>;
 };
 export declare function getLegacy(ctx: ReadContext, suite: string): Promise<Buffer | null>;
-export declare function shouldWritePointer(ctx: ReadContext, suite: string, branch: string, incomingTimestamp: string): Promise<boolean>;
+export declare function shouldWritePointer(ctx: ReadContext, suite: string, encodedBranch: string, incomingTimestamp: string): Promise<boolean>;
 export declare function readPointer(ctx: ReadContext, suite: string, branch: string): Promise<StoredPointer>;
 export {};

package/dist/src/s3-suite-store-reads.mjs

@@ -16,8 +16,8 @@ export async function getLegacy(ctx, suite) {
         throw err;
     }
 }
-export async function shouldWritePointer(ctx, suite, branch, incomingTimestamp) {
-    const key = ctx.key(suite, "branch", encodeBranchName(branch), "latest.json");
+export async function shouldWritePointer(ctx, suite, encodedBranch, incomingTimestamp) {
+    const key = ctx.key(suite, "branch", encodedBranch, "latest.json");
     try {
         const resp = (await ctx.sendS3("get branch pointer for compare", key, new GetObjectCommand({
             Bucket: ctx.bucket,

package/dist/src/s3-suite-store.d.mts

@@ -4,7 +4,6 @@ export type S3SuiteStoreOptions = {
     bucket: string;
     prefix?: string;
     region?: string;
-    /** Inject a custom S3 client (e.g. for testing). */
     client?: ClientLike;
 };
 export declare class S3SuiteStore implements SuiteStore {

package/dist/src/s3-suite-store.mjs

@@ -63,6 +63,7 @@ export class S3SuiteStore {
         }
         const { sha, branch } = meta;
         assertSafePathComponent(sha, "sha");
+        const encodedBranch = encodeBranchName(branch);
         const ts = meta.timestamp ?? new Date().toISOString();
         assertValidTimestamp(ts);
         const payload = gzipSync(lcov);
@@ -74,7 +75,7 @@ export class S3SuiteStore {
             ContentEncoding: "gzip",
             ContentType: "text/plain",
         }), { rawBytes: lcov.byteLength, storedBytes: payload.byteLength });
-        if (!(await shouldWritePointer(this, suite, branch, ts)))
+        if (!(await shouldWritePointer(this, suite, encodedBranch, ts)))
             return;
         await this.putPointer(suite, branch, sha, ts, payloadKey, lcov.byteLength, payload.byteLength);
     }

package/dist/src/suite-store.d.mts

@@ -1,5 +1,6 @@
 import type { SuiteMeta } from "./types.mts";
 export declare function assertSafePathComponent(value: string, label: string): void;
+export declare function assertValidRepo(repo: string): string;
 export type { SuiteMeta };
 export type SuitePutMeta = {
     sha: string;

package/dist/src/suite-store.mjs

@@ -10,8 +10,27 @@ export function assertSafePathComponent(value, label) {
         throw new Error(`invalid ${label}: ${JSON.stringify(value)}`);
     }
 }
+export function assertValidRepo(repo) {
+    const trimmed = typeof repo === "string" ? repo.trim() : "";
+    if (trimmed.length === 0) {
+        throw new Error(`Invalid repository format: ${repo}. Expected owner/repo.`);
+    }
+    const parts = trimmed.split("/");
+    if (parts.length !== 2 ||
+        !/^[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(parts[0]) ||
+        !/^[A-Za-z0-9_.-]+$/.test(parts[1]) ||
+        parts[1] === "." ||
+        parts[1] === "..") {
+        throw new Error(`Invalid repository format: ${repo}. Expected owner/repo.`);
+    }
+    return trimmed;
+}
 export function encodeBranchName(branch) {
-    if (typeof branch !== "string" || branch.length === 0) {
+    if (typeof branch !== "string" ||
+        branch.length === 0 ||
+        branch === "." ||
+        branch.includes("..") ||
+        branch.includes("\\")) {
         throw new Error(`invalid branch: ${JSON.stringify(branch)}`);
     }
     return Buffer.from(branch, "utf8").toString("base64url");
@@ -91,10 +110,11 @@ export class FileSystemSuiteStore {
         }
         const { sha, branch } = meta;
         assertSafePathComponent(sha, "sha");
+        const encodedBranch = encodeBranchName(branch);
         const shaDir = join(this.root, suite, "sha", sha);
         mkdirSync(shaDir, { recursive: true });
         writeFileSync(join(shaDir, "lcov.info"), lcov);
-        const branchDir = join(this.root, suite, "branch", encodeBranchName(branch));
+        const branchDir = join(this.root, suite, "branch", encodedBranch);
         mkdirSync(branchDir, { recursive: true });
         const pointerPath = join(branchDir, "latest.json");
         const timestamp = meta.timestamp ?? new Date().toISOString();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coverage-check",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "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",
@@ -31,7 +31,7 @@
     "node": ">=22.0.0"
   },
   "dependencies": {
-    "@aws-sdk/client-s3": "^3.1048.0",
+    "@aws-sdk/client-s3": "3.1075.0",
     "@smithy/node-http-handler": "^4.7.7",
     "js-yaml": "^4.1.1",
     "monocart-coverage-reports": "^2.12.11"
@@ -41,7 +41,7 @@
     "@types/node": "^25.8.0",
     "@vitest/coverage-v8": "^4.1.6",
     "husky": "^9.1.7",
-    "oxfmt": "^0.52.0",
+    "oxfmt": "^0.53.0",
     "oxlint": "^1.65.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.6"