pr-checkmate 2.1.2 → 3.0.1

package/dist/core/checks/git/leftover-debug.js

@@ -63,12 +63,18 @@ exports.leftoverDebugCheck = {
         try {
             const findings = {};
             const comments = ctx.config.leftoverDebug?.commentHandling ?? 'language';
+            // One failed language set fails the check — see todo-fixme, same reason.
+            let reviewed = true;
             if (ctx.languages.includes('python')) {
-                await (0, findings_1.reviewLines)(ctx, ['*.py'], out => collect(out, PYTHON_PATTERNS, findings, comments));
+                reviewed =
+                    (await (0, findings_1.reviewLines)(ctx, ['*.py'], out => collect(out, PYTHON_PATTERNS, findings, comments))) && reviewed;
             }
             if (ctx.languages.includes('kotlin')) {
-                await (0, findings_1.reviewLines)(ctx, ['*.kt', '*.kts', '*.java'], out => collect(out, KOTLIN_PATTERNS, findings, comments));
+                reviewed =
+                    (await (0, findings_1.reviewLines)(ctx, ['*.kt', '*.kts', '*.java'], out => collect(out, KOTLIN_PATTERNS, findings, comments))) && reviewed;
             }
+            if (!reviewed)
+                return (0, types_1.skip)('git unavailable');
             if ((0, findings_1.bucketTotal)(findings) === 0)
                 return (0, types_1.pass)();
             // Advisory by default; a repo may promote to a gate via

package/dist/core/checks/git/lockfile-drift.js

@@ -8,6 +8,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 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");
 /**
@@ -73,6 +74,10 @@ exports.lockfileDriftCheck = {
             // Raw name-only diff — manifests/locks live at the repo root, outside any
             // configured `sourcePath`, so this deliberately does NOT scope (same as
             // the Sensitive Files guard). Scoping would hide the very files we check.
+            //
+            // `excludePaths` is still applied, below: not scoping is an argument about
+            // WHERE these files live, not a licence to ignore a client who named one
+            // (ticket 080). A vendored sub-project's lockfile is a real case.
             const { stdout } = await (0, execa_1.execa)('git', [
                 'diff',
                 '--name-only',
@@ -80,7 +85,7 @@ exports.lockfileDriftCheck = {
                 ctx.baseSha,
                 ctx.headSha ?? 'HEAD',
             ], { cwd: ctx.cwd });
-            const changed = new Set(stdout.split('\n').filter(Boolean));
+            const changed = new Set((0, targets_1.excludeClientPaths)(stdout.split('\n').filter(Boolean), ctx.cwd));
             const warnings = [];
             for (const changedPath of changed) {
                 const pair = LOCK_PAIRS.find(p => p.manifest === node_path_1.default.basename(changedPath));

package/dist/core/checks/git/merge-conflict.js

@@ -82,7 +82,7 @@ exports.mergeConflictCheck = {
         // client's `ignoreDirs` and `sourcePath`), then diff only those files for
         // content. `['*']` matches every path since conflicts are language-agnostic;
         // scoping still keeps build/vendor/report dirs out, like every other check.
-        const files = await (0, targets_1.resolveScopedTargetFiles)(ctx, ['*'], (0, config_1.getSourcePaths)());
+        const files = await (0, targets_1.resolveScopedTargetFiles)(ctx, ['*'], (0, config_1.getSourcePaths)(ctx.cwd));
         if (files === null)
             return (0, types_1.skip)('git unavailable');
         if (files.length === 0)

package/dist/core/checks/git/missing-tests.js

@@ -45,7 +45,7 @@ exports.missingTestsCheck = {
     async run(ctx) {
         // Scope the same way lint does — a client's `sourcePath` and `ignoreDirs`
         // both apply, so generated/out-of-scope dirs never count as "new source".
-        const scopedList = await (0, targets_1.resolveScopedTargetFiles)(ctx, ['*'], (0, config_1.getSourcePaths)());
+        const scopedList = await (0, targets_1.resolveScopedTargetFiles)(ctx, ['*'], (0, config_1.getSourcePaths)(ctx.cwd));
         if (scopedList === null)
             return (0, types_1.skip)('git unavailable');
         const scoped = new Set(scopedList);

package/dist/core/checks/git/todo-fixme.js

@@ -51,14 +51,22 @@ exports.todoFixmeCheck = {
             const keywords = cfg?.keywords ?? DEFAULT_KEYWORDS;
             const requireTicket = cfg?.requireTicket ?? false;
             const findings = {};
+            // One failed language set fails the check: a partial answer reported as a
+            // pass says the repository is clean when half of it was never read (072).
+            let reviewed = true;
             if (ctx.languages.includes('python')) {
                 const pattern = buildPattern('#', keywords);
-                await (0, findings_1.reviewLines)(ctx, ['*.py'], out => scan(out, pattern, requireTicket, findings));
+                reviewed =
+                    (await (0, findings_1.reviewLines)(ctx, ['*.py'], out => scan(out, pattern, requireTicket, findings))) &&
+                        reviewed;
             }
             if (ctx.languages.includes('kotlin')) {
                 const ktPattern = buildPattern('//|/\\*', keywords);
-                await (0, findings_1.reviewLines)(ctx, ['*.kt', '*.kts', '*.java'], out => scan(out, ktPattern, requireTicket, findings));
+                reviewed =
+                    (await (0, findings_1.reviewLines)(ctx, ['*.kt', '*.kts', '*.java'], out => scan(out, ktPattern, requireTicket, findings))) && reviewed;
             }
+            if (!reviewed)
+                return (0, types_1.skip)('git unavailable');
             if ((0, findings_1.bucketTotal)(findings) === 0)
                 return (0, types_1.pass)();
             return (0, findings_1.reportCountedFindings)(findings, ctx, {

package/dist/core/checks/languages/cpp-format.js

@@ -6,8 +6,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.cppFormatCheck = void 0;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const config_1 = require("../../../config");
 const utils_1 = require("../../../utils");
 const execa_1 = require("../../../utils/execa");
+const targets_1 = require("../../targets");
 const types_1 = require("../../types");
 /**
  * C/C++ source & header extensions clang-format understands. `.h` is intentionally
@@ -27,46 +29,6 @@ function resolveStyleArg(ctx) {
     const style = ctx.config.cpp?.clangFormat?.style ?? DEFAULT_STYLE;
     return `--style=${style}`;
 }
-/**
- * Returns the C/C++ files to check. Uses the PR diff range when available
- * (delta mode), else scans all tracked C/C++ files. Returns an empty array
- * when there is nothing to check, `null` when git is unusable.
- */
-async function resolveTargets(ctx) {
-    try {
-        if (ctx.baseSha) {
-            const { stdout } = await (0, execa_1.execa)('git', [
-                'diff',
-                '--name-only',
-                '--diff-filter=ACMR',
-                ctx.baseSha,
-                ctx.headSha ?? 'HEAD',
-                '--',
-                ...CPP_GLOBS,
-            ], { cwd: ctx.cwd, reject: false });
-            const files = stdout
-                .split('\n')
-                .map(f => f.trim())
-                .filter(Boolean);
-            utils_1.logger.info(`[C++ Format]: 📂 Delta mode: ${files.length} changed C/C++ file(s)`);
-            return files;
-        }
-        const { stdout } = await (0, execa_1.execa)('git', ['ls-files', ...CPP_GLOBS], {
-            cwd: ctx.cwd,
-            reject: false,
-        });
-        const files = stdout
-            .split('\n')
-            .map(f => f.trim())
-            .filter(Boolean);
-        utils_1.logger.info(`[C++ Format]: Full scan: ${files.length} tracked C/C++ file(s)`);
-        return files;
-    }
-    catch (err) {
-        utils_1.logger.warn(`[C++ Format]: ⚠️ Could not list C/C++ files\n${err}`);
-        return null;
-    }
-}
 /** Counts distinct files flagged in clang-format's `--dry-run --Werror` diagnostics. */
 function countOffendingFiles(stderr) {
     const files = new Set();
@@ -89,7 +51,14 @@ exports.cppFormatCheck = {
         return ctx.config.cpp?.enabled !== false && ctx.languages.includes('cpp');
     },
     async run(ctx) {
-        const targets = await resolveTargets(ctx);
+        // Through `targets.ts`, not `git` directly. This check used to run its own
+        // `git ls-files`, which is the one mistake the authoring guide exists to
+        // prevent: it inherits neither `ignoreDirs` nor `sourcePath`. On a real C++
+        // repository that meant 403 files including a vendored copy of OpenCV — and
+        // in `write` mode clang-format was rewriting third-party sources the client
+        // does not own. It also crashed the WASM formatter, which is how this was
+        // found.
+        const targets = await (0, targets_1.resolveScopedTargetFiles)(ctx, CPP_GLOBS, (0, config_1.getSourcePaths)(ctx.cwd));
         if (targets === null)
             return (0, types_1.skip)('git unavailable');
         if (targets.length === 0)
@@ -112,7 +81,15 @@ exports.cppFormatCheck = {
         });
         if (fix.exitCode !== 0) {
             utils_1.logger.warn(`[C++ Format]: ⚠️ clang-format -i failed\n${fix.stderr}`);
-            return (0, types_1.warn)('clang-format failed to rewrite files');
+            // A WASM runtime error is the formatter giving up on a file, not a verdict
+            // about the code — and `-i` means whatever it managed before the crash is
+            // already written, so the tree is half-formatted. Saying which it was
+            // matters: "failed to rewrite files" sent people looking for a style
+            // problem that does not exist.
+            const crashed = /RuntimeError|memory access out of bounds|abort\(/.test(fix.stderr);
+            return (0, types_1.warn)(crashed
+                ? 'clang-format crashed on one of these files — some may already have been rewritten'
+                : `clang-format could not rewrite the files (exit ${fix.exitCode ?? 'killed'})`);
         }
         utils_1.logger.info(`[C++ Format]: ✅ Reformatted ${offending} C/C++ file(s)`);
         return (0, types_1.pass)(`reformatted ${offending} file(s)`);

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

@@ -0,0 +1,77 @@
+/**
+ * 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.
+ */
+/**
+ * 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.
+ */
+export declare const kotlinLintCheck: import("../..").Check;
+/**
+ * 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.
+ */
+export declare const swiftLintCheck: import("../..").Check;
+/**
+ * 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.
+ */
+export declare const rubyLintCheck: import("../..").Check;
+/**
+ * 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.
+ */
+export declare const shellcheckCheck: import("../..").Check;
+/**
+ * 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.
+ */
+export declare const goLintCheck: import("../..").Check;
+/**
+ * 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.
+ */
+export declare const rustLintCheck: import("../..").Check;
+/**
+ * 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.
+ */
+export declare const rustFormatCheck: import("../..").Check;
+/**
+ * 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.
+ */
+export declare const csharpFormatCheck: import("../..").Check;
+/**
+ * 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.
+ */
+export declare const phpFormatCheck: import("../..").Check;

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