pr-checkmate 1.23.24 → 2.0.0

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). */

package/dist/init.d.ts

@@ -1,23 +1,38 @@
+/** How strictly the generated workflow treats a failed run. */
+type GateMode = 'strict' | 'advisory';
 /**
- * Merge current defaults into an existing config, recursively.
+ * Write the bundled GitHub Actions workflow into the consumer repo.
  *
- * The user's value always wins, so hand-tuned settings survive an `init` re-run,
- * while every new default field — at any nesting depth — gets added. Arrays are
- * replaced wholesale rather than concatenated: lists like `ignoreDirs` or
- * `cspell.words` are meant to be edited, and merging them would resurrect entries
- * the user deliberately removed. {@link REPLACED_OBJECT_PATHS} extends that rule to
- * the object-shaped lists.
+ * Never overwrites an existing file. `init` is not a one-time command — the
+ * update notice asks people to re-run it after every upgrade — so clobbering
+ * would quietly discard whatever they had tuned, including the gate setting they
+ * were just asked about.
+ */
+export declare function setupWorkflow(root: string, mode: GateMode): void;
+/**
+ * Every check that fails the run out of the box, written into the generated
+ * config at its real default.
+ *
+ * Not a copy of a default for its own sake — this one is the gate's teeth, and
+ * the client is entitled to see which checks can stop their merge without
+ * reading our source or discovering it from a red pipeline. Written as `"error"`
+ * so the edit is in place: change the value, or delete the line to inherit
+ * whatever we ship next.
  *
- * Informational `//`-prefixed keys are the one exception — they are documentation,
- * not settings, so the refreshed default text wins whenever a default exists.
+ * Two things are deliberately absent. `Custom Rules` and `Banned Imports` can
+ * block too, but only for rules the client writes themselves, so listing them
+ * would suggest a gate that is inert until they act. And `Dockerfile Security`
+ * looks like it belongs here and does not: every one of its patterns is rated
+ * `warn`, so it never fails on its own.
  *
- * @param defaults Current defaults for this level of the config tree.
- * @param user The existing pr-checkmate.json content for the same level.
- * @param path Dot-joined position of `defaults` in the config tree, used to match
- * {@link REPLACED_OBJECT_PATHS}. Internal to the recursion; callers pass nothing.
+ * Keep in step with the checks' own defaults — `blocking-checks.test.ts` pins
+ * every name here to the registry, which catches a rename but not a change of
+ * heart about what should block.
  */
-export declare function mergeWithDefaults(defaults: Record<string, unknown>, user: Record<string, unknown>, path?: string): Record<string, unknown>;
+export declare const BLOCKING_BY_DEFAULT: readonly ["Security Scan", "Sensitive Files", "Diff Security", "Workflow Security", "Merge Conflict", "NPM Audit", "License Check", "Dependencies", "TypeScript", "ESLint", "YAML Lint"];
+export declare function buildInitialConfig(sourcePath: string, languages: string[]): Record<string, unknown>;
 /**
  * Initialize (or refresh) pr-checkmate configuration in the current project.
  */
 export declare function init(): Promise<void>;
+export {};