pr-checkmate 3.0.4 → 3.2.0

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

@@ -0,0 +1,40 @@
+export * from './constants.js';
+export { loadProjectConfig } from '../config/loader.js';
+/**
+ * The configured source path(s), normalised to a list.
+ *
+ * Accepts a string or an array; empty and invalid values fall back to `['.']`,
+ * the whole repository. Clients narrow scanning to a subdirectory by setting
+ * `sourcePath`.
+ *
+ * `cwd` is a parameter rather than `process.cwd()` baked in, and that is the
+ * whole of ticket 074. This used to read a `CONFIG_FILE` constant resolved at
+ * *module load*, so the answer was fixed to whatever directory the process
+ * started in — `chdir` could not change it and neither could a caller. For the
+ * CLI that is harmless, since its working directory never moves; for
+ * `runChecks({ cwd })` it meant the SDK consumer's own `sourcePath` was applied
+ * to somebody else's repository, silently scoping every scoped check to a
+ * directory that may not exist there.
+ *
+ * It also read the file itself, duplicating `loadProjectConfig` with its own
+ * defaults. One reader is now the only reader.
+ */
+export declare function getSourcePaths(cwd?: string): string[];
+/**
+ * The first configured source path, for callers that only support one directory.
+ * Prefer {@link getSourcePaths} for scan targets.
+ */
+export declare function getSourcePath(cwd?: string): string;
+/**
+ * Get the effective list of directory names excluded from every check
+ * (client `ignoreDirs` in pr-checkmate.json, or the curated default).
+ */
+export declare function getIgnoredDirs(cwd?: string): string[];
+/**
+ * Get path to package config files
+ */
+export declare function getPackageConfigPath(fileName: string): string;
+/**
+ * Check if project has local config
+ */
+export declare function hasLocalConfig(configNames: string[], cwd?: string): boolean;

package/dist/esm/config/index.js

@@ -0,0 +1,60 @@
+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 { loadProjectConfig } from '../config/loader.js';
+import { findOwnPackageRoot } from '../utils/own-deps.js';
+export * from './constants.js';
+export { loadProjectConfig } from '../config/loader.js';
+/**
+ * The configured source path(s), normalised to a list.
+ *
+ * Accepts a string or an array; empty and invalid values fall back to `['.']`,
+ * the whole repository. Clients narrow scanning to a subdirectory by setting
+ * `sourcePath`.
+ *
+ * `cwd` is a parameter rather than `process.cwd()` baked in, and that is the
+ * whole of ticket 074. This used to read a `CONFIG_FILE` constant resolved at
+ * *module load*, so the answer was fixed to whatever directory the process
+ * started in — `chdir` could not change it and neither could a caller. For the
+ * CLI that is harmless, since its working directory never moves; for
+ * `runChecks({ cwd })` it meant the SDK consumer's own `sourcePath` was applied
+ * to somebody else's repository, silently scoping every scoped check to a
+ * directory that may not exist there.
+ *
+ * It also read the file itself, duplicating `loadProjectConfig` with its own
+ * defaults. One reader is now the only reader.
+ */
+export function getSourcePaths(cwd = process.cwd()) {
+    const { sourcePath } = loadProjectConfig(cwd);
+    const paths = (Array.isArray(sourcePath) ? sourcePath : [sourcePath]).filter((p) => typeof p === 'string' && p.trim().length > 0);
+    return paths.length > 0 ? paths : ['.'];
+}
+/**
+ * The first configured source path, for callers that only support one directory.
+ * Prefer {@link getSourcePaths} for scan targets.
+ */
+export function getSourcePath(cwd) {
+    return getSourcePaths(cwd)[0];
+}
+/**
+ * Get the effective list of directory names excluded from every check
+ * (client `ignoreDirs` in pr-checkmate.json, or the curated default).
+ */
+export function getIgnoredDirs(cwd) {
+    return loadProjectConfig(cwd).ignoreDirs ?? [];
+}
+/**
+ * Get path to package config files
+ */
+export function getPackageConfigPath(fileName) {
+    const packageRoot = findOwnPackageRoot() ?? path.resolve(__dirname, '../../..');
+    return path.join(packageRoot, fileName);
+}
+/**
+ * Check if project has local config
+ */
+export function hasLocalConfig(configNames, cwd = process.cwd()) {
+    return configNames.some(name => fs.existsSync(path.join(cwd, name)));
+}

package/dist/esm/config/loader.d.ts

@@ -0,0 +1,6 @@
+import { PRCheckMateConfig } from '../interfaces/index.js';
+/**
+ * Load project configuration from pr-checkmate.json
+ * Falls back to defaults if not found
+ */
+export declare function loadProjectConfig(cwd?: string): PRCheckMateConfig;

package/dist/esm/config/loader.js

@@ -0,0 +1,191 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { logger } from '../utils/index.js';
+import { DEAD_CODE_IGNORE_DEFAULTS, DEFAULT_ALLOW_PACKAGES, DUPLICATE_CODE_FORMATS, DUPLICATE_IGNORE_DEFAULTS, IGNORED_DIRS, } from './constants.js';
+/**
+ * Load project configuration from pr-checkmate.json
+ * Falls back to defaults if not found
+ */
+export function loadProjectConfig(cwd = process.cwd()) {
+    const configPath = path.join(cwd, 'pr-checkmate.json');
+    if (fs.existsSync(configPath)) {
+        try {
+            const content = fs.readFileSync(configPath, 'utf-8');
+            const config = JSON.parse(content);
+            return mergeWithDefaults(config);
+        }
+        catch (err) {
+            logger.warn(`[loadProjectConfig]: ⚠️ Failed to parse pr-checkmate.json: ${err}`);
+        }
+    }
+    return getDefaultConfig();
+}
+/**
+ * Deep merge user config with defaults
+ */
+function mergeWithDefaults(userConfig) {
+    const defaults = getDefaultConfig();
+    return {
+        // Preserve every key the user set — including opt-in checks (vulnScan,
+        // grypeScan) and controls with no default entry below (severity, customRules,
+        // prSize, caseCollision, go/rust/ruby/php, …). The explicitly-merged keys
+        // that follow override this spread with their default-merged values.
+        ...userConfig,
+        sourcePath: userConfig.sourcePath || defaults.sourcePath,
+        // Replace (not merge): the client sees the full default list in their
+        // generated config and edits it directly, so their list is authoritative.
+        ignoreDirs: userConfig.ignoreDirs ?? defaults.ignoreDirs,
+        lint: {
+            rules: { ...defaults.lint?.rules, ...userConfig.lint?.rules },
+            ignorePatterns: [
+                ...(defaults.lint?.ignorePatterns || []),
+                ...(userConfig.lint?.ignorePatterns || []),
+            ],
+        },
+        prettier: {
+            config: { ...defaults.prettier?.config, ...userConfig.prettier?.config },
+        },
+        spellcheck: {
+            words: [...(userConfig.spellcheck?.words || [])],
+            ignoreWords: [...(userConfig.spellcheck?.ignoreWords || [])],
+            ignorePaths: [
+                ...(defaults.spellcheck?.ignorePaths || []),
+                ...(userConfig.spellcheck?.ignorePaths || []),
+            ],
+        },
+        security: {
+            ...defaults.security,
+            ...userConfig.security,
+            gitleaks: { ...defaults.security?.gitleaks, ...userConfig.security?.gitleaks },
+            'npm-audit': { ...defaults.security?.['npm-audit'], ...userConfig.security?.['npm-audit'] },
+        },
+        typecheck: { ...defaults.typecheck, ...userConfig.typecheck },
+        cpp: {
+            ...defaults.cpp,
+            ...userConfig.cpp,
+            clangFormat: { ...defaults.cpp?.clangFormat, ...userConfig.cpp?.clangFormat },
+        },
+        python: {
+            ...defaults.python,
+            ...userConfig.python,
+            ruff: { ...defaults.python?.ruff, ...userConfig.python?.ruff },
+        },
+        swift: { ...defaults.swift, ...userConfig.swift },
+        kotlin: { ...defaults.kotlin, ...userConfig.kotlin },
+        diffSmell: { ...defaults.diffSmell, ...userConfig.diffSmell },
+        prBody: { ...defaults.prBody, ...userConfig.prBody },
+        duplicate: { ...defaults.duplicate, ...userConfig.duplicate },
+        dependency: { ...defaults.dependency, ...userConfig.dependency },
+        outdatedDeps: { ...defaults.outdatedDeps, ...userConfig.outdatedDeps },
+        commitlint: { ...defaults.commitlint, ...userConfig.commitlint },
+        deadCode: { ...defaults.deadCode, ...userConfig.deadCode },
+        licenseCheck: {
+            allowPackages: [
+                ...(defaults.licenseCheck?.allowPackages || []),
+                ...(userConfig.licenseCheck?.allowPackages || []),
+            ],
+            allowLicenses: [
+                ...(defaults.licenseCheck?.allowLicenses || []),
+                ...(userConfig.licenseCheck?.allowLicenses || []),
+            ],
+        },
+    };
+}
+/**
+ * Get default configuration
+ */
+function getDefaultConfig() {
+    return {
+        sourcePath: '.',
+        ignoreDirs: [...IGNORED_DIRS],
+        lint: {
+            rules: {
+                'no-console': 'warn',
+                'no-debugger': 'error',
+                'prefer-const': 'error',
+                eqeqeq: ['error', 'always'],
+                '@typescript-eslint/no-unused-vars': [
+                    'error',
+                    { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
+                ],
+                '@typescript-eslint/explicit-function-return-type': ['warn'],
+                '@typescript-eslint/no-explicit-any': ['warn'],
+                '@typescript-eslint/no-floating-promises': ['error'],
+                'max-len': ['warn', { code: 100 }],
+                semi: ['error', 'always'],
+                quotes: ['error', 'single', { avoidEscape: true }],
+                'object-curly-spacing': ['error', 'always'],
+                'keyword-spacing': ['error', { before: true, after: true }],
+            },
+            ignorePatterns: [
+                '**/node_modules/**',
+                '**/dist/**',
+                '**/.git/**',
+                '**/build/**',
+                '**/coverage/**',
+                '**/.next/**',
+            ],
+        },
+        prettier: {
+            config: {
+                semi: true,
+                singleQuote: true,
+                trailingComma: 'all',
+                bracketSpacing: true,
+                arrowParens: 'avoid',
+                printWidth: 100,
+                tabWidth: 2,
+            },
+        },
+        spellcheck: {
+            words: [],
+            ignoreWords: [],
+            ignorePaths: ['**/node_modules/**', '**/dist/**', '**/.git/**', '**/build/**'],
+        },
+        security: {
+            gitleaks: { enabled: true },
+            'npm-audit': { enabled: true, auditLevel: 'moderate' },
+        },
+        typecheck: { enabled: true },
+        cpp: { enabled: true, clangFormat: { style: 'LLVM' } },
+        python: { enabled: true, ruff: { lint: true, format: true } },
+        swift: { enabled: true },
+        kotlin: { enabled: true },
+        diffSmell: { enabled: true },
+        prBody: { enabled: true, minLength: 20, requireTicket: true },
+        duplicate: {
+            enabled: true,
+            minLines: 5,
+            minTokens: 50,
+            ignore: DUPLICATE_IGNORE_DEFAULTS,
+            formats: DUPLICATE_CODE_FORMATS,
+        },
+        dependency: { enabled: true, ignore: [] },
+        outdatedDeps: { enabled: true, ignore: [] },
+        deadCode: { enabled: true, ignoreFiles: DEAD_CODE_IGNORE_DEFAULTS },
+        commitlint: {
+            enabled: true,
+            types: [
+                'feat',
+                'fix',
+                'docs',
+                'chore',
+                'ci',
+                'refactor',
+                'perf',
+                'style',
+                'revert',
+                'test',
+                'build',
+            ],
+            // Skip release PRs and squash-merge titles that don't follow conventional
+            // commits (e.g. "Release 15 (#114)"). commitlint already ignores literal
+            // "Merge"/"Revert" messages, but not GitHub squash-merge PR titles.
+            ignores: ['^Release\\b', '^chore\\(release\\):'],
+        },
+        licenseCheck: {
+            allowPackages: [...DEFAULT_ALLOW_PACKAGES],
+            allowLicenses: [],
+        },
+    };
+}

package/dist/esm/config/pr-checkmate-workflow-docker.yml

@@ -0,0 +1,79 @@
+name: PR CheckMate
+
+# The container variant, scaffolded because this repository does not carry
+# pr-checkmate as a dependency.
+#
+# The alternative would be `npx pr-checkmate`, and with no node_modules to reuse
+# that resolves to whatever is newest on the registry and downloads it again on
+# every job: 547 MB and about five minutes, measured. Worse, a major release
+# would land on you without a line changing here — and a major release of a gate
+# can start failing builds that passed yesterday.
+#
+# The image is pulled once and cached by the runner, and the tag below pins the
+# major so nothing moves under you.
+
+on:
+  pull_request:
+    branches: [main, master, develop]
+    types: [opened, synchronize, reopened]
+
+# Least privilege. `pull-requests: write` is what lets the run upsert its summary
+# comment on the PR; drop it and the checks still run, they just report to the log.
+permissions:
+  contents: read
+  pull-requests: write
+
+# Push three times in a minute and the first two runs become answers to questions
+# nobody is asking any more — they still hold a runner, and they still race to
+# upsert the summary comment, so a stale verdict can land on top of a fresh one.
+# Keyed per PR, so runs on different pull requests never cancel each other.
+concurrency:
+  group: pr-checkmate-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pr-checkmate:
+    name: PR CheckMate
+    runs-on: ubuntu-latest
+    # A hung step otherwise runs to GitHub's six-hour default before anyone hears
+    # about it. Every check has its own internal timeout; this is the backstop.
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          # Required, not optional. Without the full history the PR base commit is
+          # not in the clone, no diff range can be built, and every diff-based
+          # check skips itself. The run then says `Scan Scope: … set
+          # fetch-depth: 0`, which is this line.
+          fetch-depth: 0
+
+      # One job runs the whole registry. Which checks run is decided in
+      # pr-checkmate.json (`severity`), not by splitting this into jobs.
+      #
+      # `--user` is not a detail: without it every file a formatter rewrites comes
+      # back owned by root, and the next step in your pipeline fails on
+      # permissions long after this one reported success.
+      #
+      # The environment variables are passed through by name rather than by value:
+      # the run reads them to find the PR, and interpolating them into the command
+      # line would put their contents into a shell.
+      - name: Run PR CheckMate
+        env:
+          # Not injected automatically: without this the run cannot authenticate,
+          # and the summary comment silently never reaches the PR.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          docker run --rm \
+            -v "$PWD:/repo" \
+            --user "$(id -u):$(id -g)" \
+            -e GITHUB_TOKEN \
+            -e GITHUB_REPOSITORY \
+            -e GITHUB_EVENT_NAME \
+            -e GITHUB_EVENT_PATH \
+            -e GITHUB_REF \
+            -e GITHUB_SHA \
+            -e CI \
+            -v "$GITHUB_EVENT_PATH:$GITHUB_EVENT_PATH:ro" \
+            ghcr.io/mybono/pr-checkmate:__IMAGE_TAG__ all

package/dist/esm/config/pr-checkmate-workflow.yml

@@ -0,0 +1,92 @@
+name: PR CheckMate
+
+on:
+  pull_request:
+    branches: [main, master, develop]
+    types: [opened, synchronize, reopened]
+
+# Least privilege. `pull-requests: write` is what lets the run upsert its summary
+# comment on the PR; drop it and the checks still run, they just report to the log.
+permissions:
+  contents: read
+  pull-requests: write
+
+# Push three times in a minute and the first two runs become answers to questions
+# nobody is asking any more — they still hold a runner, and they still race to
+# upsert the summary comment, so a stale verdict can land on top of a fresh one.
+# Keyed per PR, so runs on different pull requests never cancel each other.
+concurrency:
+  group: pr-checkmate-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pr-checkmate:
+    name: PR CheckMate
+    runs-on: ubuntu-latest
+    # A hung step otherwise runs to GitHub's six-hour default before anyone hears
+    # about it. Every check here has its own internal timeout; this is the backstop
+    # for the ones that cannot fail themselves — a wedged network fetch, a tool
+    # waiting on stdin. Raise it for a large monorepo.
+    timeout-minutes: 20
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          # Required, not optional. Without the full history the PR base commit is
+          # not in the clone, no diff range can be built, and every diff-based
+          # check — Diff Security, Workflow Security, Dockerfile Security,
+          # Sensitive Files and a dozen others — skips itself. The run then says
+          # `Scan Scope: … set fetch-depth: 0`, which is this line.
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 24
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      # PR CheckMate fetches only the tooling this repository turns out to need
+      # (`npx pr-checkmate doctor` prints what and why). Without this step that
+      # tooling is fetched again on every run: the download shrinks, the wait
+      # does not. The key carries the pr-checkmate version, so an upgrade fetches
+      # afresh instead of reusing tooling meant for the previous one.
+      - name: Cache PR CheckMate tooling
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: ~/.cache/pr-checkmate
+          key: pr-checkmate-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            pr-checkmate-${{ runner.os }}-
+
+      # Grype keeps its own vulnerability database, and it is the single largest
+      # download in the whole run: 134 MB compressed, 1.9 GB unpacked, refreshed
+      # daily upstream. Without this step every job pays for it again. The key is
+      # dated rather than content-hashed, because the thing that changes is the
+      # upstream database, not anything in this repository — a stale entry is
+      # restored by the prefix and grype updates it in place.
+      - name: Cache Grype vulnerability database
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: ~/.cache/grype
+          key: grype-db-${{ runner.os }}-${{ github.run_id }}
+          restore-keys: |
+            grype-db-${{ runner.os }}-
+
+      # One job runs the whole registry. Splitting it per check would repeat the
+      # checkout and install for every one of them, and the selection of what runs
+      # belongs in pr-checkmate.json (`severity`), not in copied YAML.
+      #
+      # This template is the one `init` scaffolds when pr-checkmate IS a
+      # dependency: `npm ci` above installs it, so npx runs that copy at the
+      # version your lockfile pins. A repository that does not install it gets
+      # the container variant instead, because bare `npx` would resolve to the
+      # newest release and download it on every job.
+      - name: Run PR CheckMate
+        env:
+          # Not injected automatically: without this the run cannot authenticate,
+          # and the summary comment silently never reaches the PR.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: npx pr-checkmate all

package/dist/esm/core/checks/dependencies/banned-imports.d.ts

@@ -0,0 +1,2 @@
+import { Check } from '../../types.js';
+export declare const bannedImportsCheck: Check;

package/dist/esm/core/checks/dependencies/banned-imports.js

@@ -0,0 +1,70 @@
+import { logger } from '../../../utils/index.js';
+import { pass, skip } from '../../types.js';
+import { clientFindingOptions, reportSeverityBuckets, reviewLines, } from '../findings.js';
+const PREFIX = 'Banned Imports';
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * Compile `bannedImports` into matchers that catch a banned package via an ES
+ * import, a CommonJS require, or its addition to a manifest dependency list.
+ */
+function compileBans(ctx) {
+    const list = ctx.config.bannedImports ?? [];
+    return list
+        .filter(b => b?.name)
+        .map(b => {
+        const n = escapeRe(b.name);
+        const re = new RegExp(`from\\s+['"]${n}(?:/[^'"]*)?['"]|require\\(\\s*['"]${n}(?:/[^'"]*)?['"]|import\\s+['"]${n}['"]|["']${n}["']\\s*:`);
+        return {
+            message: b.message ?? `banned dependency: ${b.name}`,
+            re,
+            severity: b.severity === 'error' ? 'error' : 'warn',
+        };
+    });
+}
+export const bannedImportsCheck = {
+    name: 'Banned Imports',
+    phase: 'informational',
+    // No `requiresDiff`: a banned import is banned wherever it is, not only where
+    // it was just introduced (ticket 067).
+    applies(ctx) {
+        return (ctx.config.bannedImports?.length ?? 0) > 0;
+    },
+    async run(ctx) {
+        const bans = compileBans(ctx);
+        if (bans.length === 0)
+            return pass('no banned imports configured');
+        try {
+            const errors = {};
+            const warnings = {};
+            const reviewed = await reviewLines(ctx, ['*'], stdout => {
+                var _a;
+                for (const raw of stdout.split('\n')) {
+                    if (!raw.startsWith('+') || raw.startsWith('+++'))
+                        continue;
+                    const content = raw.slice(1);
+                    for (const ban of bans) {
+                        if (ban.re.test(content)) {
+                            const bucket = ban.severity === 'error' ? errors : warnings;
+                            (bucket[_a = ban.message] ?? (bucket[_a] = [])).push(content.trim().substring(0, 100));
+                        }
+                    }
+                }
+            });
+            // An unreadable file list is not "no banned imports" (ticket 072).
+            if (!reviewed)
+                return skip('git unavailable');
+            // A ban configured as "error" blocks the run, regardless of phase — that
+            // is the default `failOn`, and the client can still relax it per repo.
+            return reportSeverityBuckets(errors, warnings, {
+                prefix: PREFIX,
+                errorSummary: n => `${n} banned (error)`,
+                warningSummary: n => `${n} banned (warn)`,
+                ...clientFindingOptions(ctx),
+            });
+        }
+        catch (err) {
+            logger.warn(`[Banned Imports]: ⚠️ Could not analyze diff\n${err}`);
+            return skip('diff unavailable');
+        }
+    },
+};

package/dist/esm/core/checks/dependencies/circular-deps.d.ts

@@ -0,0 +1,2 @@
+import { Check } from '../../types.js';
+export declare const circularDepsCheck: Check;