pr-checkmate 3.0.3 → 3.1.0

package/dist/esm/core/checks/dependencies/grype-scan.js

@@ -0,0 +1,112 @@
+import { execa } from '../../../utils/execa.js';
+import { collectDirectDeps, logger, normalizeName } from '../../../utils/index.js';
+import { pass, skip, warn } from '../../types.js';
+import { notInstalled } from '../tool-install.js';
+const SEVERITY_ORDER = ['negligible', 'low', 'medium', 'high', 'critical'];
+/** grype artifact `type` → the ecosystem we can resolve direct deps for. */
+const TYPE_TO_ECOSYSTEM = {
+    npm: 'npm',
+    python: 'python',
+    'go-module': 'go',
+    'rust-crate': 'rust',
+    gem: 'ruby',
+    'php-composer': 'php',
+};
+/**
+ * Cap for the scan. grype has no internal limit, so without this a slow scan just
+ * looks like a hung commit — an advisory check must never be able to do that.
+ */
+const DEFAULT_TIMEOUT_MS = 120000;
+function severityRank(severity) {
+    return SEVERITY_ORDER.indexOf((severity ?? '').toLowerCase());
+}
+/**
+ * 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 const grypeScanCheck = {
+    name: 'Grype Scan',
+    phase: 'informational',
+    weight: 'heavy',
+    applies(ctx) {
+        return ctx.config.grypeScan?.enabled !== false;
+    },
+    async run(ctx) {
+        const minSeverity = (ctx.config.grypeScan?.minSeverity ?? 'medium').toLowerCase();
+        const minRank = severityRank(minSeverity);
+        const ignore = (ctx.config.grypeScan?.ignore ?? []).map(s => s.toLowerCase());
+        // Never walk `ignoreDirs` — the same contract every other check honours, and
+        // here it is the difference between a usable check and an unusable one. A bare
+        // `grype dir:.` catalogs every file under `node_modules`, which on this repo took
+        // 355s versus 0.8s with the directory excluded, for byte-for-byte the same
+        // findings: grype resolves package versions from the lockfile, and installed
+        // third-party code is not something the client could fix anyway (see below).
+        const excludes = (ctx.config.ignoreDirs ?? []).flatMap(dir => ['--exclude', `**/${dir}/**`]);
+        const timeout = ctx.config.grypeScan?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const result = await execa('grype', ['dir:.', '-o', 'json', '-q', ...excludes], {
+            cwd: ctx.cwd,
+            reject: false,
+            timeout,
+        });
+        // execa v9 with reject:false resolves (not throws) with `code: 'ENOENT'`
+        // when the binary is absent — detect the missing scanner on the result.
+        if (result.code === 'ENOENT')
+            return notInstalled('grype');
+        if (result.timedOut) {
+            logger.warn(`[Grype Scan]: ⚠️ grype timed out after ${timeout}ms — skipping`);
+            return skip('grype timed out');
+        }
+        let report;
+        try {
+            report = JSON.parse(result.stdout);
+        }
+        catch {
+            return warn('grype produced no parseable output');
+        }
+        const matches = report.matches ?? [];
+        const direct = collectDirectDeps(ctx.cwd);
+        // Keep only: severity >= threshold, a direct dependency, and not ignored.
+        const isDirect = (m) => {
+            const ecosystem = TYPE_TO_ECOSYSTEM[m.artifact?.type ?? ''];
+            const names = ecosystem && direct.get(ecosystem);
+            if (!names)
+                return false; // unknown/unparseable ecosystem → not our concern
+            return names.has(normalizeName(ecosystem, m.artifact?.name ?? ''));
+        };
+        const isIgnored = (m) => ignore.includes((m.vulnerability?.id ?? '').toLowerCase()) ||
+            ignore.includes((m.artifact?.name ?? '').toLowerCase());
+        const atSeverity = matches.filter(m => severityRank(m.vulnerability?.severity) >= minRank);
+        const findings = atSeverity.filter(m => isDirect(m) && !isIgnored(m));
+        const suppressed = atSeverity.length - findings.length;
+        if (suppressed > 0) {
+            logger.info(`[Grype Scan]: suppressed ${suppressed} finding(s) — transitive/third-party (not directly fixable) or ignored`);
+        }
+        if (findings.length === 0) {
+            logger.info('[Grype Scan]: ✅ No known vulnerabilities in direct dependencies');
+            return pass();
+        }
+        logger.warn(`[Grype Scan]: ⚠️ vulnerabilities in direct dependencies (>= ${minSeverity}):`);
+        findings
+            .slice(0, 10)
+            .forEach(m => logger.warn(`  ${m.vulnerability?.id ?? 'unknown'} — ${m.artifact?.name ?? '?'}@${m.artifact?.version ?? '?'} (${m.vulnerability?.severity ?? '?'})`));
+        if (findings.length > 10)
+            logger.warn(`  ... and ${findings.length - 10} more`);
+        return warn(`${findings.length} direct-dependency vulnerability(ies) at "${minSeverity}"+ (grype)`);
+    },
+};

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

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

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

@@ -0,0 +1,61 @@
+import { execa } from '../../../utils/execa.js';
+import { logger, resolvePackageBin, getOwnDependencyClosure } from '../../../utils/index.js';
+import { isNpmProject, pass, fail, skip } from '../../types.js';
+const FORBIDDEN_LICENSES = ['GPL-2.0', 'GPL-3.0', 'AGPL-3.0', 'LGPL-2.0', 'LGPL-2.1', 'LGPL-3.0'];
+/** Strip the trailing "@version" to get the bare package name (scoped-safe). */
+function bareName(pkgKey) {
+    const at = pkgKey.lastIndexOf('@');
+    return at > 0 ? pkgKey.slice(0, at) : pkgKey;
+}
+export const licenseCheck = {
+    name: 'License Check',
+    phase: 'blocking',
+    applies(ctx) {
+        return isNpmProject(ctx);
+    },
+    async run(ctx) {
+        const allowPackages = new Set(ctx.config.licenseCheck?.allowPackages ?? []);
+        const allowLicenses = ctx.config.licenseCheck?.allowLicenses ?? [];
+        // pr-checkmate installs into the consumer's node_modules, so its own runtime
+        // deps (eslint plugins, cspell dictionaries, …) leak into the client's
+        // production tree. Those are our dependencies, not the client's — never fail
+        // a client's PR because of a license we ourselves pulled in.
+        const ownDeps = getOwnDependencyClosure();
+        // Resolve the bundled license-checker binary and run it via the current node — never
+        // shell out to `npx`, which fails (exit 127) when license-checker isn't on the path.
+        let licenseCheckerBin;
+        try {
+            licenseCheckerBin = resolvePackageBin('license-checker-rseidelsohn', 'bin/license-checker-rseidelsohn.js');
+        }
+        catch {
+            return skip('license-checker unavailable');
+        }
+        const { stdout, failed } = await execa(process.execPath, [licenseCheckerBin, '--json', '--production'], { cwd: ctx.cwd, reject: false });
+        let licenses;
+        try {
+            licenses = JSON.parse(stdout);
+        }
+        catch {
+            // Tool couldn't produce parseable output; skip rather than fail the client's PR.
+            return skip(failed ? 'license-checker failed to run' : 'license-checker produced invalid JSON');
+        }
+        const violations = [];
+        for (const [pkg, info] of Object.entries(licenses)) {
+            const name = bareName(pkg);
+            if (allowPackages.has(name) || ownDeps.has(name))
+                continue;
+            const raw = info.licenses ?? '';
+            const license = Array.isArray(raw) ? raw.join(' OR ') : raw;
+            if (allowLicenses.some(a => license.includes(a)))
+                continue;
+            if (FORBIDDEN_LICENSES.some(f => license.includes(f))) {
+                violations.push(`${pkg}: ${license}`);
+            }
+        }
+        if (violations.length > 0) {
+            violations.forEach(v => logger.error(`[License Check]: ❌ ${v}`));
+            return fail(`${violations.length} forbidden license(s)`);
+        }
+        return pass();
+    },
+};

package/dist/esm/core/checks/dependencies/npm-audit.d.ts

@@ -0,0 +1,6 @@
+import { Check } from '../../types.js';
+/**
+ * npm audit — only direct-dependency vulnerabilities block. Transitive ones and
+ * vulnerabilities in pr-checkmate itself are ignored (the client cannot fix those).
+ */
+export declare const npmAuditCheck: Check;

package/dist/esm/core/checks/dependencies/npm-audit.js

@@ -0,0 +1,80 @@
+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 { execa } from '../../../utils/execa.js';
+import { logger, findOwnPackageRoot } from '../../../utils/index.js';
+import { isNpmProject, pass, fail, skip } from '../../types.js';
+const SEVERITY_ORDER = ['info', 'low', 'moderate', 'high', 'critical'];
+function isSeverityAtLeast(severity, level) {
+    const sevIdx = SEVERITY_ORDER.indexOf(severity);
+    const lvlIdx = SEVERITY_ORDER.indexOf(level);
+    return sevIdx >= 0 && lvlIdx >= 0 && sevIdx >= lvlIdx;
+}
+function getOwnPackageName() {
+    try {
+        const ownPkg = path.join(findOwnPackageRoot() ?? path.resolve(__dirname, '../../../..'), 'package.json');
+        return JSON.parse(fs.readFileSync(ownPkg, 'utf-8')).name ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * npm audit — only direct-dependency vulnerabilities block. Transitive ones and
+ * vulnerabilities in pr-checkmate itself are ignored (the client cannot fix those).
+ */
+export const npmAuditCheck = {
+    name: 'NPM Audit',
+    phase: 'blocking',
+    applies(ctx) {
+        if (ctx.config.security?.['npm-audit']?.enabled === false)
+            return false;
+        return isNpmProject(ctx);
+    },
+    async run(ctx) {
+        // `high`, not `moderate`. A moderate CVE in a direct dependency often has no
+        // fix available, and blocking on it stops the team shipping anything at all —
+        // indefinitely, for a risk they have usually already accepted. A gate that
+        // cannot be satisfied gets switched off, and then the high ones stop blocking
+        // too. Clients who want the stricter line set `security.npm-audit.auditLevel`.
+        const auditLevel = ctx.config.security?.['npm-audit']?.auditLevel ?? 'high';
+        const ignore = new Set((ctx.config.security?.['npm-audit']?.ignore ?? []).map(name => name.toLowerCase()));
+        const ownName = getOwnPackageName();
+        const { stdout } = await execa('npm', ['audit', '--json'], { cwd: ctx.cwd, reject: false });
+        // `npm audit` reports registry/lockfile problems as JSON on stdout, but not
+        // always: an absent npm (execa resolves with `code: 'ENOENT'`), a killed
+        // process or a proxy that answers with HTML all leave stdout unparseable.
+        // Parsing it bare made those cases throw, and a throw in a blocking check is
+        // a failed PR — the client saw "NPM Audit threw: Unexpected end of JSON
+        // input" and a red gate for an environment problem they did not cause.
+        let report;
+        try {
+            report = JSON.parse(stdout);
+        }
+        catch {
+            logger.warn('[NPM Audit]: ⚠️ npm audit produced no parseable report — skipping');
+            return skip('npm audit produced no parseable report');
+        }
+        // A repo with no lockfile, or a registry npm cannot reach, yields
+        // `{"error":{"code":"ENOLOCK",…}}` — no `vulnerabilities` key at all. Passing
+        // on that reads as "no vulnerabilities" when nothing was actually audited.
+        if (report.error) {
+            const detail = report.error.summary ?? report.error.code ?? 'unknown error';
+            logger.warn(`[NPM Audit]: ⚠️ npm could not audit this project — ${detail}`);
+            return skip(`npm audit unavailable: ${report.error.code ?? 'error'}`);
+        }
+        const relevant = Object.values(report.vulnerabilities ?? {}).filter(v => v.isDirect && v.name !== ownName && isSeverityAtLeast(v.severity, auditLevel));
+        const [ignored, directVulns] = relevant.reduce(([skip, block], v) => {
+            (ignore.has(v.name.toLowerCase()) ? skip : block).push(v);
+            return [skip, block];
+        }, [[], []]);
+        // Ignored advisories stay visible as warnings — an exception is not a silent drop.
+        ignored.forEach(v => logger.warn(`[NPM Audit]: ⚠ ${v.name} — severity: ${v.severity} (ignored via config)`));
+        if (directVulns.length === 0)
+            return pass();
+        directVulns.forEach(v => logger.error(`[NPM Audit]: ❌ ${v.name} — severity: ${v.severity}`));
+        return fail(`${directVulns.length} direct vulnerability(ies) at "${auditLevel}"+`);
+    },
+};

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

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

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

@@ -0,0 +1,66 @@
+import { execa } from '../../../utils/execa.js';
+import { logger } from '../../../utils/index.js';
+import { isNpmProject, pass, skip, warn } from '../../types.js';
+const DEFAULT_TIMEOUT_MS = 30000;
+export const outdatedDepsCheck = {
+    name: 'Outdated Deps',
+    phase: 'informational',
+    applies(ctx) {
+        if (ctx.config.outdatedDeps?.enabled === false)
+            return false;
+        return isNpmProject(ctx);
+    },
+    async run(ctx) {
+        // `npm outdated` queries the registry for every dependency and can take a
+        // long time on big dependency trees — cap it so an advisory check never
+        // holds up CI. On timeout, skip rather than fail.
+        const timeout = ctx.config.outdatedDeps?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        // npm outdated exits 1 when outdated packages exist — use reject:false.
+        const result = await execa('npm', ['outdated', '--json'], {
+            cwd: ctx.cwd,
+            reject: false,
+            timeout,
+        });
+        if (result.timedOut) {
+            logger.warn(`[Outdated Deps]: ⚠️ npm outdated timed out after ${timeout}ms — skipping`);
+            return skip('npm outdated timed out');
+        }
+        if (!result.stdout?.trim())
+            return pass();
+        let outdated;
+        try {
+            outdated = JSON.parse(result.stdout);
+        }
+        catch {
+            return pass();
+        }
+        // Packages deliberately pinned behind their latest major (see outdatedDeps.ignore
+        // in pr-checkmate.json) are dropped before counting, so they never warn.
+        const ignore = new Set(ctx.config.outdatedDeps?.ignore ?? []);
+        const entries = Object.entries(outdated).filter(([pkg]) => !ignore.has(pkg));
+        if (entries.length === 0)
+            return pass();
+        // `current` is only populated when the package is installed in node_modules.
+        // In CI (npx-invoked validator, no `npm ci` for the target repo) it's absent,
+        // so fall back to `wanted` — the version the package.json range resolves to,
+        // which npm computes from the registry even without node_modules. Comparing
+        // that baseline to `latest` keeps the check meaningful in CI. Skip entries
+        // with neither, rather than treating a missing baseline as major 0.
+        const majorBehind = entries
+            .map(([pkg, info]) => ({ pkg, baseline: info.current ?? info.wanted, latest: info.latest }))
+            .filter(({ baseline, latest }) => {
+            if (!baseline)
+                return false;
+            return parseInt(latest?.split('.')[0] ?? '0', 10) > parseInt(baseline.split('.')[0], 10);
+        });
+        if (majorBehind.length > 0) {
+            majorBehind.forEach(({ pkg, baseline, latest }) => logger.warn(`[Outdated Deps]: ⚠️ ${pkg}: ${baseline} → ${latest}`));
+            return warn(`${majorBehind.length} package(s) major versions behind`);
+        }
+        const minorBehind = entries.length - majorBehind.length;
+        if (minorBehind > 0) {
+            logger.info(`[Outdated Deps]: ${minorBehind} package(s) have minor/patch updates`);
+        }
+        return pass();
+    },
+};

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

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

package/dist/esm/core/checks/dependencies/vuln-scan.js

@@ -0,0 +1,54 @@
+import { execa } from '../../../utils/execa.js';
+import { logger } from '../../../utils/index.js';
+import { pass, skip, warn } from '../../types.js';
+import { notInstalled } from '../tool-install.js';
+/**
+ * Cross-language dependency vulnerability scan via osv-scanner, which reads
+ * lockfiles across ecosystems (npm, PyPI, Go, crates, Maven, …) against the OSV
+ * database. Runner-dependency and opt-in (`vulnScan.enabled: true`): osv-scanner
+ * must be on the runner, and the check skips gracefully when it is absent.
+ * Complements the JS-only `npm-audit` with coverage for every other ecosystem.
+ *
+ * `-r .` walks the tree, so the run is capped: an advisory check must never be able
+ * to look like a hung commit, which is exactly what an uncapped directory scan does
+ * on a repo with dependencies installed.
+ */
+const DEFAULT_TIMEOUT_MS = 120000;
+export const vulnScanCheck = {
+    name: 'Vuln Scan',
+    phase: 'informational',
+    weight: 'heavy',
+    applies(ctx) {
+        return ctx.config.vulnScan?.enabled === true;
+    },
+    async run(ctx) {
+        const timeout = ctx.config.vulnScan?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const result = await execa('osv-scanner', ['-r', '.'], {
+            cwd: ctx.cwd,
+            reject: false,
+            timeout,
+        });
+        // execa v9 with reject:false resolves (not throws) with `code: 'ENOENT'`
+        // when the binary is absent — detect the missing scanner on the result.
+        if (result.code === 'ENOENT')
+            return notInstalled('osv-scanner');
+        if (result.timedOut) {
+            logger.warn(`[Vuln Scan]: ⚠️ osv-scanner timed out after ${timeout}ms — skipping`);
+            return skip('osv-scanner timed out');
+        }
+        if (result.exitCode === 0) {
+            logger.info('[Vuln Scan]: ✅ No known vulnerabilities');
+            return pass();
+        }
+        const lines = [result.stdout, result.stderr]
+            .filter(Boolean)
+            .join('\n')
+            .split('\n')
+            .filter(l => /\b(CVE-|GHSA-|vulnerab|advisor)/i.test(l));
+        logger.warn('[Vuln Scan]: ⚠️ known vulnerabilities found:');
+        lines.slice(0, 10).forEach(l => logger.warn(`  ${l.trim()}`));
+        if (lines.length > 10)
+            logger.warn(`  ... and ${lines.length - 10} more`);
+        return warn(`${lines.length || 'unknown'} vulnerability finding(s) (osv-scanner)`);
+    },
+};