pr-checkmate 1.22.0 → 1.22.2

package/README.md

@@ -1,9 +1,7 @@
 # ♟️ PR CheckMate
 
 ![Build](https://img.shields.io/github/actions/workflow/status/Mybono/sdk_automation/publish.yml?branch=main&label=CI&color=blue)
-![npm](https://img.shields.io/npm/v/pr-checkmate?color=blue&label=npm)
 ![License](https://img.shields.io/badge/license-Proprietary-lightgrey)
-
 ![ESLint](https://img.shields.io/badge/ESLint-10-4B32C3?logo=eslint&logoColor=white)
 ![Prettier](https://img.shields.io/badge/Prettier-3-F7B93E?logo=prettier&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-6-3178C6?logo=typescript&logoColor=white)

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/config/config.d.ts

@@ -0,0 +1,2 @@
+export declare const config: any;
+export declare const SOURCE_PATH: any;

package/dist/config/constants.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Common patterns to ignore in all checks
+ */
+export declare const IGNORE_PATTERNS: string[];
+export declare const CONFIG_FILE_PATTERNS: string[];
+/**
+ * File extensions to check
+ */
+export declare const SOURCE_EXTENSIONS: {
+    typescript: string[];
+    javascript: string[];
+    markdown: string[];
+    json: string[];
+    all: string[];
+};
+export declare const DEFAULT_COMMANDS: {
+    'npx pr-checkmate init': string;
+    'npx pr-checkmate all': string;
+    'npx pr-checkmate lint': string;
+    'npx pr-checkmate prettier': string;
+    'npx pr-checkmate deps': string;
+    'npx pr-checkmate npm-audit': string;
+    'npx pr-checkmate security': string;
+    'npx pr-checkmate spellcheck': string;
+    'npx pr-checkmate typecheck': string;
+    'npx pr-checkmate diff-smell': string;
+    'npx pr-checkmate pr-body': string;
+    'npx pr-checkmate duplicate': string;
+};
+/**
+ * Packages allow-listed for the license check by default.
+ *
+ * These are pr-checkmate's own bundled cspell dictionaries. Some ship under
+ * copyleft licenses (GPL/LGPL), but they are pr-checkmate dependencies — not
+ * the consumer's — so clients should never have to allow-list them manually.
+ */
+export declare const DEFAULT_ALLOW_PACKAGES: string[];
+export declare const documentation: {
+    eslint: string;
+    typescriptEslint: string;
+    prettier: string;
+    cspell: string;
+};
+export declare const CONFIG_FILE: string;

package/dist/config/index.d.ts

@@ -0,0 +1,23 @@
+export * from './constants';
+export { loadProjectConfig } from '../config/loader';
+/**
+ * Get SOURCE_PATH dynamically
+ * This ensures fresh config is always read
+ */
+export declare function getSourcePath(): 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[]): boolean;
+/**
+ * For backward compatibility, also export as constant
+ * But this will be evaluated at module load time
+ */
+export declare const config: {
+    sourcePath: string;
+};
+export declare const SOURCE_PATH: string;

package/dist/config/loader.d.ts

@@ -0,0 +1,14 @@
+import { PRCheckMateConfig } from '../interfaces';
+/**
+ * Load project configuration from pr-checkmate.json
+ * Falls back to defaults if not found
+ */
+export declare function loadProjectConfig(): PRCheckMateConfig;
+/**
+ * Get default configuration
+ */
+export declare function getDefaultConfig(): PRCheckMateConfig;
+/**
+ * Export config for external use
+ */
+export declare const DEFAULT_CONFIG: PRCheckMateConfig;

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

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

package/dist/core/checks/commitlint.d.ts

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

package/dist/core/checks/cpp-format.d.ts

@@ -0,0 +1,7 @@
+import { Check } from '../types';
+/**
+ * Formats C/C++ code with clang-format, bundled as a self-contained WASM CLI
+ * (`@wasm-fmt/clang-format`) so it runs on a bare Node image with no system
+ * clang install. Read-only in check mode; rewrites files in place when `write`.
+ */
+export declare const cppFormatCheck: Check;

package/dist/core/checks/dead-code.d.ts

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

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

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

package/dist/core/checks/diff-security.d.ts

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

package/dist/core/checks/diff-smell.d.ts

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

package/dist/core/checks/duplicate-check.d.ts

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

package/dist/core/checks/findings.d.ts

@@ -0,0 +1,40 @@
+import { CheckContext, CheckOutcome } from '../types';
+/** Findings grouped by label → matching sample strings. */
+export type FindingBucket = Record<string, string[]>;
+/**
+ * Run `git diff` over the given file globs, returning the raw unified diff
+ * (zero context, added/copied/modified/renamed files) for added-line scanning.
+ */
+export declare function diffAddedLines(ctx: CheckContext, globs: string[]): Promise<string>;
+/** Total number of findings across all labels in a bucket. */
+export declare function bucketTotal(bucket: FindingBucket): number;
+interface LogOptions {
+    /** Log prefix, e.g. 'Diff Security'. */
+    prefix: string;
+    /** Use logger.error + ❌ instead of logger.warn + ⚠️. */
+    isError?: boolean;
+    /** Append ": N occurrence(s)" after the label (default true). */
+    showCount?: boolean;
+    /** Max samples printed per label; omit to print all. */
+    sampleLimit?: number;
+}
+/** Log one bucket of findings using the shared check format. */
+export declare function logFindings(bucket: FindingBucket, opts: LogOptions): void;
+interface SeverityReportOptions {
+    /** Log prefix, e.g. 'Diff Security'. */
+    prefix: string;
+    /** Summary phrasing given the error count. */
+    errorSummary: (n: number) => string;
+    /** Summary phrasing given the warning count. */
+    warningSummary: (n: number) => string;
+    /** Append ": N occurrence(s)" after each label (default true). */
+    showCount?: boolean;
+    /** Max samples printed per label; omit to print all. */
+    sampleLimit?: number;
+}
+/**
+ * Report error/warning finding buckets: log both, then produce the outcome.
+ * Returns pass() when both buckets are empty, otherwise warn() with a summary.
+ */
+export declare function reportSeverityBuckets(errors: FindingBucket, warnings: FindingBucket, opts: SeverityReportOptions): CheckOutcome;
+export {};

package/dist/core/checks/kotlin-lint.d.ts

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

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

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

package/dist/core/checks/lint.d.ts

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

package/dist/core/checks/markdown-lint.d.ts

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

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

@@ -0,0 +1,6 @@
+import { Check } from '../types';
+/**
+ * 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/core/checks/outdated-deps.d.ts

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

package/dist/core/checks/pr-body.d.ts

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

package/dist/core/checks/pr-size-check.d.ts

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

package/dist/core/checks/pr-title-lint.d.ts

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

package/dist/core/checks/prettier.d.ts

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

package/dist/core/checks/python-format.d.ts

@@ -0,0 +1,7 @@
+import { Check } from '../types';
+/**
+ * Formats changed Python files with Ruff's formatter (WASM, no Python/pip needed).
+ * Read-only in check mode (`warn` when files differ from formatted output); rewrites
+ * files in place when `write` so CI can auto-commit — mirrors the Prettier/C++ checks.
+ */
+export declare const pythonFormatCheck: Check;

package/dist/core/checks/python-lint.d.ts

@@ -0,0 +1,9 @@
+import { Check } from '../types';
+/**
+ * Lints changed Python files with Ruff, bundled as a self-contained WASM module
+ * (`@astral-sh/ruff-wasm-nodejs`) so it runs on a bare Node image with no Python
+ * or pip install. Informational by design — reports issues without failing the
+ * build, matching how formatting checks roll out; promote to blocking per repo
+ * once teams have adopted it. Uses Ruff's default rule set (pyflakes + pycodestyle).
+ */
+export declare const pythonLintCheck: Check;

package/dist/core/checks/security.d.ts

@@ -0,0 +1,7 @@
+import { Check } from '../types';
+/**
+ * Secret scanning via the bundled gitleaks package. Language-agnostic — runs on
+ * every repo (Node, Python, C++, mobile). Secrets found → fail (blocking).
+ * Tooling/infra errors → warn, so a scanner hiccup never blocks an unrelated PR.
+ */
+export declare const securityCheck: Check;

package/dist/core/checks/sensitive-file-guard.d.ts

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

package/dist/core/checks/spellcheck.d.ts

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

package/dist/core/checks/swift-lint.d.ts

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

package/dist/core/checks/typecheck.d.ts

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

package/dist/core/checks/typecheck.js

@@ -32,6 +32,15 @@ exports.typecheckCheck = {
         return node_fs_1.default.existsSync(node_path_1.default.join(ctx.cwd, 'tsconfig.json'));
     },
     async run(ctx) {
+        // tsc needs the project's installed type declarations — everything listed in
+        // tsconfig's `types`, plus every imported @types package — to resolve. When the
+        // project's dependencies aren't installed (e.g. a CI step that runs pr-checkmate
+        // via npx without a prior `npm ci`), tsc emits a wall of cryptic TS2688
+        // "cannot find type definition file" errors that look like code problems but are
+        // really a setup gap. Skip with an actionable message instead of failing the PR.
+        if (!node_fs_1.default.existsSync(node_path_1.default.join(ctx.cwd, 'node_modules'))) {
+            return (0, types_1.skip)('project dependencies not installed (no node_modules) — run `npm ci` before typecheck');
+        }
         const tscBin = resolveTsc(ctx.cwd);
         const result = await (0, execa_1.execa)(process.execPath, [tscBin, '--noEmit'], {
             cwd: ctx.cwd,

package/dist/core/context.d.ts

@@ -0,0 +1,6 @@
+import type { CheckContext, RunOptions } from './types';
+/**
+ * Assemble the shared CheckContext once per run. Language detection is skipped
+ * when the caller supplies `languages` (e.g. PRValidator passes its ProjectType).
+ */
+export declare function buildContext(opts?: RunOptions): Promise<CheckContext>;

package/dist/core/index.d.ts

@@ -0,0 +1,4 @@
+export { runChecks } from './run-checks';
+export { buildContext } from './context';
+export { REGISTRY } from './registry';
+export * from './types';

package/dist/core/registry.d.ts

@@ -0,0 +1,6 @@
+import { Check } from './types';
+/**
+ * Every check, in declaration order. The orchestrator groups them by `phase`
+ * (blocking → informational → format) and runs each phase's checks in parallel.
+ */
+export declare const REGISTRY: Check[];

package/dist/core/reporters.d.ts

@@ -0,0 +1,7 @@
+import type { CheckReport, CheckResult } from './types';
+/**
+ * Emit the report through the selected channel.
+ * none: nothing · stdout: console table · github: table + upsert PR comment.
+ */
+export declare function report(kind: 'none' | 'stdout' | 'github', result: CheckReport): Promise<void>;
+export type { CheckResult };

package/dist/core/run-checks.d.ts

@@ -0,0 +1,9 @@
+import { CheckReport, RunOptions } from './types';
+/**
+ * Run all applicable checks and return a structured report.
+ *
+ * Never throws for check violations and never calls `process.exit` — callers
+ * (CLI, PRValidator) decide what a failure means. Phases run in order; checks
+ * within a phase run in parallel.
+ */
+export declare function runChecks(opts?: RunOptions): Promise<CheckReport>;

package/dist/core/run-checks.js

@@ -7,7 +7,35 @@ const context_1 = require("./context");
 const registry_1 = require("./registry");
 const reporters_1 = require("./reporters");
 const types_1 = require("./types");
-/** Apply only/skip filters to the registry. */
+/**
+ * Resolve which checks to run: the built-in registry, custom `opts.checks`, or a mix.
+ * - no custom checks → the built-in registry
+ * - `extendRegistry !== false` → registry + custom (a custom check overrides a
+ *   built-in one sharing its name)
+ * - `extendRegistry === false` → only the provided custom checks
+ */
+function resolveChecks(opts) {
+    const custom = opts.checks ?? [];
+    if (opts.extendRegistry === false)
+        return custom;
+    if (custom.length === 0)
+        return registry_1.REGISTRY;
+    const byName = new Map();
+    for (const c of registry_1.REGISTRY)
+        byName.set(c.name, c);
+    for (const c of custom)
+        byName.set(c.name, c); // custom wins on name clash
+    return [...byName.values()];
+}
+/** Emit the report via a preset channel or a custom reporter function. */
+async function emitReport(reporter, result) {
+    if (typeof reporter === 'function') {
+        await reporter(result);
+        return;
+    }
+    await (0, reporters_1.report)(reporter ?? 'stdout', result);
+}
+/** Apply only/skip filters to the resolved check set. */
 function selectChecks(checks, opts) {
     const only = opts.only && opts.only.length > 0 ? new Set(opts.only) : null;
     const skip = new Set(opts.skip ?? []);
@@ -49,7 +77,7 @@ async function runOne(check, ctx, collector) {
  */
 async function runChecks(opts = {}) {
     const ctx = await (0, context_1.buildContext)(opts);
-    const selected = selectChecks(registry_1.REGISTRY, opts);
+    const selected = selectChecks(resolveChecks(opts), opts);
     const collector = new result_collector_1.ResultCollector();
     for (const phase of types_1.PHASES) {
         const inPhase = selected.filter(c => c.phase === phase);
@@ -61,6 +89,6 @@ async function runChecks(opts = {}) {
         summary,
         ok: summary.failed === 0,
     };
-    await (0, reporters_1.report)(opts.reporter ?? 'stdout', result);
+    await emitReport(opts.reporter, result);
     return result;
 }

package/dist/core/targets.d.ts

@@ -0,0 +1,11 @@
+import type { CheckContext } from './types';
+/**
+ * Lists the files a language check should operate on, matched by pathspec `globs`
+ * (e.g. `['*.py']`). Uses the PR diff range when available (delta mode), else
+ * scans all tracked files. Returns an empty array when nothing matches, and
+ * `null` when git itself is unusable (caller should `skip`).
+ *
+ * Only ACMR files are returned (Added/Copied/Modified/Renamed) — deletions are
+ * excluded, so every returned path exists on disk and is safe to read.
+ */
+export declare function resolveTargetFiles(ctx: CheckContext, globs: string[]): Promise<string[] | null>;

package/dist/core/types.d.ts

@@ -0,0 +1,102 @@
+import type { PRCheckMateConfig } from '../interfaces';
+import type { Language } from '../utils/detect-language';
+import type { CheckResult, CheckStatus } from '../utils/result-collector';
+export type { CheckResult, CheckStatus, Language };
+/**
+ * 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[];
+/**
+ * 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[];
+    /** 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;
+}
+/** 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;
+    applies(ctx: CheckContext): boolean | Promise<boolean>;
+    run(ctx: CheckContext): Promise<CheckOutcome>;
+}
+export type ReporterKind = 'none' | 'stdout' | 'github';
+/** Custom reporter: receives the final report to emit however the consumer wants. */
+export type ReporterFn = (report: CheckReport) => void | Promise<void>;
+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;
+}
+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;
+/**
+ * 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/core/types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.skip = exports.fail = exports.warn = exports.pass = exports.PHASES = void 0;
+exports.defineCheck = exports.skip = exports.fail = exports.warn = exports.pass = exports.PHASES = void 0;
 exports.PHASES = ['blocking', 'informational', 'format'];
 /** Outcome constructors — keep check bodies terse. */
 const pass = (details) => ({
@@ -14,3 +14,9 @@ const fail = (details) => ({ status: 'fail', details });
 exports.fail = fail;
 const skip = (details) => ({ status: 'skip', details });
 exports.skip = skip;
+/**
+ * Identity helper for authoring a `Check` with full type inference and checking.
+ * Purely ergonomic — `defineCheck({ ... })` is equivalent to `{ ... } satisfies Check`.
+ */
+const defineCheck = (check) => check;
+exports.defineCheck = defineCheck;

package/dist/index.d.ts

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

package/dist/index.js

@@ -5,13 +5,20 @@
  * @module pr-checkmate
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hasLocalConfig = exports.getPackageConfigPath = exports.getSourcePath = exports.REGISTRY = exports.buildContext = exports.runChecks = void 0;
+exports.hasLocalConfig = exports.getPackageConfigPath = exports.getSourcePath = exports.defineCheck = exports.skip = exports.fail = exports.warn = exports.pass = exports.REGISTRY = exports.buildContext = exports.runChecks = void 0;
 // Primary programmatic API: run checks and receive a structured report.
 // Never throws for violations, never calls process.exit — the caller decides.
 var core_1 = require("./core");
 Object.defineProperty(exports, "runChecks", { enumerable: true, get: function () { return core_1.runChecks; } });
 Object.defineProperty(exports, "buildContext", { enumerable: true, get: function () { return core_1.buildContext; } });
 Object.defineProperty(exports, "REGISTRY", { enumerable: true, get: function () { return core_1.REGISTRY; } });
+// Authoring helpers for consumers writing their own checks (plugins).
+var core_2 = require("./core");
+Object.defineProperty(exports, "pass", { enumerable: true, get: function () { return core_2.pass; } });
+Object.defineProperty(exports, "warn", { enumerable: true, get: function () { return core_2.warn; } });
+Object.defineProperty(exports, "fail", { enumerable: true, get: function () { return core_2.fail; } });
+Object.defineProperty(exports, "skip", { enumerable: true, get: function () { return core_2.skip; } });
+Object.defineProperty(exports, "defineCheck", { enumerable: true, get: function () { return core_2.defineCheck; } });
 // Config helpers for consumers embedding pr-checkmate.
 var config_1 = require("./config");
 Object.defineProperty(exports, "getSourcePath", { enumerable: true, get: function () { return config_1.getSourcePath; } });

package/dist/init.d.ts

@@ -0,0 +1,5 @@
+export declare const CONFIG_FILE: string;
+/**
+ * Initialize (or refresh) pr-checkmate configuration in the current project.
+ */
+export declare function init(): Promise<void>;

package/dist/init.js

@@ -19,7 +19,11 @@ const DEFAULT_CONFIG = {
     commands: config_1.DEFAULT_COMMANDS,
     // ESLint customization
     eslint: {
-        rules: {},
+        rules: {
+            // Off by default: its `--fix` injects empty `/** */` JSDoc stubs into
+            // client source files. Set to 'warn'/'error' to opt into doc enforcement.
+            'jsdoc/require-jsdoc': 'off',
+        },
         ignorePatterns: [],
     },
     // Prettier customization

package/dist/interfaces/index.d.ts

@@ -0,0 +1,129 @@
+import type { Language } from '../utils/detect-language';
+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[];
+}
+export interface PRCheckMateConfig {
+    sourcePath: string;
+    languages?: Language[];
+    lint?: {
+        rules?: Record<string, any>;
+        ignorePatterns?: string[];
+    };
+    prettier?: {
+        config?: Record<string, any>;
+    };
+    spellcheck?: {
+        words?: string[];
+        ignoreWords?: string[];
+        ignorePaths?: string[];
+    };
+    security?: {
+        gitleaks?: {
+            enabled: boolean;
+        };
+        'npm-audit'?: {
+            enabled: boolean;
+            auditLevel: string;
+        };
+    };
+    typecheck?: {
+        enabled?: boolean;
+    };
+    cpp?: {
+        enabled?: boolean;
+        clangFormat?: {
+            style?: string;
+        };
+    };
+    python?: {
+        enabled?: boolean;
+        ruff?: {
+            lint?: boolean;
+            format?: boolean;
+        };
+    };
+    diffSmell?: {
+        enabled?: boolean;
+    };
+    prBody?: {
+        enabled?: boolean;
+        minLength?: number;
+        requireTicket?: boolean;
+    };
+    duplicate?: {
+        enabled?: boolean;
+        minLines?: number;
+        minTokens?: number;
+    };
+    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;
+    };
+    sensitiveFileGuard?: {
+        enabled?: boolean;
+    };
+    swift?: {
+        enabled?: boolean;
+    };
+    kotlin?: {
+        enabled?: boolean;
+    };
+    deadCode?: {
+        enabled?: boolean;
+    };
+    licenseCheck?: {
+        allowPackages?: string[];
+        allowLicenses?: string[];
+    };
+}
+export interface CheckmateConfig {
+    skipLint?: boolean;
+    skipDeps?: boolean;
+    skipFormat?: boolean;
+    skipSpell?: boolean;
+    skipSecurity?: boolean;
+    skipNpmAudit?: boolean;
+    skipCircularDeps?: boolean;
+    skipLicense?: boolean;
+    skipPrSize?: boolean;
+    skipPrTitle?: boolean;
+    skipOutdated?: boolean;
+    skipMarkdown?: boolean;
+    skipTypecheck?: boolean;
+    skipDiffSmell?: boolean;
+    skipPrBody?: boolean;
+    skipDuplicate?: boolean;
+    skipDiffSecurity?: boolean;
+    skipSensitiveFiles?: boolean;
+    skipDeadCode?: boolean;
+    autoCommit?: boolean;
+}
+export type { CheckStatus, CheckResult } from '../utils/result-collector';
+export type { Language } from '../utils/detect-language';

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

@@ -0,0 +1,5 @@
+/**
+ *
+ */
+declare function copyConfigs(): void;
+export { copyConfigs };

package/dist/scripts/publish-github.d.ts

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

package/dist/utils/delta.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Returns list of changed files in the current PR filtered by extension.
+ * Returns null when not in a GitHub PR context (falls back to full-project scan).
+ */
+export declare function getChangedFiles(extensions: string[]): Promise<string[] | null>;

package/dist/utils/detect-language.d.ts

@@ -0,0 +1,10 @@
+export type Language = 'typescript' | 'javascript' | 'python' | 'cpp' | 'swift' | 'kotlin';
+/**
+ * Detects which languages a repository uses, combining marker files (definitive)
+ * with tracked source-file counts (breadth). A language is reported when it has a
+ * marker file OR at least one tracked source file.
+ *
+ * @returns languages ordered by tracked file count (most-used first). `.h` headers
+ *   are intentionally excluded from the C++ count since they are ambiguous with C.
+ */
+export declare function detectLanguages(root?: string): Promise<Language[]>;

package/dist/utils/index.d.ts

@@ -0,0 +1,10 @@
+export * from './logger';
+export * from './delta';
+export * from './result-collector';
+export * from './resolve-bin';
+export * from './own-deps';
+export * from './detect-language';
+/**
+ *
+ */
+export declare function cleanupTempFile(filePath: string): void;

package/dist/utils/logger.d.ts

@@ -0,0 +1,20 @@
+type LogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
+declare class Logger {
+    private logs;
+    private levelOrder;
+    private currentLevel;
+    private getTimestamp;
+    private shouldLog;
+    private colorize;
+    private logMessage;
+    log(msg: string): void;
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string, err?: unknown): void;
+    debug(msg: string): void;
+    getLogs(): string[];
+    setLevel(level: LogLevel): void;
+    clear(): void;
+}
+export declare const logger: Logger;
+export {};

package/dist/utils/own-deps.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Compute the full set of package names in pr-checkmate's own dependency
+ * closure (direct + transitive runtime dependencies), plus pr-checkmate itself.
+ *
+ * pr-checkmate installs into the consumer's node_modules, so its own runtime
+ * deps (eslint plugins, cspell dictionaries, …) become part of the consumer's
+ * production dependency tree. Some carry copyleft licenses that would otherwise
+ * trip pr-checkmate's own license check against an innocent client. These are
+ * pr-checkmate's dependencies, not the client's, so they must be exempt.
+ *
+ * Result is cached for the process. Returns a set containing only pr-checkmate
+ * itself if the package root cannot be located (defensive; never throws).
+ */
+export declare function getOwnDependencyClosure(): Set<string>;

package/dist/utils/resolve-bin.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Resolves a binary path for a bundled package, bypassing exports map restrictions.
+ *
+ * Strategy (tries each in order):
+ * 1. Direct subpath — fast path for packages that explicitly export their bin
+ * 2. Via package.json — for packages that export ./package.json but not the bin subpath (e.g. eslint)
+ * 3. Walk up from main entry — for packages that export neither (e.g. cspell)
+ *
+ * @param pkgName - The package whose binary to resolve (e.g. `eslint`).
+ * @param binRelPath - The bin path relative to the package root (e.g. `bin/eslint.js`).
+ * @param options - Resolution options.
+ * @param options.paths - Directories to resolve from (passed to `require.resolve`).
+ *   Use `[process.cwd()]` to prefer the consumer project's copy of the package.
+ */
+export declare function resolvePackageBin(pkgName: string, binRelPath: string, options?: {
+    paths?: string[];
+}): string;

package/dist/utils/result-collector.d.ts

@@ -0,0 +1,33 @@
+export type CheckStatus = 'pass' | 'warn' | 'fail' | 'skip';
+export interface CheckResult {
+    name: string;
+    status: CheckStatus;
+    details?: string;
+}
+/**
+ *
+ */
+export declare class ResultCollector {
+    private results;
+    /**
+     *
+     */
+    register(name: string, status: CheckStatus, details?: string): void;
+    /**
+     *
+     */
+    getResults(): CheckResult[];
+    /**
+     *
+     */
+    clear(): void;
+    /**
+     *
+     */
+    getSummary(): {
+        passed: number;
+        warned: number;
+        failed: number;
+        skipped: number;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pr-checkmate",
-    "version": "1.22.0",
+    "version": "1.22.2",
     "description": "Automated PR quality checks: linting, formatting, dependency analysis, and spellcheck",
     "keywords": [
         "github-actions",
@@ -11,11 +11,19 @@
         "code-quality",
         "automation"
     ],
-    "main": "./dist/cli.js",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
     "type": "commonjs",
     "bin": {
         "pr-checkmate": "dist/cli.js"
     },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
     "files": [
         "dist",
         "README.md",