pr-checkmate 3.0.3 → 3.1.0

package/dist/esm/core/types.d.ts

@@ -0,0 +1,195 @@
+import type { PRCheckMateConfig, ReporterConfig } from '../interfaces/index.js';
+import type { Language, LanguageUsage } from '../utils/detect-language.js';
+import type { CheckResult, CheckStatus } from '../utils/result-collector.js';
+export type { CheckResult, CheckStatus, Language, LanguageUsage };
+/**
+ * Execution phases, run strictly in order. Within a phase checks run in parallel.
+ * `format` runs last because formatters (prettier) may write files.
+ */
+export type Phase = 'blocking' | 'informational' | 'format';
+export declare const PHASES: readonly Phase[];
+/**
+ * What this run is looking at, and whether that is what was asked for.
+ *
+ * `degraded` is the field that earns this its own type: a full scan requested by
+ * a human and a full scan we fell back to because the PR base was missing are
+ * indistinguishable in the results — both just omit every delta-only check — but
+ * only one of them is a problem worth telling anyone about.
+ */
+export interface RunScope {
+    kind: 'delta' | 'full' | 'staged';
+    /** Short explanation for the log line, e.g. `PR base unavailable`. */
+    reason?: string;
+    /** True when a diff range was wanted but could not be built. */
+    degraded: boolean;
+}
+/**
+ * Everything a check needs to run. Assembled once by `buildContext` and shared
+ * across all checks — no check reads `process.cwd()` or `process.env` directly.
+ */
+export interface CheckContext {
+    /** Repository root the checks operate on. */
+    cwd: string;
+    /** Languages detected (or supplied) for this repo — drives `applies` gating. */
+    languages: Language[];
+    /**
+     * The same detection with its evidence — file counts per language. Read by the
+     * install layer, which must not confuse "this language is here" with "this
+     * language is worth a toolchain download". Absent on hand-built contexts.
+     */
+    usage?: LanguageUsage[];
+    /** Merged pr-checkmate.json + defaults. */
+    config: PRCheckMateConfig;
+    /** When false, checks that would modify files (prettier, --fix) run read-only or skip the write. */
+    write: boolean;
+    /** Diff range for delta-aware checks; undefined → full-repo scan. */
+    baseSha?: string;
+    headSha?: string;
+    /** What this run is looking at, and why. Optional so hand-built contexts stay terse. */
+    scope?: RunScope;
+    /**
+     * Display names of the checks in this run, for the one check that reasons about
+     * the others (Config Validation, verifying `severity` keys).
+     *
+     * Passed down rather than imported: a check importing the registry would close
+     * the loop registry → check → registry, and it also lets custom checks supplied
+     * through `RunOptions.checks` be validated like built-in ones.
+     */
+    checkNames?: string[];
+    /**
+     * Per-run memoization cache for identical git invocations (many checks diff
+     * the same range). Created once per `runChecks`; safe because git state is
+     * stable within a run. Keyed by the git args.
+     */
+    cache?: Map<string, string>;
+}
+/** Outcome of a single check — the name is attached by the orchestrator. */
+export interface CheckOutcome {
+    status: CheckStatus;
+    details?: string;
+}
+/**
+ * A single quality gate. `applies` decides relevance (language/marker gating);
+ * `run` performs the check and returns an outcome. `run` must NOT throw for
+ * violations — return `fail`/`warn` instead. Thrown errors are caught by the
+ * orchestrator and recorded as `fail`.
+ */
+export interface Check {
+    name: string;
+    phase: Phase;
+    /**
+     * The check reviews a diff and has nothing to say without one. Declared here
+     * rather than folded into `applies` so the orchestrator can tell the two kinds
+     * of "not applicable" apart:
+     *
+     * - a check that does not apply (SwiftLint in a Python repo) is noise, and is
+     *   left out of the report entirely;
+     * - a check that *would* have applied but had no diff range is a gap in
+     *   coverage, and is reported as a skip with the reason.
+     *
+     * Before this existed, both simply vanished — so a shallow clone removed most
+     * of the security surface and still printed a clean, complete-looking report.
+     */
+    requiresDiff?: boolean;
+    /**
+     * The check spawns something expensive — a whole-project analyser like knip,
+     * jscpd, dpdm, tsc or grype. The orchestrator admits only a couple of these at
+     * once, independently of the overall concurrency limit: four regex scans in
+     * parallel are free, four project-wide analysers are not.
+     */
+    weight?: 'heavy';
+    applies(ctx: CheckContext): boolean | Promise<boolean>;
+    run(ctx: CheckContext): Promise<CheckOutcome>;
+}
+export type ReporterKind = 'none' | 'stdout' | 'github' | 'gitlab' | 'bitbucket' | 'auto';
+/** Custom reporter: receives the final report to emit however the consumer wants. */
+export type ReporterFn = (report: CheckReport) => void | Promise<void>;
+export type { ReporterConfig };
+export interface RunOptions {
+    cwd?: string;
+    /** Override language detection (e.g. PRValidator passes its already-detected type). */
+    languages?: Language[];
+    /** Whitelist of check names — when set, only these run. */
+    only?: string[];
+    /** Blacklist of check names — always excluded. */
+    skip?: string[];
+    /**
+     * Extra checks to run. Combined with the built-in registry per `extendRegistry`.
+     * Lets consumers (e.g. PRValidator) plug their own `Check`s into the same pipeline.
+     */
+    checks?: Check[];
+    /**
+     * How `checks` combines with the built-in registry:
+     * - `true` (default when `checks` is set): append; a custom check overrides a
+     *   built-in one with the same name.
+     * - `false`: run ONLY the provided `checks`, ignoring the built-in registry.
+     */
+    extendRegistry?: boolean;
+    /**
+     * Where the report goes:
+     * - `'none'`: nothing (just return the report)
+     * - `'stdout'`: print the summary table
+     * - `'github'`: print + upsert a PR comment
+     * - a function: receives the `CheckReport` (e.g. forward to Slack).
+     */
+    reporter?: ReporterKind | ReporterFn;
+    /** Allow file-modifying checks to write. Default false. */
+    write?: boolean;
+    config?: PRCheckMateConfig;
+    baseSha?: string;
+    headSha?: string;
+    /**
+     * Pre-commit / local mode: check the staged changes (index vs HEAD) instead of
+     * a PR range. Implemented by diffing HEAD against the index tree
+     * (`git write-tree`), so every delta-aware check works unchanged.
+     */
+    staged?: boolean;
+    /**
+     * Review every tracked file instead of a diff (`--full` on the CLI, and the
+     * default when no CI environment is detected). Takes precedence over every other
+     * range source, including CI variables — see `planDiffRange`. The 16 checks that
+     * are about a diff by definition (PR Size, Diff Security, Merge Conflict, …) gate
+     * their own `applies` on `baseSha`, so they drop out of the report rather than
+     * misreporting.
+     */
+    full?: boolean;
+}
+export interface CheckReport {
+    results: CheckResult[];
+    summary: {
+        passed: number;
+        warned: number;
+        failed: number;
+        skipped: number;
+    };
+    /** True when no check failed (warnings/skips do not affect it). */
+    ok: boolean;
+}
+/** Outcome constructors — keep check bodies terse. */
+export declare const pass: (details?: string) => CheckOutcome;
+export declare const warn: (details: string) => CheckOutcome;
+export declare const fail: (details: string) => CheckOutcome;
+export declare const skip: (details: string) => CheckOutcome;
+/**
+ * Whether this repository is an npm project — the gate for every check that reads
+ * the npm dependency tree (NPM Audit, Dependencies, License Check, Outdated Deps).
+ *
+ * A `package.json` on its own is not the answer, and this is the one predicate
+ * where that matters most: installing pr-checkmate as a devDependency *creates*
+ * that file. Gate on it alone and a Python service gets four rows auditing the
+ * dependency tree of the tool auditing it — `npm audit` over our own transitive
+ * packages, licences of our own `node_modules`, "outdated" versions of tooling
+ * the team never chose. All four are unactionable by construction: nothing in the
+ * repository's own code can change any of them.
+ *
+ * So both halves must hold — a manifest to read, and JavaScript or TypeScript
+ * actually written here. A polyglot repository (a Django backend with a JS
+ * frontend) satisfies both and keeps every check; a Python repository whose only
+ * `package.json` is the one that installed us satisfies neither.
+ */
+export declare function isNpmProject(ctx: CheckContext): boolean;
+/**
+ * Identity helper for authoring a `Check` with full type inference and checking.
+ * Purely ergonomic — `defineCheck({ ... })` is equivalent to `{ ... } satisfies Check`.
+ */
+export declare const defineCheck: (check: Check) => Check;

package/dist/esm/core/types.js

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export const PHASES = ['blocking', 'informational', 'format'];
+/** Outcome constructors — keep check bodies terse. */
+export const pass = (details) => ({
+    status: 'pass',
+    ...(details ? { details } : {}),
+});
+export const warn = (details) => ({ status: 'warn', details });
+export const fail = (details) => ({ status: 'fail', details });
+export const skip = (details) => ({ status: 'skip', details });
+/**
+ * Whether this repository is an npm project — the gate for every check that reads
+ * the npm dependency tree (NPM Audit, Dependencies, License Check, Outdated Deps).
+ *
+ * A `package.json` on its own is not the answer, and this is the one predicate
+ * where that matters most: installing pr-checkmate as a devDependency *creates*
+ * that file. Gate on it alone and a Python service gets four rows auditing the
+ * dependency tree of the tool auditing it — `npm audit` over our own transitive
+ * packages, licences of our own `node_modules`, "outdated" versions of tooling
+ * the team never chose. All four are unactionable by construction: nothing in the
+ * repository's own code can change any of them.
+ *
+ * So both halves must hold — a manifest to read, and JavaScript or TypeScript
+ * actually written here. A polyglot repository (a Django backend with a JS
+ * frontend) satisfies both and keeps every check; a Python repository whose only
+ * `package.json` is the one that installed us satisfies neither.
+ */
+export function isNpmProject(ctx) {
+    if (!ctx.languages.includes('javascript') && !ctx.languages.includes('typescript'))
+        return false;
+    return fs.existsSync(path.join(ctx.cwd, 'package.json'));
+}
+/**
+ * Identity helper for authoring a `Check` with full type inference and checking.
+ * Purely ergonomic — `defineCheck({ ... })` is equivalent to `{ ... } satisfies Check`.
+ */
+export const defineCheck = (check) => check;

package/dist/esm/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * PR CheckMate — automated PR quality checks.
+ *
+ * @module pr-checkmate
+ */
+export { runChecks, buildContext, REGISTRY } from './core/index.js';
+export { pass, warn, fail, skip, defineCheck } from './core/index.js';
+export type { Check, CheckContext, CheckOutcome, CheckReport, CheckResult, CheckStatus, Language, Phase, ReporterFn, ReporterKind, RunOptions, } from './core/index.js';
+export { getSourcePath, getSourcePaths, getIgnoredDirs, getPackageConfigPath, hasLocalConfig, } from './config/index.js';
+export type { PRCheckMateConfig } from './interfaces/index.js';
+export { Logger } from './utils/logger.js';
+export type { LogLevel } from './utils/logger.js';

package/dist/esm/index.js

@@ -0,0 +1,15 @@
+/**
+ * PR CheckMate — automated PR quality checks.
+ *
+ * @module pr-checkmate
+ */
+// Primary programmatic API: run checks and receive a structured report.
+// Never throws for violations, never calls process.exit — the caller decides.
+export { runChecks, buildContext, REGISTRY } from './core/index.js';
+// Authoring helpers for consumers writing their own checks (plugins).
+export { pass, warn, fail, skip, defineCheck } from './core/index.js';
+// Config helpers for consumers embedding pr-checkmate.
+export { getSourcePath, getSourcePaths, getIgnoredDirs, getPackageConfigPath, hasLocalConfig, } from './config/index.js';
+// Standalone logging utility. Consumers instantiate their own Logger so their
+// log level and buffer stay independent from pr-checkmate's internal logger.
+export { Logger } from './utils/logger.js';

package/dist/esm/init.d.ts

@@ -0,0 +1,38 @@
+/** How strictly the generated workflow treats a failed run. */
+type GateMode = 'strict' | 'advisory';
+/**
+ * Write the bundled GitHub Actions workflow into the consumer repo.
+ *
+ * Never overwrites an existing file. `init` is not a one-time command — the
+ * update notice asks people to re-run it after every upgrade — so clobbering
+ * would quietly discard whatever they had tuned, including the gate setting they
+ * were just asked about.
+ */
+export declare function setupWorkflow(root: string, mode: GateMode): void;
+/**
+ * Every check that fails the run out of the box, written into the generated
+ * config at its real default.
+ *
+ * Not a copy of a default for its own sake — this one is the gate's teeth, and
+ * the client is entitled to see which checks can stop their merge without
+ * reading our source or discovering it from a red pipeline. Written as `"error"`
+ * so the edit is in place: change the value, or delete the line to inherit
+ * whatever we ship next.
+ *
+ * Two things are deliberately absent. `Custom Rules` and `Banned Imports` can
+ * block too, but only for rules the client writes themselves, so listing them
+ * would suggest a gate that is inert until they act. And `Dockerfile Security`
+ * looks like it belongs here and does not: every one of its patterns is rated
+ * `warn`, so it never fails on its own.
+ *
+ * Keep in step with the checks' own defaults — `blocking-checks.test.ts` pins
+ * every name here to the registry, which catches a rename but not a change of
+ * heart about what should block.
+ */
+export declare const BLOCKING_BY_DEFAULT: readonly ["Security Scan", "Sensitive Files", "Diff Security", "Workflow Security", "Merge Conflict", "NPM Audit", "License Check", "Dependencies", "TypeScript", "ESLint", "YAML Lint"];
+export declare function buildInitialConfig(sourcePath: string, languages: string[]): Record<string, unknown>;
+/**
+ * Initialize (or refresh) pr-checkmate configuration in the current project.
+ */
+export declare function init(): Promise<void>;
+export {};