pr-checkmate 2.1.0 → 3.0.0

package/dist/core/checks/languages/external-checks.js

@@ -0,0 +1,200 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.phpFormatCheck = exports.csharpFormatCheck = exports.rustFormatCheck = exports.rustLintCheck = exports.goLintCheck = exports.shellcheckCheck = exports.rubyLintCheck = exports.swiftLintCheck = exports.kotlinLintCheck = void 0;
+const external_runner_1 = require("./external-runner");
+/**
+ * Every check that runs a linter or formatter we do not ship, as a table.
+ *
+ * The engine is in `external-runner.ts`; this file is only the data. What is
+ * genuinely per-language turns out to be four things — the binary, its
+ * arguments, the files it looks at, and how to read its output — and everything
+ * else was the same in all eleven of the modules this replaces.
+ *
+ * Keeping the entries together rather than one per file is the point: it is now
+ * possible to read what nine checks do at once, and a divergence between two of
+ * them is visible instead of two directories apart. Adding a tenth is an entry,
+ * not a file.
+ *
+ * The user-facing documentation stays per check, in
+ * `documentation/checks/languages/`, because that is organised around the reader's
+ * question ("how do I configure ktlint") rather than around ours.
+ */
+// ── lint ────────────────────────────────────────────────────────────────────
+/**
+ * Lints changed Kotlin files with ktlint (style and formatting both, so it
+ * doubles as the Kotlin format signal). Uses the repo's own `.editorconfig`
+ * when present.
+ */
+exports.kotlinLintCheck = (0, external_runner_1.defineExternalLint)({
+    name: 'ktlint',
+    bin: 'ktlint',
+    tool: 'ktlint',
+    globs: ['*.kt', '*.kts'],
+    language: 'kotlin',
+    configKey: 'kotlin',
+    subject: 'Kotlin files',
+    args: (_ctx, targets) => ['--reporter=plain', ...targets],
+});
+/**
+ * Lints Swift with SwiftLint, which needs SourceKit and therefore a macOS
+ * runner. Runs over the directory rather than a file list — SwiftLint resolves
+ * its own `.swiftlint.yml` scope, and a file list would bypass the excludes a
+ * repo wrote there — so the resolved targets only decide whether it runs at all.
+ */
+exports.swiftLintCheck = (0, external_runner_1.defineExternalLint)({
+    name: 'SwiftLint',
+    bin: 'swiftlint',
+    tool: 'swiftlint',
+    globs: ['*.swift'],
+    language: 'swift',
+    configKey: 'swift',
+    subject: 'Swift files',
+    args: ctx => ['lint', '--quiet', '--path', ctx.cwd],
+    // SwiftLint's plain output carries progress and summary lines too; only the
+    // diagnostics are findings, and the two levels are worth reporting apart.
+    keep: line => line.includes(': warning:') || line.includes(': error:'),
+    summary: lines => {
+        const errors = lines.filter(line => line.includes(': error:')).length;
+        return `${errors} error(s), ${lines.length - errors} warning(s)`;
+    },
+});
+/**
+ * Lints changed Ruby files with RuboCop, which covers layout as well as style,
+ * so it doubles as the Ruby format signal. Uses the repo's own `.rubocop.yml`
+ * when present.
+ */
+exports.rubyLintCheck = (0, external_runner_1.defineExternalLint)({
+    name: 'RuboCop',
+    bin: 'rubocop',
+    tool: 'rubocop',
+    globs: ['*.rb', '*.rake'],
+    language: 'ruby',
+    configKey: 'ruby',
+    subject: 'Ruby files',
+    args: (_ctx, targets) => ['--format', 'simple', ...targets],
+    // RuboCop ends with its own count — "12 offenses detected" — which says more
+    // than a line tally of an output format that mixes offences and file headers.
+    summary: lines => lines.find(line => /offense/i.test(line))?.trim() ?? `${lines.length} line(s) of output`,
+});
+/**
+ * Lints changed shell scripts with ShellCheck. `-f gcc` gives one line per
+ * finding ending in an `[SC…]` code, which both a human and the count below can
+ * read directly.
+ *
+ * No language gate: shell is not something detection reports, and a `deploy.sh`
+ * in a Python repository is exactly the file this check exists for.
+ */
+exports.shellcheckCheck = (0, external_runner_1.defineExternalLint)({
+    name: 'ShellCheck',
+    bin: 'shellcheck',
+    tool: 'shellcheck',
+    globs: ['*.sh', '*.bash', '*.ksh'],
+    configKey: 'shellcheck',
+    subject: 'shell scripts',
+    args: (ctx, targets) => {
+        const args = ['-f', 'gcc'];
+        const { minSeverity, ignore = [] } = ctx.config.shellcheck ?? {};
+        if (minSeverity)
+            args.push('-S', minSeverity);
+        if (ignore.length > 0)
+            args.push('-e', ignore.join(','));
+        return [...args, ...targets];
+    },
+    summary: (lines, targets) => `${lines.length} issue(s) in ${targets.length} file(s)`,
+});
+/**
+ * Vets changed Go code with `go vet ./...`, which needs the Go toolchain (the
+ * formatter next door no longer does — see `go-format.ts`). `go vet` operates
+ * per package, so it runs over the module rather than a file list; the delta
+ * only decides whether it runs.
+ */
+exports.goLintCheck = (0, external_runner_1.defineExternalLint)({
+    name: 'Go Vet',
+    bin: 'go',
+    tool: 'go',
+    toolLabel: 'go',
+    globs: ['*.go'],
+    language: 'go',
+    configKey: 'go',
+    subject: 'Go files',
+    args: () => ['vet', './...'],
+    // Diagnostics and build errors both land on stderr.
+    stderrFirst: true,
+    summary: lines => `${lines.length} diagnostic line(s)`,
+});
+/**
+ * Lints changed Rust with Clippy. It compiles the crate, so it runs over the
+ * crate rather than a file list; the delta only decides whether it runs.
+ */
+exports.rustLintCheck = (0, external_runner_1.defineExternalLint)({
+    name: 'Clippy',
+    bin: 'cargo',
+    tool: 'clippy',
+    toolLabel: 'cargo/clippy',
+    globs: ['*.rs'],
+    language: 'rust',
+    configKey: 'rust',
+    subject: 'Rust files',
+    args: () => ['clippy', '--quiet', '--', '-D', 'warnings'],
+    stderrFirst: true,
+    // Clippy interleaves diagnostics with compilation progress; only the lines
+    // that carry a level are findings.
+    keep: line => /\b(warning|error)\b/.test(line),
+    summary: lines => `${lines.length} clippy diagnostic(s)`,
+});
+// ── format ──────────────────────────────────────────────────────────────────
+/**
+ * Formats changed Rust with `cargo fmt`, not a bare `rustfmt`: cargo reads the
+ * crate's edition from `Cargo.toml`, and rustfmt invoked directly does not —
+ * which silently formats 2015-edition code by 2024 rules.
+ */
+exports.rustFormatCheck = (0, external_runner_1.defineExternalFormat)({
+    name: 'Rustfmt',
+    bin: 'cargo',
+    tool: 'rustfmt',
+    toolLabel: 'cargo',
+    globs: ['*.rs'],
+    language: 'rust',
+    configKey: 'rust',
+    subject: 'Rust files',
+    code: 'Rust code',
+    checkArgs: () => ['fmt', '--check'],
+    writeArgs: () => ['fmt'],
+});
+/**
+ * Verifies C# formatting with `dotnet format`, which also runs the project's
+ * configured analyzers and style rules. It operates on the project or solution
+ * (and expects a prior `dotnet restore`), so it runs over the whole project; the
+ * delta only decides whether it runs.
+ */
+exports.csharpFormatCheck = (0, external_runner_1.defineExternalFormat)({
+    name: 'C# Format',
+    bin: 'dotnet',
+    tool: 'dotnet',
+    toolLabel: 'dotnet SDK',
+    globs: ['*.cs'],
+    language: 'csharp',
+    configKey: 'csharp',
+    subject: 'C# files',
+    code: 'C# code',
+    checkArgs: () => ['format', '--verify-no-changes'],
+    writeArgs: () => ['format'],
+});
+/**
+ * Formats changed PHP with PHP-CS-Fixer, using the repo's own
+ * `.php-cs-fixer.php` when present. `--using-cache=no` because the cache keys on
+ * absolute paths, and a CI checkout directory that changes between runs makes a
+ * stale cache report files as clean that were never examined.
+ */
+exports.phpFormatCheck = (0, external_runner_1.defineExternalFormat)({
+    name: 'PHP CS Fixer',
+    bin: 'php-cs-fixer',
+    tool: 'php-cs-fixer',
+    globs: ['*.php'],
+    language: 'php',
+    configKey: 'php',
+    subject: 'PHP files',
+    code: 'PHP code',
+    checkArgs: targets => ['fix', '--using-cache=no', ...targets, '--dry-run'],
+    writeArgs: targets => ['fix', '--using-cache=no', ...targets],
+});

package/dist/core/checks/languages/external-runner.d.ts

@@ -0,0 +1,119 @@
+import { Check, CheckContext, type Language } from '../../types';
+import { type ExternalTool } from '../tool-install';
+/**
+ * The one shape every check that shells out to somebody else's linter has.
+ *
+ * Eleven of these were written by copying a neighbour, and copying is what they
+ * had in common: `resolveTargetFiles` → `execa` → the same seven-line comment
+ * about `ENOENT` → split the output → log ten lines and a "… and N more". Of the
+ * ~600 lines that produced, about sixty said anything specific to a language.
+ *
+ * The cost of that was not the duplication. It was that each copy diverged
+ * slightly, so a fix landed in one of eleven places: the `git unavailable` skip
+ * was missing from some, the ten-line truncation counted differently in others,
+ * and `⏭️ ktlint: ktlint not installed` outlived four rewrites of the message it
+ * was supposed to match. Behaviour that is meant to be identical everywhere
+ * belongs in one function; what is genuinely per-language belongs in a table.
+ *
+ * Two factories rather than one, because a linter and a formatter differ in the
+ * only part that matters — a linter reads output, a formatter runs twice and may
+ * write. Folding them together would mean a spec with half its fields unused.
+ */
+/**
+ * Config blocks that gate a language check with `enabled: false`.
+ *
+ * Named as a union rather than typed as `keyof PRCheckMateConfig` so a spec
+ * cannot point at `reporter` or `install` and typecheck.
+ */
+type LanguageConfigKey = 'csharp' | 'go' | 'kotlin' | 'php' | 'ruby' | 'rust' | 'shellcheck' | 'swift';
+/**
+ * A finished tool run, with "the tool is not here" as a case of its own rather
+ * than an exception.
+ */
+type ToolRun = {
+    missing: true;
+} | {
+    missing: false;
+    exitCode: number | undefined;
+    stdout: string;
+    stderr: string;
+};
+/**
+ * Run an external tool, telling an absent binary apart from a failing one.
+ *
+ * execa v9 with `reject: false` does NOT throw on a missing binary — it resolves
+ * with `code: 'ENOENT'`. Detecting that on the result rather than in a
+ * `try`/`catch` (which never fires here) is the difference between an honest skip
+ * and a missing linter reporting a clean pass. This comment used to be repeated
+ * verbatim in eleven files, which is roughly how long it takes for one of the
+ * copies to lose it.
+ */
+export declare function runTool(ctx: CheckContext, bin: string, args: string[]): Promise<ToolRun>;
+/** The fields both factories read; each adds the part that differs. */
+interface ExternalSpecBase {
+    /** Display name — the report row, and the log prefix. */
+    name: string;
+    /** The binary to run. */
+    bin: string;
+    /** Key into the install-hint table, so the skip says how to fix itself. */
+    tool: ExternalTool;
+    /**
+     * How to name the tool in the skip. Omit when the check's own name already is
+     * the binary's name, or the message stutters (`ktlint: ktlint not installed`).
+     */
+    toolLabel?: string;
+    /** Pathspecs the check operates on, e.g. `['*.kt', '*.kts']`. */
+    globs: string[];
+    /**
+     * Language gate. Omit for a check that applies to any repository — ShellCheck
+     * runs wherever there is a `.sh`, and shell is not a detected language.
+     */
+    language?: Language;
+    /** Config block whose `enabled: false` switches the check off. */
+    configKey: LanguageConfigKey;
+    /** Plural noun for the nothing-to-do pass: `no Kotlin files changed`. */
+    subject: string;
+}
+/** A check that runs somebody else's linter and reports what it said. */
+export interface ExternalLintSpec extends ExternalSpecBase {
+    /**
+     * Arguments for the run. Given `ctx` as well as the files because not every
+     * linter takes a file list — `go vet` works per package and SwiftLint per
+     * directory, and for those the resolved targets only decide whether to run.
+     */
+    args(ctx: CheckContext, targets: string[]): string[];
+    /** Which output lines are findings. Default: every non-blank line. */
+    keep?(line: string): boolean;
+    /** How to phrase the count. Default: `N issue(s)`. */
+    summary?(lines: string[], targets: string[]): string;
+    /** Read stderr ahead of stdout, for tools that diagnose there. */
+    stderrFirst?: boolean;
+}
+/** A check that runs somebody else's formatter, read-only unless `write`. */
+export interface ExternalFormatSpec extends ExternalSpecBase {
+    /** Singular noun for the verdicts: `PHP code needs formatting`. */
+    code: string;
+    /** Arguments for the read-only pass. */
+    checkArgs(targets: string[]): string[];
+    /** Arguments for the pass that rewrites files. */
+    writeArgs(targets: string[]): string[];
+}
+/**
+ * Build an informational lint check from its spec.
+ *
+ * Informational for all of them, and not a field: these checks depend on a tool
+ * we do not ship, so on a runner without it they cannot distinguish clean code
+ * from unexamined code. A gate that silently stops gating is worse than no gate,
+ * and a client who wants one promotes the check with `severity`.
+ */
+export declare function defineExternalLint(spec: ExternalLintSpec): Check;
+/**
+ * Build a format check from its spec: detect, then rewrite only when asked.
+ *
+ * The two passes are deliberate. A check run must never change the tree unless
+ * the caller said `write`, and in `write` mode CI needs the files actually
+ * rewritten so it can commit them — so the read-only pass is the one that decides
+ * the verdict, and the second only carries it out.
+ */
+export declare function defineExternalFormat(spec: ExternalFormatSpec): Check;
+export {};

package/dist/core/checks/languages/external-runner.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTool = runTool;
+exports.defineExternalLint = defineExternalLint;
+exports.defineExternalFormat = defineExternalFormat;
+const utils_1 = require("../../../utils");
+const execa_1 = require("../../../utils/execa");
+const targets_1 = require("../../targets");
+const types_1 = require("../../types");
+const findings_1 = require("../findings");
+const tool_install_1 = require("../tool-install");
+/**
+ * Run an external tool, telling an absent binary apart from a failing one.
+ *
+ * execa v9 with `reject: false` does NOT throw on a missing binary — it resolves
+ * with `code: 'ENOENT'`. Detecting that on the result rather than in a
+ * `try`/`catch` (which never fires here) is the difference between an honest skip
+ * and a missing linter reporting a clean pass. This comment used to be repeated
+ * verbatim in eleven files, which is roughly how long it takes for one of the
+ * copies to lose it.
+ */
+async function runTool(ctx, bin, args) {
+    const result = await (0, execa_1.execa)(bin, args, { cwd: ctx.cwd, reject: false });
+    if (result.code === 'ENOENT')
+        return { missing: true };
+    return {
+        missing: false,
+        exitCode: result.exitCode,
+        stdout: result.stdout,
+        stderr: result.stderr,
+    };
+}
+/** Both streams as one blob — some tools diagnose on stdout, some on stderr. */
+function combinedOutput(run, stderrFirst) {
+    const streams = stderrFirst ? [run.stderr, run.stdout] : [run.stdout, run.stderr];
+    return streams.filter(Boolean).join('\n').trim();
+}
+/** Every non-blank line is a finding, unless a spec says otherwise. */
+function isNotBlank(line) {
+    return line.trim().length > 0;
+}
+/** `N issue(s)`, unless a spec phrases its count differently. */
+function countIssues(lines) {
+    return `${lines.length} issue(s)`;
+}
+/** Whether a language check is switched on for this repository. */
+function isEnabled(ctx, key, language) {
+    if (ctx.config[key]?.enabled === false)
+        return false;
+    return language === undefined || ctx.languages.includes(language);
+}
+/**
+ * Assemble the `Check` both factories return, given the part that differs.
+ *
+ * Everything here is identical between a linter and a formatter — the name, the
+ * `applies` gate, and resolving the files — and only `phase` and `work` are not.
+ * Kept as a third function rather than merged into one factory with a flag,
+ * because the two specs are genuinely different shapes: a linter reads output, a
+ * formatter runs twice and may write. One factory would mean a spec with half its
+ * fields unused, which is the trade this file's header argues against.
+ */
+function defineExternal(spec, phase, work) {
+    return {
+        name: spec.name,
+        phase,
+        applies(ctx) {
+            return isEnabled(ctx, spec.configKey, spec.language);
+        },
+        async run(ctx) {
+            const targets = await (0, targets_1.resolveTargets)(ctx, spec.globs, {
+                onEmpty: { pass: `no ${spec.subject} changed` },
+            });
+            if (!Array.isArray(targets))
+                return targets;
+            return work(ctx, targets);
+        },
+    };
+}
+/**
+ * Build an informational lint check from its spec.
+ *
+ * Informational for all of them, and not a field: these checks depend on a tool
+ * we do not ship, so on a runner without it they cannot distinguish clean code
+ * from unexamined code. A gate that silently stops gating is worse than no gate,
+ * and a client who wants one promotes the check with `severity`.
+ */
+function defineExternalLint(spec) {
+    return defineExternal(spec, 'informational', async (ctx, targets) => {
+        const run = await runTool(ctx, spec.bin, spec.args(ctx, targets));
+        if (run.missing)
+            return (0, tool_install_1.notInstalled)(spec.tool, spec.toolLabel);
+        const output = combinedOutput(run, spec.stderrFirst);
+        // Exit 0 is the tool's verdict. Empty output on a non-zero exit is a tool
+        // that objected without saying to what, and there is nothing to put in a
+        // report either way — so both are a pass rather than a warn reading
+        // "0 issue(s)".
+        if (run.exitCode === 0 || !output) {
+            utils_1.logger.info(`[${spec.name}]: ✅ No issues found`);
+            return (0, types_1.pass)();
+        }
+        const lines = output.split('\n').filter(spec.keep ?? isNotBlank);
+        // The tool objected and none of its output matched what this check knows how
+        // to read — a build error ahead of the lint pass, usually. Naming the exit
+        // code is thin, but a clean pass over an objection is a lie.
+        const summary = lines.length > 0
+            ? (spec.summary ?? countIssues)(lines, targets)
+            : `${spec.bin} exited ${run.exitCode ?? 'without a code'} with no readable diagnostics`;
+        (0, findings_1.logSample)(spec.name, `${summary}:`, lines);
+        return (0, types_1.warn)(summary);
+    });
+}
+/**
+ * Build a format check from its spec: detect, then rewrite only when asked.
+ *
+ * The two passes are deliberate. A check run must never change the tree unless
+ * the caller said `write`, and in `write` mode CI needs the files actually
+ * rewritten so it can commit them — so the read-only pass is the one that decides
+ * the verdict, and the second only carries it out.
+ */
+function defineExternalFormat(spec) {
+    return defineExternal(spec, 'format', async (ctx, targets) => {
+        const dry = await runTool(ctx, spec.bin, spec.checkArgs(targets));
+        if (dry.missing)
+            return (0, tool_install_1.notInstalled)(spec.tool, spec.toolLabel);
+        if (dry.exitCode === 0)
+            return (0, types_1.pass)();
+        if (!ctx.write) {
+            utils_1.logger.warn(`[${spec.name}]: ⚠️ ${spec.code} needs formatting`);
+            return (0, types_1.warn)(`${spec.code} needs formatting (run with write to fix)`);
+        }
+        const fix = await runTool(ctx, spec.bin, spec.writeArgs(targets));
+        // `missing` cannot happen here — the same binary answered a moment ago — but
+        // it is a case of the type, and collapsing it into the failure branch is both
+        // correct and shorter than asserting it away.
+        if (fix.missing || fix.exitCode !== 0) {
+            const detail = fix.missing ? '' : `\n${fix.stderr}`;
+            utils_1.logger.warn(`[${spec.name}]: ⚠️ ${spec.bin} failed to rewrite files${detail}`);
+            return (0, types_1.warn)(`${spec.bin} failed to rewrite files`);
+        }
+        utils_1.logger.info(`[${spec.name}]: ✅ Reformatted ${spec.code}`);
+        return (0, types_1.pass)(`reformatted ${spec.code}`);
+    });
+}

package/dist/core/checks/languages/go-format.d.ts

@@ -1,8 +1,8 @@
 import { Check } from '../../types';
 /**
- * Formats changed Go files with `gofmt`. Runner-dependency (needs `gofmt` on the
- * runner), gracefully skipping when absent. Read-only in check mode (`gofmt -l`
- * lists files that differ from gofmt output); rewrites in place with `gofmt -w`
- * when `write`, so CI can auto-commit — mirrors the Prettier/C++/Ruff format checks.
+ * Formats changed Go files with gofmt — the runner's own when it has one, and a
+ * bundled WASM build otherwise, so the check has no runner dependency at all.
+ * Read-only in check mode; rewrites in place when `write`, so CI can auto-commit
+ * — mirrors the Prettier/C++/Ruff format checks.
  */
 export declare const goFormatCheck: Check;