pr-checkmate 1.23.23 → 2.0.0

package/dist/interfaces/index.d.ts

@@ -22,10 +22,81 @@ export interface CspellConfig {
     dictionaries?: string[];
     enabled?: boolean;
 }
+/**
+ * Client `reporter` block: where the summary goes and what happens if it cannot
+ * get there.
+ *
+ * Lives here rather than beside the other run types in `core/types.ts` because
+ * it is part of the config file's shape, and `core/types.ts` already imports
+ * this module — declaring it in both is what let the two copies drift.
+ */
+/**
+ * Client `install` block: which tooling is fetched, when, and what a failure to
+ * fetch it means.
+ *
+ * The defaults are chosen so that an existing installation behaves exactly as it
+ * did before this block existed. `strategy: "eager"` is the documented way back
+ * to the old behaviour without waiting for a release from us.
+ */
+export interface InstallConfig {
+    strategy?: 'adaptive' | 'eager' | 'manual';
+    profiles?: string[];
+    excludeProfiles?: string[];
+    minFilesPerLanguage?: number;
+    reuseLocal?: 'compatible' | 'always' | 'off';
+    onMissingTool?: 'auto' | 'skip' | 'error';
+    offline?: boolean;
+    waitTimeoutMs?: number;
+    installTimeoutMs?: number;
+    cacheDir?: string;
+    prewarm?: boolean;
+    deny?: string[];
+}
+export interface ReporterConfig {
+    /**
+     * What a failed post means for the run.
+     * - `warn` (default) — log it, exit code unchanged.
+     * - `error` — fail the run, for teams whose review depends on the comment.
+     * - `off` — stay silent.
+     */
+    onPostFailure?: 'warn' | 'error' | 'off';
+    /**
+     * `update` (default) edits the previous summary in place; `append` leaves one
+     * comment per run, giving a history in the thread.
+     */
+    mode?: 'update' | 'append';
+    /** Per-request timeout in ms (default 10000). A hung API must not hold the run open. */
+    timeoutMs?: number;
+    /** Attempts per request for retryable failures — 5xx, 429, network (default 3). */
+    retries?: number;
+    /**
+     * Pages of existing comments searched for our marker before giving up
+     * (default 10, 100 comments per page). Raise it on very long threads.
+     */
+    maxPages?: number;
+    /** Trim the comment: a table of forty green rows helps nobody. */
+    include?: {
+        passed?: boolean;
+        skipped?: boolean;
+        details?: boolean;
+        docsLink?: boolean;
+    };
+    /**
+     * Post nothing when the run produced no warnings and no failures, so a clean
+     * PR does not notify every subscriber.
+     */
+    skipWhenClean?: boolean;
+}
 export interface PRCheckMateConfig {
     sourcePath: string | string[];
+    excludePaths?: string[];
     ignoreDirs?: string[];
     languages?: Language[];
+    detect?: {
+        minFiles?: number;
+        excludePaths?: string[];
+        disable?: Language[];
+    };
     customRules?: Array<{
         name: string;
         pattern: string;
@@ -36,6 +107,28 @@ export interface PRCheckMateConfig {
         flags?: string;
     }>;
     severity?: Record<string, 'error' | 'warn' | 'off'>;
+    log?: {
+        level?: 'error' | 'warn' | 'info' | 'log' | 'debug';
+        format?: 'pretty' | 'ci' | 'json';
+        color?: 'auto' | 'always' | 'never';
+        timestamps?: boolean;
+        stderrLevels?: Array<'error' | 'warn' | 'info' | 'log' | 'debug'>;
+        sampleLimit?: number;
+    };
+    install?: InstallConfig;
+    reporter?: ReporterConfig;
+    run?: {
+        reportSkipped?: 'auto' | 'always' | 'never';
+        onDegradedScope?: 'warn' | 'error' | 'off';
+        concurrency?: number | 'auto' | 'unlimited';
+        heavyConcurrency?: number;
+        checkTimeoutMs?: number;
+        timings?: boolean;
+        fullScanBehaviour?: 'scan' | 'skip';
+    };
+    severityDefaults?: {
+        failOn?: 'error' | 'warn' | 'never';
+    };
     lint?: {
         rules?: Record<string, any>;
         ignorePatterns?: string[];
@@ -89,6 +182,7 @@ export interface PRCheckMateConfig {
     };
     diffSmell?: {
         enabled?: boolean;
+        ignorePaths?: string[];
     };
     prSize?: {
         enabled?: boolean;
@@ -98,6 +192,7 @@ export interface PRCheckMateConfig {
     leftoverDebug?: {
         enabled?: boolean;
         severity?: 'error' | 'warn';
+        commentHandling?: 'language' | 'legacy' | 'off';
     };
     todoFixme?: {
         enabled?: boolean;
@@ -192,6 +287,18 @@ export interface PRCheckMateConfig {
     diffSecurity?: {
         enabled?: boolean;
         ignore?: string[];
+        failOn?: 'error' | 'warn' | 'never';
+        severityOverrides?: Record<string, 'error' | 'warn' | 'off'>;
+        ignorePaths?: string[];
+        disablePatterns?: string[];
+        extraPatterns?: Array<{
+            label: string;
+            pattern: string;
+            severity?: 'error' | 'warn';
+            view?: 'raw' | 'code';
+            flags?: string;
+        }>;
+        commentHandling?: 'language' | 'legacy' | 'off';
     };
     mergeConflict?: {
         enabled?: boolean;
@@ -200,16 +307,35 @@ export interface PRCheckMateConfig {
     workflowSecurity?: {
         enabled?: boolean;
         ignore?: string[];
+        failOn?: 'error' | 'warn' | 'never';
+        severityOverrides?: Record<string, 'error' | 'warn' | 'off'>;
+        ignorePaths?: string[];
     };
     dockerfileSecurity?: {
         enabled?: boolean;
         ignore?: string[];
+        failOn?: 'error' | 'warn' | 'never';
+        severityOverrides?: Record<string, 'error' | 'warn' | 'off'>;
+        ignorePaths?: string[];
     };
     caseCollision?: {
         enabled?: boolean;
     };
     configValidation?: {
         enabled?: boolean;
+        severity?: 'error' | 'warn';
+        validateCheckNames?: boolean;
+        allowUnknownKeys?: string[];
+    };
+    symlinks?: {
+        enabled?: boolean;
+        severity?: 'error' | 'warn';
+        ignore?: string[];
+    };
+    shellcheck?: {
+        enabled?: boolean;
+        minSeverity?: 'error' | 'warning' | 'info' | 'style';
+        ignore?: string[];
     };
     yamlLint?: {
         enabled?: boolean;
@@ -250,6 +376,10 @@ export interface PRCheckMateConfig {
     };
     sensitiveFileGuard?: {
         enabled?: boolean;
+        ignorePaths?: string[];
+        ignore?: string[];
+        failOn?: 'error' | 'warn' | 'never';
+        severityOverrides?: Record<string, 'error' | 'warn' | 'off'>;
     };
     swift?: {
         enabled?: boolean;

package/dist/scripts/generate-install-manifests.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Build step: turn our own lockfile into one installable manifest per profile.
+ *
+ * Why the manifests are cut out of `package-lock.json` rather than resolved
+ * fresh from the registry:
+ *
+ * - **What clients fetch is then exactly what we tested.** Resolving at build
+ *   time would drift the moment a transitive dependency publishes a patch, and
+ *   the tooling clients run would stop being the tooling that passed our suite.
+ * - **The build stays offline.** A release pipeline that needs the network to
+ *   produce a manifest is a release pipeline that fails when the registry does.
+ * - **Integrity comes free.** Every entry carries the hash npm recorded, so the
+ *   runtime install is a plain `npm ci`, and npm refuses a tampered tarball
+ *   itself — over the whole transitive tree, not just the packages we name.
+ */
+interface LockEntry {
+    version?: string;
+    resolved?: string;
+    integrity?: string;
+    dependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    peerDependenciesMeta?: Record<string, {
+        optional?: boolean;
+    }>;
+    dev?: boolean;
+    link?: boolean;
+    [key: string]: unknown;
+}
+export interface Lock {
+    lockfileVersion: number;
+    packages: Record<string, LockEntry>;
+}
+/** Build the `package.json` + `package-lock.json` pair for one profile. */
+export declare function buildManifest(lock: Lock, profile: string, packages: string[], overrides?: Record<string, unknown>): {
+    pkg: object;
+    lockfile: object;
+};
+export {};

package/dist/scripts/generate-install-manifests.js

@@ -0,0 +1,121 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildManifest = buildManifest;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const profiles_1 = require("../core/install/profiles");
+/**
+ * Find the entry npm would resolve `name` to from inside `fromPath`.
+ *
+ * This reproduces node's own lookup: nearest `node_modules` first, then upwards
+ * to the root. Getting it wrong shows up as a package silently resolved to the
+ * wrong copy — `dpdm` bundles its own TypeScript, so "nearest wins" is not
+ * theoretical here.
+ */
+function resolveEntry(lock, name, fromPath) {
+    const segments = fromPath === '' ? [] : fromPath.split('/');
+    for (let depth = segments.length; depth >= 0; depth--) {
+        const prefix = segments.slice(0, depth).join('/');
+        const candidate = prefix ? `${prefix}/node_modules/${name}` : `node_modules/${name}`;
+        if (lock.packages[candidate])
+            return candidate;
+    }
+    return null;
+}
+/** Every dependency path reachable from the given top-level packages. */
+function closureOf(lock, roots) {
+    const seen = new Set();
+    const queue = [];
+    for (const name of roots) {
+        const entryPath = resolveEntry(lock, name, '');
+        if (entryPath)
+            queue.push(entryPath);
+    }
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (seen.has(current))
+            continue;
+        seen.add(current);
+        const entry = lock.packages[current];
+        if (!entry)
+            continue;
+        // Optional AND peer dependencies are included, both for the same reason:
+        // npm 7+ installs peers automatically, so a peer absent from the manifest is
+        // not simply skipped — npm resolves it fresh against the registry, gets the
+        // latest version, and then rejects the manifest as out of sync. That is
+        // exactly how the commitlint profile failed: `Missing: typescript@7.0.2 from
+        // lock file`, a version we never shipped and never tested.
+        const names = [
+            ...Object.keys(entry.dependencies ?? {}),
+            ...Object.keys(entry.optionalDependencies ?? {}),
+            ...Object.keys(entry.peerDependencies ?? {}),
+        ];
+        for (const name of names) {
+            const resolved = resolveEntry(lock, name, current);
+            if (resolved && !seen.has(resolved))
+                queue.push(resolved);
+        }
+    }
+    return seen;
+}
+/** Build the `package.json` + `package-lock.json` pair for one profile. */
+function buildManifest(lock, profile, packages, overrides) {
+    const closure = closureOf(lock, packages);
+    const dependencies = {};
+    for (const name of packages) {
+        const entryPath = resolveEntry(lock, name, '');
+        const version = entryPath ? lock.packages[entryPath]?.version : undefined;
+        if (!version)
+            throw new Error(`profile "${profile}": ${name} is not in package-lock.json`);
+        // Pinned, not ranged: a range would let the client resolve a version we
+        // never ran a single check against.
+        dependencies[name] = version;
+    }
+    const name = `pr-checkmate-profile-${profile}`;
+    // `overrides` are carried over — without them npm re-checks each declared
+    // range against the tree and rejects the manifest: `dpdm` asks for
+    // `typescript@^5.9.3`, our override points it at the copy we ship, and a
+    // manifest that dropped the override fails with `Missing: typescript@5.9.3`.
+    //
+    // Only the ones that apply, though. These manifests are the list of what a
+    // client's machine downloads at run time, so they are meant to be read; an
+    // override naming a package this profile never installs is noise in exactly
+    // the artefact that has to be scrutable.
+    const applicable = Object.fromEntries(Object.entries(overrides ?? {}).filter(([pkg]) => closure.has(resolveEntry(lock, pkg, '') ?? '')));
+    const scoped = Object.keys(applicable).length > 0 ? { overrides: applicable } : {};
+    const root = { name, version: '1.0.0', dependencies, ...scoped };
+    const pkg = { ...root, private: true };
+    const packagesOut = { '': root };
+    for (const entryPath of [...closure].sort()) {
+        const entry = { ...lock.packages[entryPath] };
+        // `dev` is about our repository, not about this manifest; leaving it set
+        // would make `npm ci --omit=dev` skip tooling the client needs.
+        delete entry.dev;
+        packagesOut[entryPath] = entry;
+    }
+    return {
+        pkg,
+        lockfile: { name, version: '1.0.0', lockfileVersion: 3, requires: true, packages: packagesOut },
+    };
+}
+function main() {
+    const root = process.cwd();
+    const lock = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(root, 'package-lock.json'), 'utf-8'));
+    const manifest = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(root, 'package.json'), 'utf-8'));
+    const outDir = node_path_1.default.join(root, 'install-manifests');
+    node_fs_1.default.rmSync(outDir, { recursive: true, force: true });
+    for (const profile of profiles_1.PROFILES) {
+        const { pkg, lockfile } = buildManifest(lock, profile.name, profile.packages, manifest.overrides);
+        const dir = node_path_1.default.join(outDir, profile.name);
+        node_fs_1.default.mkdirSync(dir, { recursive: true });
+        node_fs_1.default.writeFileSync(node_path_1.default.join(dir, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`);
+        node_fs_1.default.writeFileSync(node_path_1.default.join(dir, 'package-lock.json'), `${JSON.stringify(lockfile, null, 2)}\n`);
+        const count = Object.keys(lockfile.packages).length - 1;
+        process.stdout.write(`[manifests]: ${profile.name} — ${count} package(s)\n`);
+    }
+}
+if (require.main === module)
+    main();

package/dist/scripts/publish-github.js

@@ -21,16 +21,30 @@ function publishToGithub() {
     delete pkg.scripts?.prepublishOnly;
     fs_1.default.writeFileSync(tempPath, JSON.stringify(pkg, null, 2));
     try {
-        (0, child_process_1.execSync)(`mv ${pkgPath} ${backupPath}`);
-        (0, child_process_1.execSync)(`mv ${tempPath} ${pkgPath}`);
-        (0, child_process_1.execSync)('npm publish --registry=https://npm.pkg.github.com');
+        // `fs.renameSync` rather than shelling out to `mv`: the paths are built here
+        // and are not attacker-controlled, but a template literal inside execSync is
+        // a shell invocation regardless, and one that runs holding npm credentials.
+        // Found by our own Diff Security once `--full` began reviewing whole files
+        // (ticket 067) — the delta mode could never see it, since the file is old.
+        fs_1.default.renameSync(pkgPath, backupPath);
+        fs_1.default.renameSync(tempPath, pkgPath);
+        (0, child_process_1.execSync)('npm publish --registry=https://npm.pkg.github.com', { stdio: 'inherit' });
         utils_1.logger.log('[publishToGithub]: ✅ Published to GitHub Packages');
     }
     catch (err) {
         utils_1.logger.error(`[publishToGithub]: ${err}`);
     }
     finally {
-        (0, child_process_1.execSync)(`mv ${backupPath} ${pkgPath} || true`);
+        // The backup only exists if the first rename succeeded; restoring is
+        // best-effort so a failure here cannot mask the original error.
+        if (fs_1.default.existsSync(backupPath)) {
+            try {
+                fs_1.default.renameSync(backupPath, pkgPath);
+            }
+            catch (err) {
+                utils_1.logger.error(`[publishToGithub]: could not restore package.json: ${err}`);
+            }
+        }
     }
 }
 publishToGithub();

package/dist/utils/detect-language.d.ts

@@ -1,15 +1,48 @@
+/** Client `detect` block: how strictly a language is inferred from the tree. */
+export interface DetectOptions {
+    /** Source files needed to count a language as present. A marker file bypasses it. */
+    minFiles?: number;
+    /** Extra paths excluded from the count, on top of the built-in list. */
+    excludePaths?: string[];
+    /** Languages never reported, whatever the tree looks like. */
+    disable?: Language[];
+}
 export type Language = 'typescript' | 'javascript' | 'python' | 'cpp' | 'swift' | 'kotlin' | 'go' | 'rust' | 'csharp' | 'ruby' | 'php';
+/** One detected language, with the evidence that detected it. */
+export interface LanguageUsage {
+    lang: Language;
+    /** Tracked source files, excluding generated, vendored and manifest files. */
+    files: number;
+    /** A marker file declares the language regardless of the file count. */
+    marker: boolean;
+}
 /**
- * Detects which languages a repository uses, combining marker files (definitive)
- * with tracked source-file counts (breadth). A language is reported when it has a
- * marker file OR at least one tracked source file.
+ * Detects the languages a repository uses, and *why* each one was detected.
+ *
+ * Two different decisions read this, and they should not read it the same way:
+ *
+ * - **Which checks to run.** A marker is enough. A repo scaffolded from a
+ *   template has `pyproject.toml` and no `.py` yet, and running Python checks on
+ *   it costs nothing but a skip.
+ * - **Which toolchains to download** (ticket 064). A marker is *not* enough — a
+ *   `Cargo.toml` beside zero `.rs` files would pull a Rust profile on every CI
+ *   run for a language nobody has written yet. That decision wants `files > 0`.
+ *
+ * Returning the evidence rather than a bare list is what lets each caller pick.
  *
  * @param root Repository root.
  * @param ignoreDirs Directory names whose contents do not count as the repo's own
  *   code. Defaults to the curated list; `buildContext` passes the client's
  *   `ignoreDirs` so a repo that vendors dependencies is described by its own
  *   sources. Marker files are unaffected — they are only ever read from `root`.
+ * @param detect Client overrides for the heuristics.
  * @returns languages ordered by tracked file count (most-used first). `.h` headers
  *   are intentionally excluded from the C++ count since they are ambiguous with C.
  */
-export declare function detectLanguages(root?: string, ignoreDirs?: string[]): Promise<Language[]>;
+export declare function detectLanguageUsage(root?: string, ignoreDirs?: string[], detect?: DetectOptions): Promise<LanguageUsage[]>;
+/**
+ * The languages a repository uses, most-used first — the answer to "which checks
+ * should run". See {@link detectLanguageUsage} when the file counts matter, as
+ * they do for deciding what to download.
+ */
+export declare function detectLanguages(root?: string, ignoreDirs?: string[], detect?: DetectOptions): Promise<Language[]>;

package/dist/utils/detect-language.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectLanguageUsage = detectLanguageUsage;
 exports.detectLanguages = detectLanguages;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -36,6 +37,35 @@ const MARKER_FILES = {
     ruby: ['Gemfile', '.rubocop.yml'],
     php: ['composer.json'],
 };
+/**
+ * Paths whose files never count towards a language, on top of `ignoreDirs`.
+ *
+ * Every entry here comes from a real client repository, not from imagination:
+ *
+ * - `**\/*UnitTest*\/**` — Gradle/Android writes HTML+JS test reports into
+ *   `tests/testProdReleaseUnitTest_25.4.11/js/`. One generated `report.js` was
+ *   enough to make a 302-file Kotlin project detect as JavaScript.
+ * - `get-pip.py` — vendored bootstrap script, not the project's Python.
+ * - `vendor` / `third_party` — dependencies someone committed; the repo did not
+ *   write them and should not be judged by them.
+ */
+const DEFAULT_DETECT_EXCLUDES = [
+    '**/*UnitTest*/**',
+    '**/get-pip.py',
+    '**/vendor/**',
+    '**/third_party/**',
+];
+/**
+ * Extensions that mean a different language depending on where the file sits.
+ *
+ * `.rs` is Rust almost everywhere — but in an Android project `src/main/rs/`
+ * holds RenderScript, and `BrainEyeAndroid/src/main/rs/yuv2rgb.rs` made a mobile
+ * SDK detect as a Rust project. Real Rust (`build.rs`, `src/main.rs` in a Tauri
+ * app) is unaffected, which is why this is a path rule rather than a count threshold.
+ */
+const EXTENSION_COLLISIONS = [
+    { ext: '.rs', notUnder: /(^|\/)src\/main\/rs\//, lang: 'rust' },
+];
 /**
  * Source extensions per language, used to count tracked files via `git ls-files`.
  */
@@ -67,11 +97,39 @@ function hasMarker(root, lang) {
     });
 }
 /**
- * Counts tracked files per language using `git ls-files`. Returns an empty map
- * when git is unavailable or the directory is not a repo — callers then fall
- * back to marker files alone.
+ * Every marker filename that is also a source file, so it is never counted as
+ * one. `Package.swift` is a Swift *manifest*: counting it made a C++ repository
+ * report one Swift source it does not have. Same shape for `setup.py` and
+ * `conanfile.py`.
+ *
+ * The marker still detects the language on its own — that path is untouched.
+ * What changes is only that a manifest no longer inflates the file count, which
+ * is what the install decision in ticket 064 will read.
  */
-async function countTrackedFiles(root, ignoreDirs) {
+function markerFilenames() {
+    const names = new Set();
+    for (const list of Object.values(MARKER_FILES)) {
+        for (const name of list) {
+            if (!name.includes('*') && node_path_1.default.extname(name))
+                names.add(name);
+        }
+    }
+    return names;
+}
+/** Which language a file counts towards, or null when it counts towards none. */
+function languageOf(file, ext) {
+    for (const collision of EXTENSION_COLLISIONS) {
+        if (ext === collision.ext) {
+            return collision.notUnder.test(file) ? null : collision.lang;
+        }
+    }
+    for (const lang of Object.keys(EXTENSIONS)) {
+        if (EXTENSIONS[lang].includes(ext))
+            return lang;
+    }
+    return null;
+}
+async function countTrackedFiles(root, ignoreDirs, excludePaths) {
     const counts = {
         typescript: 0,
         javascript: 0,
@@ -89,6 +147,7 @@ async function countTrackedFiles(root, ignoreDirs) {
         const { stdout } = await (0, execa_1.execa)('git', ['ls-files'], { cwd: root });
         const files = stdout.split('\n').map(f => f.trim());
         const ignored = new Set(ignoreDirs);
+        const markers = markerFilenames();
         for (const file of files) {
             if (!file)
                 continue;
@@ -100,13 +159,16 @@ async function countTrackedFiles(root, ignoreDirs) {
             // check's file list already applies via `excludeIgnoredDirs`.
             if ((0, glob_1.isUnderIgnoredDir)(file, ignored))
                 continue;
-            const ext = node_path_1.default.extname(file).toLowerCase();
-            for (const lang of Object.keys(EXTENSIONS)) {
-                if (EXTENSIONS[lang].includes(ext)) {
-                    counts[lang] += 1;
-                    break;
-                }
-            }
+            // Generated reports and vendored bootstrap scripts are not the repo's code.
+            if ((0, glob_1.matchesAnyGlob)(file, excludePaths))
+                continue;
+            // A manifest that happens to be source-shaped (`Package.swift`) declares a
+            // language; it is not a line of it.
+            if (markers.has(node_path_1.default.basename(file)))
+                continue;
+            const lang = languageOf(file, node_path_1.default.extname(file).toLowerCase());
+            if (lang)
+                counts[lang] += 1;
         }
     }
     catch {
@@ -115,23 +177,55 @@ async function countTrackedFiles(root, ignoreDirs) {
     return counts;
 }
 /**
- * Detects which languages a repository uses, combining marker files (definitive)
- * with tracked source-file counts (breadth). A language is reported when it has a
- * marker file OR at least one tracked source file.
+ * Detects the languages a repository uses, and *why* each one was detected.
+ *
+ * Two different decisions read this, and they should not read it the same way:
+ *
+ * - **Which checks to run.** A marker is enough. A repo scaffolded from a
+ *   template has `pyproject.toml` and no `.py` yet, and running Python checks on
+ *   it costs nothing but a skip.
+ * - **Which toolchains to download** (ticket 064). A marker is *not* enough — a
+ *   `Cargo.toml` beside zero `.rs` files would pull a Rust profile on every CI
+ *   run for a language nobody has written yet. That decision wants `files > 0`.
+ *
+ * Returning the evidence rather than a bare list is what lets each caller pick.
  *
  * @param root Repository root.
  * @param ignoreDirs Directory names whose contents do not count as the repo's own
  *   code. Defaults to the curated list; `buildContext` passes the client's
  *   `ignoreDirs` so a repo that vendors dependencies is described by its own
  *   sources. Marker files are unaffected — they are only ever read from `root`.
+ * @param detect Client overrides for the heuristics.
  * @returns languages ordered by tracked file count (most-used first). `.h` headers
  *   are intentionally excluded from the C++ count since they are ambiguous with C.
  */
-async function detectLanguages(root = process.cwd(), ignoreDirs = constants_1.IGNORED_DIRS) {
-    const counts = await countTrackedFiles(root, ignoreDirs);
-    const detected = Object.keys(EXTENSIONS).filter(lang => hasMarker(root, lang) || counts[lang] > 0);
-    detected.sort((a, b) => counts[b] - counts[a]);
+async function detectLanguageUsage(root = process.cwd(), ignoreDirs = constants_1.IGNORED_DIRS, detect = {}) {
+    const excludePaths = [...DEFAULT_DETECT_EXCLUDES, ...(detect.excludePaths ?? [])];
+    const counts = await countTrackedFiles(root, ignoreDirs, excludePaths);
+    // 1 by default: with the causes of the false positives fixed above, a single
+    // real source file is a real language. The knob exists for repositories that
+    // carry stray one-off scripts they would rather not have checked.
+    const minFiles = Math.max(1, detect.minFiles ?? 1);
+    const disabled = new Set(detect.disable ?? []);
+    const detected = [];
+    for (const lang of Object.keys(EXTENSIONS)) {
+        if (disabled.has(lang))
+            continue;
+        const marker = hasMarker(root, lang);
+        if (marker || counts[lang] >= minFiles)
+            detected.push({ lang, files: counts[lang], marker });
+    }
+    detected.sort((a, b) => b.files - a.files);
     const countStr = Object.keys(counts).map(l => `${l}=${counts[l]}`).join(', ');
-    logger_1.logger.info(`[detectLanguages]: Detected ${detected.length ? detected.join(', ') : 'none'} (counts: ${countStr})`);
+    const names = detected.map(u => u.lang).join(', ');
+    logger_1.logger.info(`[detectLanguages]: Detected ${names || 'none'} (counts: ${countStr})`);
     return detected;
 }
+/**
+ * The languages a repository uses, most-used first — the answer to "which checks
+ * should run". See {@link detectLanguageUsage} when the file counts matter, as
+ * they do for deciding what to download.
+ */
+async function detectLanguages(root = process.cwd(), ignoreDirs = constants_1.IGNORED_DIRS, detect = {}) {
+    return (await detectLanguageUsage(root, ignoreDirs, detect)).map(u => u.lang);
+}