pr-checkmate 3.0.3 → 3.1.0

package/dist/esm/interfaces/index.d.ts

@@ -0,0 +1,432 @@
+import type { Language } from '../utils/detect-language.js';
+export interface ConfigFile {
+    source: string;
+    dest: string;
+}
+export interface PrettierConfig {
+    semi: boolean;
+    singleQuote: boolean;
+    trailingComma: string;
+    bracketSpacing: boolean;
+    arrowParens: string;
+    printWidth: number;
+}
+export interface CspellConfig {
+    version: string;
+    language: string;
+    import?: string[];
+    words: string[];
+    ignorePaths: string[];
+    enableFiletypes: string[];
+    ignoreRegExpList: string[];
+    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;
+        message?: string;
+        severity?: 'error' | 'warn';
+        include?: string[];
+        exclude?: string[];
+        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[];
+    };
+    prettier?: {
+        config?: Record<string, any>;
+    };
+    spellcheck?: {
+        enabled?: boolean;
+        words?: string[];
+        ignoreWords?: string[];
+        ignorePaths?: string[];
+    };
+    cspell?: {
+        enabled?: boolean;
+        words?: string[];
+        ignorePaths?: string[];
+        ignoreRegExpList?: string[];
+        dictionaries?: string[];
+        language?: string;
+    };
+    security?: {
+        gitleaks?: {
+            enabled?: boolean;
+            version?: string;
+            depth?: number;
+        };
+        'npm-audit'?: {
+            enabled?: boolean;
+            auditLevel?: string;
+            ignore?: string[];
+        };
+    };
+    typecheck?: {
+        enabled?: boolean;
+    };
+    cpp?: {
+        enabled?: boolean;
+        clangFormat?: {
+            style?: string;
+        };
+    };
+    python?: {
+        enabled?: boolean;
+        ruff?: {
+            lint?: boolean;
+            format?: boolean;
+        };
+        typecheck?: boolean;
+        typeChecker?: 'mypy' | 'pyright';
+    };
+    packageSize?: {
+        enabled?: boolean;
+        maxGrowthPercent?: number;
+        compareWith?: string;
+    };
+    diffSmell?: {
+        enabled?: boolean;
+        ignorePaths?: string[];
+    };
+    prSize?: {
+        enabled?: boolean;
+        maxFiles?: number;
+        maxLines?: number;
+    };
+    leftoverDebug?: {
+        enabled?: boolean;
+        severity?: 'error' | 'warn';
+        commentHandling?: 'language' | 'legacy' | 'off';
+    };
+    todoFixme?: {
+        enabled?: boolean;
+        severity?: 'error' | 'warn';
+        requireTicket?: boolean;
+        keywords?: string[];
+    };
+    lockfileDrift?: {
+        enabled?: boolean;
+        severity?: 'error' | 'warn';
+    };
+    missingTests?: {
+        enabled?: boolean;
+        severity?: 'error' | 'warn';
+        ignore?: string[];
+    };
+    migrationSafety?: {
+        enabled?: boolean;
+        severity?: 'error' | 'warn';
+        paths?: string[];
+    };
+    coverage?: {
+        enabled?: boolean;
+        severity?: 'error' | 'warn';
+        reportPath?: string | string[];
+    };
+    largeFiles?: {
+        enabled?: boolean;
+        severity?: 'error' | 'warn';
+        maxSizeKb?: number;
+        allow?: string[];
+    };
+    prBody?: {
+        enabled?: boolean;
+        minLength?: number;
+        requireTicket?: boolean;
+    };
+    duplicate?: {
+        enabled?: boolean;
+        minLines?: number;
+        minTokens?: number;
+        /**
+         * Glob patterns excluded from duplicate detection, in addition to the always-on
+         * node_modules/dist/.git ignores. Defaults to test files/folders
+         * (see DUPLICATE_IGNORE_DEFAULTS). Setting this replaces the default list.
+         */
+        ignore?: string[];
+        /**
+         * jscpd formats to scan. Defaults to source-code formats only
+         * (see DUPLICATE_CODE_FORMATS) — data formats like `yaml`, `json` and
+         * `markdown` are intentionally NOT scanned, since their repetition is rarely
+         * meaningful duplication. Add them back (e.g. `["typescript", "yaml"]`) if you
+         * do want to detect duplication in those files. Setting this replaces the list.
+         */
+        formats?: string[];
+    };
+    dependency?: {
+        enabled?: boolean;
+        /**
+         * Dependency names to exclude from the unused/missing check (knip).
+         * Supports globs matched against the whole name, e.g. "@types/*" — so
+         * "eslint-*" covers "eslint-plugin-x" but never "eslint" itself. Use for
+         * packages that are invoked only as CLI binaries or referenced from config —
+         * knip sees no `import` for them and would otherwise report them as unused.
+         * Compiled into a temporary knip config, so a repo that ships its own knip
+         * config keeps full control instead.
+         */
+        ignore?: string[];
+    };
+    outdatedDeps?: {
+        enabled?: boolean;
+        timeoutMs?: number;
+        /**
+         * Exact package names to exclude from the outdated-deps warning, e.g.
+         * "commander". Use for dependencies deliberately pinned behind their latest
+         * major (a breaking upgrade you have chosen not to take, or one held back by
+         * an `overrides` entry) so `npm outdated` no longer flags them as major-behind.
+         * Matched by exact name — no globs or version ranges.
+         */
+        ignore?: string[];
+    };
+    commitlint?: {
+        enabled?: boolean;
+        types?: string[];
+        /**
+         * Regex sources (matched case-insensitively) for commit messages to skip,
+         * e.g. release PRs or squash-merge titles that don't follow conventional
+         * commits. Applied in addition to commitlint's built-in merge/revert ignores.
+         */
+        ignores?: string[];
+    };
+    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';
+        dataflowWindow?: number;
+    };
+    mergeConflict?: {
+        enabled?: boolean;
+        severity?: 'error' | 'warn';
+    };
+    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;
+        severity?: 'error' | 'warn';
+        ignore?: string[];
+    };
+    circularDeps?: {
+        enabled?: boolean;
+        severity?: 'error' | 'warn';
+        ignore?: string[];
+        timeoutMs?: number;
+    };
+    vulnScan?: {
+        enabled?: boolean;
+        timeoutMs?: number;
+    };
+    grypeScan?: {
+        enabled?: boolean;
+        minSeverity?: 'negligible' | 'low' | 'medium' | 'high' | 'critical';
+        ignore?: string[];
+        /**
+         * Max time (ms) for the grype scan before the check skips. Default 120000.
+         * `ignoreDirs` already keeps `node_modules`, `dist` and friends out of the walk,
+         * which is what makes the scan fast; this is the backstop so an advisory check
+         * can never stall a commit.
+         */
+        timeoutMs?: number;
+    };
+    bannedImports?: Array<{
+        name: string;
+        message?: string;
+        severity?: 'error' | 'warn';
+    }>;
+    licenseHeader?: {
+        enabled?: boolean;
+        pattern?: string;
+        lines?: number;
+    };
+    sensitiveFileGuard?: {
+        enabled?: boolean;
+        ignorePaths?: string[];
+        ignore?: string[];
+        failOn?: 'error' | 'warn' | 'never';
+        severityOverrides?: Record<string, 'error' | 'warn' | 'off'>;
+    };
+    swift?: {
+        enabled?: boolean;
+    };
+    kotlin?: {
+        enabled?: boolean;
+    };
+    go?: {
+        enabled?: boolean;
+    };
+    rust?: {
+        enabled?: boolean;
+    };
+    csharp?: {
+        enabled?: boolean;
+    };
+    ruby?: {
+        enabled?: boolean;
+    };
+    php?: {
+        enabled?: boolean;
+    };
+    deadCode?: {
+        enabled?: boolean;
+        /**
+         * Regex sources matched against reported file paths; matching files are
+         * dropped from the dead-code report. Use to exempt intentional public
+         * surface — a package entry point (`src/index.ts`) or re-export barrels
+         * whose exports are consumed by external installers, not within the repo.
+         * Applied to the report (not ts-unused-exports' own `--ignoreFiles`), so it
+         * never removes a file from analysis and cannot cascade onto other files.
+         * Defaults to test/mock files (see DEAD_CODE_IGNORE_DEFAULTS), whose exports
+         * are consumed only by the test runner and would otherwise show as unused.
+         * Setting this replaces the default list.
+         */
+        ignoreFiles?: string[];
+    };
+    licenseCheck?: {
+        allowPackages?: string[];
+        allowLicenses?: string[];
+    };
+}
+export type { CheckStatus, CheckResult } from '../utils/result-collector.js';
+export type { Language } from '../utils/detect-language.js';

package/dist/esm/interfaces/index.js

@@ -0,0 +1,2 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export {};

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/dist/esm/scripts/copy-configs.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/scripts/copy-configs.js

@@ -0,0 +1,64 @@
+import { fileURLToPath as __fileURLToPath } from 'node:url';
+import { dirname as __dirnameFn } from 'node:path';
+const __dirname = __dirnameFn(__fileURLToPath(import.meta.url));
+import fs from 'node:fs';
+import path from 'node:path';
+import { logger } from '../utils/index.js';
+const configFiles = [
+    // Source is named so ESLint's auto-discovery does NOT treat it as a nested
+    // config for files under src/config/ — it ships to the package root as the
+    // canonical `eslint.config.mjs`.
+    { source: 'src/config/eslint-flat-config.mjs', dest: 'eslint.config.mjs' },
+    { source: 'src/config/eslint-default-rules.json', dest: 'eslint-default-rules.json' },
+    { source: 'src/config/.eslintrc.js', dest: '.eslintrc.js' },
+    { source: 'src/config/.prettierrc', dest: '.prettierrc' },
+    { source: 'src/config/cspell.json', dest: 'cspell.json' },
+    { source: 'tsconfig.json', dest: 'tsconfig.json' },
+    // `init.ts` reads these as a sibling of its own compiled location
+    // (`__dirname/config/...`), which means they must exist under both build
+    // outputs — dist/cjs and dist/esm are no longer siblings of a single
+    // shared dist/config the way the old flat dist/ layout was.
+    {
+        source: 'src/config/pr-checkmate-workflow.yml',
+        dest: 'dist/cjs/config/pr-checkmate-workflow.yml',
+    },
+    {
+        source: 'src/config/pr-checkmate-workflow.yml',
+        dest: 'dist/esm/config/pr-checkmate-workflow.yml',
+    },
+    {
+        source: 'src/config/pr-checkmate-workflow-docker.yml',
+        dest: 'dist/cjs/config/pr-checkmate-workflow-docker.yml',
+    },
+    {
+        source: 'src/config/pr-checkmate-workflow-docker.yml',
+        dest: 'dist/esm/config/pr-checkmate-workflow-docker.yml',
+    },
+    { source: 'src/config/pr-checkmate.schema.json', dest: 'pr-checkmate.schema.json' },
+];
+/**
+ *
+ */
+function copyConfigs() {
+    const root = path.resolve(__dirname, '../..');
+    logger.log('[copyConfigs]: Copying config files to package root...\n');
+    configFiles.forEach(({ source, dest }) => {
+        const srcPath = path.join(root, source);
+        const destPath = path.join(root, dest);
+        if (!fs.existsSync(srcPath)) {
+            logger.warn(`[copyConfigs]: ⚠️ Source not found: ${source}`);
+            return;
+        }
+        // Create destination directory if it doesn't exist
+        const destDir = path.dirname(destPath);
+        if (!fs.existsSync(destDir)) {
+            fs.mkdirSync(destDir, { recursive: true });
+        }
+        fs.copyFileSync(srcPath, destPath);
+        logger.log(`[copyConfigs]: ✅ Copied ${dest}`);
+    });
+    logger.info('\n[copyConfigs]: ✨ Configs successfully copied to root!\n');
+}
+if (require.main === module) {
+    copyConfigs();
+}

package/dist/esm/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/esm/scripts/generate-install-manifests.js

@@ -0,0 +1,115 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { PROFILES } from '../core/install/profiles.js';
+/**
+ * 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. */
+export 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(fs.readFileSync(path.join(root, 'package-lock.json'), 'utf-8'));
+    const manifest = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf-8'));
+    const outDir = path.join(root, 'install-manifests');
+    fs.rmSync(outDir, { recursive: true, force: true });
+    for (const profile of PROFILES) {
+        const { pkg, lockfile } = buildManifest(lock, profile.name, profile.packages, manifest.overrides);
+        const dir = path.join(outDir, profile.name);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`);
+        fs.writeFileSync(path.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/esm/scripts/publish-github.d.ts

@@ -0,0 +1 @@
+export {};