@rmartz/pr-policy 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,276 @@
+/**
+ * One changed file's text on both sides of the pull request. An absent side
+ * means the PR added (no `baseText`) or deleted (no `headText`) the file.
+ */
+interface FileChange {
+    /** Repo-relative path at head (or at base, for a deletion). */
+    path: string;
+    /** Content at the merge base — not the base tip, so others' merges don't count. */
+    baseText?: string;
+    /** Content at the PR head. */
+    headText?: string;
+}
+/**
+ * The facts about a pull request that policy checks judge. Every field is a
+ * property of the PR's own content — never its review history, which belongs to
+ * the separate lifecycle reconciler (rmartz/ai-tools#306).
+ */
+interface PullRequestFacts {
+    title: string;
+    labels: readonly string[];
+    changedFiles: readonly string[];
+    /** Both sides of every changed `.github/workflows/**` file. */
+    workflowChanges: readonly FileChange[];
+    /** Both sides of every changed dependency manifest (`package.json`, `requirements*.txt`). */
+    manifestChanges: readonly FileChange[];
+}
+/**
+ * What a finding does to the `pr-policy` check-run:
+ *
+ * - `block` — red (`failure`). The author can fix it (a title edit, a code
+ *   change), so it reads correctly as "this PR has a problem".
+ * - `hold` — pending (`in_progress`). Nothing is broken; the PR is waiting on a
+ *   human act, such as applying a sign-off label. Posting it red would read as a
+ *   broken build and invite a fix pass that cannot clear it.
+ * - `info` — listed in the summary, never gates.
+ */
+declare const FINDING_EFFECTS: readonly ["block", "hold", "info"];
+type FindingEffect = (typeof FINDING_EFFECTS)[number];
+/** One policy observation, attributed to the check that produced it. */
+interface Finding {
+    check: string;
+    message: string;
+    effect: FindingEffect;
+    /**
+     * A short line that can stand as the check-run title when nothing gates —
+     * e.g. "CI loosening signed off". The first headline wins.
+     */
+    headline?: boolean;
+}
+/**
+ * What one check reports: its findings, plus edits to labels it owns outright.
+ * A check never lists a label someone else owns.
+ */
+interface CheckResult {
+    findings: readonly Finding[];
+    labelsToAdd?: readonly string[];
+    labelsToRemove?: readonly string[];
+}
+/**
+ * A read-only classifier. It reports and plans label edits; the caller applies
+ * them. It never mutates the PR itself.
+ */
+interface PolicyCheck {
+    name: string;
+    evaluate(pr: PullRequestFacts): Promise<CheckResult>;
+}
+
+/**
+ * Every registered policy check, in report order. Each check lives in its own
+ * module under src/checks/ and is added here; all of them report into the single
+ * `pr-policy` check-run. See docs/adding-a-check.md.
+ */
+declare const CHECKS: readonly PolicyCheck[];
+
+/**
+ * The indicator vocabulary — the classifier's whole output surface.
+ *
+ * Each indicator names one recognised change to a workflow document and the
+ * class it falls in. The two classes are asymmetric on purpose: `loosening` is a
+ * change the CI directive requires a human to sign off, and `ambiguous` is a
+ * change the directive says to *treat as* a loosening because it cannot be shown
+ * to be benign. Both produce the same verdict; they are kept apart so the
+ * check-run output can tell a reader which it saw.
+ */
+/** Changes that reduce CI coverage outright (review.md Step 5, "loosening indicators"). */
+declare const LOOSENING_INDICATORS: readonly ["workflow-removed", "job-removed", "step-removed", "continue-on-error-added", "if-added", "trigger-narrowed", "matrix-reduced", "needs-reduced"];
+/** Changes the directive says to treat as loosening because they are not clearly tightening. */
+declare const AMBIGUOUS_INDICATORS: readonly ["runs-on-changed", "permissions-changed", "env-changed", "timeout-changed", "unparseable", "unclassified-change"];
+type LooseningIndicator = (typeof LOOSENING_INDICATORS)[number];
+type AmbiguousIndicator = (typeof AMBIGUOUS_INDICATORS)[number];
+type IndicatorKind = LooseningIndicator | AmbiguousIndicator;
+/** Which bucket an indicator falls in. Both hold the merge; only the wording differs. */
+type IndicatorClass = 'loosening' | 'ambiguous';
+/** One recognised change, bound to the file and the place in it that produced it. */
+interface Indicator {
+    kind: IndicatorKind;
+    class: IndicatorClass;
+    /** Repo-relative path of the workflow file. */
+    file: string;
+    /** Where in the document — e.g. `jobs.build.steps[install]`, `on.pull_request.branches`. */
+    location: string;
+    /** One human-readable sentence naming what changed. */
+    detail: string;
+}
+/**
+ * The verdict for a whole pull request.
+ *
+ * - `no-change` — the diff touches no CI workflow file. Nothing to report.
+ * - `tightening` — every recognised change adds coverage or is maintenance.
+ * - `loosening` — at least one loosening *or* ambiguous indicator fired, so the
+ *   `CI approval needed` merge gate applies.
+ */
+declare const CI_CHANGE_VERDICTS: readonly ["no-change", "tightening", "loosening"];
+type CiChangeVerdict = (typeof CI_CHANGE_VERDICTS)[number];
+
+/** One workflow file's before/after text. */
+type WorkflowFileChange = FileChange;
+/** The verdict for a pull request, with the evidence that produced it. */
+interface Classification {
+    verdict: CiChangeVerdict;
+    indicators: Indicator[];
+}
+/** Every indicator for a single workflow file. */
+declare function classifyWorkflowFile(change: WorkflowFileChange): Indicator[];
+/** The pull-request-wide verdict across every workflow file it touches. */
+declare function classifyWorkflowChanges(changes: readonly WorkflowFileChange[]): Classification;
+
+declare const CI_CHANGE_CHECK = "ci-change";
+/** Decide the findings and label edits for one classified PR. */
+declare function decideCiChange(classification: Classification, labels: readonly string[]): CheckResult;
+declare const ciChangeCheck: PolicyCheck;
+
+/**
+ * Which files this guard considers "a CI workflow".
+ *
+ * Scoped to `.github/workflows/**` as the CI directive is: those are the files
+ * whose content decides what CI runs. A composite action under
+ * `.github/actions/` can change behaviour too, but it is invoked *by* a workflow
+ * step, so a change there that matters shows up as a step change here — and
+ * widening the scope would make every consuming repo's Action edits carry a
+ * human sign-off gate.
+ */
+declare function isWorkflowPath(path: string): boolean;
+
+declare const TITLE_CHECK = "title";
+/** Every title rule violated by this PR's current title, labels, and diff. */
+declare function decideTitle(pr: PullRequestFacts): CheckResult;
+declare const titleCheck: PolicyCheck;
+
+/**
+ * The Conventional-Commit grammar a squash subject must satisfy. It mirrors the
+ * fleet's `pr-title-lint.yml` and `commit-convention.yml` exactly, so a title
+ * this accepts is one the post-merge tripwire accepts too.
+ */
+declare const COMMIT_TYPES: readonly ["feat", "fix", "docs", "chore", "refactor", "test", "style", "perf", "ci", "build", "revert"];
+type CommitType = (typeof COMMIT_TYPES)[number];
+/**
+ * The only types that may carry `!`. Under semantic-release `!` cuts a major, so
+ * it is reserved for shippable functional change (rmartz/dotfiles#1559).
+ */
+declare const FUNCTIONAL_TYPES: readonly ["feat", "fix", "perf", "revert"];
+interface ParsedTitle {
+    type: CommitType;
+    scope?: string;
+    breaking: boolean;
+    subject: string;
+}
+/** Parse a title, or `null` when it is not a valid Conventional Commit. */
+declare function parseTitle(title: string): ParsedTitle | null;
+
+/**
+ * Detects a version change to a CI-sensitive linter or formatter. A new
+ * black/ruff/prettier/eslint/pylint can change results on files a PR never
+ * touched, so every in-flight PR must re-test against it — which the
+ * coordinator keys off the `ci` type. Comparison is structural: each manifest is
+ * parsed on both sides and the declared versions compared.
+ */
+
+declare const CI_SENSITIVE_PACKAGES: readonly ["eslint", "black", "pylint", "ruff", "prettier"];
+/** Whether a path is a dependency manifest the title check reads. */
+declare function isManifestPath(path: string): boolean;
+/**
+ * The CI-sensitive packages whose declared version changed between the two
+ * sides of any manifest. A package only added or only removed is not a bump.
+ */
+declare function sensitiveBumps(changes: readonly FileChange[]): string[];
+
+/**
+ * Names read outside this repo. Each is a fleet contract: consumers' rulesets
+ * require the check-run by literal name, the coordinator's gate model parks a PR
+ * on the label, and a human applies the sign-off label by hand. Renaming any of
+ * them is a coordinated cross-repo migration, never a local refactor — see
+ * docs/check-run-contract.md. `test/contract.test.ts` pins every value.
+ */
+/**
+ * The one check-run this package posts. Every policy check reports into it, so
+ * adding a check never adds a required-status name.
+ */
+declare const PR_POLICY_CHECK_NAME = "pr-policy";
+/** The merge-gate label the CI-change check applies to an unsigned loosening. */
+declare const CI_APPROVAL_NEEDED_LABEL = "CI approval needed";
+/**
+ * The human sign-off on a CI loosening. Read-only here: this package never
+ * applies it.
+ */
+declare const CI_CHANGE_APPROVED_LABEL = "CI change approved";
+/**
+ * Labels the title check reads and never writes. They belong to the review and
+ * release flow: `breaking change` is the source of truth for a breaking PR,
+ * `hotfix` implies one, and release-please marks its release PRs with
+ * `autorelease: pending`.
+ */
+declare const BREAKING_CHANGE_LABEL = "breaking change";
+declare const HOTFIX_LABEL = "hotfix";
+declare const RELEASE_PLEASE_PENDING_LABEL = "autorelease: pending";
+
+/**
+ * The overall result of one evaluation. `pending` posts the check-run as
+ * `in_progress` (no conclusion), so a PR waiting on a human sign-off shows as
+ * waiting rather than as a failing build; the required check still holds the
+ * merge until a later run completes it.
+ */
+declare const POLICY_OUTCOMES: readonly ["success", "pending", "failure"];
+type PolicyOutcome = (typeof POLICY_OUTCOMES)[number];
+/** The body of the one `pr-policy` check-run. */
+interface CheckRunReport {
+    outcome: PolicyOutcome;
+    title: string;
+    summary: string;
+    findings: readonly Finding[];
+}
+/**
+ * Fold every check's findings into the single check-run. Any `block` finding
+ * makes it `failure`; otherwise any `hold` makes it `pending`; otherwise it is
+ * `success`. A fixable problem outranks a pending sign-off, so the author sees
+ * the thing they can act on.
+ */
+declare function buildReport(findings: readonly Finding[]): CheckRunReport;
+
+/** The one check-run report, plus the label edits the checks planned. */
+interface PolicyEvaluation extends CheckRunReport {
+    labelsToAdd: string[];
+    labelsToRemove: string[];
+}
+/** Run every policy check against one PR and fold the results into one report. */
+declare function evaluatePolicy(pr: PullRequestFacts, checks?: readonly PolicyCheck[]): Promise<PolicyEvaluation>;
+
+/**
+ * Parse and validate a JSON facts document into `PullRequestFacts`.
+ * `workflowChanges` and `manifestChanges` are optional and default to none.
+ */
+declare function parseFacts(raw: string): PullRequestFacts;
+
+interface PullRequestTarget {
+    repo: string;
+    pr: number;
+    cwd?: string;
+}
+/**
+ * Gather everything the checks judge. Workflow files and dependency manifests
+ * are read at the **merge base**, not the base tip, so a change merged into the
+ * base after this PR branched is not attributed to it.
+ */
+declare function gatherFacts(target: PullRequestTarget): Promise<{
+    facts: PullRequestFacts;
+    headSha: string;
+}>;
+/** Apply the label edits the checks planned (labels this package owns). */
+declare function applyLabelEdits(target: PullRequestTarget, evaluation: PolicyEvaluation): Promise<void>;
+
+/** The request body for this evaluation's check-run state. */
+declare function checkRunBody(evaluation: PolicyEvaluation, now: Date): Record<string, unknown>;
+/** Post (or complete) the one `pr-policy` check-run on the head commit. */
+declare function postCheckRun(target: PullRequestTarget, headSha: string, evaluation: PolicyEvaluation): Promise<void>;
+
+export { AMBIGUOUS_INDICATORS, type AmbiguousIndicator, BREAKING_CHANGE_LABEL, CHECKS, CI_APPROVAL_NEEDED_LABEL, CI_CHANGE_APPROVED_LABEL, CI_CHANGE_CHECK, CI_CHANGE_VERDICTS, CI_SENSITIVE_PACKAGES, COMMIT_TYPES, type CheckResult, type CheckRunReport, type CiChangeVerdict, type Classification, type CommitType, FUNCTIONAL_TYPES, type FileChange, type Finding, HOTFIX_LABEL, type Indicator, type IndicatorClass, type IndicatorKind, LOOSENING_INDICATORS, type LooseningIndicator, POLICY_OUTCOMES, PR_POLICY_CHECK_NAME, type ParsedTitle, type PolicyCheck, type PolicyEvaluation, type PolicyOutcome, type PullRequestFacts, type PullRequestTarget, RELEASE_PLEASE_PENDING_LABEL, TITLE_CHECK, type WorkflowFileChange, applyLabelEdits, buildReport, checkRunBody, ciChangeCheck, classifyWorkflowChanges, classifyWorkflowFile, decideCiChange, decideTitle, evaluatePolicy, gatherFacts, isManifestPath, isWorkflowPath, parseFacts, parseTitle, postCheckRun, sensitiveBumps, titleCheck };

package/dist/index.js

@@ -0,0 +1,70 @@
+import {
+  AMBIGUOUS_INDICATORS,
+  BREAKING_CHANGE_LABEL,
+  CHECKS,
+  CI_APPROVAL_NEEDED_LABEL,
+  CI_CHANGE_APPROVED_LABEL,
+  CI_CHANGE_CHECK,
+  CI_CHANGE_VERDICTS,
+  CI_SENSITIVE_PACKAGES,
+  COMMIT_TYPES,
+  FUNCTIONAL_TYPES,
+  HOTFIX_LABEL,
+  LOOSENING_INDICATORS,
+  POLICY_OUTCOMES,
+  PR_POLICY_CHECK_NAME,
+  RELEASE_PLEASE_PENDING_LABEL,
+  TITLE_CHECK,
+  applyLabelEdits,
+  buildReport,
+  checkRunBody,
+  ciChangeCheck,
+  classifyWorkflowChanges,
+  classifyWorkflowFile,
+  decideCiChange,
+  decideTitle,
+  evaluatePolicy,
+  gatherFacts,
+  isManifestPath,
+  isWorkflowPath,
+  parseFacts,
+  parseTitle,
+  postCheckRun,
+  sensitiveBumps,
+  titleCheck
+} from "./chunk-QINHHFJN.js";
+export {
+  AMBIGUOUS_INDICATORS,
+  BREAKING_CHANGE_LABEL,
+  CHECKS,
+  CI_APPROVAL_NEEDED_LABEL,
+  CI_CHANGE_APPROVED_LABEL,
+  CI_CHANGE_CHECK,
+  CI_CHANGE_VERDICTS,
+  CI_SENSITIVE_PACKAGES,
+  COMMIT_TYPES,
+  FUNCTIONAL_TYPES,
+  HOTFIX_LABEL,
+  LOOSENING_INDICATORS,
+  POLICY_OUTCOMES,
+  PR_POLICY_CHECK_NAME,
+  RELEASE_PLEASE_PENDING_LABEL,
+  TITLE_CHECK,
+  applyLabelEdits,
+  buildReport,
+  checkRunBody,
+  ciChangeCheck,
+  classifyWorkflowChanges,
+  classifyWorkflowFile,
+  decideCiChange,
+  decideTitle,
+  evaluatePolicy,
+  gatherFacts,
+  isManifestPath,
+  isWorkflowPath,
+  parseFacts,
+  parseTitle,
+  postCheckRun,
+  sensitiveBumps,
+  titleCheck
+};

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@rmartz/pr-policy",
+  "version": "0.2.0",
+  "description": "Read-only PR content classifiers — CI-change classification, title-type rules, and more — reported as one blocking pr-policy check-run. Distributed as a pinned Action kept current by Dependabot.",
+  "keywords": [
+    "pr-policy",
+    "pull-request",
+    "github-actions",
+    "check-run",
+    "merge-gate",
+    "conventional-commits"
+  ],
+  "homepage": "https://github.com/rmartz/pr-policy#readme",
+  "bugs": {
+    "url": "https://github.com/rmartz/pr-policy/issues"
+  },
+  "type": "module",
+  "packageManager": "pnpm@9.12.0",
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "ai-pr-policy": "./dist/bin/pr-policy.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "@rmartz:registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rmartz/pr-policy.git"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "verify:release-notes": "node scripts/verify-changelog-render.mjs"
+  },
+  "dependencies": {
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@semantic-release/release-notes-generator": "^14.1.1",
+    "@types/node": "^26.6.2",
+    "@typescript-eslint/eslint-plugin": "^8.70.0",
+    "@typescript-eslint/parser": "^8.70.0",
+    "@vitest/coverage-v8": "^5.0.1",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
+    "eslint": "^10.11.0",
+    "eslint-import-resolver-typescript": "^4.4.5",
+    "eslint-plugin-import": "^2.32.0",
+    "prettier": "^3.9.8",
+    "semantic-release": "^25.0.9",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vite": "^8.3.0",
+    "vitest": "^5.0.1"
+  },
+  "pnpm": {
+    "overrides": {
+      "esbuild": ">=0.28.1"
+    }
+  }
+}