pr-checkmate 1.23.24 → 2.0.0

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

package/dist/core/reporters.js

@@ -3,9 +3,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMarkdownReport = buildMarkdownReport;
 exports.report = report;
 const node_fs_1 = __importDefault(require("node:fs"));
 const utils_1 = require("../utils");
+const http_1 = require("../utils/http");
 const STATUS_ICON = {
     pass: '✅',
     warn: '⚠️',
@@ -16,6 +18,9 @@ const STATUS_ICON = {
 const COMMENT_MARKER = '<!-- pr-checkmate-summary -->';
 const SUMMARY_BORDER = '═══════════════════════════════════════════════════════════════';
 const SUMMARY_RULE = '───────────────────────────────────────────────────────────────';
+/** Page size asked for everywhere; both GitHub and GitLab cap at 100. */
+const PER_PAGE = 100;
+const SKIPPED = { attempted: false, ok: true };
 function getPrContext() {
     const token = process.env.GITHUB_TOKEN;
     const repository = process.env.GITHUB_REPOSITORY;
@@ -35,14 +40,28 @@ function getPrContext() {
         return null;
     }
 }
-function buildMarkdownReport(report) {
+/** Rows the client wants in the PR comment. */
+function visibleResults(report, cfg) {
+    const include = cfg.include ?? {};
+    return report.results.filter(r => {
+        if (r.status === 'pass' && include.passed === false)
+            return false;
+        if (r.status === 'skip' && include.skipped === false)
+            return false;
+        return true;
+    });
+}
+function buildMarkdownReport(report, cfg = {}) {
     const { passed, warned, failed, skipped } = report.summary;
-    const rows = report.results
+    const include = cfg.include ?? {};
+    const rows = visibleResults(report, cfg);
+    const table = rows
         .map(r => {
-        const details = r.details ? ` — ${r.details}` : '';
+        const details = r.details && include.details !== false ? ` — ${r.details}` : '';
         return `| ${r.name} | ${STATUS_ICON[r.status]} ${r.status}${details} |`;
     })
         .join('\n');
+    const hidden = report.results.length - rows.length;
     return [
         COMMENT_MARKER,
         '## PR CheckMate Summary',
@@ -51,144 +70,156 @@ function buildMarkdownReport(report) {
         '',
         '| Check | Result |',
         '|---|---|',
-        rows,
+        table,
+        // Say so rather than letting the table quietly disagree with the counts above.
+        ...(hidden > 0 ? ['', `_${hidden} row(s) hidden by \`reporter.include\`._`] : []),
         '',
         '_Generated by [PR CheckMate](https://www.npmjs.com/package/pr-checkmate)_',
     ].join('\n');
 }
-function printStdout(report) {
+/**
+ * The run summary, printed verbatim.
+ *
+ * `logger.print` rather than `logger.info`: this is the product's output, not a
+ * note about producing it. Sent through the log formatter, every line picked up
+ * an ISO timestamp and a level tag, which pushed the box borders out of
+ * alignment — the headline artefact of the whole run looked broken.
+ */
+function printStdout(report, cfg) {
     const { passed, warned, failed, skipped } = report.summary;
-    utils_1.logger.info('');
-    utils_1.logger.info(SUMMARY_BORDER);
-    utils_1.logger.info('  PR CheckMate Summary');
-    utils_1.logger.info(SUMMARY_BORDER);
+    utils_1.logger.print('');
+    utils_1.logger.print(SUMMARY_BORDER);
+    utils_1.logger.print('  PR CheckMate Summary');
+    utils_1.logger.print(SUMMARY_BORDER);
     for (const r of report.results) {
         const details = r.details ? `: ${r.details}` : '';
-        utils_1.logger.info(`  ${STATUS_ICON[r.status]}  ${r.name}${details}`);
+        utils_1.logger.print(`  ${STATUS_ICON[r.status]}  ${r.name}${details}`);
+    }
+    utils_1.logger.print(SUMMARY_RULE);
+    utils_1.logger.print(`  ✅ ${passed} passed  ⚠️ ${warned} warnings  ❌ ${failed} failed  ⏭️ ${skipped} skipped`);
+    utils_1.logger.print(SUMMARY_BORDER);
+    if (cfg.include?.docsLink !== false) {
+        // The docs cover every check and config key.
+        utils_1.logger.print(' DOCUMENTATION: https://pr-checkmate-docs.pages.dev/');
+    }
+}
+/** Network settings shared by every platform call. */
+function httpOptions(cfg, label) {
+    return {
+        timeoutMs: cfg.timeoutMs,
+        retries: cfg.retries,
+        maxPages: cfg.maxPages,
+        label,
+    };
+}
+/** Log and shape the result of a write. */
+function finish(platform, res, verb) {
+    if (res.ok) {
+        utils_1.logger.info(`[reporter]: ✅ ${verb} PR CheckMate summary on ${platform}`);
+        return { attempted: true, ok: true };
     }
-    utils_1.logger.info(SUMMARY_RULE);
-    utils_1.logger.info(`  ✅ ${passed} passed  ⚠️ ${warned} warnings  ❌ ${failed} failed  ⏭️ ${skipped} skipped`);
-    utils_1.logger.info(SUMMARY_BORDER);
-    // Always shown under the report — the docs cover every check and config key.
-    utils_1.logger.info(' DOCUMENTATION: https://pr-checkmate-docs.pages.dev/');
+    utils_1.logger.warn(`[reporter]: ⚠️ Could not ${verb.toLowerCase()} ${platform} comment: ${res.error}`);
+    return { attempted: true, ok: false, error: res.error };
 }
-async function upsertGithubComment(body) {
+/** Page-number pagination: stop as soon as a page comes back short. */
+function pageAfter(base, count, page) {
+    return count < PER_PAGE ? null : `${base}${base.includes('?') ? '&' : '?'}page=${page + 1}`;
+}
+async function upsertGithubComment(body, cfg) {
     const ctx = getPrContext();
     if (!ctx) {
         utils_1.logger.info('[reporter]: Skipping GitHub comment (not in PR context or GITHUB_TOKEN missing)');
-        return;
+        return SKIPPED;
     }
     const { token, owner, repo, prNumber } = ctx;
     const apiBase = `https://api.github.com/repos/${owner}/${repo}`;
+    const listBase = `${apiBase}/issues/${prNumber}/comments?per_page=${PER_PAGE}`;
     const headers = {
         Authorization: `Bearer ${token}`,
         'User-Agent': 'pr-checkmate',
         Accept: 'application/vnd.github.v3+json',
         'Content-Type': 'application/json',
     };
-    try {
-        const listRes = await fetch(`${apiBase}/issues/${prNumber}/comments`, { headers });
-        if (listRes.ok) {
-            const comments = (await listRes.json());
-            const existing = comments.find(c => typeof c.body === 'string' && c.body.includes(COMMENT_MARKER));
-            if (existing) {
-                await fetch(`${apiBase}/issues/comments/${existing.id}`, {
-                    method: 'PATCH',
-                    headers,
-                    body: JSON.stringify({ body }),
-                });
-                utils_1.logger.info('[reporter]: ✅ Updated PR CheckMate comment on PR');
-                return;
-            }
-        }
-        await fetch(`${apiBase}/issues/${prNumber}/comments`, {
-            method: 'POST',
-            headers,
-            body: JSON.stringify({ body }),
-        });
-        utils_1.logger.info('[reporter]: ✅ Posted PR CheckMate summary comment to PR');
-    }
-    catch (err) {
-        utils_1.logger.warn(`[reporter]: ⚠️ Could not post GitHub comment: ${err}`);
+    const opts = httpOptions(cfg, 'GitHub');
+    const existing = await findExisting(listBase, { headers }, b => (Array.isArray(b) ? b : []), c => typeof c.body === 'string' && c.body.includes(COMMENT_MARKER), opts);
+    if (existing.reuse && cfg.mode !== 'append') {
+        const res = await (0, http_1.request)(`${apiBase}/issues/comments/${existing.reuse.id}`, { method: 'PATCH', headers, body: JSON.stringify({ body }) }, opts);
+        return finish('GitHub', res, 'Updated');
     }
+    const res = await (0, http_1.request)(`${apiBase}/issues/${prNumber}/comments`, { method: 'POST', headers, body: JSON.stringify({ body }) }, opts);
+    return finish('GitHub', res, 'Posted');
 }
 /**
- * Upsert a GitLab MR note (find our marker → update, else create). Uses the
- * standard CI variables plus a `GITLAB_TOKEN` with `api` scope. Skips gracefully
- * when not in an MR pipeline or the token is missing.
+ * Upsert a GitLab MR note. Uses the standard CI variables plus a `GITLAB_TOKEN`
+ * with `api` scope. Skips gracefully when not in an MR pipeline or the token is
+ * missing.
  */
-async function upsertGitlabNote(body) {
+async function upsertGitlabNote(body, cfg) {
     const base = process.env.CI_API_V4_URL;
     const project = process.env.CI_PROJECT_ID;
     const iid = process.env.CI_MERGE_REQUEST_IID;
     const token = process.env.GITLAB_TOKEN;
     if (!base || !project || !iid || !token) {
         utils_1.logger.info('[reporter]: Skipping GitLab note (not an MR pipeline or GITLAB_TOKEN missing)');
-        return;
+        return SKIPPED;
     }
     const notes = `${base}/projects/${project}/merge_requests/${iid}/notes`;
     const headers = { 'PRIVATE-TOKEN': token, 'Content-Type': 'application/json' };
-    try {
-        const listRes = await fetch(notes, { headers });
-        if (listRes.ok) {
-            const existing = (await listRes.json()).find(n => typeof n.body === 'string' && n.body.includes(COMMENT_MARKER));
-            if (existing) {
-                await fetch(`${notes}/${existing.id}`, {
-                    method: 'PUT',
-                    headers,
-                    body: JSON.stringify({ body }),
-                });
-                utils_1.logger.info('[reporter]: ✅ Updated PR CheckMate note on GitLab MR');
-                return;
-            }
-        }
-        await fetch(notes, { method: 'POST', headers, body: JSON.stringify({ body }) });
-        utils_1.logger.info('[reporter]: ✅ Posted PR CheckMate summary to GitLab MR');
-    }
-    catch (err) {
-        utils_1.logger.warn(`[reporter]: ⚠️ Could not post GitLab note: ${err}`);
+    const opts = httpOptions(cfg, 'GitLab');
+    const existing = await findExisting(`${notes}?per_page=${PER_PAGE}`, { headers }, b => (Array.isArray(b) ? b : []), n => typeof n.body === 'string' && n.body.includes(COMMENT_MARKER), opts);
+    if (existing.reuse && cfg.mode !== 'append') {
+        const res = await (0, http_1.request)(`${notes}/${existing.reuse.id}`, { method: 'PUT', headers, body: JSON.stringify({ body }) }, opts);
+        return finish('GitLab', res, 'Updated');
     }
+    const res = await (0, http_1.request)(notes, { method: 'POST', headers, body: JSON.stringify({ body }) }, opts);
+    return finish('GitLab', res, 'Posted');
 }
 /**
- * Upsert a Bitbucket PR comment (find our marker → update, else create). Uses
- * Bitbucket Pipelines variables plus a `BITBUCKET_TOKEN` (repo/PR write). Skips
- * gracefully when not in a PR pipeline or the token is missing.
+ * Upsert a Bitbucket PR comment. Uses Bitbucket Pipelines variables plus a
+ * `BITBUCKET_TOKEN` (repo/PR write). Skips gracefully when not in a PR pipeline
+ * or the token is missing.
  */
-async function upsertBitbucketComment(body) {
+async function upsertBitbucketComment(body, cfg) {
     const fullName = process.env.BITBUCKET_REPO_FULL_NAME;
     const prId = process.env.BITBUCKET_PR_ID;
     const token = process.env.BITBUCKET_TOKEN;
     if (!fullName || !prId || !token) {
         utils_1.logger.info('[reporter]: Skipping Bitbucket comment (not a PR pipeline or BITBUCKET_TOKEN missing)');
-        return;
+        return SKIPPED;
     }
     const commentsUrl = `https://api.bitbucket.org/2.0/repositories/${fullName}/pullrequests/${prId}/comments`;
     const headers = { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' };
-    try {
-        const listRes = await fetch(`${commentsUrl}?pagelen=100`, { headers });
-        if (listRes.ok) {
-            const values = (await listRes.json()).values;
-            const existing = values?.find(c => c.content?.raw?.includes(COMMENT_MARKER));
-            if (existing) {
-                await fetch(`${commentsUrl}/${existing.id}`, {
-                    method: 'PUT',
-                    headers,
-                    body: JSON.stringify({ content: { raw: body } }),
-                });
-                utils_1.logger.info('[reporter]: ✅ Updated PR CheckMate comment on Bitbucket PR');
-                return;
-            }
-        }
-        await fetch(commentsUrl, {
-            method: 'POST',
-            headers,
-            body: JSON.stringify({ content: { raw: body } }),
-        });
-        utils_1.logger.info('[reporter]: ✅ Posted PR CheckMate summary to Bitbucket PR');
+    const opts = httpOptions(cfg, 'Bitbucket');
+    const existing = await findExisting(`${commentsUrl}?pagelen=${PER_PAGE}`, { headers }, b => b?.values ?? [], c => Boolean(c.content?.raw?.includes(COMMENT_MARKER)), opts, 
+    // Bitbucket is cursor-paginated: the next page is a URL in the body.
+    b => b?.next ?? null);
+    if (existing.reuse && cfg.mode !== 'append') {
+        const res = await (0, http_1.request)(`${commentsUrl}/${existing.reuse.id}`, { method: 'PUT', headers, body: JSON.stringify({ content: { raw: body } }) }, opts);
+        return finish('Bitbucket', res, 'Updated');
     }
-    catch (err) {
-        utils_1.logger.warn(`[reporter]: ⚠️ Could not post Bitbucket comment: ${err}`);
+    const res = await (0, http_1.request)(commentsUrl, { method: 'POST', headers, body: JSON.stringify({ content: { raw: body } }) }, opts);
+    return finish('Bitbucket', res, 'Posted');
+}
+/**
+ * Search every page of a comment thread for our own marker.
+ *
+ * Reading only the first page is what turned the upsert into an insert: with 30
+ * comments per page on GitHub and 20 on GitLab, an actively reviewed PR pushed
+ * the marker past the end and each new push added another summary.
+ */
+async function findExisting(listUrl, init, extract, matches, opts, cursorNext) {
+    const base = listUrl;
+    const result = await (0, http_1.paginate)(listUrl, init, extract, (body, page, count) => (cursorNext ? cursorNext(body) : pageAfter(base, count, page)), opts);
+    if (!result.ok) {
+        // A failed search is not a failed post: fall through and create a comment.
+        // A duplicate is a far smaller problem than no report at all.
+        utils_1.logger.warn(`[reporter]: ⚠️ Could not read existing comments (${result.error}) — will create`);
     }
+    if (result.truncated) {
+        utils_1.logger.warn('[reporter]: ⚠️ Stopped searching comments at the page limit — a duplicate summary is ' +
+            'possible (raise reporter.maxPages)');
+    }
+    return { reuse: result.items.find(matches) ?? null };
 }
 /** Detect the CI platform from the environment, or null when unknown/local. */
 function detectPlatform() {
@@ -201,26 +232,36 @@ function detectPlatform() {
     return null;
 }
 /** Post the markdown report to a specific platform's PR/MR. */
-async function postToPlatform(platform, result) {
-    const body = buildMarkdownReport(result);
+async function postToPlatform(platform, result, cfg) {
+    const body = buildMarkdownReport(result, cfg);
     if (platform === 'github')
-        return upsertGithubComment(body);
+        return upsertGithubComment(body, cfg);
     if (platform === 'gitlab')
-        return upsertGitlabNote(body);
-    return upsertBitbucketComment(body);
+        return upsertGitlabNote(body, cfg);
+    return upsertBitbucketComment(body, cfg);
 }
 /**
  * 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.
  */
-async function report(kind, result) {
+async function report(kind, result, cfg = {}) {
     if (kind === 'none')
-        return;
-    printStdout(result);
+        return SKIPPED;
+    printStdout(result, cfg);
     if (result.results.length === 0)
-        return;
+        return SKIPPED;
+    // Nothing to say and nothing wrong: don't notify every PR subscriber.
+    if (cfg.skipWhenClean && result.summary.failed === 0 && result.summary.warned === 0) {
+        utils_1.logger.info('[reporter]: Nothing to report (skipWhenClean)');
+        return SKIPPED;
+    }
     const platform = kind === 'auto' ? detectPlatform() : kind === 'stdout' ? null : kind;
-    if (platform)
-        await postToPlatform(platform, result);
+    if (!platform)
+        return SKIPPED;
+    return postToPlatform(platform, result, cfg);
 }