pr-checkmate 1.23.23 → 2.0.0

package/dist/core/install/ensure.js

@@ -0,0 +1,169 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.manifestDir = manifestDir;
+exports.ensureProfile = ensureProfile;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const execa_1 = require("../../utils/execa");
+const logger_1 = require("../../utils/logger");
+const cache_1 = require("./cache");
+const lock_1 = require("./lock");
+/** Where the shipped manifests live inside the installed package. */
+function manifestDir(profile) {
+    return node_path_1.default.resolve(__dirname, '../../..', 'install-manifests', profile);
+}
+const stampPath = (dir) => node_path_1.default.join(dir, '.pr-checkmate-installed');
+/** The manifest pair copied into the cache; `npm ci` reads exactly these two. */
+const MANIFEST_FILES = ['package.json', 'package-lock.json'];
+const LOCKFILE = MANIFEST_FILES[1];
+/**
+ * A fingerprint of the manifest a profile directory was installed from.
+ *
+ * Comparing the lockfile hash rather than merely checking that `node_modules`
+ * exists is what makes an upgrade correct: the cache path already includes our
+ * version, but a client can also pin a `cacheDir` shared between checkouts, and
+ * a half-written directory from an interrupted install must not read as ready.
+ */
+function manifestHash(dir) {
+    try {
+        const lock = node_fs_1.default.readFileSync(node_path_1.default.join(dir, LOCKFILE));
+        return node_crypto_1.default.createHash('sha256').update(lock).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether this profile directory already holds exactly this manifest, installed. */
+function isInstalled(dir, expected) {
+    if (!expected)
+        return false;
+    try {
+        return (node_fs_1.default.readFileSync(stampPath(dir), 'utf-8').trim() === expected &&
+            node_fs_1.default.existsSync(node_path_1.default.join(dir, 'node_modules')));
+    }
+    catch {
+        return false;
+    }
+}
+/** Copy the shipped manifest into the cache so `npm ci` has something to read. */
+function stageManifest(from, to) {
+    node_fs_1.default.mkdirSync(to, { recursive: true });
+    for (const file of MANIFEST_FILES) {
+        node_fs_1.default.copyFileSync(node_path_1.default.join(from, file), node_path_1.default.join(to, file));
+    }
+}
+/**
+ * Make one profile's tooling available, fetching it only if it is not already there.
+ *
+ * Idempotent by design: this is the single entry point for both the postinstall
+ * warm-up and the lazy path taken when postinstall never ran (`npm ci
+ * --ignore-scripts`, a `node_modules` restored from a CI cache). Two code paths
+ * for the same job is how the two drift apart and how one of them silently stops
+ * working.
+ *
+ * The install itself is a plain `npm ci` against a manifest we generated from our
+ * own lockfile, run from the client's repository so their `.npmrc`, registry and
+ * proxy settings apply unchanged. `--ignore-scripts` is not negotiable: we are a
+ * supply-chain tool, and running arbitrary install hooks from a security check
+ * would be indefensible. Integrity is npm's own, over the whole transitive tree —
+ * a tampered tarball aborts with `EINTEGRITY` rather than being installed.
+ */
+async function ensureProfile(profile, opts) {
+    const { install } = opts;
+    if (install.strategy === 'manual') {
+        return { profile, status: 'skipped', reason: 'install.strategy is "manual"' };
+    }
+    const source = manifestDir(profile);
+    const expected = manifestHash(source);
+    if (!expected) {
+        return { profile, status: 'failed', reason: `no shipped manifest for profile "${profile}"` };
+    }
+    const location = (0, cache_1.resolveCacheDir)(opts.version, install.cacheDir);
+    if (!location) {
+        return {
+            profile,
+            status: 'failed',
+            reason: 'no writable cache directory (tried the configured path, ~/.cache and the temp dir)',
+        };
+    }
+    const dir = (0, cache_1.profileDir)(location.dir, profile);
+    if (isInstalled(dir, expected)) {
+        return { profile, status: 'cached', reason: 'already installed', dir };
+    }
+    if (install.offline || process.env.PR_CHECKMATE_OFFLINE === 'true') {
+        return {
+            profile,
+            status: 'skipped',
+            reason: 'install.offline is set and the profile is not in the cache',
+            dir,
+        };
+    }
+    // The lock file lives in the profile directory, so the directory has to exist
+    // before there is anything to lock. Creating it inside `withLock` would put
+    // the creation itself outside the lock, which is the race it exists to close.
+    try {
+        node_fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+    catch (err) {
+        return { profile, status: 'failed', reason: `cannot create ${dir}: ${err.message}` };
+    }
+    const release = await (0, lock_1.withLock)(dir, install.waitTimeoutMs ?? 120000);
+    if (!release) {
+        return { profile, status: 'failed', reason: `cannot write to ${dir}`, dir };
+    }
+    try {
+        // Re-checked inside the lock: while we waited, the process we were waiting
+        // for probably did the work. Without this, waiting is pointless — every
+        // queued job would reinstall in turn.
+        if (isInstalled(dir, expected)) {
+            return { profile, status: 'cached', reason: 'installed by another process', dir };
+        }
+        return await runInstall(profile, source, dir, expected, opts);
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * The real fetch: `npm ci` against the staged manifest.
+ *
+ * Run from the repository under review so the client's `.npmrc` — registry,
+ * scopes, proxy, auth — is the one npm reads; we never substitute our own.
+ * `--ignore-scripts` is not negotiable in a supply-chain tool.
+ */
+async function npmCi(dir, opts) {
+    const result = await (0, execa_1.execa)('npm', ['ci', '--prefix', dir, '--ignore-scripts', '--no-audit', '--no-fund', '--loglevel', 'error'], { cwd: opts.cwd, reject: false, timeout: opts.install.installTimeoutMs ?? 300000 });
+    if (result.exitCode === 0)
+        return { ok: true };
+    const detail = (result.stderr || result.stdout || '').split('\n').slice(-3).join(' ').trim();
+    return { ok: false, detail: detail || `exit ${result.exitCode}` };
+}
+/** The fetch itself, once we hold the lock and know it is needed. */
+async function runInstall(profile, source, dir, expected, opts) {
+    const started = Date.now();
+    stageManifest(source, dir);
+    const count = Object.keys(JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(dir, LOCKFILE), 'utf-8')).packages).length;
+    // Always logged, never behind --debug: this is a security tool downloading
+    // code at run time, and that must be visible in every CI log by default.
+    logger_1.logger.info(`[install]: 📦 fetching profile "${profile}" (${count} packages) → ${dir}`);
+    try {
+        const install = opts.installer ?? ((target) => npmCi(target, opts));
+        const result = await install(dir);
+        if (!result.ok) {
+            return { profile, status: 'failed', reason: `npm ci failed: ${result.detail}`, dir };
+        }
+        node_fs_1.default.writeFileSync(stampPath(dir), expected);
+        const durationMs = Date.now() - started;
+        logger_1.logger.info(`[install]: ✅ profile "${profile}" ready in ${(durationMs / 1000).toFixed(1)}s`);
+        return { profile, status: 'installed', reason: `${count} packages`, dir, durationMs };
+    }
+    catch (err) {
+        // A timeout arrives here as a thrown error. It is a skip, not a crash: the
+        // rest of the run is still worth doing, and the affected checks say why.
+        return { profile, status: 'failed', reason: `npm ci failed: ${err.message}`, dir };
+    }
+}

package/dist/core/install/lock.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Whether the process named in a lock is still alive.
+ *
+ * Signal 0 performs the permission and existence checks without delivering
+ * anything. `EPERM` means the process exists but belongs to another user — alive,
+ * and not ours to override.
+ */
+export declare function processAlive(pid: number): boolean;
+/**
+ * Take the lock, waiting for whoever holds it.
+ *
+ * A held lock is not an error — it is the normal path when jobs run in parallel,
+ * and the right response is to wait and then use what the other process fetched.
+ * Waiting is announced and its progress printed: a silent wait is indistinguishable
+ * from a hang, and the whole point of the log is that a client can tell the
+ * difference at a glance.
+ *
+ * @param dir Profile directory to lock.
+ * @param timeoutMs How long to wait before taking the lock by force.
+ * @param deps Injected for tests: waiting, the clock, and how liveness of the
+ *   holding process is decided. The last one matters because `process.kill(pid, 0)`
+ *   is the one part whose answer depends on the operating system, and a test that
+ *   depends on it is a test that behaves differently on a CI runner than on the
+ *   machine it was written on.
+ * @returns A release function, or `null` when the lock could not be created at
+ *   all (an unwritable directory — the caller reports that, it is not fatal here).
+ */
+export interface LockDeps {
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    alive?: (pid: number) => boolean;
+}
+export declare function withLock(dir: string, timeoutMs: number, deps?: LockDeps): Promise<(() => void) | null>;

package/dist/core/install/lock.js

@@ -0,0 +1,99 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processAlive = processAlive;
+exports.withLock = withLock;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const logger_1 = require("../../utils/logger");
+const lockPath = (dir) => node_path_1.default.join(dir, '.pr-checkmate-install.lock');
+function readLock(file) {
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether the process named in a lock is still alive.
+ *
+ * Signal 0 performs the permission and existence checks without delivering
+ * anything. `EPERM` means the process exists but belongs to another user — alive,
+ * and not ours to override.
+ */
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+async function withLock(dir, timeoutMs, deps = {}) {
+    const sleep = deps.sleep ?? ((ms) => new Promise(r => setTimeout(r, ms)));
+    const now = deps.now ?? Date.now;
+    const alive = deps.alive ?? processAlive;
+    const file = lockPath(dir);
+    const deadline = now() + timeoutMs;
+    let announced = false;
+    for (;;) {
+        try {
+            const record = { pid: process.pid, startedAt: now(), host: 'local' };
+            node_fs_1.default.writeFileSync(file, JSON.stringify(record), { flag: 'wx' });
+            return () => {
+                try {
+                    node_fs_1.default.unlinkSync(file);
+                }
+                catch {
+                    // Already gone: another process broke a lock it believed to be stale.
+                    // Nothing to undo, and nothing worth failing a run over.
+                }
+            };
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                return null;
+        }
+        const held = readLock(file);
+        // A lock whose owner died — the job was cancelled, the container was killed —
+        // would otherwise block every later run forever. Breaking it needs to be
+        // loud: it is the one case where two installs could genuinely overlap.
+        if (held && !alive(held.pid)) {
+            logger_1.logger.warn(`[install]: ⚠️ removing a stale lock left by process ${held.pid}, which is no longer running.`);
+            try {
+                node_fs_1.default.unlinkSync(file);
+            }
+            catch {
+                // Someone else got there first; the next iteration will find it gone.
+            }
+            // Yield before retrying. Both `continue`s below used to loop straight back
+            // to `writeFileSync`, so an unlink that kept failing became a tight loop
+            // that never returned to the event loop: no output, no timer, no timeout
+            // — a process pegged at 100% until something killed it. A hang with no
+            // symptom is the worst failure mode this code could have.
+            await sleep(50);
+            continue;
+        }
+        if (now() >= deadline) {
+            logger_1.logger.warn(`[install]: ⚠️ waited ${Math.round(timeoutMs / 1000)}s for another process to finish installing — taking over.`);
+            try {
+                node_fs_1.default.unlinkSync(file);
+            }
+            catch {
+                // Same as above.
+            }
+            await sleep(50);
+            continue;
+        }
+        if (!announced) {
+            const age = held ? Math.round((now() - held.startedAt) / 1000) : 0;
+            logger_1.logger.info(`[install]: ⏳ another process is installing into ${node_path_1.default.basename(dir)} (started ${age}s ago) — waiting up to ${Math.round(timeoutMs / 1000)}s`);
+            announced = true;
+        }
+        await sleep(500);
+    }
+}

package/dist/core/install/profiles.d.ts

@@ -0,0 +1,64 @@
+import type { PRCheckMateConfig } from '../../interfaces';
+import type { Language, LanguageUsage } from '../../utils/detect-language';
+/**
+ * A named bundle of tooling, and the checks that stop working without it.
+ *
+ * The package ships ~233 MB of tooling, and no repository needs all of it: a
+ * Python service pays for the whole JavaScript toolchain, a repository with
+ * Spellcheck switched off still pays for cspell. Profiles are how that stops —
+ * they name which slice of the tooling a given repository actually needs.
+ *
+ * `checks` is not documentation. It is what turns a failed install into an
+ * honest report: when a profile is missing, exactly those checks skip, with the
+ * reason, instead of quietly disappearing (the mistake of ticket 057).
+ */
+interface Profile {
+    name: ProfileName;
+    /** Top-level packages installed for this profile. */
+    packages: string[];
+    /** Registry names of the checks that need it. */
+    checks: string[];
+    /**
+     * Languages that make this profile necessary. Absent for profiles driven by
+     * enabled checks rather than by what the repository is written in.
+     */
+    languages?: Language[];
+}
+export type ProfileName = 'core' | 'js' | 'python' | 'cpp' | 'spellcheck' | 'markdown' | 'commitlint' | 'duplicate';
+/**
+ * The catalogue.
+ *
+ * Sizes in the comments are measured exclusive footprints — what leaves with the
+ * profile and is shared with nothing else (see ticket 069).
+ */
+export declare const PROFILES: Profile[];
+/** The profile a check belongs to, or `undefined` when it needs no extra tooling. */
+export declare function profileForCheck(check: string): Profile | undefined;
+/** Why a profile is (or is not) part of this run — the answer `doctor` prints. */
+export interface ProfileDecision {
+    profile: ProfileName;
+    required: boolean;
+    reason: string;
+}
+/**
+ * Decide which profiles this repository needs, and why.
+ *
+ * The two inputs are deliberately different in kind:
+ *
+ * - **Languages are counted in files, never in markers.** A Python service that
+ *   installed us through npm has a `package.json`, which is a JavaScript marker
+ *   — and downloading 152 MB of JavaScript tooling because of the file that
+ *   installed us would be the whole feature backfiring. `LanguageUsage.files`
+ *   exists for exactly this (ticket 068).
+ * - **Universal profiles are driven by enabled checks**, so `severity: {
+ *   "Spellcheck": "off" }` starts saving bandwidth instead of only a report row.
+ *
+ * @param usage Detected languages with their tracked file counts.
+ * @param config The client's config; `install.profiles` and `install.excludeProfiles`
+ *   have the last word, in that order — an explicit exclusion beats an explicit
+ *   request, because it is the one that can be a hard requirement (air-gapped,
+ *   licence policy, a runner that must not download a wasm binary).
+ * @returns One decision per profile, in catalogue order.
+ */
+export declare function planProfiles(usage: LanguageUsage[], config: PRCheckMateConfig): ProfileDecision[];
+export {};

package/dist/core/install/profiles.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROFILES = void 0;
+exports.profileForCheck = profileForCheck;
+exports.planProfiles = planProfiles;
+/**
+ * The catalogue.
+ *
+ * Sizes in the comments are measured exclusive footprints — what leaves with the
+ * profile and is shared with nothing else (see ticket 069).
+ */
+exports.PROFILES = [
+    {
+        // Always installed. Everything here backs a check that runs on any
+        // repository whatever it is written in, so there is nothing to decide.
+        name: 'core',
+        packages: ['execa', 'yaml', 'inquirer', 'gitleaks-secret-scanner-fixed'],
+        checks: ['Security Scan'],
+    },
+    {
+        // 152 MB, the largest by far, and the one a Python repository pays for
+        // today with nothing to show for it.
+        name: 'js',
+        packages: [
+            'typescript',
+            'eslint',
+            'eslint-config-prettier',
+            'eslint-plugin-import-x',
+            'eslint-plugin-jsdoc',
+            'eslint-plugin-prettier',
+            'eslint-plugin-sonarjs',
+            '@typescript-eslint/eslint-plugin',
+            '@typescript-eslint/parser',
+            'prettier',
+            'dpdm',
+            'knip',
+            'ts-unused-exports',
+            'license-checker-rseidelsohn',
+        ],
+        checks: [
+            'ESLint',
+            'Prettier',
+            'TypeScript',
+            'Circular Deps',
+            'Dependencies',
+            'Dead Code',
+            'License Check',
+        ],
+        languages: ['typescript', 'javascript'],
+    },
+    {
+        name: 'python',
+        packages: ['@astral-sh/ruff-wasm-nodejs'],
+        checks: ['Ruff Lint', 'Ruff Format'],
+        languages: ['python'],
+    },
+    {
+        name: 'cpp',
+        packages: ['@wasm-fmt/clang-format'],
+        checks: ['C++ Format'],
+        languages: ['cpp'],
+    },
+    {
+        // The four below are not languages. They are single checks with heavy
+        // tooling behind them, which is exactly why they are separate: switching
+        // one off should stop costing megabytes, not just a line in the report.
+        name: 'spellcheck',
+        packages: ['cspell'],
+        checks: ['Spellcheck'],
+    },
+    {
+        name: 'markdown',
+        packages: ['markdownlint-cli2'],
+        checks: ['Markdown'],
+    },
+    {
+        name: 'commitlint',
+        packages: ['@commitlint/cli', '@commitlint/config-conventional'],
+        checks: ['Commitlint'],
+    },
+    {
+        name: 'duplicate',
+        packages: ['jscpd'],
+        checks: ['Duplicate Code'],
+    },
+];
+/** The profile a check belongs to, or `undefined` when it needs no extra tooling. */
+function profileForCheck(check) {
+    return exports.PROFILES.find(p => p.checks.includes(check));
+}
+/**
+ * A check counts as enabled unless it is switched off.
+ *
+ * Deliberately asymmetric with how the runner selects checks: this must not
+ * import the registry (that would drag every check into the install path), and
+ * being wrong in the "enabled" direction only costs a download, while being
+ * wrong the other way silently removes a check. So anything not explicitly off
+ * is treated as on.
+ */
+function isCheckEnabled(check, config) {
+    return config.severity?.[check] !== 'off';
+}
+/**
+ * Decide which profiles this repository needs, and why.
+ *
+ * The two inputs are deliberately different in kind:
+ *
+ * - **Languages are counted in files, never in markers.** A Python service that
+ *   installed us through npm has a `package.json`, which is a JavaScript marker
+ *   — and downloading 152 MB of JavaScript tooling because of the file that
+ *   installed us would be the whole feature backfiring. `LanguageUsage.files`
+ *   exists for exactly this (ticket 068).
+ * - **Universal profiles are driven by enabled checks**, so `severity: {
+ *   "Spellcheck": "off" }` starts saving bandwidth instead of only a report row.
+ *
+ * @param usage Detected languages with their tracked file counts.
+ * @param config The client's config; `install.profiles` and `install.excludeProfiles`
+ *   have the last word, in that order — an explicit exclusion beats an explicit
+ *   request, because it is the one that can be a hard requirement (air-gapped,
+ *   licence policy, a runner that must not download a wasm binary).
+ * @returns One decision per profile, in catalogue order.
+ */
+function planProfiles(usage, config) {
+    const install = config.install ?? {};
+    const minFiles = Math.max(1, install.minFilesPerLanguage ?? 1);
+    const requested = new Set(install.profiles ?? []);
+    const excluded = new Set(install.excludeProfiles ?? []);
+    return exports.PROFILES.map(profile => {
+        const decision = decide(profile, usage, config, minFiles);
+        if (excluded.has(profile.name)) {
+            return {
+                profile: profile.name,
+                required: false,
+                reason: 'excluded by install.excludeProfiles',
+            };
+        }
+        if (!decision.required && requested.has(profile.name)) {
+            return { profile: profile.name, required: true, reason: 'requested by install.profiles' };
+        }
+        return { profile: profile.name, required: decision.required, reason: decision.reason };
+    });
+}
+/** The automatic half of {@link planProfiles}, before the client's overrides. */
+function decide(profile, usage, config, minFiles) {
+    if (profile.name === 'core')
+        return { required: true, reason: 'always installed' };
+    if (profile.languages) {
+        const found = profile.languages
+            .map(lang => usage.find(u => u.lang === lang))
+            .filter((u) => Boolean(u) && u.files >= minFiles);
+        if (found.length > 0) {
+            const detail = found.map(u => `${u.files} ${u.lang} file(s)`).join(', ');
+            return { required: true, reason: detail };
+        }
+        // Named separately from "no files": a marker with no source files is the
+        // OctoBot case — a `Cargo.toml` beside zero `.rs`. The language is real
+        // enough to run checks for; it is not real enough to download a toolchain.
+        const markerOnly = profile.languages.some(lang => usage.some(u => u.lang === lang));
+        return {
+            required: false,
+            reason: markerOnly
+                ? 'declared by a marker file but no source files tracked'
+                : 'no source files tracked',
+        };
+    }
+    const enabled = profile.checks.filter(check => isCheckEnabled(check, config));
+    return enabled.length > 0
+        ? { required: true, reason: `${enabled.join(', ')} enabled` }
+        : { required: false, reason: `${profile.checks.join(', ')} switched off` };
+}

package/dist/core/registry.js

@@ -31,6 +31,7 @@ const python_typecheck_1 = require("./checks/languages/python-typecheck");
 const ruby_lint_1 = require("./checks/languages/ruby-lint");
 const rust_format_1 = require("./checks/languages/rust-format");
 const rust_lint_1 = require("./checks/languages/rust-lint");
+const shellcheck_1 = require("./checks/languages/shellcheck");
 const swift_lint_1 = require("./checks/languages/swift-lint");
 const typecheck_1 = require("./checks/languages/typecheck");
 const commitlint_1 = require("./checks/pr/commitlint");
@@ -45,6 +46,7 @@ const duplicate_check_1 = require("./checks/quality/duplicate-check");
 const license_header_1 = require("./checks/quality/license-header");
 const markdown_lint_1 = require("./checks/quality/markdown-lint");
 const spellcheck_1 = require("./checks/quality/spellcheck");
+const symlinks_1 = require("./checks/quality/symlinks");
 const yaml_lint_1 = require("./checks/quality/yaml-lint");
 const diff_security_1 = require("./checks/security/diff-security");
 const dockerfile_security_1 = require("./checks/security/dockerfile-security");
@@ -95,6 +97,7 @@ exports.REGISTRY = [
     markdown_lint_1.markdownLintCheck,
     spellcheck_1.spellcheckCheck,
     yaml_lint_1.yamlLintCheck,
+    symlinks_1.symlinksCheck,
     python_lint_1.pythonLintCheck,
     python_typecheck_1.pythonTypecheckCheck,
     dead_code_1.deadCodeCheck,
@@ -103,6 +106,7 @@ exports.REGISTRY = [
     go_lint_1.goLintCheck,
     rust_lint_1.rustLintCheck,
     ruby_lint_1.rubyLintCheck,
+    shellcheck_1.shellcheckCheck,
     // format
     prettier_1.prettierCheck,
     cpp_format_1.cppFormatCheck,

package/dist/core/reporters.d.ts

@@ -1,7 +1,18 @@
-import type { CheckReport, ReporterKind } from './types';
+import type { CheckReport, ReporterConfig, ReporterKind } from './types';
+/** Whether the comment reached the PR, so the caller can act on a failure. */
+export interface PostOutcome {
+    attempted: boolean;
+    ok: boolean;
+    error?: string;
+}
+export declare function buildMarkdownReport(report: CheckReport, cfg?: ReporterConfig): string;
 /**
  * Emit the report through the selected channel.
  * none: nothing · stdout: console table · github/gitlab/bitbucket: table +
  * upsert the PR/MR comment · auto: detect the platform from the environment.
+ *
+ * Returns whether the comment reached the PR, so `runChecks` can honour
+ * `reporter.onPostFailure` — for teams whose review process depends on the
+ * comment, a silently lost report is worse than a red build.
  */
-export declare function report(kind: ReporterKind, result: CheckReport): Promise<void>;
+export declare function report(kind: ReporterKind, result: CheckReport, cfg?: ReporterConfig): Promise<PostOutcome>;