pr-checkmate 3.0.3 → 3.1.0

package/dist/esm/utils/package-version.js

@@ -0,0 +1,38 @@
+import { fileURLToPath as __fileURLToPath } from 'node:url';
+import { dirname as __dirnameFn } from 'node:path';
+const __dirname = __dirnameFn(__fileURLToPath(import.meta.url));
+import fs from 'node:fs';
+import path from 'node:path';
+import { findOwnPackageRoot } from './own-deps.js';
+/**
+ * Our own name and version, read from the manifest that ships inside the package.
+ *
+ * Read from disk rather than baked in at build time so it is the *running* copy
+ * that answers. That distinction is the whole point: a stale global install
+ * (`npm i -g pr-checkmate`) shadows the project's own copy on `PATH`, and a repo
+ * pinned to the latest version can still be checked by a year-old binary without
+ * anything in the log saying so. One client spent a while reading an upgrade
+ * notice for a version they had already installed, because nothing printed which
+ * version was speaking.
+ *
+ * Falls back to placeholders rather than throwing: no caller here is important
+ * enough to fail a run over a manifest it could not read.
+ */
+function readManifest() {
+    try {
+        const manifest = path.join(findOwnPackageRoot() ?? path.resolve(__dirname, '../../..'), 'package.json');
+        const parsed = JSON.parse(fs.readFileSync(manifest, 'utf-8'));
+        return { name: parsed.name ?? 'pr-checkmate', version: parsed.version ?? '0.0.0' };
+    }
+    catch {
+        return { name: 'pr-checkmate', version: '0.0.0' };
+    }
+}
+/** The version of pr-checkmate that is executing right now. */
+export function packageVersion() {
+    return readManifest().version;
+}
+/** The package name that is executing right now — the one to query npm for. */
+export function packageName() {
+    return readManifest().name;
+}

package/dist/esm/utils/pool.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Run tasks with a bounded number in flight.
+ *
+ * `Promise.all` over a whole phase started every check at once — thirty-seven of
+ * them in the informational phase, many spawning heavy processes (cspell, jscpd,
+ * knip, dpdm, grype, tsc). On a two-core runner that is context-switch thrashing:
+ * the wall clock gets worse, not better, and a large monorepo can run the machine
+ * out of memory.
+ *
+ * Results come back in the order the tasks were given, so callers can pair them
+ * with their inputs.
+ */
+export declare function runPool<T>(tasks: Array<() => Promise<T>>, limit: number): Promise<Array<T | undefined>>;
+/**
+ * Default concurrency for this machine.
+ *
+ * One core is left for the orchestrator and whatever else the runner is doing,
+ * and the ceiling of four keeps a 32-core developer laptop from starting thirty
+ * subprocesses that then fight over disk. On the standard two-core CI runner this
+ * resolves to 1, which is the case the old code handled worst.
+ */
+export declare function defaultConcurrency(): number;
+/** Resolve the client's `run.concurrency` setting into a number. */
+export declare function resolveConcurrency(setting: number | 'auto' | 'unlimited' | undefined): number;
+/**
+ * A counting semaphore, used to admit only a few expensive checks at a time.
+ *
+ * The overall limit is not enough on its own: four concurrent checks are fine
+ * when they are regex scans and ruinous when they are knip, jscpd, dpdm and tsc,
+ * each of which wants a core and a few hundred megabytes to itself.
+ */
+export declare class Semaphore {
+    private available;
+    private readonly waiting;
+    constructor(limit: number);
+    /** Run `fn` once a slot is free, releasing it even if `fn` throws. */
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    private acquire;
+    private release;
+}
+/**
+ * Race a promise against a timeout, resolving to `onTimeout` if it wins.
+ *
+ * A check that never returns used to hold the whole phase — and with it the run —
+ * open indefinitely. Note the underlying work is not killed: there is no portable
+ * way to do that here, so it is left to finish in the background while the run
+ * moves on and reports the timeout.
+ */
+export declare function withTimeout<T>(work: Promise<T>, timeoutMs: number, onTimeout: () => T): Promise<T>;

package/dist/esm/utils/pool.js

@@ -0,0 +1,113 @@
+import os from 'node:os';
+/**
+ * Run tasks with a bounded number in flight.
+ *
+ * `Promise.all` over a whole phase started every check at once — thirty-seven of
+ * them in the informational phase, many spawning heavy processes (cspell, jscpd,
+ * knip, dpdm, grype, tsc). On a two-core runner that is context-switch thrashing:
+ * the wall clock gets worse, not better, and a large monorepo can run the machine
+ * out of memory.
+ *
+ * Results come back in the order the tasks were given, so callers can pair them
+ * with their inputs.
+ */
+export async function runPool(tasks, limit) {
+    const bound = Math.max(1, Math.floor(limit));
+    const results = new Array(tasks.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < tasks.length) {
+            const index = next++;
+            results[index] = await tasks[index]();
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(bound, tasks.length) }, worker));
+    return results;
+}
+/**
+ * Default concurrency for this machine.
+ *
+ * One core is left for the orchestrator and whatever else the runner is doing,
+ * and the ceiling of four keeps a 32-core developer laptop from starting thirty
+ * subprocesses that then fight over disk. On the standard two-core CI runner this
+ * resolves to 1, which is the case the old code handled worst.
+ */
+export function defaultConcurrency() {
+    const cores = os.cpus()?.length ?? 2;
+    return Math.max(1, Math.min(4, cores - 1));
+}
+/** Resolve the client's `run.concurrency` setting into a number. */
+export function resolveConcurrency(setting) {
+    const fromEnv = process.env.PR_CHECKMATE_CONCURRENCY;
+    const value = fromEnv ?? setting ?? 'auto';
+    if (value === 'unlimited')
+        return Number.MAX_SAFE_INTEGER;
+    if (value === 'auto')
+        return defaultConcurrency();
+    const parsed = typeof value === 'number' ? value : parseInt(value, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : defaultConcurrency();
+}
+/**
+ * A counting semaphore, used to admit only a few expensive checks at a time.
+ *
+ * The overall limit is not enough on its own: four concurrent checks are fine
+ * when they are regex scans and ruinous when they are knip, jscpd, dpdm and tsc,
+ * each of which wants a core and a few hundred megabytes to itself.
+ */
+export class Semaphore {
+    constructor(limit) {
+        this.waiting = [];
+        this.available = Math.max(1, limit);
+    }
+    /** Run `fn` once a slot is free, releasing it even if `fn` throws. */
+    async run(fn) {
+        await this.acquire();
+        try {
+            return await fn();
+        }
+        finally {
+            this.release();
+        }
+    }
+    async acquire() {
+        if (this.available > 0) {
+            this.available--;
+            return;
+        }
+        return new Promise(resolve => this.waiting.push(resolve));
+    }
+    release() {
+        const next = this.waiting.shift();
+        if (next)
+            next();
+        else
+            this.available++;
+    }
+}
+/**
+ * Race a promise against a timeout, resolving to `onTimeout` if it wins.
+ *
+ * A check that never returns used to hold the whole phase — and with it the run —
+ * open indefinitely. Note the underlying work is not killed: there is no portable
+ * way to do that here, so it is left to finish in the background while the run
+ * moves on and reports the timeout.
+ */
+export async function withTimeout(work, timeoutMs, onTimeout) {
+    if (timeoutMs <= 0)
+        return work;
+    let timer;
+    try {
+        return await Promise.race([
+            work,
+            new Promise(resolve => {
+                timer = setTimeout(() => resolve(onTimeout()), timeoutMs);
+                // Do not keep the event loop alive purely for this timer.
+                timer.unref?.();
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/esm/utils/resolve-bin.d.ts

@@ -0,0 +1,67 @@
+/** Where a tool was found, in the order the candidates are tried. */
+export type ToolSource = 'client' | 'profile' | 'bundled';
+/** A resolved tool binary, and which copy of it answered. */
+export interface ResolvedTool {
+    bin: string;
+    source: ToolSource;
+    /** The search root that produced it; `undefined` for module-relative resolution. */
+    root?: string;
+}
+/**
+ * Point tool resolution at the profile directories fetched for this run.
+ *
+ * Called by the install layer once the cache is known. Passing an empty list —
+ * or never calling it at all — leaves resolution exactly as it was before
+ * profiles existed, which is what keeps a run that needs no fetching identical
+ * to a run from before there was anything to fetch.
+ */
+export declare function registerToolPaths(dirs: string[]): void;
+/** Drop every registered profile root. For tests, and for a second run in-process. */
+export declare function clearToolPaths(): void;
+/** The root of the installed pr-checkmate package — where our own tooling lives. */
+export declare function ownPackageRoot(): string;
+/**
+ * Whether a package is physically present in our own dependency tree.
+ *
+ * Checked by walking `node_modules` upwards rather than by `require.resolve`,
+ * because a package that restricts its `exports` map resolves for neither its
+ * main entry nor its `package.json` while being perfectly well installed —
+ * `cspell` is one. The question here is only "is it there", and the directory
+ * answers that without an opinion about what it chooses to export.
+ *
+ * Walking up matters as much as the check itself: installed as a dependency, our
+ * own packages are hoisted to the client's `node_modules`, one level above ours.
+ */
+export declare function packagePresent(pkgName: string, from?: string): boolean;
+/**
+ * Resolve a tool's binary and say which copy answered.
+ *
+ * Use this over {@link resolvePackageBin} when the answer is worth logging — the
+ * source is the difference between "the client's ESLint 8 ran" and "ours did",
+ * and that is the first thing anyone asks when a lint result looks wrong.
+ *
+ * @param pkgName Package whose binary to resolve (e.g. `eslint`).
+ * @param binRelPath Bin path relative to the package root (e.g. `bin/eslint.js`).
+ * @param options Resolution options.
+ * @param options.paths Roots to prefer ahead of everything else. Use
+ *   `[process.cwd()]` to prefer the consumer project's copy.
+ */
+export declare function resolveTool(pkgName: string, binRelPath: string, options?: {
+    paths?: string[];
+}): ResolvedTool | null;
+/**
+ * Resolves a binary path for a bundled package, bypassing exports map restrictions.
+ *
+ * Throws when no copy can be found anywhere, which is the honest outcome: a check
+ * that cannot find its tool has nothing to report, and the install layer turns
+ * that into a skip with a reason rather than letting it surface as a stack trace.
+ *
+ * @param pkgName - The package whose binary to resolve (e.g. `eslint`).
+ * @param binRelPath - The bin path relative to the package root (e.g. `bin/eslint.js`).
+ * @param options - Resolution options.
+ * @param options.paths - Directories to resolve from, preferred over everything
+ *   else. Use `[process.cwd()]` to prefer the consumer project's copy.
+ */
+export declare function resolvePackageBin(pkgName: string, binRelPath: string, options?: {
+    paths?: string[];
+}): string;

package/dist/esm/utils/resolve-bin.js

@@ -0,0 +1,156 @@
+import { fileURLToPath as __fileURLToPath } from 'node:url';
+import { dirname as __dirnameFn } from 'node:path';
+const __dirname = __dirnameFn(__fileURLToPath(import.meta.url));
+import fs from 'node:fs';
+import path from 'node:path';
+import { findOwnPackageRoot } from './own-deps.js';
+/**
+ * Extra roots to search, registered once per run by the install layer.
+ *
+ * Module state rather than a parameter threaded through fifteen call sites: a
+ * profile directory is a property of the *run*, not of any one check, and every
+ * check that resolves a binary would otherwise have to be handed a value it has
+ * no opinion about. `registerToolPaths` is called before the first check starts
+ * and never during one, so nothing observes it changing underneath.
+ */
+let profileRoots = [];
+/**
+ * Point tool resolution at the profile directories fetched for this run.
+ *
+ * Called by the install layer once the cache is known. Passing an empty list —
+ * or never calling it at all — leaves resolution exactly as it was before
+ * profiles existed, which is what keeps a run that needs no fetching identical
+ * to a run from before there was anything to fetch.
+ */
+export function registerToolPaths(dirs) {
+    profileRoots = [...dirs];
+}
+/** Drop every registered profile root. For tests, and for a second run in-process. */
+export function clearToolPaths() {
+    profileRoots = [];
+}
+/** The root of the installed pr-checkmate package — where our own tooling lives. */
+export function ownPackageRoot() {
+    return findOwnPackageRoot() ?? path.resolve(__dirname, '../../..');
+}
+/**
+ * Whether a package is physically present in our own dependency tree.
+ *
+ * Checked by walking `node_modules` upwards rather than by `require.resolve`,
+ * because a package that restricts its `exports` map resolves for neither its
+ * main entry nor its `package.json` while being perfectly well installed —
+ * `cspell` is one. The question here is only "is it there", and the directory
+ * answers that without an opinion about what it chooses to export.
+ *
+ * Walking up matters as much as the check itself: installed as a dependency, our
+ * own packages are hoisted to the client's `node_modules`, one level above ours.
+ */
+export function packagePresent(pkgName, from = ownPackageRoot()) {
+    let dir = from;
+    while (dir !== path.dirname(dir)) {
+        if (fs.existsSync(path.join(dir, 'node_modules', pkgName, 'package.json')))
+            return true;
+        dir = path.dirname(dir);
+    }
+    return false;
+}
+/** One resolution attempt against a single set of search paths. */
+function tryResolve(pkgName, binRelPath, paths) {
+    const resolveOpts = paths ? { paths } : undefined;
+    // 1. Direct subpath — the fast path for packages that export their bin.
+    try {
+        return require.resolve(`${pkgName}/${binRelPath}`, resolveOpts);
+    }
+    catch { }
+    // 2. Via package.json — for packages that export `./package.json` but not the
+    //    bin subpath (eslint).
+    try {
+        const pkgJsonPath = require.resolve(`${pkgName}/package.json`, resolveOpts);
+        return path.join(path.dirname(pkgJsonPath), binRelPath);
+    }
+    catch { }
+    // 3. Walk up from the main entry, matching the package name — for packages
+    //    that export neither (cspell).
+    try {
+        let dir = path.dirname(require.resolve(pkgName, resolveOpts));
+        while (dir !== path.dirname(dir)) {
+            const pkgJsonPath = path.join(dir, 'package.json');
+            if (fs.existsSync(pkgJsonPath)) {
+                try {
+                    const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+                    if (pkg.name === pkgName)
+                        return path.join(dir, binRelPath);
+                }
+                catch { }
+            }
+            dir = path.dirname(dir);
+        }
+    }
+    catch { }
+    return null;
+}
+/**
+ * The roots to try, in order, and what finding a tool in each one means.
+ *
+ * The order is the policy, and it is deliberate:
+ *
+ * 1. **The client's own copy**, when a caller asked for it. A repository pinned
+ *    to ESLint 8 with a legacy `.eslintrc` must keep working, and only its copy
+ *    can do that.
+ * 2. **A fetched profile**, for tooling that does not ship inside the package.
+ * 3. **Our bundle** — module-relative, exactly as resolution worked before
+ *    profiles existed.
+ *
+ * Branch 3 is passed `undefined` rather than our package root on purpose: that is
+ * literally the previous behaviour, so a run with nothing registered resolves
+ * every tool along the identical path it always did.
+ */
+function candidates(optPaths) {
+    const list = [];
+    if (optPaths && optPaths.length > 0)
+        list.push({ paths: optPaths, source: 'client' });
+    for (const root of profileRoots)
+        list.push({ paths: [root], source: 'profile' });
+    list.push({ source: 'bundled' });
+    return list;
+}
+/**
+ * Resolve a tool's binary and say which copy answered.
+ *
+ * Use this over {@link resolvePackageBin} when the answer is worth logging — the
+ * source is the difference between "the client's ESLint 8 ran" and "ours did",
+ * and that is the first thing anyone asks when a lint result looks wrong.
+ *
+ * @param pkgName Package whose binary to resolve (e.g. `eslint`).
+ * @param binRelPath Bin path relative to the package root (e.g. `bin/eslint.js`).
+ * @param options Resolution options.
+ * @param options.paths Roots to prefer ahead of everything else. Use
+ *   `[process.cwd()]` to prefer the consumer project's copy.
+ */
+export function resolveTool(pkgName, binRelPath, options) {
+    for (const candidate of candidates(options?.paths)) {
+        const bin = tryResolve(pkgName, binRelPath, candidate.paths);
+        if (bin)
+            return { bin, source: candidate.source, root: candidate.paths?.[0] };
+    }
+    return null;
+}
+/**
+ * Resolves a binary path for a bundled package, bypassing exports map restrictions.
+ *
+ * Throws when no copy can be found anywhere, which is the honest outcome: a check
+ * that cannot find its tool has nothing to report, and the install layer turns
+ * that into a skip with a reason rather than letting it surface as a stack trace.
+ *
+ * @param pkgName - The package whose binary to resolve (e.g. `eslint`).
+ * @param binRelPath - The bin path relative to the package root (e.g. `bin/eslint.js`).
+ * @param options - Resolution options.
+ * @param options.paths - Directories to resolve from, preferred over everything
+ *   else. Use `[process.cwd()]` to prefer the consumer project's copy.
+ */
+export function resolvePackageBin(pkgName, binRelPath, options) {
+    const resolved = resolveTool(pkgName, binRelPath, options);
+    if (resolved)
+        return resolved.bin;
+    throw new Error(`Cannot resolve binary "${binRelPath}" for package "${pkgName}"`);
+}

package/dist/esm/utils/result-collector.d.ts

@@ -0,0 +1,33 @@
+export type CheckStatus = 'pass' | 'warn' | 'fail' | 'skip';
+export interface CheckResult {
+    name: string;
+    status: CheckStatus;
+    details?: string;
+}
+/**
+ *
+ */
+export declare class ResultCollector {
+    private results;
+    /**
+     *
+     */
+    register(name: string, status: CheckStatus, details?: string): void;
+    /**
+     *
+     */
+    getResults(): CheckResult[];
+    /**
+     *
+     */
+    clear(): void;
+    /**
+     *
+     */
+    getSummary(): {
+        passed: number;
+        warned: number;
+        failed: number;
+        skipped: number;
+    };
+}

package/dist/esm/utils/result-collector.js

@@ -0,0 +1,44 @@
+/**
+ *
+ */
+export class ResultCollector {
+    constructor() {
+        this.results = [];
+    }
+    /**
+     *
+     */
+    register(name, status, details) {
+        const idx = this.results.findIndex(r => r.name === name);
+        const entry = { name, status, ...(details && { details }) };
+        if (idx >= 0) {
+            this.results[idx] = entry;
+        }
+        else {
+            this.results.push(entry);
+        }
+    }
+    /**
+     *
+     */
+    getResults() {
+        return [...this.results];
+    }
+    /**
+     *
+     */
+    clear() {
+        this.results = [];
+    }
+    /**
+     *
+     */
+    getSummary() {
+        return {
+            passed: this.results.filter(r => r.status === 'pass').length,
+            warned: this.results.filter(r => r.status === 'warn').length,
+            failed: this.results.filter(r => r.status === 'fail').length,
+            skipped: this.results.filter(r => r.status === 'skip').length,
+        };
+    }
+}

package/dist/esm/utils/update-notifier.d.ts

@@ -0,0 +1,19 @@
+/** True when the upgrade crosses a major version, i.e. behaviour may change. */
+export declare function isMajorUpgrade(latest: string, current: string): boolean;
+/**
+ * Best-effort check for a newer published version. Returns the notice lines when
+ * an update exists, or `null` (up-to-date, offline, timed out, or opted out).
+ * Non-blocking and fully silent on any failure: short timeout, swallowed errors,
+ * opt-out via `PR_CHECKMATE_NO_UPDATE_CHECK`. Returns lines instead of logging so
+ * the caller can print them at the very end — after the summary — where they're
+ * noticeable. Deliberately called ONLY from the CLI (not `runChecks`) so
+ * programmatic consumers (e.g. a wrapping SDK) never trigger a network call.
+ *
+ * The notice is framed like the run summary so it is noticed, but it is now a
+ * one-liner: upgrading is just installing. It used to demand `npx pr-checkmate
+ * init` afterwards, because `init` copied the release's new defaults into the
+ * client's config — a step nobody could safely skip, for a file that should
+ * never have held those defaults in the first place. They are merged in when the
+ * config loads, so the second step no longer exists.
+ */
+export declare function getUpdateNotice(timeoutMs?: number): Promise<string[] | null>;

package/dist/esm/utils/update-notifier.js

@@ -0,0 +1,108 @@
+// Imported from the module rather than the `../config` barrel on purpose:
+// `config/index.ts` imports `../utils`, so going through the barrel would make
+// utils ⇄ config circular. `constants.ts` itself pulls in nothing from utils.
+import { DOCS_URL } from '../config/constants.js';
+import { packageName, packageVersion } from './package-version.js';
+// Same widths as the run summary in `reporters.ts`, so the two boxes line up
+// when both are printed at the end of a run.
+const NOTICE_BORDER = '═'.repeat(63);
+const NOTICE_RULE = '─'.repeat(63);
+/** Compare dotted versions; true when `latest` is strictly greater than `current`. */
+function isNewer(latest, current) {
+    const a = latest.split('.').map(n => parseInt(n, 10) || 0);
+    const b = current.split('.').map(n => parseInt(n, 10) || 0);
+    for (let i = 0; i < 3; i++) {
+        if ((a[i] ?? 0) !== (b[i] ?? 0))
+            return (a[i] ?? 0) > (b[i] ?? 0);
+    }
+    return false;
+}
+/** True when the upgrade crosses a major version, i.e. behaviour may change. */
+export function isMajorUpgrade(latest, current) {
+    return (parseInt(latest.split('.')[0], 10) || 0) > (parseInt(current.split('.')[0], 10) || 0);
+}
+/**
+ * Extra lines for a major upgrade. A patch bump is a routine "install it"; a
+ * major one can change what fails a build, and finding that out from a red PR is
+ * the wrong way to learn it. Says what to read and how to stage the rollout,
+ * because the answer to "everything went red" should arrive before it happens.
+ */
+function majorNotice(pkgName) {
+    return [
+        NOTICE_RULE,
+        '  ⚠️  MAJOR VERSION — behaviour changes, read before upgrading',
+        '',
+        '     Findings a check rates "error" now BLOCK the run. Previously they were',
+        '     reported and the run still passed, so a repo with existing findings will',
+        '     start failing its PRs.',
+        '',
+        '     To stage it, make everything advisory first and promote checks back one',
+        '     at a time — in pr-checkmate.json:',
+        '       "severityDefaults": { "failOn": "warn" }',
+        '       "severity": { "Security Scan": "error" }',
+        '',
+        `     Full notes: https://www.npmjs.com/package/${pkgName}?activeTab=versions`,
+    ];
+}
+/**
+ * Best-effort check for a newer published version. Returns the notice lines when
+ * an update exists, or `null` (up-to-date, offline, timed out, or opted out).
+ * Non-blocking and fully silent on any failure: short timeout, swallowed errors,
+ * opt-out via `PR_CHECKMATE_NO_UPDATE_CHECK`. Returns lines instead of logging so
+ * the caller can print them at the very end — after the summary — where they're
+ * noticeable. Deliberately called ONLY from the CLI (not `runChecks`) so
+ * programmatic consumers (e.g. a wrapping SDK) never trigger a network call.
+ *
+ * The notice is framed like the run summary so it is noticed, but it is now a
+ * one-liner: upgrading is just installing. It used to demand `npx pr-checkmate
+ * init` afterwards, because `init` copied the release's new defaults into the
+ * client's config — a step nobody could safely skip, for a file that should
+ * never have held those defaults in the first place. They are merged in when the
+ * config loads, so the second step no longer exists.
+ */
+export async function getUpdateNotice(timeoutMs = 2500) {
+    if (process.env.PR_CHECKMATE_NO_UPDATE_CHECK)
+        return null;
+    try {
+        // The *running* copy's identity, not the project's declared dependency. A
+        // stale global install shadows the local one on `PATH`, and it is the stale
+        // copy that must own the notice it prints.
+        const pkg = { name: packageName(), version: packageVersion() };
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let latest;
+        try {
+            const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(pkg.name)}/latest`, {
+                signal: controller.signal,
+            });
+            if (res.ok)
+                latest = (await res.json()).version;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (latest && isNewer(latest, pkg.version)) {
+            const major = isMajorUpgrade(latest, pkg.version);
+            return [
+                NOTICE_BORDER,
+                `  ⬆️  UPDATE AVAILABLE — ${pkg.name} ${pkg.version} → ${latest}`,
+                ...(major ? majorNotice(pkg.name) : []),
+                NOTICE_RULE,
+                `  Install: npm install ${pkg.name}@latest`,
+                '',
+                '  That is the whole upgrade. New checks and new defaults apply on their',
+                '  own — your pr-checkmate.json holds only what you changed, and nothing',
+                '  in it needs topping up.',
+                NOTICE_RULE,
+                `  📚 Docs:    ${DOCS_URL}`,
+                `  📦 Release: https://www.npmjs.com/package/${pkg.name}`,
+                NOTICE_BORDER,
+            ];
+        }
+        return null;
+    }
+    catch {
+        // Best-effort only — never let an update check slow or break a run.
+        return null;
+    }
+}

package/install-manifests/core/package-lock.json

@@ -11,7 +11,7 @@
         "execa": "9.6.1",
         "yaml": "2.9.1",
         "inquirer": "14.2.2",
-        "gitleaks-secret-scanner-fixed": "3.0.3"
+        "gitleaks-secret-scanner-fixed": "3.0.4"
       }
     },
     "node_modules/@inquirer/ansi": {
@@ -572,9 +572,9 @@
       }
     },
     "node_modules/gitleaks-secret-scanner-fixed": {
-      "version": "3.0.3",
-      "resolved": "https://registry.npmjs.org/gitleaks-secret-scanner-fixed/-/gitleaks-secret-scanner-fixed-3.0.3.tgz",
-      "integrity": "sha512-j7cKwmZYmkeixE1danLi3GBq40PGMDGsxeXxBYQ35kyKa+ThcVeedt2lzTIoH4inFZsH4fG5vUqiwchXxalDnw==",
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/gitleaks-secret-scanner-fixed/-/gitleaks-secret-scanner-fixed-3.0.4.tgz",
+      "integrity": "sha512-UxNQSWIcSIux7M6Ue/pcEDz+E/UQVicvpoa/a5TCq6PD32B3sSNe3WY7wIpiyddpJIUImF2gFkQbWM+wZQrKFQ==",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {

package/install-manifests/core/package.json

@@ -5,7 +5,7 @@
     "execa": "9.6.1",
     "yaml": "2.9.1",
     "inquirer": "14.2.2",
-    "gitleaks-secret-scanner-fixed": "3.0.3"
+    "gitleaks-secret-scanner-fixed": "3.0.4"
   },
   "private": true
 }