pr-checkmate 3.0.4 → 3.2.0

package/dist/esm/core/install/reuse.js

@@ -0,0 +1,100 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { logger } from '../../utils/logger.js';
+import { ownPackageRoot } from '../../utils/resolve-bin.js';
+/**
+ * The major version we declare for a tool, from our own manifest.
+ *
+ * Read from `dependencies` rather than from the installed tree: what matters is
+ * the version our configuration was written against, and a hoisted install can
+ * resolve to something else entirely.
+ */
+function ownMajor(pkgName) {
+    try {
+        const manifest = path.join(ownPackageRoot(), 'package.json');
+        const deps = JSON.parse(fs.readFileSync(manifest, 'utf-8')).dependencies;
+        const range = deps?.[pkgName];
+        if (!range)
+            return null;
+        // `^10.6.0`, `>=3.0.0`, `~5.1` — the leading number is the major in every
+        // form we declare. Deliberately not a semver parser: this package ships zero
+        // runtime dependencies on purpose, and a major comparison is the only
+        // question being asked.
+        const major = /(\d+)/.exec(range)?.[1];
+        return major ? Number(major) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The major version of a package as the client actually has it installed. */
+function installedMajor(pkgName, from) {
+    let dir = from;
+    while (dir !== path.dirname(dir)) {
+        const manifest = path.join(dir, 'node_modules', pkgName, 'package.json');
+        try {
+            if (fs.existsSync(manifest)) {
+                const version = JSON.parse(fs.readFileSync(manifest, 'utf-8'))
+                    .version;
+                const major = version ? /(\d+)/.exec(version)?.[1] : undefined;
+                return major ? Number(major) : null;
+            }
+        }
+        catch {
+            return null;
+        }
+        dir = path.dirname(dir);
+    }
+    return null;
+}
+/**
+ * Decide whether this run should prefer the client's copy of `pkgName`.
+ *
+ * `compatible` (the default) reuses when the client's major matches ours, or when
+ * the client's own configuration is what the tool will read. A mismatch is not an
+ * error — we have our own copy — so it downgrades to ours with a line saying why.
+ */
+export function reuseDecision(pkgName, ctx, opts = {}) {
+    const policy = ctx.config.install?.reuseLocal ?? 'compatible';
+    if (policy === 'off') {
+        return { reason: 'install.reuseLocal is "off" — using our own copy for reproducibility' };
+    }
+    const clientMajor = installedMajor(pkgName, ctx.cwd);
+    if (clientMajor === null) {
+        return { reason: `${pkgName} is not installed in the repository — using our own copy` };
+    }
+    if (policy === 'always') {
+        return {
+            paths: [ctx.cwd],
+            reason: `install.reuseLocal is "always" — using ${pkgName}@${clientMajor} from the repository`,
+        };
+    }
+    if (opts.clientOwnsConfig) {
+        return {
+            paths: [ctx.cwd],
+            reason: `using ${pkgName}@${clientMajor} from the repository — it reads the repository's own config`,
+        };
+    }
+    const ourMajor = ownMajor(pkgName);
+    if (ourMajor === null || clientMajor === ourMajor) {
+        return {
+            paths: [ctx.cwd],
+            reason: `using ${pkgName}@${clientMajor} from the repository (matches ours)`,
+        };
+    }
+    return {
+        reason: `the repository has ${pkgName}@${clientMajor} and our config is written for @${ourMajor} — using our own copy`,
+    };
+}
+/**
+ * The search roots a check should prefer for `pkgName`, logging the reason once.
+ *
+ * The reason is logged rather than returned to each caller because it answers the
+ * question every confusing lint result starts with — "whose ESLint ran" — and no
+ * check should have to remember to say so.
+ */
+export function clientToolPaths(pkgName, ctx, opts = {}) {
+    const decision = reuseDecision(pkgName, ctx, opts);
+    logger.debug(`[reuseLocal]: ${decision.reason}`);
+    return decision.paths;
+}

package/dist/esm/core/registry.d.ts

@@ -0,0 +1,6 @@
+import { Check } from './types.js';
+/**
+ * Every check, in declaration order. The orchestrator groups them by `phase`
+ * (blocking → informational → format) and runs each phase's checks in parallel.
+ */
+export declare const REGISTRY: Check[];

package/dist/esm/core/registry.js

@@ -0,0 +1,109 @@
+import { bannedImportsCheck } from './checks/dependencies/banned-imports.js';
+import { circularDepsCheck } from './checks/dependencies/circular-deps.js';
+import { dependencyCheck } from './checks/dependencies/dependency-check.js';
+import { grypeScanCheck } from './checks/dependencies/grype-scan.js';
+import { licenseCheck } from './checks/dependencies/license-check.js';
+import { npmAuditCheck } from './checks/dependencies/npm-audit.js';
+import { outdatedDepsCheck } from './checks/dependencies/outdated-deps.js';
+import { vulnScanCheck } from './checks/dependencies/vuln-scan.js';
+import { customRulesCheck } from './checks/git/custom-rules.js';
+import { diffSmellCheck } from './checks/git/diff-smell.js';
+import { largeFilesCheck } from './checks/git/large-files.js';
+import { leftoverDebugCheck } from './checks/git/leftover-debug.js';
+import { lockfileDriftCheck } from './checks/git/lockfile-drift.js';
+import { mergeConflictCheck } from './checks/git/merge-conflict.js';
+import { missingTestsCheck } from './checks/git/missing-tests.js';
+import { todoFixmeCheck } from './checks/git/todo-fixme.js';
+import { cppFormatCheck } from './checks/languages/cpp-format.js';
+import { csharpFormatCheck, goLintCheck, kotlinLintCheck, phpFormatCheck, rubyLintCheck, rustFormatCheck, rustLintCheck, shellcheckCheck, swiftLintCheck, } from './checks/languages/external-checks.js';
+import { goFormatCheck } from './checks/languages/go-format.js';
+import { lintCheck } from './checks/languages/lint.js';
+import { prettierCheck } from './checks/languages/prettier.js';
+import { pythonFormatCheck } from './checks/languages/python-format.js';
+import { pythonLintCheck } from './checks/languages/python-lint.js';
+import { pythonTypecheckCheck } from './checks/languages/python-typecheck.js';
+import { typecheckCheck } from './checks/languages/typecheck.js';
+import { commitlintCheck } from './checks/pr/commitlint.js';
+import { prBodyCheck } from './checks/pr/pr-body.js';
+import { prSizeCheck } from './checks/pr/pr-size-check.js';
+import { prTitleLintCheck } from './checks/pr/pr-title-lint.js';
+import { caseCollisionCheck } from './checks/quality/case-collision.js';
+import { configValidationCheck } from './checks/quality/config-validation.js';
+import { coverageCheck } from './checks/quality/coverage.js';
+import { deadCodeCheck } from './checks/quality/dead-code.js';
+import { duplicateCheck } from './checks/quality/duplicate-check.js';
+import { licenseHeaderCheck } from './checks/quality/license-header.js';
+import { markdownLintCheck } from './checks/quality/markdown-lint.js';
+import { packageSizeCheck } from './checks/quality/package-size.js';
+import { spellcheckCheck } from './checks/quality/spellcheck.js';
+import { symlinksCheck } from './checks/quality/symlinks.js';
+import { yamlLintCheck } from './checks/quality/yaml-lint.js';
+import { diffSecurityCheck } from './checks/security/diff-security.js';
+import { dockerfileSecurityCheck } from './checks/security/dockerfile-security.js';
+import { migrationSafetyCheck } from './checks/security/migration-safety.js';
+import { securityCheck } from './checks/security/security.js';
+import { sensitiveFileGuardCheck } from './checks/security/sensitive-file-guard.js';
+import { workflowSecurityCheck } from './checks/security/workflow-security.js';
+/**
+ * Every check, in declaration order. The orchestrator groups them by `phase`
+ * (blocking → informational → format) and runs each phase's checks in parallel.
+ */
+export const REGISTRY = [
+    // blocking
+    mergeConflictCheck,
+    securityCheck,
+    typecheckCheck,
+    lintCheck,
+    dependencyCheck,
+    npmAuditCheck,
+    circularDepsCheck,
+    licenseCheck,
+    // informational
+    diffSmellCheck,
+    diffSecurityCheck,
+    workflowSecurityCheck,
+    dockerfileSecurityCheck,
+    caseCollisionCheck,
+    vulnScanCheck,
+    grypeScanCheck,
+    customRulesCheck,
+    bannedImportsCheck,
+    licenseHeaderCheck,
+    configValidationCheck,
+    leftoverDebugCheck,
+    lockfileDriftCheck,
+    largeFilesCheck,
+    todoFixmeCheck,
+    missingTestsCheck,
+    coverageCheck,
+    migrationSafetyCheck,
+    sensitiveFileGuardCheck,
+    prBodyCheck,
+    duplicateCheck,
+    commitlintCheck,
+    prSizeCheck,
+    prTitleLintCheck,
+    outdatedDepsCheck,
+    markdownLintCheck,
+    spellcheckCheck,
+    yamlLintCheck,
+    symlinksCheck,
+    packageSizeCheck,
+    pythonLintCheck,
+    pythonTypecheckCheck,
+    deadCodeCheck,
+    swiftLintCheck,
+    kotlinLintCheck,
+    goLintCheck,
+    rustLintCheck,
+    rubyLintCheck,
+    shellcheckCheck,
+    // format
+    prettierCheck,
+    cppFormatCheck,
+    pythonFormatCheck,
+    goFormatCheck,
+    rustFormatCheck,
+    csharpFormatCheck,
+    phpFormatCheck,
+];

package/dist/esm/core/reporters.d.ts

@@ -0,0 +1,18 @@
+import type { CheckReport, ReporterConfig, ReporterKind } from './types.js';
+/** 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, cfg?: ReporterConfig): Promise<PostOutcome>;

package/dist/esm/core/reporters.js

@@ -0,0 +1,266 @@
+import fs from 'node:fs';
+import { paginate, request } from '../utils/http.js';
+import { logger } from '../utils/index.js';
+import { packageVersion } from '../utils/package-version.js';
+const STATUS_ICON = {
+    pass: '✅',
+    warn: '⚠️',
+    fail: '❌',
+    skip: '⏭️',
+};
+// Unique marker so we can find and update the comment on re-runs.
+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;
+    const eventPath = process.env.GITHUB_EVENT_PATH;
+    if (!token || !repository || !eventPath || !fs.existsSync(eventPath)) {
+        return null;
+    }
+    try {
+        const event = JSON.parse(fs.readFileSync(eventPath, 'utf-8'));
+        const prNumber = event?.pull_request?.number;
+        if (!prNumber)
+            return null;
+        const [owner, repo] = repository.split('/');
+        return { token, owner, repo, prNumber };
+    }
+    catch {
+        return null;
+    }
+}
+/** 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;
+    });
+}
+export function buildMarkdownReport(report, cfg = {}) {
+    const { passed, warned, failed, skipped } = report.summary;
+    const include = cfg.include ?? {};
+    const rows = visibleResults(report, cfg);
+    const table = rows
+        .map(r => {
+        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',
+        '',
+        `**${passed} passed** · **${warned} warnings** · **${failed} failed** · **${skipped} skipped**`,
+        '',
+        '| Check | Result |',
+        '|---|---|',
+        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) v${packageVersion()}_`,
+    ].join('\n');
+}
+/**
+ * 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;
+    logger.print('');
+    logger.print(SUMMARY_BORDER);
+    // The version belongs in the headline, not in a footnote. Which copy of
+    // pr-checkmate produced a report is the first thing to establish when the
+    // report disagrees with what someone expects, and it is not otherwise
+    // recoverable from the log: a stale global install answers `pr-checkmate` on
+    // `PATH` ahead of the project's own, and reads the same config while doing it.
+    logger.print(`  PR CheckMate Summary  ·  v${packageVersion()}`);
+    logger.print(SUMMARY_BORDER);
+    for (const r of report.results) {
+        const details = r.details ? `: ${r.details}` : '';
+        logger.print(`  ${STATUS_ICON[r.status]}  ${r.name}${details}`);
+    }
+    logger.print(SUMMARY_RULE);
+    logger.print(`  ✅ ${passed} passed  ⚠️ ${warned} warnings  ❌ ${failed} failed  ⏭️ ${skipped} skipped`);
+    logger.print(SUMMARY_BORDER);
+    if (cfg.include?.docsLink !== false) {
+        // The docs cover every check and config key.
+        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) {
+        logger.info(`[reporter]: ✅ ${verb} PR CheckMate summary on ${platform}`);
+        return { attempted: true, ok: true };
+    }
+    logger.warn(`[reporter]: ⚠️ Could not ${verb.toLowerCase()} ${platform} comment: ${res.error}`);
+    return { attempted: true, ok: false, error: res.error };
+}
+/** 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) {
+        logger.info('[reporter]: Skipping GitHub comment (not in PR context or GITHUB_TOKEN missing)');
+        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',
+    };
+    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 request(`${apiBase}/issues/comments/${existing.reuse.id}`, { method: 'PATCH', headers, body: JSON.stringify({ body }) }, opts);
+        return finish('GitHub', res, 'Updated');
+    }
+    const res = await request(`${apiBase}/issues/${prNumber}/comments`, { method: 'POST', headers, body: JSON.stringify({ body }) }, opts);
+    return finish('GitHub', res, 'Posted');
+}
+/**
+ * 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, 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) {
+        logger.info('[reporter]: Skipping GitLab note (not an MR pipeline or GITLAB_TOKEN missing)');
+        return SKIPPED;
+    }
+    const notes = `${base}/projects/${project}/merge_requests/${iid}/notes`;
+    const headers = { 'PRIVATE-TOKEN': token, 'Content-Type': 'application/json' };
+    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 request(`${notes}/${existing.reuse.id}`, { method: 'PUT', headers, body: JSON.stringify({ body }) }, opts);
+        return finish('GitLab', res, 'Updated');
+    }
+    const res = await request(notes, { method: 'POST', headers, body: JSON.stringify({ body }) }, opts);
+    return finish('GitLab', res, 'Posted');
+}
+/**
+ * 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, 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) {
+        logger.info('[reporter]: Skipping Bitbucket comment (not a PR pipeline or BITBUCKET_TOKEN missing)');
+        return SKIPPED;
+    }
+    const commentsUrl = `https://api.bitbucket.org/2.0/repositories/${fullName}/pullrequests/${prId}/comments`;
+    const headers = { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' };
+    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 request(`${commentsUrl}/${existing.reuse.id}`, { method: 'PUT', headers, body: JSON.stringify({ content: { raw: body } }) }, opts);
+        return finish('Bitbucket', res, 'Updated');
+    }
+    const res = await 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 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.
+        logger.warn(`[reporter]: ⚠️ Could not read existing comments (${result.error}) — will create`);
+    }
+    if (result.truncated) {
+        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() {
+    if (process.env.GITHUB_ACTIONS || process.env.GITHUB_EVENT_NAME)
+        return 'github';
+    if (process.env.GITLAB_CI)
+        return 'gitlab';
+    if (process.env.BITBUCKET_PIPELINE_UUID || process.env.BITBUCKET_PR_ID)
+        return 'bitbucket';
+    return null;
+}
+/** Post the markdown report to a specific platform's PR/MR. */
+async function postToPlatform(platform, result, cfg) {
+    const body = buildMarkdownReport(result, cfg);
+    if (platform === 'github')
+        return upsertGithubComment(body, cfg);
+    if (platform === 'gitlab')
+        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.
+ */
+export async function report(kind, result, cfg = {}) {
+    if (kind === 'none')
+        return SKIPPED;
+    printStdout(result, cfg);
+    if (result.results.length === 0)
+        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) {
+        logger.info('[reporter]: Nothing to report (skipWhenClean)');
+        return SKIPPED;
+    }
+    const platform = kind === 'auto' ? detectPlatform() : kind === 'stdout' ? null : kind;
+    if (!platform)
+        return SKIPPED;
+    return postToPlatform(platform, result, cfg);
+}

package/dist/esm/core/run-checks.d.ts

@@ -0,0 +1,33 @@
+import type { RunScope } from './types.js';
+import { CheckContext, CheckReport, CheckStatus, RunOptions } from './types.js';
+/**
+ * Apply the universal `config.severity` override for a check. Only remaps
+ * between warn↔fail (pass/skip are never changed); `off` is handled earlier by
+ * excluding the check from the run entirely. This is what lets a repo turn any
+ * advisory check into a gate, or downgrade a blocking one, by name.
+ */
+export declare function applySeverity(name: string, status: CheckStatus, ctx: CheckContext): CheckStatus;
+/**
+ * Whether a diff-only check's skip is worth a row in the report.
+ *
+ * The two cases look identical from inside the check and are opposites to the
+ * person reading the result:
+ *
+ * - The range is missing because the run FELL BACK to a full scan — a shallow
+ *   clone, an unreachable PR base. Coverage was lost without anyone choosing
+ *   that, and saying nothing is how it stays lost (ticket 057).
+ * - The full scan was ASKED FOR. `--full` means "look at everything now", so
+ *   three rows explaining that three checks review a diff repeat what the reader
+ *   just said and push the real findings further down.
+ *
+ * `always` and `never` remain absolute; only `auto` distinguishes them.
+ */
+export declare function shouldReportDiffSkip(scope: RunScope | undefined, reportSkipped?: 'auto' | 'always' | 'never'): boolean;
+/**
+ * Run all applicable checks and return a structured report.
+ *
+ * Never throws for check violations and never calls `process.exit` — callers
+ * (CLI, PRValidator) decide what a failure means. Phases run in order; checks
+ * within a phase run in parallel.
+ */
+export declare function runChecks(opts?: RunOptions): Promise<CheckReport>;