coverage-check 0.2.1 → 0.2.2

package/README.md

@@ -52,9 +52,11 @@ The `--suite` flag on `check` tells the tool to use fresh `--artifacts` for the
 
 ```text
 <prefix>/<suite>/sha/<sha>/lcov.info          # payload
-<prefix>/<suite>/branch/<branch>/latest.json  # pointer: { "sha": "...", "timestamp": "..." }
+<prefix>/<suite>/branch/<encoded-branch>/latest.json  # pointer: { "sha": "...", "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.
+
 ### Suite store with filesystem
 
 For local development or simpler deployments:
@@ -122,7 +124,7 @@ Rules are matched in order; the first match wins. Files in the diff not matched
 | `--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 `\\`)                        |
+| `--branch`       | `"main"`               | Branch pointer to follow when reading from the store                                         |
 | `--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                                                       |
@@ -137,13 +139,15 @@ Rules are matched in order; the first match wins. Files in the diff not matched
 | `--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`)                     |
+| `--sha`          | —                      | Git SHA to associate with this coverage payload               |
+| `--branch`       | —                      | Branch name for the pointer (e.g. `main` or `feature/foo`)    |
 | `--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.
 
+When `--sha` and `--branch` are both provided, `store-put` writes a SHA-addressed payload and advances the branch pointer only if the incoming timestamp is not older than the current pointer. Omitting both flags preserves the legacy `<suite>/lcov.info` storage layout.
+
 ## Programmatic API
 
 ```ts
@@ -194,7 +198,7 @@ class MyCustomStore implements SuiteStore {
   async put(
     suite: string,
     lcov: Buffer,
-    meta: { sha: string; branch: string; timestamp?: string },
+    meta?: { sha: string; branch: string; timestamp?: string },
   ): Promise<void> {
     /* ... */
   }

package/bin/coverage-check.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../dist/src/cli.mjs";
+/* c8 ignore next */
+process.exit(await main(process.argv.slice(2)));

package/dist/src/cli.d.mts

@@ -0,0 +1 @@
+export declare function main(argv: string[]): Promise<number>;

package/dist/src/cli.mjs

@@ -0,0 +1,14 @@
+import { main as checkMain } from "./commands/check.mjs";
+import { main as storePutMain } from "./commands/store-put.mjs";
+const stderr = (msg) => process.stderr.write(`${msg}\n`);
+export async function main(argv) {
+    const sub = argv[0];
+    if (!sub || sub.startsWith("-"))
+        return checkMain(argv);
+    if (sub === "check")
+        return checkMain(argv.slice(1));
+    if (sub === "store-put")
+        return storePutMain(argv.slice(1));
+    stderr(`coverage-check: unknown subcommand: ${JSON.stringify(sub)}`);
+    return 2;
+}

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

@@ -0,0 +1,20 @@
+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 declare function parseCheckArgs(argv: string[]): CheckArgs;

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

@@ -0,0 +1,89 @@
+import { makeStore } from "../store-factory.mjs";
+import { assertSafePathComponent } from "../suite-store.mjs";
+export function parseCheckArgs(argv) {
+    let storeFs = null;
+    let storeS3 = null;
+    const args = {
+        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 = () => {
+            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 branch = val();
+                if (branch.length === 0)
+                    throw new Error(`invalid branch: ${JSON.stringify(branch)}`);
+                args.branch = branch;
+                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/dist/src/commands/check.d.mts

@@ -0,0 +1,4 @@
+import type { CheckArgs } from "./check-args.mts";
+export type { CheckArgs } from "./check-args.mts";
+export declare function main(argv: string[]): Promise<number>;
+export declare function runCheck(args: CheckArgs): Promise<number>;

package/dist/src/commands/check.mjs

@@ -0,0 +1,128 @@
+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 { loadRules } from "../rules.mjs";
+import { computePatchCoverage } from "../patch-coverage.mjs";
+import { collapseRanges, renderFailureComment } from "../report.mjs";
+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";
+const stdout = (msg) => process.stdout.write(`${msg}\n`);
+const stderr = (msg) => process.stderr.write(`${msg}\n`);
+export async function main(argv) {
+    let args;
+    try {
+        args = parseCheckArgs(argv);
+    }
+    catch (err) {
+        stderr(`coverage-check: ${String(err)}`);
+        return 2;
+    }
+    return runCheck(args);
+}
+export async function runCheck(args) {
+    let rules;
+    try {
+        rules = loadRules(args.rules);
+    }
+    catch (err) {
+        stderr(`coverage-check: failed to load rules: ${err}`);
+        return 2;
+    }
+    const branch = args.branch ?? "main";
+    const stripPrefixes = buildStripPrefixes(args.stripPrefixes);
+    const reports = [];
+    const suiteSources = [];
+    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, { branch });
+            if (buf !== null) {
+                const lcov = parseLcov(buf.toString("utf8"), stripPrefixes);
+                reports.push(lcov);
+                suiteSources.push({ suite, source: "store", lcov });
+            }
+        }
+    }
+    const lcovFiles = collectLcovFiles(args.artifacts);
+    const freshLcovs = [];
+    for (const f of lcovFiles) {
+        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) {
+        stderr(`coverage-check: no coverage data found — skipping`);
+        return 0;
+    }
+    const lcov = mergeLcov(reports);
+    let diff;
+    try {
+        diff = await getChangedLines(args.base, args.head);
+    }
+    catch (err) {
+        stderr(`coverage-check: git diff failed: ${err}`);
+        return 2;
+    }
+    const { buckets, informational } = computePatchCoverage(diff, lcov, rules);
+    const passed = buckets.every((b) => b.passed);
+    const result = { buckets, informational, passed };
+    if (args.json) {
+        writeFileSync(args.json, JSON.stringify(result, null, 2));
+    }
+    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) {
+        stdout("\ncoverage-check: FAILED\n");
+        for (const bucket of 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}%`);
+            for (const file of bucket.files.filter((f) => f.uncoveredLines.length > 0)) {
+                stdout(`    ${file.file}: ${collapseRanges(file.uncoveredLines)}`);
+            }
+        }
+    }
+    else {
+        stdout("\ncoverage-check: PASSED\n");
+        for (const bucket of 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} ✓`);
+        }
+    }
+    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 passed ? 0 : 1;
+}

package/dist/src/commands/store-put.d.mts

@@ -0,0 +1,11 @@
+import type { SuiteStore } from "../suite-store.mts";
+export type StorePutArgs = {
+    suite: string;
+    store: SuiteStore;
+    artifacts: string;
+    stripPrefixes: string[];
+    sha?: string;
+    branch?: string;
+};
+export declare function main(argv: string[]): Promise<number>;
+export declare function runStorePut(args: StorePutArgs): Promise<number>;

package/dist/src/commands/store-put.mjs

@@ -0,0 +1,104 @@
+import { readFileSync } from "node:fs";
+import { parseLcov } from "../lcov-parser.mjs";
+import { mergeLcov, toLcov } from "../lcov-merge.mjs";
+import { collectLcovFiles, buildStripPrefixes } from "../load-artifacts.mjs";
+import { makeStore } from "../store-factory.mjs";
+import { assertSafePathComponent } from "../suite-store.mjs";
+const stdout = (msg) => process.stdout.write(`${msg}\n`);
+const stderr = (msg) => process.stderr.write(`${msg}\n`);
+function parseArgs(argv) {
+    let storeFs = null;
+    let storeS3 = null;
+    const args = {
+        suite: "",
+        artifacts: "./coverage-artifacts",
+        stripPrefixes: [],
+        sha: undefined,
+        branch: undefined,
+    };
+    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 "--suite":
+                args.suite = val();
+                break;
+            case "--store":
+            case "--store-fs":
+                storeFs = val();
+                break;
+            case "--store-s3":
+                storeS3 = val();
+                break;
+            case "--artifacts":
+                args.artifacts = val();
+                break;
+            case "--strip-prefix":
+                args.stripPrefixes.push(val());
+                break;
+            case "--sha":
+                args.sha = val();
+                break;
+            case "--branch":
+                args.branch = val();
+                break;
+            default:
+                throw new Error(`unknown flag: ${flag}`);
+        }
+    }
+    if (!args.suite)
+        throw new Error("--suite is required");
+    if (storeFs && storeS3)
+        throw new Error("--store-fs and --store-s3 are mutually exclusive");
+    if (!storeFs && !storeS3)
+        throw new Error("--store-fs/--store or --store-s3 is required");
+    const hasSha = args.sha !== undefined;
+    const hasBranch = args.branch !== undefined;
+    if (hasSha !== hasBranch) {
+        throw new Error("--sha and --branch must be provided together");
+    }
+    assertSafePathComponent(args.suite, "suite");
+    if (args.sha !== undefined)
+        assertSafePathComponent(args.sha, "sha");
+    if (args.branch !== undefined && args.branch.length === 0) {
+        throw new Error(`invalid branch: ${JSON.stringify(args.branch)}`);
+    }
+    const store = makeStore({ fs: storeFs, s3: storeS3 });
+    return { ...args, store };
+}
+export async function main(argv) {
+    let args;
+    try {
+        args = parseArgs(argv);
+    }
+    catch (err) {
+        stderr(`coverage-check store-put: ${String(err)}`);
+        return 2;
+    }
+    return runStorePut(args);
+}
+export async function runStorePut(args) {
+    const lcovFiles = collectLcovFiles(args.artifacts);
+    if (lcovFiles.length === 0) {
+        stderr(`coverage-check store-put: no lcov.info files found under ${args.artifacts}`);
+        return 2;
+    }
+    const stripPrefixes = buildStripPrefixes(args.stripPrefixes);
+    const reports = lcovFiles.map((f) => parseLcov(readFileSync(f, "utf8"), stripPrefixes));
+    const merged = mergeLcov(reports);
+    const lcovText = toLcov(merged);
+    const meta = args.sha !== undefined && args.branch !== undefined
+        ? { sha: args.sha, branch: args.branch }
+        : undefined;
+    await args.store.put(args.suite, Buffer.from(lcovText, "utf8"), meta);
+    const metaLabel = args.sha !== undefined ? ` sha=${args.sha} branch=${args.branch}` : "";
+    stdout(`coverage-check store-put: stored suite "${args.suite}" (${lcovFiles.length} file(s))${metaLabel}`);
+    return 0;
+}

package/{src/coverage-check.mts → dist/src/coverage-check.d.mts}

@@ -2,16 +2,8 @@ export { runCheck } from "./commands/check.mts";
 export { runStorePut } from "./commands/store-put.mts";
 export { FileSystemSuiteStore } from "./suite-store.mts";
 export { S3SuiteStore } from "./s3-suite-store.mts";
-
 export type { CheckArgs } from "./commands/check.mts";
 export type { StorePutArgs } from "./commands/store-put.mts";
 export type { SuiteStore, SuiteMeta } from "./suite-store.mts";
 export type { S3SuiteStoreOptions } from "./s3-suite-store.mts";
-export type {
-  CoverageCheckResult,
-  BucketResult,
-  FileCoverageResult,
-  LcovData,
-  DiffLines,
-  CoverageRule,
-} from "./types.mts";
+export type { CoverageCheckResult, BucketResult, FileCoverageResult, LcovData, DiffLines, CoverageRule, } from "./types.mts";

package/dist/src/coverage-check.mjs

@@ -0,0 +1,4 @@
+export { runCheck } from "./commands/check.mjs";
+export { runStorePut } from "./commands/store-put.mjs";
+export { FileSystemSuiteStore } from "./suite-store.mjs";
+export { S3SuiteStore } from "./s3-suite-store.mjs";

package/dist/src/diff-parser.d.mts

@@ -0,0 +1,17 @@
+import type { DiffLines } from "./types.mts";
+/**
+ * Decodes a git C-string (inner content between surrounding double-quotes).
+ * Git quotes unusual paths (non-ASCII, spaces, etc.) with core.quotePath=true.
+ * Handles octal byte escapes (\nnn), \\, \", \n, \t.
+ */
+export declare function decodeGitCString(s: string): string;
+/**
+ * Parses the output of `git diff --unified=0` into a map of
+ * repo-root-relative file path → set of added/modified line numbers.
+ *
+ * Only added lines (lines in the new version) are tracked. Deleted-only
+ * hunks (where the `+` count is 0) are skipped.
+ */
+export declare function parseDiff(text: string): DiffLines;
+/** Runs git diff and returns the parsed result. */
+export declare function getChangedLines(baseRef: string, headRef: string): Promise<DiffLines>;

package/dist/src/diff-parser.mjs

@@ -0,0 +1,127 @@
+/**
+ * Decodes a git C-string (inner content between surrounding double-quotes).
+ * Git quotes unusual paths (non-ASCII, spaces, etc.) with core.quotePath=true.
+ * Handles octal byte escapes (\nnn), \\, \", \n, \t.
+ */
+export function decodeGitCString(s) {
+    const bytes = [];
+    for (let i = 0; i < s.length;) {
+        if (s[i] === "\\" && i + 1 < s.length) {
+            const next = s[i + 1];
+            if (next >= "0" && next <= "7") {
+                bytes.push(parseInt(s.slice(i + 1, i + 4), 8));
+                i += 4;
+            }
+            else if (next === "\\") {
+                bytes.push(92);
+                i += 2;
+            }
+            else if (next === '"') {
+                bytes.push(34);
+                i += 2;
+            }
+            else if (next === "n") {
+                bytes.push(10);
+                i += 2;
+            }
+            else if (next === "t") {
+                bytes.push(9);
+                i += 2;
+            }
+            else {
+                bytes.push(s.charCodeAt(i));
+                i++;
+            }
+        }
+        else {
+            bytes.push(s.charCodeAt(i));
+            i++;
+        }
+    }
+    return Buffer.from(new Uint8Array(bytes)).toString("utf8");
+}
+/**
+ * Parses the output of `git diff --unified=0` into a map of
+ * repo-root-relative file path → set of added/modified line numbers.
+ *
+ * Only added lines (lines in the new version) are tracked. Deleted-only
+ * hunks (where the `+` count is 0) are skipped.
+ */
+export function parseDiff(text) {
+    const result = new Map();
+    let currentLines = null;
+    let inHeader = false;
+    for (const raw of text.split("\n")) {
+        const line = raw.trimEnd();
+        // Only parse +++ as a file header when we are in the diff header block
+        // (after `diff --git` / `---`). Without this guard a source line beginning
+        // with `++ b/` would appear as `+++ b/…` in the diff and be misclassified.
+        let newFilePath = null;
+        if (inHeader) {
+            if (line.startsWith("+++ b/")) {
+                newFilePath = line.slice(6);
+            }
+            else if (line.startsWith('+++ "b/') && line.endsWith('"')) {
+                newFilePath = decodeGitCString(line.slice(5, -1)).slice(2);
+            }
+        }
+        if (newFilePath !== null) {
+            inHeader = false;
+            const path = newFilePath;
+            if (path === "dev/null") {
+                currentLines = null;
+                continue;
+            }
+            currentLines = result.get(path) ?? new Set();
+            result.set(path, currentLines);
+        }
+        else if (line.startsWith("--- ")) {
+            // ignore (part of diff header)
+        }
+        else if (line.startsWith("@@ ") && currentLines !== null) {
+            // @@ -old_start[,old_count] +new_start[,new_count] @@
+            const match = line.match(/@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/);
+            if (!match)
+                continue;
+            const newStart = parseInt(match[1], 10);
+            const newCount = match[2] !== undefined ? parseInt(match[2], 10) : 1;
+            if (newCount === 0)
+                continue;
+            for (let i = 0; i < newCount; i++) {
+                currentLines.add(newStart + i);
+            }
+        }
+        else if (line.startsWith("diff --git ")) {
+            currentLines = null;
+            inHeader = true;
+        }
+    }
+    return result;
+}
+/** Runs git diff and returns the parsed result. */
+export async function getChangedLines(baseRef, headRef) {
+    const { spawn } = await import("node:child_process");
+    const spawnProcess = (cmd, args) => new Promise((resolve, reject) => {
+        const chunks = [];
+        const proc = spawn(cmd, args, { stdio: ["ignore", "pipe", "inherit"] });
+        proc.stdout.on("data", (chunk) => chunks.push(chunk));
+        proc.on("error", reject);
+        proc.on("close", (code) => code === 0
+            ? resolve(Buffer.concat(chunks).toString("utf8"))
+            : reject(new Error(`${cmd} exited with code ${code}`)));
+    });
+    const mergeBase = await spawnProcess("git", ["merge-base", baseRef, headRef]);
+    const base = mergeBase.trim();
+    // --src-prefix/--dst-prefix override diff.noprefix and diff.mnemonicPrefix git config
+    const diff = await spawnProcess("git", [
+        "diff",
+        "--unified=0",
+        "--inter-hunk-context=0",
+        "--no-color",
+        "--src-prefix=a/",
+        "--dst-prefix=b/",
+        base,
+        headRef,
+    ]);
+    return parseDiff(diff);
+}

package/dist/src/github-comment.d.mts

@@ -0,0 +1,9 @@
+export type GhRunner = (args: string[]) => Promise<string>;
+/**
+ * Posts or updates the sticky coverage-check comment on a pull request.
+ *
+ * - On failure: upserts the failure comment body (POST if absent, PATCH if exists).
+ * - On pass with prior comment: deletes the prior comment.
+ * - On pass with no prior comment: stays silent.
+ */
+export declare function upsertComment(body: string, repo: string, pr: number, passed: boolean, gh?: GhRunner): Promise<void>;