pr-checkmate 3.0.4 → 3.2.0

package/dist/esm/core/checks/pr/pr-title-lint.js

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import { logger } from '../../../utils/index.js';
+import { pass, warn, skip } from '../../types.js';
+const CONVENTIONAL_PREFIX = /^(feat|fix|docs|style|refactor|test|chore|perf|ci|build|revert)(\(.+\))?!?: .+/;
+export const prTitleLintCheck = {
+    name: 'PR Title',
+    phase: 'informational',
+    applies() {
+        const eventPath = process.env.GITHUB_EVENT_PATH;
+        return Boolean(eventPath && fs.existsSync(eventPath));
+    },
+    async run() {
+        let event;
+        try {
+            event = JSON.parse(fs.readFileSync(process.env.GITHUB_EVENT_PATH, 'utf-8'));
+        }
+        catch (err) {
+            logger.warn(`[PR Title]: ⚠️ Could not read GitHub event\n${err}`);
+            return skip('event unreadable');
+        }
+        const pr = event.pull_request;
+        if (!pr?.title)
+            return skip('no PR title');
+        const title = pr.title;
+        if (!CONVENTIONAL_PREFIX.test(title)) {
+            logger.warn(`[PR Title]: ⚠️ Not Conventional Commits: "${title}"`);
+            return warn('title does not follow Conventional Commits');
+        }
+        return pass();
+    },
+};

package/dist/esm/core/checks/quality/case-collision.d.ts

@@ -0,0 +1,8 @@
+import { Check } from '../../types.js';
+/**
+ * Flags tracked files whose paths differ only by case (e.g. `Foo.ts` vs
+ * `foo.ts`). Such pairs coexist on Linux (case-sensitive) but collide on macOS/
+ * Windows and in many Docker layers, silently breaking checkouts and builds.
+ * Whole-repo scan (not delta), scoped to `sourcePath` and honouring `ignoreDirs`.
+ */
+export declare const caseCollisionCheck: Check;

package/dist/esm/core/checks/quality/case-collision.js

@@ -0,0 +1,39 @@
+import { logger } from '../../../utils/index.js';
+import { resolveTargets } from '../../targets.js';
+import { pass, warn } from '../../types.js';
+/**
+ * Flags tracked files whose paths differ only by case (e.g. `Foo.ts` vs
+ * `foo.ts`). Such pairs coexist on Linux (case-sensitive) but collide on macOS/
+ * Windows and in many Docker layers, silently breaking checkouts and builds.
+ * Whole-repo scan (not delta), scoped to `sourcePath` and honouring `ignoreDirs`.
+ */
+export const caseCollisionCheck = {
+    name: 'Case Collision',
+    phase: 'informational',
+    applies(ctx) {
+        return ctx.config.caseCollision?.enabled !== false;
+    },
+    async run(ctx) {
+        const files = await resolveTargets(ctx, ['*'], {
+            wholeTree: true,
+            onEmpty: { skip: 'no tracked files' },
+        });
+        if (!Array.isArray(files))
+            return files;
+        const byLower = new Map();
+        for (const f of files) {
+            const key = f.toLowerCase();
+            let set = byLower.get(key);
+            if (!set) {
+                set = new Set();
+                byLower.set(key, set);
+            }
+            set.add(f);
+        }
+        const collisions = [...byLower.values()].filter(set => set.size > 1);
+        if (collisions.length === 0)
+            return pass();
+        collisions.forEach(set => logger.warn(`[Case Collision]: ⚠️ ${[...set].join(' ↔ ')}`));
+        return warn(`${collisions.length} case-collision(s) — paths differing only by case`);
+    },
+};

package/dist/esm/core/checks/quality/config-validation.d.ts

@@ -0,0 +1,11 @@
+import { Check } from '../../types.js';
+/**
+ * The closest real name to `input`, when one is close enough to be a typo.
+ *
+ * "unknown check" alone leaves someone rereading their config for the missing
+ * character; naming the intended check ends the search. The threshold scales
+ * with length so short names need an exact-ish match and long ones tolerate a
+ * slip or two.
+ */
+export declare function suggestName(input: string, candidates: string[]): string | null;
+export declare const configValidationCheck: Check;

package/dist/esm/core/checks/quality/config-validation.js

@@ -0,0 +1,188 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { KNOWN_CONFIG_KEYS } from '../../../config/index.js';
+import { pass, skip, warn } from '../../types.js';
+import { severityEmitter } from '../findings.js';
+const VALID_SEVERITIES = ['error', 'warn', 'off'];
+const VALID_FAIL_ON = ['error', 'warn', 'never'];
+/** Edit distance, capped: we only care whether two names are one or two typos apart. */
+function distance(a, b) {
+    const rows = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 0; j <= b.length; j++)
+        rows[0][j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1].toLowerCase() === b[j - 1].toLowerCase() ? 0 : 1;
+            rows[i][j] = Math.min(rows[i - 1][j] + 1, rows[i][j - 1] + 1, rows[i - 1][j - 1] + cost);
+        }
+    }
+    return rows[a.length][b.length];
+}
+/**
+ * The closest real name to `input`, when one is close enough to be a typo.
+ *
+ * "unknown check" alone leaves someone rereading their config for the missing
+ * character; naming the intended check ends the search. The threshold scales
+ * with length so short names need an exact-ish match and long ones tolerate a
+ * slip or two.
+ */
+export function suggestName(input, candidates) {
+    let best = null;
+    for (const name of candidates) {
+        const d = distance(input, name);
+        if (!best || d < best.d)
+            best = { name, d };
+    }
+    const limit = Math.max(2, Math.floor(input.length / 4));
+    return best && best.d <= limit ? best.name : null;
+}
+/** Describe a bad value without dumping an entire nested object into the report. */
+function shortValue(value) {
+    const text = JSON.stringify(value);
+    return text === undefined ? String(value) : text.slice(0, 40);
+}
+/**
+ * Validate the `severity` map: values must be a known level, and — more
+ * importantly — keys must name a check that exists.
+ *
+ * A typo here is the worst kind of silent failure in the whole config. `severity`
+ * is how a client promotes an advisory check to a gate, so `"Diff Securty":
+ * "error"` reads as "this now blocks merges", does nothing at all, and leaves a
+ * green pipeline that looks like proof it worked.
+ *
+ * The misspelling above is the example, so it is muted here rather than added to
+ * the dictionary — a global entry would wave through every real "Securty" typo
+ * in the repo, which is the exact failure this function exists to catch.
+ * cspell:ignore Securty
+ */
+function validateSeverity(json, checkNames) {
+    const issues = [];
+    const sev = json.severity;
+    if (!sev || typeof sev !== 'object')
+        return issues;
+    for (const [name, val] of Object.entries(sev)) {
+        if (!VALID_SEVERITIES.includes(val)) {
+            issues.push(`severity["${name}"] must be error|warn|off (got ${shortValue(val)})`);
+        }
+        if (!checkNames.includes(name)) {
+            const hint = suggestName(name, checkNames);
+            issues.push(`severity["${name}"] names no check${hint ? ` — did you mean "${hint}"?` : ''}` +
+                ' (it has no effect)');
+        }
+    }
+    return issues;
+}
+/** `failOn` and `severityOverrides` are new and easy to mistype; check them too. */
+function validateFailOn(json) {
+    const issues = [];
+    const check = (where, block) => {
+        if (!block || typeof block !== 'object')
+            return;
+        const { failOn, severityOverrides } = block;
+        if (failOn !== undefined && !VALID_FAIL_ON.includes(failOn)) {
+            issues.push(`${where}.failOn must be error|warn|never (got ${shortValue(failOn)})`);
+        }
+        if (severityOverrides && typeof severityOverrides === 'object') {
+            for (const [label, level] of Object.entries(severityOverrides)) {
+                if (!VALID_SEVERITIES.includes(level)) {
+                    issues.push(`${where}.severityOverrides["${label}"] must be error|warn|off (got ${shortValue(level)})`);
+                }
+            }
+        }
+    };
+    check('severityDefaults', json.severityDefaults);
+    for (const key of Object.keys(json)) {
+        if (key.startsWith('//') || key === 'severityDefaults')
+            continue;
+        check(key, json[key]);
+    }
+    return issues;
+}
+/**
+ * Validates pr-checkmate.json itself: unknown top-level keys (typos like
+ * `mergeConfict` that silently do nothing), invalid values in `severity` and
+ * `failOn`, and names in `severity` that match no check. Reads the raw file so it
+ * checks what the user actually wrote, not the merged defaults. `//`-comment keys
+ * and `$schema` are ignored.
+ */
+/**
+ * Report a `sourcePath` that points nowhere.
+ *
+ * Every scoped check restricts itself to these directories, so a path that does
+ * not exist silences them — and silences them as a PASS. Measured on a fixture
+ * with `"sourcePath": "src"` and the code in `app/`: a real conflict marker in
+ * `app/conflict.py` went unreported while Merge Conflict, a blocking check,
+ * printed ✅. Nothing else in the run mentioned that most of the repository had
+ * not been looked at.
+ *
+ * `init` defaults to `.` and recommends it, so this is not the common case — it
+ * is what happens when someone picks `src` at setup, or moves the code later, and
+ * that is precisely when nobody is looking for it.
+ */
+function validateSourcePath(json, cwd) {
+    const raw = json.sourcePath;
+    if (raw === undefined)
+        return [];
+    const paths = (Array.isArray(raw) ? raw : [raw]).filter((p) => typeof p === 'string' && p.trim().length > 0);
+    return paths
+        .filter(p => {
+        const normalised = p.replace(/^\.\/?/, '').replace(/\/+$/, '');
+        // `.` and `./` mean the whole repository and always exist.
+        if (normalised === '')
+            return false;
+        return !fs.existsSync(path.join(cwd, normalised));
+    })
+        .map(p => `sourcePath "${p}" does not exist — every scoped check silently reviews nothing, and reports a pass`);
+}
+export const configValidationCheck = {
+    name: 'Config Validation',
+    phase: 'informational',
+    applies(ctx) {
+        return ctx.config.configValidation?.enabled !== false;
+    },
+    async run(ctx) {
+        const cfg = ctx.config.configValidation ?? {};
+        const file = path.join(ctx.cwd, 'pr-checkmate.json');
+        let raw;
+        try {
+            raw = fs.readFileSync(file, 'utf-8');
+        }
+        catch {
+            return skip('no pr-checkmate.json');
+        }
+        let json;
+        try {
+            json = JSON.parse(raw);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message.split('\n')[0] : String(err);
+            return warn(`pr-checkmate.json is not valid JSON: ${msg}`);
+        }
+        const issues = [];
+        const allowed = new Set(cfg.allowUnknownKeys ?? []);
+        // Absent only for a hand-built context; then there is nothing to verify names
+        // against, and claiming a name is wrong would be worse than staying quiet.
+        const checkNames = ctx.checkNames ?? [];
+        for (const key of Object.keys(json)) {
+            if (key.startsWith('//') || key === '$schema' || allowed.has(key))
+                continue;
+            if (!KNOWN_CONFIG_KEYS.has(key)) {
+                const hint = suggestName(key, [...KNOWN_CONFIG_KEYS]);
+                issues.push(`unknown key "${key}"${hint ? ` — did you mean "${hint}"?` : ''}`);
+            }
+        }
+        if (cfg.validateCheckNames !== false && checkNames.length > 0) {
+            issues.push(...validateSeverity(json, checkNames));
+        }
+        issues.push(...validateFailOn(json));
+        issues.push(...validateSourcePath(json, ctx.cwd));
+        if (issues.length === 0)
+            return pass();
+        // Advisory by default: a config problem is worth knowing about, but a repo
+        // that wants a broken config to stop the build sets `severity: "error"`.
+        const sev = severityEmitter(cfg.severity, 'warn');
+        issues.slice(0, 10).forEach(i => sev.log(`[Config Validation]: ${sev.icon} ${i}`));
+        const sample = issues.slice(0, 3).join('; ');
+        return sev.emit(`${issues.length} config issue(s): ${sample}${issues.length > 3 ? ' …' : ''}`);
+    },
+};

package/dist/esm/core/checks/quality/coverage.d.ts

@@ -0,0 +1,2 @@
+import { Check } from '../../types.js';
+export declare const coverageCheck: Check;

package/dist/esm/core/checks/quality/coverage.js

@@ -0,0 +1,62 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pass } from '../../types.js';
+import { severityEmitter } from '../findings.js';
+/**
+ * Common coverage-report locations across languages/tools. Presence of any one
+ * means the test step produced coverage. Reports are usually git-ignored, so we
+ * probe the working tree with fs, not git. A client with a non-standard path
+ * sets `coverage.reportPath`.
+ */
+const DEFAULT_REPORTS = [
+    'coverage/lcov.info', // JS/TS (lcov), C++
+    'lcov.info',
+    'coverage/coverage-final.json', // istanbul
+    'coverage/coverage-summary.json',
+    'coverage/cobertura-coverage.xml', // Cobertura (JS, Python)
+    'coverage/clover.xml',
+    'coverage.xml', // Python (pytest-cov / coverage.py)
+    'coverage.out', // Go
+    'build/reports/jacoco/test/jacocoTestReport.xml', // Kotlin/Java (Gradle)
+    'target/site/jacoco/jacoco.xml', // Java (Maven)
+];
+export const coverageCheck = {
+    name: 'Coverage',
+    phase: 'informational',
+    /**
+     * Opt-in: only runs when a repo explicitly enables it (`coverage.enabled:
+     * true`). Presence-warning by default everywhere would be pure noise in repos
+     * that don't collect coverage — so a client turns it on to say "we produce
+     * coverage", and the check then guards against the report silently going
+     * missing (a broken `--coverage` flag, tests not running, etc.).
+     */
+    applies(ctx) {
+        return ctx.config.coverage?.enabled === true;
+    },
+    async run(ctx) {
+        const cfg = ctx.config.coverage;
+        const candidates = cfg?.reportPath
+            ? Array.isArray(cfg.reportPath)
+                ? cfg.reportPath
+                : [cfg.reportPath]
+            : DEFAULT_REPORTS;
+        const found = candidates.find(rel => {
+            try {
+                // `isFile()` as well as the size: `statSync` reports a non-zero size for
+                // a directory too, so a path that happens to be one would read as a
+                // report. Non-empty matters because a zero-byte report is what a test
+                // run that died halfway leaves behind — the case this check exists for.
+                const stat = fs.statSync(path.join(ctx.cwd, rel));
+                return stat.isFile() && stat.size > 0;
+            }
+            catch {
+                return false;
+            }
+        });
+        if (found)
+            return pass(`coverage report found: ${found}`);
+        const sev = severityEmitter(cfg?.severity, 'warn');
+        sev.log(`[Coverage]: ${sev.icon} no coverage report found (looked for ${candidates.length} location(s), e.g. ${candidates.slice(0, 3).join(', ')})`);
+        return sev.emit('no coverage report found — is the test step running with coverage enabled?');
+    },
+};

package/dist/esm/core/checks/quality/dead-code.d.ts

@@ -0,0 +1,2 @@
+import { Check } from '../../types.js';
+export declare const deadCodeCheck: Check;

package/dist/esm/core/checks/quality/dead-code.js

@@ -0,0 +1,124 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEAD_CODE_IGNORE_DEFAULTS } from '../../../config/constants.js';
+import { execa } from '../../../utils/execa.js';
+import { logger, resolvePackageBin } from '../../../utils/index.js';
+import { clientToolPaths } from '../../install/reuse.js';
+import { pass, warn, skip } from '../../types.js';
+/**
+ * Resolve ts-unused-exports, preferring the consumer project's own copy (so a
+ * repo pinned to a different major keeps its own behaviour) and falling back to
+ * the copy bundled with pr-checkmate — the order `lint`/`typecheck` use for
+ * eslint/tsc, and `circular-deps` uses for dpdm.
+ *
+ * Returns null instead of throwing: an unresolvable analyzer is a skip, never a
+ * failed PR. Previously this always resolved with no `paths`, which only ever
+ * searched pr-checkmate's own bundle — a repository whose only copy of
+ * ts-unused-exports is its own dependency (ours does not declare it as a bundled
+ * dependency) hit `Cannot resolve binary` on every run.
+ */
+function resolveTsUnusedExports(ctx) {
+    // No configuration of its own — it reads the module graph via tsconfig — so
+    // the version check is the right question here and `clientOwnsConfig` stays
+    // off, same as dpdm.
+    for (const options of [{ paths: clientToolPaths('ts-unused-exports', ctx) }, undefined]) {
+        try {
+            return resolvePackageBin('ts-unused-exports', 'bin/ts-unused-exports', options);
+        }
+        catch {
+            // Try the next location; both failing is a skip, handled by the caller.
+        }
+    }
+    return null;
+}
+export const deadCodeCheck = {
+    name: 'Dead Code',
+    phase: 'informational',
+    weight: 'heavy',
+    applies(ctx) {
+        if (ctx.config.deadCode?.enabled === false)
+            return false;
+        return ctx.languages.includes('typescript');
+    },
+    async run(ctx) {
+        const tsConfigPath = path.join(ctx.cwd, 'tsconfig.json');
+        if (!fs.existsSync(tsConfigPath)) {
+            return skip('no tsconfig.json found');
+        }
+        const bin = resolveTsUnusedExports(ctx);
+        if (!bin) {
+            return skip('ts-unused-exports could not be resolved');
+        }
+        try {
+            // Run the full analysis unfiltered: ignore patterns are applied to the
+            // *report* below, not passed to ts-unused-exports' own `--ignoreFiles`.
+            // That flag drops files from analysis entirely, so a file's imports stop
+            // counting as usage — ignoring a barrel or entry point would then cascade
+            // and flag everything it re-exports. Filtering the output instead keeps
+            // every usage edge intact and only hides the exempted files' own reports.
+            const result = await execa(process.execPath, [bin, tsConfigPath], {
+                cwd: ctx.cwd,
+                reject: false,
+            });
+            const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+            if (!output || result.exitCode === 0) {
+                logger.info('[Dead Code]: ✅ No unused exports found');
+                return pass();
+            }
+            const ignore = compileIgnorePatterns(ctx.config.deadCode?.ignoreFiles ?? DEAD_CODE_IGNORE_DEFAULTS);
+            // ts-unused-exports prints one `path: sym1, sym2` line per file, preceded
+            // by a `N modules with unused exports` summary line we skip.
+            const parsed = output
+                .split('\n')
+                .map(line => line.trim().match(/^(.+\.[cm]?tsx?): (.+)$/))
+                .filter((match) => match !== null)
+                .map(match => ({
+                file: match[1],
+                symbols: match[2]
+                    .split(',')
+                    .map(sym => sym.trim())
+                    .filter(Boolean),
+            }));
+            // The tool said something and none of it was a report. That is not a clean
+            // repository — it is an answer this check cannot read, and calling it a
+            // pass is how Circular Deps stayed green on every repository for its whole
+            // existence while grepping for console wording that had changed. Same
+            // resolution as Grype Scan: say so rather than invent a verdict.
+            if (parsed.length === 0) {
+                logger.warn(`[Dead Code]: ⚠️ ts-unused-exports produced no parseable output:\n${output}`);
+                return warn('ts-unused-exports produced no parseable output');
+            }
+            const entries = parsed.filter(entry => !ignore.some(re => re.test(entry.file)));
+            if (entries.length === 0) {
+                logger.info('[Dead Code]: ✅ No unused exports found');
+                return pass();
+            }
+            const fileCount = entries.length;
+            const exportCount = entries.reduce((sum, entry) => sum + entry.symbols.length, 0);
+            logger.warn(`[Dead Code]: ⚠️ ${exportCount} unused export(s) across ${fileCount} file(s):`);
+            for (const entry of entries) {
+                logger.warn(`${entry.file}: ${entry.symbols.join(', ')}`);
+            }
+            return warn(`${exportCount} unused export(s) in ${fileCount} file(s)`);
+        }
+        catch (err) {
+            logger.warn(`[Dead Code]: ⚠️ Could not run dead code check\n${err}`);
+            return skip('ts-unused-exports unavailable');
+        }
+    },
+};
+/**
+ * Compile `deadCode.ignoreFiles` regex sources, skipping any that fail to parse
+ * (a bad pattern warns rather than aborting the whole check).
+ */
+function compileIgnorePatterns(patterns) {
+    return (patterns ?? []).filter(Boolean).flatMap(pattern => {
+        try {
+            return [new RegExp(pattern)];
+        }
+        catch {
+            logger.warn(`[Dead Code]: ⚠️ Ignoring invalid ignoreFiles pattern: ${pattern}`);
+            return [];
+        }
+    });
+}

package/dist/esm/core/checks/quality/duplicate-check.d.ts

@@ -0,0 +1,2 @@
+import { Check } from '../../types.js';
+export declare const duplicateCheck: Check;

package/dist/esm/core/checks/quality/duplicate-check.js

@@ -0,0 +1,141 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { CONFIG_FILE_PATTERNS, DUPLICATE_CODE_FORMATS, DUPLICATE_IGNORE_DEFAULTS, } from '../../../config/constants.js';
+import { getSourcePaths } from '../../../config/index.js';
+import { execa } from '../../../utils/execa.js';
+import { logger, resolvePackageBin } from '../../../utils/index.js';
+import { resolveScopedTargetFiles } from '../../targets.js';
+import { pass, warn, skip } from '../../types.js';
+import { logSample } from '../findings.js';
+/**
+ * The files to hand jscpd, per language.
+ *
+ * This map is why the check reads `ctx.languages` at all. It used to pass a fixed
+ * `*.ts,*.tsx,*.js,*.jsx` and gate itself on TypeScript/JavaScript, so a Python
+ * repository got `⏭️ Duplicate Code: no relevant files` — not because it had no
+ * duplication, but because nothing ever looked. The formats list in `constants.ts`
+ * named Python and C++ all along, which made the report's own claim untrue.
+ *
+ * Extensions mirror `detect-language.ts` so a language that decides the check runs
+ * is a language whose files it actually scans, with one deliberate addition: `.c`
+ * and `.h` under `cpp`, since a C project detects as `cpp` and the `c` format is
+ * one jscpd supports.
+ */
+const LANGUAGE_GLOBS = {
+    typescript: ['*.ts', '*.tsx'],
+    javascript: ['*.js', '*.jsx', '*.mjs', '*.cjs'],
+    python: ['*.py'],
+    cpp: ['*.cpp', '*.cc', '*.cxx', '*.c++', '*.hpp', '*.hh', '*.hxx', '*.c', '*.h'],
+    swift: ['*.swift'],
+    kotlin: ['*.kt', '*.kts', '*.java'],
+    go: ['*.go'],
+    rust: ['*.rs'],
+    csharp: ['*.cs'],
+    ruby: ['*.rb'],
+    php: ['*.php'],
+};
+/** The scan globs for one run: every detected language jscpd can tokenise. */
+function globsFor(languages) {
+    return [...new Set(languages.flatMap(lang => LANGUAGE_GLOBS[lang] ?? []))];
+}
+// Always excluded regardless of client config — scanning these never yields
+// meaningful production duplication. Config files (eslint/*.config.*) are data,
+// not logic, and are commonly shipped in two formats (e.g. .eslintrc + flat
+// config), so their repetition is expected rather than a code smell.
+const BASE_IGNORE = ['node_modules/**', 'dist/**', '.git/**', ...CONFIG_FILE_PATTERNS];
+/** `<path>:<start>-<end>`, repo-relative, for one end of a clone. */
+function locate(cwd, at) {
+    const name = at?.name ?? '';
+    const rel = name ? path.relative(cwd, name) || path.basename(name) : '<unknown file>';
+    return `${rel}:${at?.start ?? '?'}-${at?.end ?? '?'}`;
+}
+/** One reportable line per clone: both ends, and how big it is. */
+function describe(cwd, clone) {
+    const size = clone.lines === undefined ? '' : ` (${clone.lines} lines)`;
+    return `${locate(cwd, clone.firstFile)} ↔ ${locate(cwd, clone.secondFile)}${size}`;
+}
+export const duplicateCheck = {
+    name: 'Duplicate Code',
+    phase: 'informational',
+    weight: 'heavy',
+    applies(ctx) {
+        if (ctx.config.duplicate?.enabled === false)
+            return false;
+        return globsFor(ctx.languages).length > 0;
+    },
+    async run(ctx) {
+        const minLines = ctx.config.duplicate?.minLines ?? 5;
+        const minTokens = ctx.config.duplicate?.minTokens ?? 50;
+        const targetPaths = await resolveScopedTargetFiles(ctx, globsFor(ctx.languages), getSourcePaths(ctx.cwd));
+        if (targetPaths === null)
+            return skip('git unavailable');
+        if (targetPaths.length === 0)
+            return skip('no relevant files');
+        const jscpdBin = resolvePackageBin('jscpd', 'run-jscpd.js');
+        // Client-configurable exclusions (pr-checkmate.json `duplicate.ignore`),
+        // defaulting to test files/folders, appended to the always-on base ignores.
+        const configuredIgnore = ctx.config.duplicate?.ignore ?? DUPLICATE_IGNORE_DEFAULTS;
+        const ignore = [...BASE_IGNORE, ...configuredIgnore].join(',');
+        // Client-configurable formats (pr-checkmate.json `duplicate.formats`),
+        // defaulting to source-code formats so data files (yaml/json/markdown) are
+        // not scanned. Clients can add them back explicitly.
+        const formats = (ctx.config.duplicate?.formats ?? DUPLICATE_CODE_FORMATS).join(',');
+        // The JSON reporter writes a file, so it needs somewhere to write it. Outside
+        // the repository deliberately: with no `--output`, jscpd creates `report/`
+        // in the client's working tree, and a check that leaves a directory behind is
+        // a check that shows up in the next commit.
+        const reportDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pr-checkmate-jscpd-'));
+        try {
+            // `--silent` keeps jscpd's own console output away from the client entirely.
+            // That is what retired `stripJscpdPromo` — six string markers matching the
+            // funding lines jscpd v5 prints after its report, each good until the next
+            // release of somebody else's package.
+            const result = await execa(process.execPath, [
+                jscpdBin,
+                '--min-lines',
+                String(minLines),
+                '--min-tokens',
+                String(minTokens),
+                '--reporters',
+                'json',
+                '--output',
+                reportDir,
+                '--absolute',
+                '--silent',
+                '--format',
+                formats,
+                '--ignore',
+                ignore,
+                ...targetPaths,
+            ], { cwd: ctx.cwd, reject: false });
+            const reportPath = path.join(reportDir, 'jscpd-report.json');
+            if (!fs.existsSync(reportPath)) {
+                // No report and nothing to read it from: jscpd did not get as far as
+                // writing one. Its stderr is the only thing that can say why, and a skip
+                // is the honest outcome — an empty report would read as "no duplication".
+                logger.warn(`[Duplicate Code]: ⚠️ jscpd wrote no report (exit ${result.exitCode ?? 'killed'})` +
+                    `${result.stderr ? `\n${result.stderr}` : ''}`);
+                return skip('jscpd produced no report');
+            }
+            const report = JSON.parse(fs.readFileSync(reportPath, 'utf-8'));
+            const clones = report.duplicates ?? [];
+            // jscpd's own count, not a regex over its prose. `output.match(/(\d+)\s+clone/i)`
+            // read the number out of an English sentence, so a reworded summary upstream
+            // would have reported zero duplication on a repository full of it — and
+            // reported it as a pass.
+            const cloneCount = report.statistics?.total?.clones ?? clones.length;
+            if (cloneCount === 0)
+                return pass();
+            logSample('Duplicate Code', `${cloneCount} duplicate block(s):`, clones.map(clone => describe(ctx.cwd, clone)));
+            return warn(`${cloneCount} duplicate block(s)`);
+        }
+        catch (err) {
+            logger.warn(`[Duplicate Code]: ⚠️ Could not run duplicate check\n${err}`);
+            return skip('jscpd unavailable');
+        }
+        finally {
+            fs.rmSync(reportDir, { recursive: true, force: true });
+        }
+    },
+};

package/dist/esm/core/checks/quality/license-header.d.ts

@@ -0,0 +1,7 @@
+import { Check } from '../../types.js';
+/**
+ * Requires a license/copyright header (a configured regex) in the first N lines
+ * of newly ADDED source files. Opt-in — needs `licenseHeader.pattern`; does
+ * nothing until a repo configures one. Advisory (warn).
+ */
+export declare const licenseHeaderCheck: Check;