pr-checkmate 3.0.3 → 3.1.0

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;

package/dist/esm/core/checks/dependencies/circular-deps.js

@@ -0,0 +1,155 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getSourcePaths } from '../../../config/index.js';
+import { execa } from '../../../utils/execa.js';
+import { cleanupTempFile, logger, matchesAnyGlob, resolvePackageBin, } from '../../../utils/index.js';
+import { clientToolPaths } from '../../install/reuse.js';
+import { listTrackedFiles } from '../../targets.js';
+import { pass, skip } from '../../types.js';
+import { severityEmitter } from '../findings.js';
+/**
+ * Cap for the analysis. dpdm builds the whole module graph, which on a large repo
+ * is the slowest part of a run — an uncapped analysis looks like a hung commit.
+ */
+const DEFAULT_TIMEOUT_MS = 120000;
+/**
+ * Ceiling for the assembled argument list. Passing every tracked source file as a
+ * separate argument overflows the OS argument limit (`E2BIG`) on a large repo, and
+ * a spawn that never starts writes no report. Past the ceiling dpdm gets globs
+ * instead — it expands them itself, over the same source paths.
+ */
+const MAX_ARGV_CHARS = 100000;
+/** Extensions dpdm resolves for us; also the globs used in the fallback. */
+const SOURCE_GLOBS = ['*.ts', '*.tsx', '*.js', '*.jsx'];
+/**
+ * Resolve dpdm, preferring the consumer project's own copy (so a repo pinned to a
+ * different major keeps its own behaviour) and falling back to the copy bundled
+ * with pr-checkmate — the order `lint` and `typecheck` use for eslint/tsc.
+ *
+ * Returns null instead of throwing: an unresolvable analyzer is a skip, never a
+ * failed PR. This check used to shell out to `npx dpdm`, which silently fetched
+ * dpdm from the registry on first use — and when that fetch could not happen
+ * (offline or locked-down CI, private registry, exit 127) nothing was analyzed.
+ */
+function resolveDpdm(ctx) {
+    // No configuration of its own — dpdm reads the module graph — so the version
+    // check is the right question here and `clientOwnsConfig` stays off.
+    for (const options of [{ paths: clientToolPaths('dpdm', ctx) }, undefined]) {
+        try {
+            return resolvePackageBin('dpdm', 'lib/bin/dpdm.js', options);
+        }
+        catch {
+            // Try the next location; both failing is a skip, handled by the caller.
+        }
+    }
+    return null;
+}
+/**
+ * Build the file arguments for dpdm, falling back to globs when the explicit list
+ * would overflow the OS argument limit. `sourcePaths` scopes the globs the same way
+ * `listTrackedFiles` scopes the explicit list.
+ */
+function toFileArgs(files, sourcePaths) {
+    const explicitLength = files.reduce((sum, file) => sum + file.length + 1, 0);
+    if (explicitLength <= MAX_ARGV_CHARS)
+        return files;
+    const roots = sourcePaths.length > 0 ? sourcePaths : ['.'];
+    const globs = roots.flatMap(root => SOURCE_GLOBS.map(ext => `${root.replace(/\/+$/, '')}/**/${ext}`));
+    logger.info(`[Circular Deps]: ${files.length} files exceed the argument limit — analyzing via globs (${globs.join(', ')})`);
+    return globs;
+}
+/** Read dpdm's report file; null when it is absent or unparseable. */
+function readReport(reportPath) {
+    try {
+        return JSON.parse(fs.readFileSync(reportPath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export const circularDepsCheck = {
+    name: 'Circular Deps',
+    phase: 'blocking',
+    weight: 'heavy',
+    applies(ctx) {
+        if (ctx.config.circularDeps?.enabled === false)
+            return false;
+        return ctx.languages.includes('typescript') || ctx.languages.includes('javascript');
+    },
+    async run(ctx) {
+        const allFiles = await listTrackedFiles(ctx, SOURCE_GLOBS, getSourcePaths(ctx.cwd));
+        // A cycle detector needs the WHOLE graph, so an unreadable file list is the
+        // one case where passing would be worst: half a graph produces confident
+        // nonsense, and no graph reported as `pass` says the repository is acyclic
+        // when nobody looked (ticket 072).
+        if (allFiles === null)
+            return skip('git unavailable');
+        if (allFiles.length === 0)
+            return pass();
+        // Files the client exempted (generated code, vendored bundles) are dropped
+        // before analysis — and again from the cycles below, since the graph can reach
+        // an ignored file by following imports from one that is analyzed.
+        const ignore = ctx.config.circularDeps?.ignore ?? [];
+        const files = ignore.length > 0 ? allFiles.filter(f => !matchesAnyGlob(f, ignore)) : allFiles;
+        if (files.length === 0)
+            return skip('all files ignored');
+        const dpdmBin = resolveDpdm(ctx);
+        if (!dpdmBin) {
+            logger.warn('[Circular Deps]: ⚠️ dpdm could not be resolved — skipping');
+            return skip('dpdm unavailable');
+        }
+        const timeout = ctx.config.circularDeps?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const reportPath = path.join(ctx.cwd, '.dpdm.temp.json');
+        try {
+            // Read the cycles from dpdm's JSON report rather than its console output.
+            // The console shapes this check used to grep for ("Circular Dependencies:",
+            // "[1] a -> b") are not what dpdm 4 prints ("• Circular Dependencies",
+            // "1) a -> b"), so no cycle ever matched and the check passed every repo,
+            // including one built solely out of a cycle. `--exit-code circular:1` gives
+            // the same answer independently: dpdm otherwise exits 0 even when it finds
+            // cycles, so the exit code alone cannot tell a clean repo from a broken run.
+            const result = await execa(process.execPath, [
+                dpdmBin,
+                '--no-warning',
+                '--no-tree',
+                '--no-circular',
+                '--exit-code',
+                'circular:1',
+                '-o',
+                reportPath,
+                ...toFileArgs(files, getSourcePaths(ctx.cwd)),
+            ], { cwd: ctx.cwd, reject: false, timeout });
+            if (result.timedOut) {
+                logger.warn(`[Circular Deps]: ⚠️ dpdm timed out after ${timeout}ms — skipping`);
+                return skip('dpdm timed out');
+            }
+            const report = readReport(reportPath);
+            // No report means dpdm never got far enough to write one (a tsconfig it
+            // cannot read, a file it cannot parse, a killed process). Skip: reporting
+            // that as "no cycles" hides a check that did not run, and failing on it
+            // blocks a PR that may have no cycle at all.
+            if (!report) {
+                const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+                logger.warn(`[Circular Deps]: ⚠️ dpdm wrote no report (exit ${result.exitCode ?? 'killed'})${output ? `:\n${output}` : ''}`);
+                return skip(`dpdm failed to run (exit ${result.exitCode ?? 'killed'})`);
+            }
+            const cycles = (report.circulars ?? []).filter(cycle => ignore.length === 0 || !cycle.some(file => matchesAnyGlob(file, ignore)));
+            if (cycles.length === 0)
+                return pass();
+            // Advisory by default. This check reported nothing for its whole existence
+            // (see the note above), so switching it on turns every long-standing cycle
+            // in every client repo into a finding at once — barrel files alone account
+            // for most of them. Warning first lets a repo see its cycles before they
+            // gate anything; promote with `circularDeps.severity: "error"`.
+            const sev = severityEmitter(ctx.config.circularDeps?.severity, 'warn');
+            sev.log(`[Circular Deps]: ${sev.icon} ${cycles.length} circular dependency(ies):`);
+            cycles.slice(0, 10).forEach((cycle, i) => sev.log(`  ${i + 1}) ${cycle.join(' -> ')}`));
+            if (cycles.length > 10)
+                sev.log(`  ... and ${cycles.length - 10} more`);
+            return sev.emit(`${cycles.length} circular dependency(ies) found`);
+        }
+        finally {
+            cleanupTempFile(reportPath);
+        }
+    },
+};

package/dist/esm/core/checks/dependencies/dependency-check.d.ts

@@ -0,0 +1,43 @@
+import { Check } from '../../types.js';
+/** One entry of knip's JSON reporter — a file plus the issues found for it. */
+interface KnipIssue {
+    file: string;
+    dependencies?: {
+        name: string;
+    }[];
+    unlisted?: {
+        name: string;
+    }[];
+}
+interface KnipReport {
+    issues?: KnipIssue[];
+}
+/**
+ * Compile one `dependency.ignore` entry into a pattern knip matches the way this
+ * config documents it — a glob over the whole dependency name.
+ *
+ * knip turns any value containing `* + \ ( | { ^ $` into an *unanchored* `RegExp`
+ * and compares everything else by string equality. A glob passed straight through
+ * would therefore silence far more than it names: `eslint-*` reads as "eslint
+ * followed by zero or more dashes", tested as a substring, so it also swallows
+ * `eslint` itself. Escaping first and anchoring the result keeps `eslint-*` matching
+ * only `eslint-…`, and keeps a plain name matching exactly that name.
+ */
+export declare function toKnipIgnorePattern(entry: string): string;
+/**
+ * Pull knip's report out of a stdout stream that may carry unrelated output.
+ *
+ * knip imports the project's own config files while analyzing (a `wdio.conf.ts`
+ * for its WebdriverIO plugin, say), so any top-level side effect in them —
+ * a dotenv banner, a `console.log` in a config module — is printed before the
+ * report. Slicing from the first `{` to the last `}` therefore captured that
+ * noise instead: a dotenvx tip ending in `{ path: '…/.env' }` made the whole
+ * check fail on a repo whose report was perfectly valid.
+ *
+ * The json reporter writes the report as a single line (`JSON.stringify` with no
+ * indentation), so the last line that parses AND carries `issues` is the report.
+ * Anything else on stdout is noise, whatever braces it happens to contain.
+ */
+export declare function parseKnipReport(stdout: string): KnipReport | null;
+export declare const dependencyCheck: Check;
+export {};

package/dist/esm/core/checks/dependencies/dependency-check.js

@@ -0,0 +1,174 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { hasLocalConfig } from '../../../config/index.js';
+import { execa } from '../../../utils/execa.js';
+import { logger, cleanupTempFile, resolvePackageBin } from '../../../utils/index.js';
+import { isNpmProject, pass, fail, warn, skip } from '../../types.js';
+/**
+ * Config files knip discovers on its own. When a client ships one, it is the source
+ * of truth and pr-checkmate passes no config of its own — the same rule spellcheck
+ * follows for cspell.json.
+ *
+ * Mirrors knip's own `KNIP_CONFIG_LOCATIONS` exactly. Listing a name knip does not
+ * read (`knip.config.mjs`, say) would be worse than useless: the repo would count as
+ * "configures knip itself", so `dependency.ignore` would be dropped, while knip
+ * ignored that file too — leaving the client with warnings they had silenced.
+ */
+const KNIP_CONFIG_FILES = [
+    'knip.json',
+    'knip.jsonc',
+    '.knip.json',
+    '.knip.jsonc',
+    'knip.ts',
+    'knip.js',
+    'knip.config.ts',
+    'knip.config.js',
+];
+/** Regex metacharacters to neutralise before a glob is compiled. */
+const REGEX_SPECIALS = /[.*+?^${}()|[\]\\]/g;
+/**
+ * Compile one `dependency.ignore` entry into a pattern knip matches the way this
+ * config documents it — a glob over the whole dependency name.
+ *
+ * knip turns any value containing `* + \ ( | { ^ $` into an *unanchored* `RegExp`
+ * and compares everything else by string equality. A glob passed straight through
+ * would therefore silence far more than it names: `eslint-*` reads as "eslint
+ * followed by zero or more dashes", tested as a substring, so it also swallows
+ * `eslint` itself. Escaping first and anchoring the result keeps `eslint-*` matching
+ * only `eslint-…`, and keeps a plain name matching exactly that name.
+ */
+export function toKnipIgnorePattern(entry) {
+    const escaped = entry.replace(REGEX_SPECIALS, '\\$&');
+    return `^${escaped.replace(/\\\*/g, '.*').replace(/\\\?/g, '.')}$`;
+}
+/** knip also reads a `knip` key from package.json. */
+function hasPackageJsonConfig(cwd) {
+    try {
+        return 'knip' in JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Pull knip's report out of a stdout stream that may carry unrelated output.
+ *
+ * knip imports the project's own config files while analyzing (a `wdio.conf.ts`
+ * for its WebdriverIO plugin, say), so any top-level side effect in them —
+ * a dotenv banner, a `console.log` in a config module — is printed before the
+ * report. Slicing from the first `{` to the last `}` therefore captured that
+ * noise instead: a dotenvx tip ending in `{ path: '…/.env' }` made the whole
+ * check fail on a repo whose report was perfectly valid.
+ *
+ * The json reporter writes the report as a single line (`JSON.stringify` with no
+ * indentation), so the last line that parses AND carries `issues` is the report.
+ * Anything else on stdout is noise, whatever braces it happens to contain.
+ */
+export function parseKnipReport(stdout) {
+    const lines = stdout.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i].trim();
+        if (!line.startsWith('{'))
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (Array.isArray(parsed.issues))
+                return parsed;
+        }
+        catch {
+            // A noise line that merely looks like JSON — keep scanning upwards.
+        }
+    }
+    return null;
+}
+/** Collect the names reported for one issue type across every file in the report. */
+function collectNames(issues, key) {
+    return [...new Set(issues.flatMap(issue => (issue[key] ?? []).map(entry => entry.name)))];
+}
+/** Files a given unlisted dependency is imported from, for the failure message. */
+function filesUsing(issues, name) {
+    return issues
+        .filter(issue => (issue.unlisted ?? []).some(entry => entry.name === name))
+        .map(issue => issue.file);
+}
+export const dependencyCheck = {
+    name: 'Dependencies',
+    phase: 'blocking',
+    weight: 'heavy',
+    applies(ctx) {
+        if (ctx.config.dependency?.enabled === false)
+            return false;
+        return isNpmProject(ctx);
+    },
+    async run(ctx) {
+        // Resolve the bundled knip binary and run it via the current node — never
+        // shell out to `npx`, which fails (exit 127) when knip isn't on the path.
+        let knipBin;
+        try {
+            knipBin = resolvePackageBin('knip', 'bin/knip.js');
+        }
+        catch {
+            return skip('knip unavailable');
+        }
+        // Dependency names to skip, configured in pr-checkmate.json. knip takes these
+        // from a config file only, so they go into a temp one — but a client's own knip
+        // config wins outright, exactly as it does for cspell.
+        const ignore = ctx.config.dependency?.ignore ?? [];
+        const clientOwnsConfig = hasLocalConfig(KNIP_CONFIG_FILES, ctx.cwd) || hasPackageJsonConfig(ctx.cwd);
+        let tempConfigPath = null;
+        if (ignore.length > 0 && clientOwnsConfig) {
+            // Say so out loud: a silently ignored `ignore` list looks like a broken check.
+            logger.info(`[Dependencies]: ℹ️ this repo has its own knip config, so dependency.ignore (${ignore.join(', ')}) is not applied — add those names to knip's ignoreDependencies instead.`);
+        }
+        if (ignore.length > 0 && !clientOwnsConfig) {
+            tempConfigPath = path.join(ctx.cwd, '.knip.temp.json');
+            fs.writeFileSync(tempConfigPath, JSON.stringify({ ignoreDependencies: ignore.map(toKnipIgnorePattern) }, null, 2));
+        }
+        // Only unused prod dependencies and imports missing from package.json are
+        // reported. knip's other issue types (unused devDependencies, binaries,
+        // unresolved paths) are noise here: CLI tools and shell commands legitimately
+        // have no import to find.
+        const args = [
+            knipBin,
+            '--reporter',
+            'json',
+            '--include',
+            'dependencies,unlisted',
+            '--no-config-hints',
+            '--no-exit-code',
+            '--no-progress',
+        ];
+        if (tempConfigPath)
+            args.push('--config', tempConfigPath);
+        try {
+            // reject:false — knip can still exit non-zero (e.g. config hints) while
+            // writing a perfectly good report to stdout.
+            const { stdout } = await execa(process.execPath, args, {
+                cwd: ctx.cwd,
+                reject: false,
+            });
+            const result = parseKnipReport(stdout);
+            // No report on stdout → the tool couldn't produce a result; skip rather than
+            // fail the client's PR. Never fail here: a check that blocks a PR because a
+            // tool misbehaved reports our problem as the client's.
+            if (!result)
+                return skip('knip produced no report');
+            const issues = result.issues ?? [];
+            const unused = collectNames(issues, 'dependencies');
+            const missing = collectNames(issues, 'unlisted');
+            if (missing.length > 0) {
+                missing.forEach(dep => logger.error(`[Dependencies]: ❌ missing ${dep} (used in: ${filesUsing(issues, dep).join(', ')})`));
+                return fail(`missing: ${missing.join(', ')}`);
+            }
+            if (unused.length > 0) {
+                unused.forEach(dep => logger.warn(`[Dependencies]: ⚠️ unused ${dep}`));
+                return warn(`${unused.length} unused dependency(ies)`);
+            }
+            return pass();
+        }
+        finally {
+            if (tempConfigPath)
+                cleanupTempFile(tempConfigPath);
+        }
+    },
+};

package/dist/esm/core/checks/dependencies/grype-scan.d.ts

@@ -0,0 +1,22 @@
+import { Check } from '../../types.js';
+/**
+ * Dependency vulnerability scan via Anchore's `grype`. Non-blocking and ON by
+ * default — runs unless `grypeScan.enabled` is explicitly `false`. grype is a
+ * runner-dependency: it must be on the runner, and the check skips gracefully
+ * (not fails) when it is absent.
+ *
+ * grype resolves versions from lockfiles, so its raw output includes the entire
+ * transitive tree — and, because pr-checkmate installs into the consumer's
+ * node_modules, its own bundled dependencies too. Neither is something the
+ * consumer can fix. We therefore report ONLY vulnerabilities in DIRECT
+ * dependencies (those declared in the project's manifests, see
+ * `collectDirectDeps`): the set the maintainer actually controls. Findings whose
+ * ecosystem has no manifest we can parse are suppressed too, and the count of
+ * everything dropped is logged so nothing is hidden silently.
+ *
+ * The scan is confined to the project's own files: `ignoreDirs` is passed to grype
+ * as `--exclude`, and a timeout backstops the run. Both matter — cataloguing an
+ * installed `node_modules` is minutes of work whose every finding this check then
+ * throws away as third-party.
+ */
+export declare const grypeScanCheck: Check;