pr-checkmate 1.23.23 → 2.0.0

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

package/dist/core/run-checks.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runChecks = runChecks;
 const utils_1 = require("../utils");
+const pool_1 = require("../utils/pool");
 const result_collector_1 = require("../utils/result-collector");
 const context_1 = require("./context");
 const registry_1 = require("./registry");
@@ -27,13 +28,19 @@ function resolveChecks(opts) {
         byName.set(c.name, c); // custom wins on name clash
     return [...byName.values()];
 }
-/** Emit the report via a preset channel or a custom reporter function. */
-async function emitReport(reporter, result) {
+/**
+ * Emit the report via a preset channel or a custom reporter function.
+ *
+ * Returns whether delivery succeeded so the caller can honour
+ * `reporter.onPostFailure`. A custom function owns its own error handling, so it
+ * is always treated as delivered.
+ */
+async function emitReport(reporter, result, cfg) {
     if (typeof reporter === 'function') {
         await reporter(result);
-        return;
+        return { attempted: false, ok: true };
     }
-    await (0, reporters_1.report)(reporter ?? 'stdout', result);
+    return (0, reporters_1.report)(reporter ?? 'stdout', result, cfg);
 }
 /** Apply only/skip filters to the resolved check set. */
 function selectChecks(checks, opts) {
@@ -64,9 +71,34 @@ function applySeverity(name, status, ctx) {
         return 'warn';
     return status;
 }
-/** Run one check: gate on `applies`, execute, translate throws into `fail`. */
-async function runOne(check, ctx, collector) {
+/**
+ * Why a `requiresDiff` check could not run, phrased for the person reading the
+ * report. A full scan the client asked for is expected; one we fell back to is
+ * a configuration problem, and the message says which.
+ */
+function noDiffReason(ctx) {
+    const scope = ctx.scope;
+    if (scope?.degraded)
+        return `no diff range (${scope.reason}) — set fetch-depth: 0`;
+    return 'full scan — this check reviews a diff';
+}
+/**
+ * Run one check: gate on `applies`, execute, translate throws into `fail`.
+ *
+ * `heavy` admits only a couple of expensive checks at a time, and the per-check
+ * timeout means one that never returns costs a warning rather than the run.
+ */
+async function runOne(check, ctx, collector, heavy) {
     try {
+        // A diff-only check without a range is a hole in coverage, not an
+        // irrelevance: report it as a skip so the gap is visible in the summary.
+        if (check.requiresDiff && !ctx.baseSha) {
+            const show = ctx.config.run?.reportSkipped ?? 'auto';
+            if (show !== 'never' && (await check.applies(ctx))) {
+                collector.register(check.name, 'skip', noDiffReason(ctx));
+            }
+            return;
+        }
         if (!(await check.applies(ctx))) {
             // A check that doesn't apply is irrelevant to this project/run — e.g. a
             // language-specific check (SwiftLint, ktlint, Ruff, C++) in a repo of a
@@ -76,7 +108,16 @@ async function runOne(check, ctx, collector) {
             // from run() (e.g. "no relevant files changed") are still reported.
             return;
         }
-        const outcome = await check.run(ctx);
+        const started = Date.now();
+        const timeoutMs = ctx.config.run?.checkTimeoutMs ?? 300000;
+        const execute = () => (0, pool_1.withTimeout)(check.run(ctx), timeoutMs, () => {
+            utils_1.logger.warn(`[runChecks]: ⏱️ ${check.name} exceeded ${timeoutMs}ms`);
+            return { status: 'warn', details: `timed out after ${timeoutMs}ms` };
+        });
+        const outcome = check.weight === 'heavy' ? await heavy.run(execute) : await execute();
+        if (ctx.config.run?.timings) {
+            utils_1.logger.info(`[runChecks]: ${check.name} took ${Date.now() - started}ms`);
+        }
         collector.register(check.name, applySeverity(check.name, outcome.status, ctx), outcome.details);
     }
     catch (err) {
@@ -102,16 +143,52 @@ async function runChecks(opts = {}) {
     const off = ctx.config.severity ?? {};
     const selected = selectChecks(resolveChecks(opts), opts).filter(c => off[c.name] !== 'off');
     const collector = new result_collector_1.ResultCollector();
+    // Config Validation verifies that `severity` keys name real checks. It reads
+    // the list from here rather than importing the registry, which would make
+    // registry → check → registry a cycle.
+    ctx.checkNames = resolveChecks(opts).map(c => c.name);
+    const limit = (0, pool_1.resolveConcurrency)(ctx.config.run?.concurrency);
+    const heavyLimit = Math.max(1, ctx.config.run?.heavyConcurrency ?? 1);
+    const heavy = new pool_1.Semaphore(heavyLimit);
     for (const phase of types_1.PHASES) {
         const inPhase = selected.filter(c => c.phase === phase);
-        await Promise.all(inPhase.map(c => runOne(c, ctx, collector)));
+        await (0, pool_1.runPool)(inPhase.map(c => () => runOne(c, ctx, collector, heavy)), limit);
     }
-    const summary = collector.getSummary();
-    const result = {
-        results: collector.getResults(),
-        summary,
-        ok: summary.failed === 0,
+    reportDegradedScope(ctx, collector);
+    const build = () => {
+        const summary = collector.getSummary();
+        return { results: collector.getResults(), summary, ok: summary.failed === 0 };
     };
-    await emitReport(opts.reporter, result);
+    const result = build();
+    const posted = await emitReport(opts.reporter, result, ctx.config.reporter ?? {});
+    // A summary that never reached the PR can matter as much as a finding. The row
+    // is added after the report was rendered — the printed table is what the run
+    // actually found — and the returned report carries it so the exit code can.
+    const onFailure = ctx.config.reporter?.onPostFailure ?? 'warn';
+    if (posted.attempted && !posted.ok && onFailure !== 'off') {
+        collector.register('Reporting', onFailure === 'error' ? 'fail' : 'warn', posted.error);
+        return build();
+    }
     return result;
 }
+/**
+ * Surface a scope that silently narrowed the run.
+ *
+ * Falling back to a full scan keeps the file-based checks working, but it drops
+ * every diff-only check — most of the security surface — and the report gives no
+ * sign of it. Outside CI a full scan is simply the default, so this stays quiet
+ * there; inside CI it means the range could not be built, which is a
+ * configuration problem the client should hear about.
+ *
+ * `run.onDegradedScope: "error"` turns it into a gate, for repos where losing
+ * the security checks silently is worse than a red build.
+ */
+function reportDegradedScope(ctx, collector) {
+    const mode = ctx.config.run?.onDegradedScope ?? 'warn';
+    if (mode === 'off' || !ctx.scope?.degraded || !(0, utils_1.isCiEnvironment)())
+        return;
+    const dropped = collector.getResults().filter(r => r.status === 'skip').length;
+    const detail = `${ctx.scope.reason}; ${dropped} diff-only check(s) did not run — set fetch-depth: 0`;
+    utils_1.logger.error(`[runChecks]: ${mode === 'error' ? '❌' : '⚠️'} Degraded scope: ${detail}`);
+    collector.register('Scan Scope', mode === 'error' ? 'fail' : 'warn', detail);
+}

package/dist/core/targets.js

@@ -9,6 +9,7 @@ exports.listTrackedFiles = listTrackedFiles;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const config_1 = require("../config");
+const loader_1 = require("../config/loader");
 const utils_1 = require("../utils");
 const execa_1 = require("../utils/execa");
 /**
@@ -21,6 +22,27 @@ const execa_1 = require("../utils/execa");
  * keeps the CI dirs (`.github`, `.gitlab`, `.circleci`), which are ignored
  * globally but hold the workflow files a YAML linter most needs to see.
  */
+/**
+ * Drop files the client excluded by path.
+ *
+ * Separate from `ignoreDirs`, which matches a directory *name* on any segment:
+ * that cannot express "this one file" and cannot express "this one path" —
+ * `ignoreDirs: ["generated"]` silences every `generated/` in the repository, not
+ * the one that is actually generated. Globs answer both, and because this sits
+ * in the one function every file-scanning check calls, a client writes the rule
+ * once instead of hunting for the right key on each check.
+ */
+function excludeConfiguredPaths(files) {
+    let patterns = [];
+    try {
+        patterns = (0, loader_1.loadProjectConfig)().excludePaths ?? [];
+    }
+    catch {
+        // A config that cannot be read is the loader's problem to report, not a
+        // reason to scan nothing.
+    }
+    return patterns.length > 0 ? files.filter(f => !(0, utils_1.matchesAnyGlob)(f, patterns)) : files;
+}
 function excludeIgnoredDirs(files, keepDirs = []) {
     const ignored = new Set((0, config_1.getIgnoredDirs)());
     for (const dir of keepDirs)
@@ -60,10 +82,10 @@ async function resolveTargetFiles(ctx, globs, opts = {}) {
             stdout = (await (0, execa_1.execa)('git', args, { cwd: ctx.cwd, reject: false })).stdout;
             ctx.cache?.set(cacheKey, stdout);
         }
-        const files = excludeIgnoredDirs(stdout
+        const files = excludeConfiguredPaths(excludeIgnoredDirs(stdout
             .split('\n')
             .map(f => f.trim())
-            .filter(Boolean), opts.keepDirs).filter(f => node_fs_1.default.existsSync(node_path_1.default.join(ctx.cwd, f)));
+            .filter(Boolean), opts.keepDirs)).filter(f => node_fs_1.default.existsSync(node_path_1.default.join(ctx.cwd, f)));
         utils_1.logger.info(`[targets]: ${ctx.baseSha ? '📂 Delta' : 'Full scan'}: ${files.length} file(s) for ${globs.join(', ')}`);
         return files;
     }
@@ -103,10 +125,10 @@ async function resolveScopedTargetFiles(ctx, globs, sourcePaths) {
 async function listTrackedFiles(ctx, globs, sourcePaths) {
     try {
         const { stdout } = await (0, execa_1.execa)('git', ['ls-files', ...globs], { cwd: ctx.cwd, reject: false });
-        const files = excludeIgnoredDirs(stdout
+        const files = excludeConfiguredPaths(excludeIgnoredDirs(stdout
             .split('\n')
             .map(f => f.trim())
-            .filter(Boolean));
+            .filter(Boolean)));
         return scopeToSourcePaths(files, sourcePaths);
     }
     catch (err) {

package/dist/core/types.d.ts

@@ -1,4 +1,4 @@
-import type { PRCheckMateConfig } from '../interfaces';
+import type { PRCheckMateConfig, ReporterConfig } from '../interfaces';
 import type { Language } from '../utils/detect-language';
 import type { CheckResult, CheckStatus } from '../utils/result-collector';
 export type { CheckResult, CheckStatus, Language };
@@ -8,6 +8,21 @@ export type { CheckResult, CheckStatus, Language };
  */
 export type Phase = 'blocking' | 'informational' | 'format';
 export declare const PHASES: readonly Phase[];
+/**
+ * What this run is looking at, and whether that is what was asked for.
+ *
+ * `degraded` is the field that earns this its own type: a full scan requested by
+ * a human and a full scan we fell back to because the PR base was missing are
+ * indistinguishable in the results — both just omit every delta-only check — but
+ * only one of them is a problem worth telling anyone about.
+ */
+export interface RunScope {
+    kind: 'delta' | 'full' | 'staged';
+    /** Short explanation for the log line, e.g. `PR base unavailable`. */
+    reason?: string;
+    /** True when a diff range was wanted but could not be built. */
+    degraded: boolean;
+}
 /**
  * Everything a check needs to run. Assembled once by `buildContext` and shared
  * across all checks — no check reads `process.cwd()` or `process.env` directly.
@@ -24,6 +39,17 @@ export interface CheckContext {
     /** Diff range for delta-aware checks; undefined → full-repo scan. */
     baseSha?: string;
     headSha?: string;
+    /** What this run is looking at, and why. Optional so hand-built contexts stay terse. */
+    scope?: RunScope;
+    /**
+     * Display names of the checks in this run, for the one check that reasons about
+     * the others (Config Validation, verifying `severity` keys).
+     *
+     * Passed down rather than imported: a check importing the registry would close
+     * the loop registry → check → registry, and it also lets custom checks supplied
+     * through `RunOptions.checks` be validated like built-in ones.
+     */
+    checkNames?: string[];
     /**
      * Per-run memoization cache for identical git invocations (many checks diff
      * the same range). Created once per `runChecks`; safe because git state is
@@ -45,12 +71,34 @@ export interface CheckOutcome {
 export interface Check {
     name: string;
     phase: Phase;
+    /**
+     * The check reviews a diff and has nothing to say without one. Declared here
+     * rather than folded into `applies` so the orchestrator can tell the two kinds
+     * of "not applicable" apart:
+     *
+     * - a check that does not apply (SwiftLint in a Python repo) is noise, and is
+     *   left out of the report entirely;
+     * - a check that *would* have applied but had no diff range is a gap in
+     *   coverage, and is reported as a skip with the reason.
+     *
+     * Before this existed, both simply vanished — so a shallow clone removed most
+     * of the security surface and still printed a clean, complete-looking report.
+     */
+    requiresDiff?: boolean;
+    /**
+     * The check spawns something expensive — a whole-project analyser like knip,
+     * jscpd, dpdm, tsc or grype. The orchestrator admits only a couple of these at
+     * once, independently of the overall concurrency limit: four regex scans in
+     * parallel are free, four project-wide analysers are not.
+     */
+    weight?: 'heavy';
     applies(ctx: CheckContext): boolean | Promise<boolean>;
     run(ctx: CheckContext): Promise<CheckOutcome>;
 }
 export type ReporterKind = 'none' | 'stdout' | 'github' | 'gitlab' | 'bitbucket' | 'auto';
 /** Custom reporter: receives the final report to emit however the consumer wants. */
 export type ReporterFn = (report: CheckReport) => void | Promise<void>;
+export type { ReporterConfig };
 export interface RunOptions {
     cwd?: string;
     /** Override language detection (e.g. PRValidator passes its already-detected type). */