pr-checkmate 1.23.24 → 2.0.0

package/dist/utils/http.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.request = request;
+exports.paginate = paginate;
+const logger_1 = require("./logger");
+const DEFAULT_TIMEOUT_MS = 10000;
+const DEFAULT_RETRIES = 3;
+/** 5xx and 429 are worth another attempt; a 4xx will fail identically forever. */
+function isRetryable(status) {
+    return status === 0 || status === 429 || status >= 500;
+}
+/**
+ * Turn a response into a diagnosis a person can act on.
+ *
+ * "Could not post comment: 403" sends someone hunting through Actions docs;
+ * naming the likely cause is the difference between a fixable message and a
+ * shrug. These three account for nearly every real failure.
+ */
+function explain(status, body) {
+    if (status === 401 || status === 403) {
+        return `${status} — token missing, expired, or lacking write scope (GitHub needs \`permissions: pull-requests: write\` AND \`env: GITHUB_TOKEN\`)`;
+    }
+    if (status === 404)
+        return `${status} — repository or PR not found, or the token cannot see it`;
+    if (status === 429)
+        return `${status} — rate limited`;
+    return `${status}${body ? ` — ${body.slice(0, 200)}` : ''}`;
+}
+/**
+ * Never let a token reach a log line, whatever an API decides to echo back.
+ *
+ * `pousr` and `glpat` below are not words: the first is the character class of
+ * GitHub's token prefixes (`ghp_`/`gho_`/`ghu_`/`ghs_`/`ghr_`), the second is
+ * GitLab's literal `glpat-`. Muted here rather than in the dictionary, which
+ * ships to every client and should not carry our regex fragments.
+ * cspell:ignore pousr glpat
+ */
+function redact(text) {
+    return text.replace(/\b(gh[pousr]_|glpat-|xox[baprs]-)[A-Za-z0-9_-]{8,}/g, '$1***');
+}
+/**
+ * One HTTP request with a timeout and bounded retries, returning a result rather
+ * than throwing.
+ *
+ * The reason this exists: every write in the reporter used to be a bare `await
+ * fetch(...)` whose result was discarded, followed by a log line claiming
+ * success. A 403 from a workflow missing `pull-requests: write` produced
+ * "✅ Posted PR CheckMate summary" and no comment — the user had nothing to
+ * debug from.
+ */
+async function request(url, init = {}, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const attempts = Math.max(1, opts.retries ?? DEFAULT_RETRIES);
+    const label = opts.label ? `[${opts.label}] ` : '';
+    let last = { ok: false, status: 0, error: 'no attempt made' };
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        last = await attempt_(url, init, timeoutMs);
+        if (last.ok || !isRetryable(last.status))
+            return last;
+        if (attempt < attempts) {
+            // Exponential backoff, capped so three attempts stay well inside a CI step.
+            const waitMs = Math.min(2000, 250 * 2 ** (attempt - 1));
+            logger_1.logger.warn(`${label}retrying after ${last.error} (attempt ${attempt}/${attempts})`);
+            await new Promise(resolve => setTimeout(resolve, waitMs));
+        }
+    }
+    return last;
+}
+/** A single attempt, with every failure mode flattened into an HttpResult. */
+async function attempt_(url, init, timeoutMs) {
+    try {
+        const res = await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            return { ok: false, status: res.status, error: redact(explain(res.status, text)) };
+        }
+        // A successful response with an unreadable body is still a successful write;
+        // only callers that need the body care, and they check for `undefined`.
+        const body = (await res.json().catch(() => undefined));
+        return { ok: true, status: res.status, body };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { ok: false, status: 0, error: redact(`request failed — ${reason}`) };
+    }
+}
+/**
+ * Walk a paginated collection until `nextUrl` returns nothing or `maxPages` is
+ * reached, returning every item found.
+ *
+ * Without this the reporter read only the first page — 30 comments on GitHub, 20
+ * on GitLab — so on any PR with more discussion than that its own marker fell off
+ * the end, the upsert became an insert, and every push added another comment.
+ *
+ * Stopping at `maxPages` is logged rather than silent: a truncated search can
+ * only produce a duplicate comment, and that should be explainable.
+ */
+async function paginate(firstUrl, init, extract, 
+/**
+ * URL of the page after this one, or null when the collection is exhausted.
+ * Receives the page's item count so page-number APIs (GitHub, GitLab) can stop
+ * on a short page, while cursor APIs (Bitbucket) read a link out of the body.
+ */
+nextUrl, opts = {}) {
+    const maxPages = Math.max(1, opts.maxPages ?? 10);
+    const items = [];
+    let url = firstUrl;
+    for (let page = 1; page <= maxPages; page++) {
+        const res = await request(url, init, opts);
+        if (!res.ok)
+            return { items, ok: false, truncated: false, error: res.error };
+        const pageItems = extract(res.body);
+        items.push(...pageItems);
+        url = nextUrl(res.body, page, pageItems.length);
+        if (!url)
+            return { items, ok: true, truncated: false };
+    }
+    return { items, ok: true, truncated: true };
+}

package/dist/utils/logger.d.ts

@@ -1,19 +1,65 @@
+/** Destination for log lines; see {@link Logger.setSink}. */
+export interface LogSink {
+    out(chunk: string): void;
+    err(chunk: string): void;
+}
 export type LogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
+/** How a line is rendered. */
+export type LogFormat = 'pretty' | 'ci' | 'json';
+export interface LoggerOptions {
+    level?: LogLevel;
+    format?: LogFormat;
+    color?: 'auto' | 'always' | 'never';
+    timestamps?: boolean;
+    /** Levels routed to stderr rather than stdout. */
+    stderrLevels?: LogLevel[];
+}
 export declare class Logger {
-    private logs;
-    private levelOrder;
     private currentLevel;
-    private getTimestamp;
+    private format;
+    private color;
+    private timestamps;
+    private stderrLevels;
+    constructor(options?: LoggerOptions);
+    /** Apply options; unset fields keep their current value. */
+    configure(options: LoggerOptions): void;
     private shouldLog;
-    private colorize;
+    private streamFor;
+    /**
+     * Where lines actually go. Swappable so tests can capture output without
+     * touching `process.stdout`.
+     *
+     * That distinction is not stylistic. Node's test runner reports each file's
+     * results to the parent process over stdout, so a test that replaces
+     * `process.stdout.write` and swallows what it receives also swallows those
+     * frames: the parent then waits forever for a file that already finished. It
+     * only shows up under load — on a two-core CI runner the frames land inside
+     * the capture window, on a developer's machine they usually do not — which
+     * made it a three-hour hang that never reproduced locally.
+     */
+    private sink;
+    /**
+     * Redirect output, returning the previous sink so the caller can restore it.
+     * Passing `null` restores the real streams.
+     */
+    setSink(sink: LogSink | null): LogSink | null;
+    private emit;
+    private render;
     private logMessage;
     log(msg: string): void;
     info(msg: string): void;
     warn(msg: string): void;
     error(msg: string, err?: unknown): void;
     debug(msg: string): void;
-    getLogs(): string[];
+    /**
+     * Product output: the run summary, printed verbatim.
+     *
+     * Distinct from `info` because the summary is the thing the run exists to
+     * produce, not a note about producing it. Routing it through the log formatter
+     * prefixed every line with a timestamp and a level, which pushed the box
+     * borders out of alignment and made the headline artefact look broken.
+     */
+    print(msg: string): void;
     setLevel(level: LogLevel): void;
-    clear(): void;
 }
 export declare const logger: Logger;

package/dist/utils/logger.js

@@ -1,44 +1,131 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.logger = exports.Logger = void 0;
+const LEVEL_ORDER = {
+    error: 0,
+    warn: 1,
+    info: 2,
+    log: 2,
+    debug: 3,
+};
+const COLORS = {
+    error: '\x1b[31m', // red
+    warn: '\x1b[33m', // yellow
+    info: '\x1b[32m', // green
+    log: '\x1b[37m', // white
+    debug: '\x1b[36m', // cyan
+};
+const RESET = '\x1b[0m';
+/**
+ * Whether ANSI colour is wanted on `stream`.
+ *
+ * Colour used to be emitted unconditionally, so a piped or redirected run — and
+ * every CI log — was littered with escape sequences. `NO_COLOR` is the de-facto
+ * standard (no-color.org) and `FORCE_COLOR` the usual override; both are honoured
+ * here, and the TTY test asks about the stream actually being written to.
+ */
+function wantsColor(mode, stream) {
+    if (mode === 'never')
+        return false;
+    if (mode === 'always')
+        return true;
+    if (process.env.FORCE_COLOR)
+        return process.env.FORCE_COLOR !== '0';
+    if (process.env.NO_COLOR !== undefined)
+        return false;
+    return Boolean(stream.isTTY);
+}
 class Logger {
-    constructor() {
-        this.logs = [];
-        this.levelOrder = {
-            error: 0,
-            warn: 1,
-            info: 2,
-            log: 2,
-            debug: 3,
-        };
+    constructor(options = {}) {
         this.currentLevel = 'info';
+        this.color = 'auto';
+        this.stderrLevels = new Set(['error', 'warn']);
+        /**
+         * Where lines actually go. Swappable so tests can capture output without
+         * touching `process.stdout`.
+         *
+         * That distinction is not stylistic. Node's test runner reports each file's
+         * results to the parent process over stdout, so a test that replaces
+         * `process.stdout.write` and swallows what it receives also swallows those
+         * frames: the parent then waits forever for a file that already finished. It
+         * only shows up under load — on a two-core CI runner the frames land inside
+         * the capture window, on a developer's machine they usually do not — which
+         * made it a three-hour hang that never reproduced locally.
+         */
+        this.sink = null;
+        // CI logs are read long after the fact and benefit from timestamps; a
+        // terminal is read as it scrolls, where they are noise that also breaks the
+        // alignment of the summary box.
+        const inCi = Boolean(process.env.CI);
+        this.format = options.format ?? (inCi ? 'ci' : 'pretty');
+        this.timestamps = options.timestamps ?? this.format === 'ci';
+        this.configure(options);
     }
-    getTimestamp() {
-        return new Date().toISOString();
+    /** Apply options; unset fields keep their current value. */
+    configure(options) {
+        if (options.level)
+            this.currentLevel = options.level;
+        if (options.format) {
+            this.format = options.format;
+            if (options.timestamps === undefined)
+                this.timestamps = options.format === 'ci';
+        }
+        if (options.color)
+            this.color = options.color;
+        if (options.timestamps !== undefined)
+            this.timestamps = options.timestamps;
+        if (options.stderrLevels)
+            this.stderrLevels = new Set(options.stderrLevels);
     }
     shouldLog(level) {
-        return this.levelOrder[level] <= this.levelOrder[this.currentLevel];
+        return LEVEL_ORDER[level] <= LEVEL_ORDER[this.currentLevel];
+    }
+    streamFor(level) {
+        return this.stderrLevels.has(level) ? process.stderr : process.stdout;
+    }
+    /**
+     * Redirect output, returning the previous sink so the caller can restore it.
+     * Passing `null` restores the real streams.
+     */
+    setSink(sink) {
+        const previous = this.sink;
+        this.sink = sink;
+        return previous;
     }
-    colorize(level, message) {
-        const colors = {
-            error: '\x1b[31m', // red
-            warn: '\x1b[33m', // yellow
-            info: '\x1b[32m', // green
-            log: '\x1b[37m', // white
-            debug: '\x1b[36m', // cyan
-        };
-        const reset = '\x1b[0m';
-        return `${colors[level]}${message}${reset}`;
+    emit(stream, text) {
+        if (!this.sink) {
+            stream.write(text);
+            return;
+        }
+        if (stream === process.stderr)
+            this.sink.err(text);
+        else
+            this.sink.out(text);
+    }
+    render(level, message, error) {
+        const stack = error instanceof Error ? `\n${error.stack}` : '';
+        if (this.format === 'json') {
+            return JSON.stringify({
+                level,
+                message,
+                ...(stack ? { stack: stack.trim() } : {}),
+                time: new Date().toISOString(),
+            });
+        }
+        const time = this.timestamps ? `[${new Date().toISOString()}] ` : '';
+        const tag = this.format === 'ci' ? `[${level.toUpperCase()}] ` : '';
+        return `${time}${tag}${message}${stack}`;
     }
     logMessage(level, message, error) {
         if (!this.shouldLog(level))
             return;
-        const timestamp = this.getTimestamp();
-        const fullMessage = `[${timestamp}] [${level.toUpperCase()}] ${message}` +
-            (error instanceof Error ? `\n${error.stack}` : '');
-        this.logs.push(fullMessage);
-        /* eslint-disable-next-line no-console */
-        console.log(this.colorize(level, fullMessage));
+        const stream = this.streamFor(level);
+        const line = this.render(level, message, error);
+        // JSON output is meant to be parsed; coloring it would corrupt the payload.
+        const colored = this.format !== 'json' && wantsColor(this.color, stream)
+            ? `${COLORS[level]}${line}${RESET}`
+            : line;
+        this.emit(stream, `${colored}\n`);
     }
     log(msg) {
         this.logMessage('log', msg);
@@ -55,15 +142,20 @@ class Logger {
     debug(msg) {
         this.logMessage('debug', msg);
     }
-    getLogs() {
-        return this.logs;
+    /**
+     * Product output: the run summary, printed verbatim.
+     *
+     * Distinct from `info` because the summary is the thing the run exists to
+     * produce, not a note about producing it. Routing it through the log formatter
+     * prefixed every line with a timestamp and a level, which pushed the box
+     * borders out of alignment and made the headline artefact look broken.
+     */
+    print(msg) {
+        this.emit(process.stdout, `${msg}\n`);
     }
     setLevel(level) {
         this.currentLevel = level;
     }
-    clear() {
-        this.logs = [];
-    }
 }
 exports.Logger = Logger;
 exports.logger = new Logger();

package/dist/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/utils/pool.js

@@ -0,0 +1,124 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Semaphore = void 0;
+exports.runPool = runPool;
+exports.defaultConcurrency = defaultConcurrency;
+exports.resolveConcurrency = resolveConcurrency;
+exports.withTimeout = withTimeout;
+const node_os_1 = __importDefault(require("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.
+ */
+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.
+ */
+function defaultConcurrency() {
+    const cores = node_os_1.default.cpus()?.length ?? 2;
+    return Math.max(1, Math.min(4, cores - 1));
+}
+/** Resolve the client's `run.concurrency` setting into a number. */
+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.
+ */
+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++;
+    }
+}
+exports.Semaphore = Semaphore;
+/**
+ * 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.
+ */
+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/utils/update-notifier.d.ts

@@ -1,3 +1,5 @@
+/** 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).
@@ -6,5 +8,12 @@
  * 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/utils/update-notifier.js

@@ -3,9 +3,18 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isMajorUpgrade = isMajorUpgrade;
 exports.getUpdateNotice = getUpdateNotice;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+// 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.
+const constants_1 = require("../config/constants");
+// 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);
@@ -16,6 +25,33 @@ function isNewer(latest, current) {
     }
     return false;
 }
+/** True when the upgrade crosses a major version, i.e. behaviour may change. */
+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).
@@ -24,6 +60,13 @@ function isNewer(latest, current) {
  * 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.
  */
 async function getUpdateNotice(timeoutMs = 2500) {
     if (process.env.PR_CHECKMATE_NO_UPDATE_CHECK)
@@ -45,10 +88,21 @@ async function getUpdateNotice(timeoutMs = 2500) {
             clearTimeout(timer);
         }
         if (latest && isNewer(latest, pkg.version)) {
+            const major = isMajorUpgrade(latest, pkg.version);
             return [
-                `⬆️  A new version of ${pkg.name} is available: ${pkg.version} → ${latest}`,
-                `    Update:  npm install ${pkg.name}@latest`,
-                '    Details: https://www.npmjs.com/package/pr-checkmate',
+                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:    ${constants_1.DOCS_URL}`,
+                `  📦 Release: https://www.npmjs.com/package/${pkg.name}`,
+                NOTICE_BORDER,
             ];
         }
         return null;