pr-checkmate 3.0.4 → 3.2.0

package/dist/esm/core/checks/quality/license-header.js

@@ -0,0 +1,81 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execa } from '../../../utils/execa.js';
+import { logger } from '../../../utils/index.js';
+import { excludeClientPaths } from '../../targets.js';
+import { pass, skip, warn } from '../../types.js';
+/** Source extensions a license header is expected on. */
+const SOURCE_EXT = /\.(ts|tsx|js|jsx|mjs|cjs|py|kt|java|go|rs|cs|rb|php|swift|c|cc|cpp|h|hpp)$/i;
+const DEFAULT_HEADER_LINES = 10;
+/**
+ * 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 const licenseHeaderCheck = {
+    name: 'License Header',
+    phase: 'informational',
+    // No `requiresDiff`: with no range the question becomes "which source files
+    // lack the header", which is what a repo adopting the policy actually needs —
+    // the delta form only ever covers files added since the policy was turned on
+    // (ticket 067).
+    applies(ctx) {
+        return ctx.config.licenseHeader?.enabled === true;
+    },
+    async run(ctx) {
+        const patternSrc = ctx.config.licenseHeader?.pattern;
+        if (!patternSrc)
+            return skip('no licenseHeader.pattern configured');
+        let header;
+        try {
+            header = new RegExp(patternSrc);
+        }
+        catch (err) {
+            logger.warn(`[License Header]: ⚠️ invalid pattern\n${err}`);
+            return skip('invalid licenseHeader.pattern');
+        }
+        const maxLines = ctx.config.licenseHeader?.lines ?? DEFAULT_HEADER_LINES;
+        let added;
+        try {
+            if (!ctx.baseSha && ctx.config.run?.fullScanBehaviour === 'skip')
+                return pass();
+            // Added files in delta mode; every tracked source file in full mode.
+            const args = ctx.baseSha
+                ? ['diff', '--name-only', '--diff-filter=A', ctx.baseSha, ctx.headSha ?? 'HEAD']
+                : ['ls-files'];
+            const { stdout } = await execa('git', args, { cwd: ctx.cwd });
+            // Its own git call rather than `resolveTargets`, and for one reason:
+            // `--diff-filter=A`. This check is about files a PR ADDS, and the shared
+            // resolver asks for ACMR — routing through it would start demanding a
+            // header on every modified file too, which is a different check. So the
+            // client's `excludePaths` is applied here explicitly instead (ticket 080).
+            added = excludeClientPaths(stdout.split('\n').filter(Boolean), ctx.cwd).filter(f => SOURCE_EXT.test(f));
+        }
+        catch (err) {
+            logger.warn(`[License Header]: ⚠️ Could not analyze diff\n${err}`);
+            return skip('diff unavailable');
+        }
+        const missing = [];
+        for (const file of added) {
+            let head;
+            try {
+                head = fs
+                    .readFileSync(path.join(ctx.cwd, file), 'utf-8')
+                    .split('\n')
+                    .slice(0, maxLines)
+                    .join('\n');
+            }
+            catch {
+                continue; // removed/renamed between diff and read
+            }
+            if (!header.test(head))
+                missing.push(file);
+        }
+        if (missing.length === 0)
+            return pass();
+        missing.slice(0, 10).forEach(f => logger.warn(`[License Header]: ⚠️ missing header: ${f}`));
+        if (missing.length > 10)
+            logger.warn(`[License Header]: ⚠️ ... and ${missing.length - 10} more`);
+        return warn(`${missing.length} new source file(s) missing the license header`);
+    },
+};

package/dist/esm/core/checks/quality/markdown-lint.d.ts

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

package/dist/esm/core/checks/quality/markdown-lint.js

@@ -0,0 +1,141 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { GENERATED_DOC_FILES, getPackageConfigPath, hasLocalConfig, } from '../../../config/index.js';
+import { logger, resolvePackageBin } from '../../../utils/index.js';
+import { resolveTargetFiles } from '../../targets.js';
+import { pass, warn, skip } from '../../types.js';
+function loadUserMarkdownConfig(cwd) {
+    const configPath = path.join(cwd, 'pr-checkmate.json');
+    if (!fs.existsSync(configPath))
+        return {};
+    try {
+        return JSON.parse(fs.readFileSync(configPath, 'utf-8')).markdownlint || {};
+    }
+    catch (err) {
+        logger.warn(`[Markdown]: ⚠️ Failed to read markdownlint config: ${err}`);
+        return {};
+    }
+}
+/**
+ * Load the markdownlint library, or `null` when it cannot be found.
+ *
+ * The library rather than `markdownlint-cli2`: the CLI drags in globby →
+ * micromatch → braces, which carries an unpatched advisory every client's
+ * `npm audit` then reports against pr-checkmate. We already have the file list
+ * from git, so the CLI's globbing bought nothing.
+ *
+ * Resolved through `resolvePackageBin` and loaded by a dynamic `import()` for the
+ * same two reasons as the bundled gofmt: the package may live in a fetched
+ * profile directory, and it is ESM while we emit CommonJS.
+ */
+async function loadMarkdownlint() {
+    try {
+        const promiseEntry = resolvePackageBin('markdownlint', 'lib/exports-promise.mjs');
+        const mainEntry = path.join(path.dirname(promiseEntry), 'exports.mjs');
+        const promise = (await import(pathToFileURL(promiseEntry).href));
+        const main = (await import(pathToFileURL(mainEntry).href));
+        return { lint: promise.lint, readConfig: promise.readConfig, applyFixes: main.applyFixes };
+    }
+    catch (err) {
+        logger.warn(`[Markdown]: ⚠️ markdownlint could not be loaded\n${err}`);
+        return null;
+    }
+}
+/**
+ * The rules to lint with: the repository's own config when it has one, ours
+ * (plus the client's `markdownlint.rules`) when it does not. Someone with a
+ * `.markdownlint.json` has an opinion; merging ours into it would silently
+ * override the rules they wrote.
+ */
+async function readLintConfig(lib, cwd, userRules) {
+    const local = ['.markdownlint.json', '.markdownlint.jsonc'].find(name => hasLocalConfig([name], cwd));
+    if (local)
+        return lib.readConfig(path.join(cwd, local));
+    if (hasLocalConfig(['.markdownlint.yaml', '.markdownlint.yml'], cwd)) {
+        logger.warn('[Markdown]: ⚠️ YAML markdownlint configs are not supported, using bundled rules');
+    }
+    const bundled = await lib.readConfig(getPackageConfigPath('.markdownlint.json'));
+    return { ...bundled, ...userRules };
+}
+/**
+ * An ignore pattern as a regular expression over a repo-relative path.
+ *
+ * A bare directory name excludes its contents; a file name matches exactly; `*`
+ * stays within a segment and `**` crosses them. `path.extname` is what tells a
+ * directory from a file, and it reads a leading dot as part of the name, so
+ * `.claude` is still the directory it is.
+ */
+function toIgnoreRegExp(pattern) {
+    const clean = pattern.replace(/\/+$/, '');
+    const escaped = clean
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*\*\//g, '\u0001')
+        .replace(/\*\*/g, '\u0000')
+        .replace(/\*/g, '[^/]*')
+        .replace(/\u0001/g, '(?:.*/)?')
+        .replace(/\u0000/g, '.*');
+    const isDir = !clean.includes('*') && !path.extname(clean);
+    return new RegExp(`^${escaped}${isDir ? '(/.*)?' : ''}$`);
+}
+export const markdownLintCheck = {
+    name: 'Markdown',
+    phase: 'informational',
+    applies() {
+        return true;
+    },
+    async run(ctx) {
+        const targets = await resolveTargetFiles(ctx, ['*.md', '*.mdx']);
+        if (targets === null)
+            return skip('git unavailable');
+        if (targets.length === 0)
+            return skip('no markdown files');
+        const userConfig = loadUserMarkdownConfig(ctx.cwd);
+        const userRules = userConfig.rules ?? {};
+        const lib = await loadMarkdownlint();
+        if (!lib)
+            return warn('markdownlint failed to run (exit 2) — check the markdownlint config');
+        const ignores = [
+            'node_modules/**',
+            'dist/**',
+            'coverage/**',
+            'graphify-out/**',
+            '.claude/**',
+            // Release-tool output, not prose anyone edits — see GENERATED_DOC_FILES.
+            ...GENERATED_DOC_FILES,
+            ...(userConfig.ignores ?? []),
+        ].map(toIgnoreRegExp);
+        const files = targets.filter(file => !ignores.some(re => re.test(file)));
+        if (files.length === 0)
+            return skip('no markdown files');
+        try {
+            const config = await readLintConfig(lib, ctx.cwd, userRules);
+            const results = await lib.lint({ files: files.map(f => path.resolve(ctx.cwd, f)), config });
+            let findings = 0;
+            for (const [file, errors] of Object.entries(results)) {
+                if (errors.length === 0)
+                    continue;
+                const rel = path.relative(ctx.cwd, file);
+                let remaining = errors;
+                if (ctx.write && errors.some(e => e.fixInfo)) {
+                    const fixed = lib.applyFixes(fs.readFileSync(file, 'utf-8'), errors);
+                    fs.writeFileSync(file, fixed);
+                    remaining = errors.filter(e => !e.fixInfo);
+                }
+                for (const e of remaining) {
+                    findings++;
+                    const col = e.errorRange?.[0] ? `:${e.errorRange[0]}` : '';
+                    logger.warn(`${rel}:${e.lineNumber}${col} ${e.ruleNames.join('/')} ${e.ruleDescription}` +
+                        (e.errorDetail ? ` [${e.errorDetail}]` : ''));
+                }
+            }
+            return findings === 0 ? pass() : warn('markdown lint issues found');
+        }
+        catch (err) {
+            // An unreadable config or a file that vanished: the tool could not run,
+            // which is not the same claim as "the prose has problems".
+            logger.warn(`[Markdown]: ⚠️ ${err}`);
+            return warn('markdownlint failed to run (exit 2) — check the markdownlint config');
+        }
+    },
+};

package/dist/esm/core/checks/quality/package-size.d.ts

@@ -0,0 +1,36 @@
+import { Check } from '../../types.js';
+/** Why we could not read a published version. */
+export type QueryFailure = 'absent' | 'unauthenticated' | 'unreadable';
+/**
+ * Tell "never published" apart from "we were not let in".
+ *
+ * Lumped into one sentence they read the same and they are not: one is a fact
+ * about the package, the other is about this run's credentials. A skip whose
+ * reason is a guess between two causes is the defect of ticket 057, one layer up.
+ *
+ * A 401 is also evidence in itself, and it points one way: a name nobody ever
+ * published answers 404 on the public registry, while 401 comes from a host that
+ * has the package and will not show it to a stranger. So the message leads with
+ * the token, which is what that situation actually needs.
+ *
+ * It deliberately does NOT suggest `"private": true` as the way out. That field
+ * means "never publish this", and a package behind a private registry is
+ * published — advising it would break the publish step of the very repository
+ * asking. `packageSize.enabled: false` silences the row and touches nothing
+ * else, so that is the opt-out worth naming.
+ */
+export declare function classifyQueryFailure(stderr: string): QueryFailure;
+/**
+ * Reports how much the published package grew since the last release.
+ *
+ * The question this answers is "is it growing without anyone noticing", not "has
+ * it crossed a line" — so the comparison is against the previously published
+ * version rather than a threshold somebody had to invent. A number a client never
+ * configured is a number they will not trust, and a check that fires on every
+ * release teaches people to skim the whole report.
+ *
+ * Advisory by design. Growth is usually earned — a language profile was added, a
+ * WASM binary landed — and a red build for it would be wrong. `severity:
+ * { "Package Size": "error" }` makes it a gate for a repository that wants one.
+ */
+export declare const packageSizeCheck: Check;

package/dist/esm/core/checks/quality/package-size.js

@@ -0,0 +1,196 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execa } from '../../../utils/execa.js';
+import { logger } from '../../../utils/index.js';
+import { pass, skip, warn } from '../../types.js';
+import { logSample } from '../findings.js';
+/** Growth that is worth a row in the report, unless the client says otherwise. */
+const DEFAULT_MAX_GROWTH = 20;
+/** How many of the files behind the growth are named. */
+const NAMED_FILES = 5;
+/**
+ * Ask npm what a tarball would contain, without producing one.
+ *
+ * `--dry-run` writes nothing to the working tree — which matters, because a check
+ * whose side effect is a `.tgz` beside the source shows up in the client's next
+ * commit. Given a package spec instead of nothing, npm answers for the PUBLISHED
+ * version, with the same shape and the same per-file detail; that is what makes a
+ * real comparison possible rather than a bare number.
+ *
+ * `--ignore-scripts` is not negotiable. `npm pack` runs `prepare` and `prepack`,
+ * and in a client's repository those are arbitrary commands — frequently a full
+ * build. A quality check that executes them has stopped being a check and started
+ * being a build step with side effects nobody asked for. We are a supply-chain
+ * tool; the same rule already governs the install path and the Docker build.
+ *
+ * @param cwd Repository to run in.
+ * @param spec `undefined` for the working tree, or `name@tag` for a release.
+ * @param registry Where to look for a published version; the manifest's own
+ *   `publishConfig.registry` when it names one.
+ */
+async function packManifest(cwd, spec, registry) {
+    const args = [
+        'pack',
+        ...(spec ? [spec] : []),
+        '--dry-run',
+        '--json',
+        '--ignore-scripts',
+        ...(registry ? ['--registry', registry] : []),
+    ];
+    const result = await execa('npm', args, { cwd, reject: false });
+    if (result.exitCode !== 0)
+        return { failure: classifyQueryFailure(result.stderr ?? '') };
+    try {
+        const parsed = JSON.parse(result.stdout);
+        if (Array.isArray(parsed) && parsed.length > 0) {
+            return { manifest: parsed[0] };
+        }
+    }
+    catch {
+        // Fall through: npm answered with something that is not a manifest.
+    }
+    return { failure: 'unreadable' };
+}
+/**
+ * Tell "never published" apart from "we were not let in".
+ *
+ * Lumped into one sentence they read the same and they are not: one is a fact
+ * about the package, the other is about this run's credentials. A skip whose
+ * reason is a guess between two causes is the defect of ticket 057, one layer up.
+ *
+ * A 401 is also evidence in itself, and it points one way: a name nobody ever
+ * published answers 404 on the public registry, while 401 comes from a host that
+ * has the package and will not show it to a stranger. So the message leads with
+ * the token, which is what that situation actually needs.
+ *
+ * It deliberately does NOT suggest `"private": true` as the way out. That field
+ * means "never publish this", and a package behind a private registry is
+ * published — advising it would break the publish step of the very repository
+ * asking. `packageSize.enabled: false` silences the row and touches nothing
+ * else, so that is the opt-out worth naming.
+ */
+export function classifyQueryFailure(stderr) {
+    if (/\bE?40[13]\b|Unauthorized|Forbidden|authentication token/i.test(stderr)) {
+        return 'unauthenticated';
+    }
+    if (/\bE?404\b|Not found/i.test(stderr))
+        return 'absent';
+    return 'unreadable';
+}
+/** `1.15 MB`, at the precision a human compares two of these at. */
+function mb(bytes) {
+    return `${(bytes / 1024 / 1024).toFixed(2)} MB`;
+}
+/**
+ * Which files account for the growth, biggest first.
+ *
+ * A percentage alone is a finding nobody can act on — the same defect as a
+ * duplicate-code report with no file names (ticket 078). The published manifest
+ * carries per-file sizes, so the answer is a plain diff of the two lists: files
+ * that appeared, and files that grew.
+ */
+function growthByFile(before, after) {
+    const old = new Map(before.map(f => [f.path, f.size]));
+    return after
+        .map(f => ({ path: f.path, delta: f.size - (old.get(f.path) ?? 0), isNew: !old.has(f.path) }))
+        .filter(f => f.delta > 0)
+        .sort((a, b) => b.delta - a.delta)
+        .slice(0, NAMED_FILES)
+        .map(f => `${f.path} +${mb(f.delta)}${f.isNew ? ' (new)' : ''}`);
+}
+/** What this repository publishes, and where — or `null` if it publishes nothing. */
+function published(cwd) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'));
+        if (pkg.private || !pkg.name)
+            return null;
+        // `publishConfig.registry` is the manifest's own statement of where this
+        // package lives, and npm uses it for `publish` but not for a fetch. Asking
+        // the default registry instead reports "no published version" for every
+        // package on GitHub Packages or a company mirror — which is not a fact about
+        // the package, it is us having asked the wrong host. Measured on a real
+        // client: the default registry answered 404 for a package published at
+        // version 1.2.15.
+        const registry = pkg.publishConfig?.registry;
+        return registry ? { name: pkg.name, registry } : { name: pkg.name };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reports how much the published package grew since the last release.
+ *
+ * The question this answers is "is it growing without anyone noticing", not "has
+ * it crossed a line" — so the comparison is against the previously published
+ * version rather than a threshold somebody had to invent. A number a client never
+ * configured is a number they will not trust, and a check that fires on every
+ * release teaches people to skim the whole report.
+ *
+ * Advisory by design. Growth is usually earned — a language profile was added, a
+ * WASM binary landed — and a red build for it would be wrong. `severity:
+ * { "Package Size": "error" }` makes it a gate for a repository that wants one.
+ */
+export const packageSizeCheck = {
+    name: 'Package Size',
+    phase: 'informational',
+    weight: 'heavy',
+    applies(ctx) {
+        if (ctx.config.packageSize?.enabled === false)
+            return false;
+        // A private package is never published, so there is nothing to compare with
+        // and no consumer to pay for the growth.
+        return published(ctx.cwd) !== null;
+    },
+    async run(ctx) {
+        const target = published(ctx.cwd);
+        if (!target)
+            return skip('no publishable package.json');
+        const tag = ctx.config.packageSize?.compareWith ?? 'latest';
+        const maxGrowth = ctx.config.packageSize?.maxGrowthPercent ?? DEFAULT_MAX_GROWTH;
+        const spec = `${target.name}@${tag}`;
+        const local = await packManifest(ctx.cwd);
+        if (!('manifest' in local))
+            return skip('npm could not describe this package');
+        const current = local.manifest;
+        // Never a pass: a green row over a comparison that did not happen is the
+        // mistake of ticket 072. And never one reason standing in for three — the
+        // three are different situations for the reader, and only one of them is a
+        // fact about the package rather than about the run.
+        const remote = await packManifest(ctx.cwd, spec, target.registry);
+        if (!('manifest' in remote)) {
+            // The fact, and nothing past it. The remedy for a private registry is three
+            // lines in a workflow — `setup-node` with `registry-url`, a scope, and
+            // `NODE_AUTH_TOKEN`, because npm reads the token through a reference in
+            // `.npmrc` — and instructions that do not fit cannot be followed. They
+            // belong on the check's page, which the report already links to.
+            //
+            // The package name is left out on purpose: the reader owns it. The host is
+            // not, because it is the one part they cannot infer — and the difference
+            // between "we asked the wrong registry" and "we were refused" is exactly
+            // what this row got wrong before.
+            // Named only when we know it. Without `publishConfig.registry` npm used
+            // whatever the client's own config points at, and we do not know what that
+            // was — "at the registry" would be filler dressed up as information.
+            const host = target.registry ? new URL(target.registry).host : null;
+            const at = host ? ` at ${host}` : '';
+            const reason = {
+                absent: `nothing published under this name${at} yet`,
+                unauthenticated: `no credentials for ${host ?? 'the registry'}`,
+                unreadable: `could not read the published version${at}`,
+            }[remote.failure];
+            return skip(reason);
+        }
+        const previous = remote.manifest;
+        const delta = current.unpackedSize - previous.unpackedSize;
+        const growth = previous.unpackedSize > 0 ? (delta / previous.unpackedSize) * 100 : 0;
+        const summary = `${mb(previous.unpackedSize)} → ${mb(current.unpackedSize)} ` +
+            `(${growth >= 0 ? '+' : ''}${growth.toFixed(1)}%) vs ${previous.version}`;
+        if (growth <= maxGrowth) {
+            logger.info(`[Package Size]: ✅ ${summary}`);
+            return pass(summary);
+        }
+        logSample('Package Size', `${summary}:`, growthByFile(previous.files, current.files));
+        return warn(summary);
+    },
+};

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

@@ -0,0 +1,77 @@
+import { CspellConfig } from '../../../interfaces/index.js';
+import { Check } from '../../types.js';
+/**
+ * Anchors an ignore glob to the repository root.
+ *
+ * cspell matches `ignorePaths` against each file's ABSOLUTE path, so an unanchored
+ * `**\/build/**` also matches every ancestor directory of the workspace. On Bitbucket
+ * Pipelines the clone lives in `/opt/atlassian/pipelines/agent/build`, so that one
+ * pattern excluded the entire repository and the check silently spellchecked nothing.
+ * A leading `/` anchors the pattern to the config's directory (the repo root) while
+ * `/**\/dir/**` still matches at any depth INSIDE the repo — verified against cspell 10.
+ *
+ * Patterns that are already anchored (`/…`) or plainly relative (`dir/**`,
+ * `CHANGELOG.md`) are left untouched: they cannot match an ancestor.
+ */
+export declare function anchorIgnoreGlob(pattern: string): string;
+/**
+ * Folds the client's `cspell` block from pr-checkmate.json into the bundled
+ * defaults. `enabled` is deliberately not carried over — it gates the check
+ * itself (see `applies`) and is not a cspell setting.
+ *
+ * Lists are appended so a client extends the curated vocabulary instead of
+ * replacing it; `language` is the one exception and replaces the default, because
+ * a client writing `"en"` means exactly that and appending would be meaningless.
+ */
+export declare function mergeCspellConfig(defaultConfig: CspellConfig, userConfig: Partial<CspellConfig>): CspellConfig;
+/**
+ * The optional dictionaries this installation actually has — and what to do
+ * about the ones it does not.
+ *
+ * Dropping a dictionary must not turn into a flood of warnings: a repository
+ * with Russian comments would report every Russian word as a misspelling, which
+ * is worse than the ~9 MB the dictionaries cost. So for the languages written in
+ * a script of their own, absence suppresses that script instead: cspell cannot
+ * judge those words, and reporting words it cannot judge is noise, not coverage.
+ *
+ * Latin-script languages (French, Spanish) have no such escape — their words are
+ * indistinguishable from misspelled English — so their absence is only logged,
+ * with the command that restores them.
+ *
+ * @returns imports and language codes to enable, ignore patterns for scripts left
+ *   without a dictionary, and the packages a client may want to install.
+ */
+export declare function availableDictionaries(resolve?: (id: string) => string): {
+    imports: string[];
+    languages: string[];
+    ignoreRegExpList: string[];
+    absent: string[];
+};
+/**
+ * Turn config imports into absolute paths, dropping the ones that are not installed.
+ *
+ * An unresolvable `import` is not a soft failure in cspell: it aborts config
+ * loading, checks **zero files**, and exits 1 — which this check would then have
+ * reported as "spelling issues found", a warning about problems that do not exist
+ * on a run that examined nothing. Passing the raw string through and hoping cspell
+ * copes is therefore the one thing that must not happen.
+ *
+ * @returns the imports that resolved, plus the language codes left without a
+ *   dictionary so the caller can drop them from `language`.
+ */
+export declare function resolveImports(imports: string[], baseDir: string, resolve?: (id: string) => string): {
+    resolved: string[];
+    missing: Array<{
+        pkg: string;
+        lang?: string;
+    }>;
+};
+/**
+ * Drop language codes whose dictionary is absent.
+ *
+ * Leaving `ru` in `language` with no Russian dictionary does not spellcheck
+ * Russian — it reports every Russian word as a misspelling. Having no opinion is
+ * the honest outcome when the dictionary that would form one is not installed.
+ */
+export declare function dropMissingLanguages(language: string, missing: string[]): string;
+export declare const spellcheckCheck: Check;