pr-checkmate 1.22.2 → 1.22.3

package/README.md

@@ -7,6 +7,7 @@
 ![TypeScript](https://img.shields.io/badge/TypeScript-6-3178C6?logo=typescript&logoColor=white)
 ![cspell](https://img.shields.io/badge/cspell-10-4285F4)
 ![jscpd](https://img.shields.io/badge/jscpd-5-blue)
+[![API Docs](https://img.shields.io/badge/API_docs-TypeDoc-9600FF?logo=readthedocs&logoColor=white)](https://pr-checkmate-docs.pages.dev)
 
 > **PR CheckMate** is a universal PR quality checker that runs as a single `npm install` and works across **TypeScript, JavaScript, Python, C++, Swift, and Android/Kotlin** repositories — no per-language toolchain setup required.
 
@@ -280,6 +281,60 @@ In GitHub Actions PR context, language checks automatically switch to **delta mo
 
 ---
 
+## Programmatic API
+
+Besides the CLI, PR CheckMate ships a typed programmatic API. Install the package and import checks directly — useful for embedding the same quality gates inside your own tooling. The full reference is published at the [API docs site](https://pr-checkmate-docs.pages.dev).
+
+Run the built-in checks:
+
+```ts
+import { runChecks } from 'pr-checkmate';
+import type { CheckReport } from 'pr-checkmate';
+
+const report: CheckReport = await runChecks({
+  cwd: process.cwd(),
+  reporter: 'stdout', // 'none' | 'stdout' | 'github' | (report) => void
+});
+
+if (!report.ok) process.exit(1);
+```
+
+`runChecks` never throws on violations and never calls `process.exit` — the caller decides. `report.ok` is `true` when nothing failed; warnings and skips do not affect it.
+
+Author a custom check:
+
+```ts
+import { runChecks, defineCheck, pass, fail } from 'pr-checkmate';
+
+const noFixmes = defineCheck({
+  name: 'no-fixmes',
+  phase: 'lint',
+  applies: () => true,
+  run: async (ctx) => {
+    // inspect ctx (config, changed files, language, sha range) and return an outcome
+    return pass();
+  },
+});
+
+await runChecks({ checks: [noFixmes] }); // appended to the built-in registry by default
+```
+
+### Key exports
+
+| Export | Purpose |
+|---|---|
+| `runChecks` | Run the check pipeline; returns a structured `CheckReport` |
+| `buildContext` | Build the `CheckContext` (language, config, sha range) checks receive |
+| `REGISTRY` | The array of built-in checks |
+| `defineCheck` | Identity helper for authoring a `Check` with full type inference |
+| `pass` / `warn` / `fail` / `skip` | Outcome constructors for check bodies |
+| `getSourcePath` / `getPackageConfigPath` / `hasLocalConfig` | Config-path helpers |
+| Types | `Check`, `CheckContext`, `CheckReport`, `CheckResult`, `CheckOutcome`, `CheckStatus`, `RunOptions`, `Language`, `Phase`, `ReporterKind`, `ReporterFn`, `PRCheckMateConfig` |
+
+Regenerate the docs locally with `npm run docs` (output in `docs/api`).
+
+---
+
 ## PR Summary Comment
 
 After `npx pr-checkmate all`, a summary table is posted to the PR. On repeated pushes the comment is updated in place — no duplicate comments.

package/dist/index.d.ts

@@ -7,3 +7,4 @@ 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';
+export type { PRCheckMateConfig } from './interfaces';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pr-checkmate",
-    "version": "1.22.2",
+    "version": "1.22.3",
     "description": "Automated PR quality checks: linting, formatting, dependency analysis, and spellcheck",
     "keywords": [
         "github-actions",
@@ -46,6 +46,7 @@
         "lint": "eslint \"src/**/*.{ts,tsx}\" --fix",
         "prettier": "prettier --write \"src/**/*.{ts,tsx,js,jsx,json,md}\"",
         "spellcheck": "cspell '**/*.{ts,tsx,js,jsx,md,json}' --no-progress",
+        "docs": "typedoc",
         "scan:secrets": "gitleaks-secret-scanner --diff-mode ci --html-report gitleaks-report.html",
         "test": "echo 'Tests coming soon'",
         "security-scan": "npx pr-checkmate security",
@@ -99,6 +100,7 @@
         "typescript": "^6.0.3"
     },
     "devDependencies": {
-        "standard-version": "^9.5.0"
+        "standard-version": "^9.5.0",
+        "typedoc": "^0.28.20"
     }
 }