pr-checkmate 1.23.23 → 2.0.0

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

package/dist/init.js

@@ -3,7 +3,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.mergeWithDefaults = mergeWithDefaults;
+exports.BLOCKING_BY_DEFAULT = void 0;
+exports.setupWorkflow = setupWorkflow;
+exports.buildInitialConfig = buildInitialConfig;
 exports.init = init;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -12,184 +14,11 @@ const config_1 = require("./config");
 const utils_1 = require("./utils");
 const CONFIG_FILE = path_1.default.resolve(process.cwd(), 'pr-checkmate.json');
 /**
- * Default configuration structure with customization options
+ * Points editors at the bundled JSON schema. With the generated config reduced
+ * to the client's own decisions, this line is what makes every other option
+ * discoverable: the editor autocompletes each key and shows its description.
  */
-const DEFAULT_CONFIG = {
-    // Points editors (VS Code, etc.) at the bundled JSON schema for autocomplete
-    // and inline validation of this file.
-    $schema: './node_modules/pr-checkmate/pr-checkmate.schema.json',
-    // Available CLI commands — kept at the very top as a quick reference.
-    // Informational only; PR CheckMate ignores this at runtime.
-    commands: config_1.DEFAULT_COMMANDS,
-    // Human-readable hints. JSON has no comments, so these `//`-prefixed keys are
-    // just informational strings — PR CheckMate ignores them at runtime.
-    '// reporting': [
-        'Results post to the PR/MR automatically.',
-        'GitHub: no setup — the runner injects GITHUB_TOKEN; just keep `permissions: pull-requests: write` in the workflow.',
-        'GitLab: create a token (Project → Settings → Access Tokens, scope `api`) and add it as CI/CD variable GITLAB_TOKEN.',
-        'Bitbucket: create a token (Repo → Settings → Access tokens, scope pull-requests:write) and add it as repo variable BITBUCKET_TOKEN.',
-        'The token lives in YOUR CI variables, never in this file. Without it, checks still run and print to the log — only the comment is skipped.',
-    ].join(' '),
-    sourcePath: '.',
-    // Directories excluded from every check (matched on any path segment). Edit
-    // freely — add your own generated/vendored dirs or remove ones you want scanned.
-    ignoreDirs: config_1.IGNORED_DIRS,
-    // ESLint — `rules` starts EMPTY on purpose and holds overrides only, each merged
-    // over the bundled default for that one rule.
-    //
-    // It used to be written out in full (all 27 rules with their severities) so every
-    // rule was visible and editable in this file. That copy then won over the bundled
-    // defaults forever: `eslint.rules` is in REPLACED_OBJECT_PATHS, so a later `init`
-    // keeps the user's block wholesale, and improvements to the defaults never reached
-    // a repo that had ever run `init`. Downgrading `prettier/prettier` from error to
-    // warn — so formatting stops failing pipelines — is exactly such an improvement,
-    // and it stopped at the config boundary for every existing client.
-    //
-    // The full list with defaults lives in the ESLint check documentation and in the
-    // package's own eslint-default-rules.json; discoverability there costs nothing,
-    // un-updatable defaults cost every client an edit.
-    eslint: {
-        rules: {},
-        ignorePatterns: [],
-    },
-    // Prettier customization
-    prettier: {
-        rules: {},
-    },
-    // Spellcheck (cspell). `enabled: false` turns the check off — that part always
-    // applies. The lists feed the cspell config pr-checkmate generates, so they are
-    // ignored when the repo has a cspell.json of its own; all of them are appended to
-    // the bundled defaults. `ignorePaths` takes globs to skip (e.g. "CHANGELOG.md",
-    // "generated/**"), anchored to the repo root so a pattern never matches a
-    // directory above the checkout.
-    cspell: {
-        enabled: true,
-        words: [],
-        ignorePaths: [],
-        ignoreRegExpList: [],
-    },
-    // Markdownlint customization
-    markdownlint: {
-        rules: {},
-        ignores: [],
-    },
-    // YAML lint (bundled `yaml` parser). Reports syntax errors, duplicate keys,
-    // and tab/indentation problems in .yml/.yaml files. Blocking by default
-    // (severity "error"); set severity "warn" to make it advisory, or enabled
-    // false to disable. `ignore` takes glob patterns to skip (e.g. "charts/**").
-    yamlLint: {
-        enabled: true,
-        ignore: [],
-    },
-    // TypeScript type check
-    typecheck: {
-        enabled: true,
-    },
-    // Diff code smell detection
-    diffSmell: {
-        enabled: true,
-    },
-    // PR description validation
-    prBody: {
-        enabled: true,
-        minLength: 20,
-        requireTicket: true,
-    },
-    // Duplicate code detection (jscpd)
-    duplicate: {
-        enabled: true,
-        minLines: 5,
-        minTokens: 50,
-        // Test files/folders are excluded by default; edit to customise.
-        ignore: config_1.DUPLICATE_IGNORE_DEFAULTS,
-        // Only source-code formats are scanned. Data formats (yaml, json, markdown)
-        // are intentionally absent — add them here to detect duplication in them too.
-        formats: config_1.DUPLICATE_CODE_FORMATS,
-    },
-    // Dependency usage check (knip)
-    dependency: {
-        enabled: true,
-        // Dependency names to skip (e.g. CLI-only tools invoked as binaries,
-        // which knip can't see as imports and would report as unused).
-        ignore: [],
-    },
-    // Circular-import check (dpdm, bundled — nothing needed on the runner). Uses
-    // the project's own dpdm when it has one. Advisory by default (severity
-    // "warn"): most repos have long-standing cycles through barrel files, so see
-    // yours first, then set severity "error" to gate merges on them. enabled false
-    // disables the check; `ignore` takes glob patterns kept out of the analysis
-    // (generated or vendored code, or barrels whose cycles you tolerate). When the
-    // analyzer cannot run, the check skips rather than passing or failing.
-    circularDeps: {
-        enabled: true,
-        severity: 'warn',
-        ignore: [],
-        timeoutMs: 120000,
-    },
-    // Unused-exports check (ts-unused-exports)
-    deadCode: {
-        enabled: true,
-        // Regex sources matched against file paths; matching files are dropped from
-        // the report. Defaults to test/mock files, whose exports are used only by the
-        // test runner. Add barrels/entry points here to exempt intentional exports.
-        ignoreFiles: config_1.DEAD_CODE_IGNORE_DEFAULTS,
-    },
-    // User-defined rules: regex patterns run against added diff lines. The escape
-    // hatch to enforce any project rule without code. Example entry:
-    //   { "name": "no-focused-tests", "pattern": "\\b(describe|it)\\.only\\(",
-    //     "message": "focused test left in", "severity": "error",
-    //     "include": ["src/**"], "exclude": ["**/*.test.*"] }
-    customRules: [],
-    // Universal per-check severity override, keyed by the check's display name (as
-    // shown in the report). "error" fails the run, "warn" is advisory, "off"
-    // disables the check. Empty by default — every check uses its built-in
-    // severity. Examples: { "Merge Conflict": "warn", "ESLint": "error" }.
-    severity: {},
-    // Git / PR-diff heuristics (delta-aware). Merge Conflict is blocking by
-    // default; the rest are advisory — promote any of them with `severity`.
-    mergeConflict: { enabled: true },
-    leftoverDebug: { enabled: true },
-    lockfileDrift: { enabled: true },
-    largeFiles: { enabled: true, maxSizeKb: 500, allow: [] },
-    missingTests: { enabled: true },
-    todoFixme: { enabled: true, requireTicket: false },
-    migrationSafety: { enabled: true },
-    // Security (regex diff scans + sensitive-file guard). Secret scan / npm audit
-    // live under `security`.
-    diffSecurity: { enabled: true },
-    sensitiveFileGuard: { enabled: true },
-    workflowSecurity: { enabled: true }, // GitHub Actions: injection, unpinned actions
-    dockerfileSecurity: { enabled: true }, // Dockerfile: :latest, USER root, curl|bash, …
-    caseCollision: { enabled: true }, // files differing only by case
-    vulnScan: { enabled: false }, // cross-language dep vulns (osv-scanner, runner-dependency)
-    // dep vulns (grype, non-blocking, runner-dependency; skips if grype absent).
-    // Never walks `ignoreDirs`; `timeoutMs` caps the scan so it cannot stall a commit.
-    grypeScan: { enabled: true, minSeverity: 'medium', timeoutMs: 120000 },
-    // Test-coverage presence. Opt-in: enable once your CI produces a coverage
-    // report (lcov/cobertura/jacoco/…); warns if none is found.
-    coverage: { enabled: false },
-    // PR metadata / dependency hygiene.
-    prSize: { enabled: true, maxFiles: 50, maxLines: 1000 },
-    commitlint: { enabled: true },
-    // Dependencies you want to forbid. Example: { "name": "moment", "message": "use date-fns" }.
-    bannedImports: [],
-    // License/copyright header on new source files. Opt-in — set enabled + pattern.
-    licenseHeader: { enabled: false, pattern: '', lines: 10 },
-    outdatedDeps: { enabled: true, ignore: [] },
-    // Per-language checks. Bundled (no client install): TypeScript, Python (Ruff),
-    // C++ (clang-format). Runner-dependency (need the tool on the runner, skip
-    // gracefully if absent): Swift, Kotlin, Go, Rust, C#, Ruby, PHP.
-    python: { enabled: true, typecheck: true },
-    cpp: { enabled: true },
-    swift: { enabled: true },
-    kotlin: { enabled: true },
-    go: { enabled: true },
-    rust: { enabled: true },
-    csharp: { enabled: true },
-    ruby: { enabled: true },
-    php: { enabled: true },
-    documentation: config_1.documentation,
-};
+const SCHEMA_PATH = './node_modules/pr-checkmate/pr-checkmate.schema.json';
 const MANUAL_ENTRY = 'Enter manually';
 /** Prompt the user for the project source path, allowing a manual entry. */
 async function promptSourcePath() {
@@ -213,8 +42,55 @@ async function promptSourcePath() {
     ]);
     return answers.sourcePath === MANUAL_ENTRY ? answers.manualPath : answers.sourcePath;
 }
-/** Copy the bundled GitHub Actions workflow into the consumer repo. */
-function setupWorkflow(root) {
+/**
+ * Ask whether the generated workflow should block merges.
+ *
+ * Two levers decide strictness and they are not interchangeable: this one says
+ * whether a failed run means anything to GitHub at all, while `severity` in
+ * pr-checkmate.json says which findings count as a failure. The recommended way
+ * into an existing codebase is a strict workflow plus a permissive config — the
+ * gate is real from day one, and checks are promoted one at a time.
+ */
+async function promptGateMode() {
+    const { mode } = await inquirer_1.default.prompt([
+        {
+            type: 'select',
+            name: 'mode',
+            message: 'Should a failed check block the pull request?',
+            default: 'strict',
+            choices: [
+                { name: 'Yes — block the merge (recommended)', value: 'strict' },
+                { name: 'No — report only, never block', value: 'advisory' },
+            ],
+        },
+    ]);
+    return mode;
+}
+/** The banner an advisory workflow carries, so it reads as a decision, not an accident. */
+const ADVISORY_NOTICE = [
+    '      # ADVISORY MODE — this run cannot block a merge.',
+    '      #',
+    '      # Chosen at `pr-checkmate init`. Reasonable while adopting the tool on an',
+    '      # existing codebase, but it also means a detected secret does not stop the',
+    '      # PR. To make this a real gate, delete the `continue-on-error` line below.',
+    '      #',
+    '      # Prefer the opposite arrangement: keep the gate real and relax individual',
+    '      # checks in pr-checkmate.json instead —',
+    '      #   "severityDefaults": { "failOn": "warn" }   everything advisory',
+    '      #   "severity": { "Security Scan": "error" }   promote one back to a gate',
+    '      # That way whatever you have already made clean stays enforced.',
+].join('\n');
+/** Indented to sit inside the step, not beside it — YAML is unforgiving here. */
+const ADVISORY_FLAG = '        continue-on-error: true';
+/**
+ * Write the bundled GitHub Actions workflow into the consumer repo.
+ *
+ * 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.
+ */
+function setupWorkflow(root, mode) {
     const workflowSource = path_1.default.join(__dirname, 'config', 'pr-checkmate-workflow.yml');
     const workflowDir = path_1.default.join(root, '.github', 'workflows');
     const workflowDest = path_1.default.join(workflowDir, 'pr-checkmate.yml');
@@ -222,13 +98,22 @@ function setupWorkflow(root) {
         utils_1.logger.warn('[init]: ⚠️ Workflow template not found, skipping workflow setup');
         return;
     }
+    if (fs_1.default.existsSync(workflowDest)) {
+        utils_1.logger.info('[init]: ⏭️ .github/workflows/pr-checkmate.yml already exists — left untouched');
+        return;
+    }
     if (!fs_1.default.existsSync(workflowDir)) {
         fs_1.default.mkdirSync(workflowDir, { recursive: true });
     }
-    fs_1.default.copyFileSync(workflowSource, workflowDest);
-    utils_1.logger.info('[init]: ✅ Created .github/workflows/pr-checkmate.yml');
-    utils_1.logger.info('[init]: GitHub Actions workflow is ready for your PRs!');
+    const template = fs_1.default.readFileSync(workflowSource, 'utf-8');
+    const workflow = mode === 'advisory'
+        ? template.replace(RUN_STEP_ANCHOR, `${ADVISORY_NOTICE}\n${RUN_STEP_ANCHOR}\n${ADVISORY_FLAG}`)
+        : template;
+    fs_1.default.writeFileSync(workflowDest, workflow);
+    utils_1.logger.info(`[init]: ✅ Created .github/workflows/pr-checkmate.yml (${mode === 'strict' ? 'blocking' : 'advisory'})`);
 }
+/** Where the advisory banner is spliced in — the step that runs the checks. */
+const RUN_STEP_ANCHOR = '      - name: Run PR CheckMate';
 /** Create a tsconfig.json scaffold if the consumer repo lacks one. */
 function setupTsConfig(root, sourcePath) {
     const tsconfigPath = path_1.default.join(root, 'tsconfig.json');
@@ -254,107 +139,164 @@ function setupTsConfig(root, sourcePath) {
     fs_1.default.writeFileSync(tsconfigPath, JSON.stringify(newTsConfig, null, 2));
     utils_1.logger.info('[init]: ✅ Created tsconfig.json using your sourcePath');
 }
+/**
+ * The file `init` writes for a new project — the client's decisions, nothing else.
+ *
+ * Every other setting is deliberately absent. The config is deep-merged over the
+ * built-in defaults when it is loaded, so a key that repeats a default changes
+ * nothing: it only lengthens the file and freezes today's value in someone
+ * else's repository. Three hundred generated lines also read as a wall of
+ * settings to maintain, when there is nothing to maintain.
+ *
+ * Discoverability moves to two places that cannot go stale — `$schema`, which
+ * makes an editor autocomplete every option with its description, and the
+ * annotated reference shipped inside the package.
+ */
+/** The one-line answer to "how do I change this" — see {@link buildInitialConfig}. */
+const REPORTING_HINT = [
+    'Results post to the PR/MR automatically.',
+    'GitHub: keep `permissions: pull-requests: write` AND pass the token to the step',
+    '(`env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}`) — Actions does not provide it',
+    'on its own, and without it the comment is silently skipped. The generated',
+    'workflow already does both.',
+    'GitLab: create a token (Project → Settings → Access Tokens, scope `api`) and add',
+    'it as CI/CD variable GITLAB_TOKEN.',
+    'Bitbucket: create a token (Repo → Settings → Access tokens, scope',
+    'pull-requests:write) and add it as repo variable BITBUCKET_TOKEN.',
+    'The token lives in YOUR CI variables, never in this file. Without it checks',
+    'still run and print to the log — only the comment is skipped.',
+].join(' ');
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+exports.BLOCKING_BY_DEFAULT = [
+    'Security Scan',
+    'Sensitive Files',
+    'Diff Security',
+    'Workflow Security',
+    'Merge Conflict',
+    'NPM Audit',
+    'License Check',
+    'Dependencies',
+    'TypeScript',
+    'ESLint',
+    'YAML Lint',
+];
+const HOW_TO = [
+    'Only what differs from the defaults belongs here — everything else is implicit',
+    'and stays current on upgrade, so this file stays short.',
+    'Turn a check off:      "severity": { "Spellcheck": "off" }',
+    'Make one advisory:     "severity": { "Sensitive Files": "warn" }',
+    'Make everything advisory while adopting: "severityDefaults": { "failOn": "warn" }',
+    'Skip a file or folder: "excludePaths": ["src/generated/**", "vendor/legacy.ts"]',
+    'Check names are the ones printed in the report.',
+    `Every option, annotated, with its default: ${config_1.FULL_CONFIG_URL}`,
+    `Docs: ${config_1.DOCS_URL}`,
+].join(' ');
+function buildInitialConfig(sourcePath, languages) {
+    return {
+        $schema: SCHEMA_PATH,
+        '// how-to': HOW_TO,
+        commands: config_1.DEFAULT_COMMANDS,
+        '// reporting': REPORTING_HINT,
+        sourcePath,
+        // What can stop a merge, and how to stand any of it down. "warn" keeps the
+        // finding in the report without failing the run; "off" removes the check.
+        severity: Object.fromEntries(exports.BLOCKING_BY_DEFAULT.map(name => [name, 'error'])),
+        // The knobs people reach for first, seeded EMPTY.
+        //
+        // Empty is the whole point: an empty container changes nothing, so it cannot
+        // freeze today's default in someone else's repository, but it puts the edit
+        // one line away instead of behind a lookup. Which blocks appear here is
+        // decided by what actually makes noise in real repositories — spelling,
+        // lint rules, generated files, knip's guesses about unused dependencies.
+        //
+        // Three blocks are deliberately NOT here, because for them an empty value is
+        // not neutral — it REPLACES a non-empty default and makes things worse:
+        //   ignoreDirs           → seeded empty, nothing is ignored at all
+        //   duplicate.ignore     → test boilerplate starts reporting as duplication
+        //   deadCode.ignoreFiles → test helpers start reporting as unused exports
+        // Anyone who needs those sets them deliberately, with the defaults in view.
+        excludePaths: [],
+        cspell: { words: [], ignorePaths: [] },
+        eslint: { rules: {}, ignorePatterns: [] },
+        markdownlint: { ignores: [] },
+        dependency: { ignore: [] },
+        circularDeps: { ignore: [] },
+        yamlLint: { ignore: [] },
+        documentation: config_1.documentation,
+        languages,
+    };
+}
 /** First-run setup: prompt, write config, and scaffold workflow + tsconfig. */
 async function createConfig(root) {
     const sourcePath = await promptSourcePath();
+    const gateMode = await promptGateMode();
     const languages = await (0, utils_1.detectLanguages)(root);
     utils_1.logger.info(`[init]: 🔍 Detected languages: ${languages.length ? languages.join(', ') : 'none'}`);
-    const config = {
-        ...DEFAULT_CONFIG,
-        sourcePath,
-        languages,
-    };
-    // Omit config blocks for languages not present in the repo — a cleaner,
-    // tailored file. This does NOT disable them: the key is simply absent, which
-    // still defaults to enabled, and runtime language detection gates whether each
-    // check runs. So a language added later auto-activates without editing config.
-    const LANGUAGE_TOGGLE_KEYS = [
-        'python',
-        'cpp',
-        'swift',
-        'kotlin',
-        'go',
-        'rust',
-        'csharp',
-        'ruby',
-        'php',
-    ];
-    for (const key of LANGUAGE_TOGGLE_KEYS) {
-        if (!languages.includes(key))
-            delete config[key];
-    }
-    fs_1.default.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+    const config = buildInitialConfig(sourcePath, languages);
+    fs_1.default.writeFileSync(CONFIG_FILE, `${JSON.stringify(config, null, 2)}\n`);
     utils_1.logger.info(`[init]: ✅ Created pr-checkmate.json with sourcePath: ${sourcePath}`);
     utils_1.logger.info(`[init]: 💡 You can now customize ESLint rules, Prettier settings,
       and cspell words in pr-checkmate.json`);
-    setupWorkflow(root);
+    setupWorkflow(root, gateMode);
     setupTsConfig(root, sourcePath);
 }
-function isPlainObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 /**
- * Config paths whose object value is a curated list, not a set of settings — the
- * user is meant to add and remove entries, exactly like an array.
+ * Re-run setup: refresh the detected languages and leave everything else alone.
  *
- * These are merged the way arrays are: the user's object replaces the default one
- * wholesale. Deep-merging them would hand back every rule the user deleted, and for
- * `eslint.rules` that is not cosmetic — Lint is a blocking check, so a re-run of
- * `init` would silently reinstate rules and start failing the next PR on them. The
- * documented way to switch a rule off is `"off"`, which survives either way.
+ * It used to merge current defaults into the client's file, which is why the
+ * update notice insisted `init` must not be skipped after an upgrade. Defaults
+ * now apply when the config is loaded, so there is nothing to top up.
  */
-const REPLACED_OBJECT_PATHS = new Set(['eslint.rules', 'prettier.rules', 'markdownlint.rules']);
-/**
- * Merge current defaults into an existing config, recursively.
- *
- * 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.
- *
- * Informational `//`-prefixed keys are the one exception — they are documentation,
- * not settings, so the refreshed default text wins whenever a default exists.
- *
- * @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.
- */
-function mergeWithDefaults(defaults, user, path = '') {
-    const merged = { ...defaults };
-    for (const [key, userValue] of Object.entries(user)) {
-        const defaultValue = defaults[key];
-        const keyPath = path ? `${path}.${key}` : key;
-        if (key.startsWith('//') && defaultValue !== undefined)
-            continue;
-        merged[key] =
-            isPlainObject(defaultValue) && isPlainObject(userValue) && !REPLACED_OBJECT_PATHS.has(keyPath)
-                ? mergeWithDefaults(defaultValue, userValue, keyPath)
-                : userValue;
-    }
-    return merged;
-}
-/** Re-run setup: merge the existing config with current defaults. */
 async function updateConfig(root) {
     utils_1.logger.info('[init]: pr-checkmate.json already exists — updating it.');
     try {
         const raw = fs_1.default.readFileSync(CONFIG_FILE, 'utf-8');
         const json = JSON.parse(raw);
-        const languages = await (0, utils_1.detectLanguages)(root);
+        // Re-detection has to obey the config it is about to rewrite: a client who
+        // tuned `detect` (or `ignoreDirs`) precisely because detection was wrong
+        // would otherwise get the wrong answer written back over the right one on
+        // the next `init`.
+        const languages = await (0, utils_1.detectLanguages)(root, json.ignoreDirs, json.detect);
         utils_1.logger.info(`[init]: 🔍 Detected languages: ${languages.length ? languages.join(', ') : 'none'}`);
-        // Merge with defaults to add new fields at every depth — a hand-maintained
-        // list of sections to merge would silently stop delivering new defaults to
-        // existing configs the moment a section is forgotten.
+        // The client's file is left exactly as they wrote it. Defaults are no longer
+        // copied into it, because they never needed to be: they are merged in when
+        // the config is loaded, so a new default reaches every repository on upgrade
+        // without anyone editing anything. Writing them here only grew the file and
+        // made `init` a step nobody could safely skip after a release.
+        //
+        // `languages` is still refreshed — it is a fact about the repository, not a
+        // preference. `$schema` and the how-to hint are added when missing, because
+        // an existing config is exactly the case where nobody has seen them: the
+        // people who most need to know how to switch a check off are the ones whose
+        // file predates the advice.
         const updated = {
-            ...mergeWithDefaults(DEFAULT_CONFIG, json),
-            // Refresh detected languages on every init so new source dirs are picked up
+            $schema: json.$schema ?? SCHEMA_PATH,
+            '// how-to': json['// how-to'] ?? HOW_TO,
+            ...json,
             languages,
         };
-        fs_1.default.writeFileSync(CONFIG_FILE, JSON.stringify(updated, null, 2));
-        utils_1.logger.info('[init]: 🔧 Updated pr-checkmate.json with customization options.');
-        utils_1.logger.info('[init]: 💡 You can now add custom ESLint rules, cspell words, and more!');
+        fs_1.default.writeFileSync(CONFIG_FILE, `${JSON.stringify(updated, null, 2)}\n`);
+        utils_1.logger.info('[init]: 🔧 Refreshed the detected languages in pr-checkmate.json.');
+        utils_1.logger.info(`[init]: 💡 Everything else is left as you wrote it — defaults apply on their own. Options: ${config_1.DOCS_URL}`);
     }
     catch (e) {
         utils_1.logger.error(`[init]: ❌ Failed to update pr-checkmate.json: ${e}`);