pr-checkmate 3.0.4 → 3.1.0

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,104 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { GENERATED_DOC_FILES, getPackageConfigPath, hasLocalConfig, } from '../../../config/index.js';
+import { execa } from '../../../utils/execa.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 {};
+    }
+}
+function buildMergedConfig(bundledConfigPath, userRules) {
+    const bundled = JSON.parse(fs.readFileSync(bundledConfigPath, 'utf-8'));
+    const merged = { ...bundled, ...userRules };
+    const tmpFile = path.join(os.tmpdir(), `.markdownlint-merged-${process.pid}.json`);
+    fs.writeFileSync(tmpFile, JSON.stringify(merged, null, 2));
+    return tmpFile;
+}
+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 ?? {};
+        let tempConfigFile = null;
+        let configArg;
+        if (hasLocalConfig(['.markdownlint.json', '.markdownlint.jsonc', '.markdownlint.yaml', '.markdownlint.yml'], ctx.cwd)) {
+            configArg = [];
+        }
+        else {
+            const bundledConfig = getPackageConfigPath('.markdownlint.json');
+            if (Object.keys(userRules).length > 0) {
+                tempConfigFile = buildMergedConfig(bundledConfig, userRules);
+                configArg = ['--config', tempConfigFile];
+            }
+            else {
+                configArg = ['--config', bundledConfig];
+            }
+        }
+        const markdownlintBin = resolvePackageBin('markdownlint-cli2', 'markdownlint-cli2-bin.mjs');
+        const defaultIgnorePatterns = [
+            'node_modules/**',
+            'dist/**',
+            'coverage/**',
+            'graphify-out/**',
+            '.claude/**',
+            // Release-tool output, not prose anyone edits — see GENERATED_DOC_FILES.
+            ...GENERATED_DOC_FILES,
+            ...(userConfig.ignores ?? []),
+        ];
+        // markdownlint-cli2 has no --ignore-path flag; exclusions are expressed as
+        // negated globs (`#pattern`). A bare directory name also needs `#name/**`
+        // to exclude its contents — but a filename does not, and `#CHANGELOG.md/**`
+        // is a glob that can never match. `path.extname` is what tells them apart,
+        // and it reads a leading dot as part of the name, so `.claude` is still
+        // treated as the directory it is.
+        const ignoreGlobs = defaultIgnorePatterns.flatMap(pattern => {
+            const clean = pattern.replace(/\/+$/, '');
+            const globs = [`#${clean}`];
+            if (!clean.includes('*') && !path.extname(clean))
+                globs.push(`#${clean}/**`);
+            return globs;
+        });
+        const args = [...(ctx.write ? ['--fix'] : []), ...targets, ...ignoreGlobs, ...configArg];
+        try {
+            const result = await execa(process.execPath, [markdownlintBin, ...args], {
+                cwd: ctx.cwd,
+                reject: false,
+                stdio: 'inherit',
+            });
+            if (result.exitCode === 0)
+                return pass();
+            // markdownlint-cli2 exits 1 for lint findings and 2 when it could not run
+            // (an unreadable config, a bad glob). Reporting the latter as "markdown lint
+            // issues found" names the wrong cause — and under `severity: error` it
+            // becomes a gate on a tooling problem.
+            if (result.exitCode === 2) {
+                return warn('markdownlint failed to run (exit 2) — check the markdownlint config');
+            }
+            return warn('markdown lint issues found');
+        }
+        finally {
+            if (tempConfigFile && fs.existsSync(tempConfigFile))
+                fs.unlinkSync(tempConfigFile);
+        }
+    },
+};

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;