@rmartz/pr-policy 0.2.0 → 0.8.0

package/dist/index.d.ts

@@ -10,19 +10,56 @@ interface FileChange {
     /** Content at the PR head. */
     headText?: string;
 }
+/**
+ * A repository role, fine-grained where GitHub reports one. `none` covers a
+ * non-collaborator and a lookup that failed, so an unknown actor never counts.
+ */
+declare const REPO_PERMISSIONS: readonly ["admin", "maintain", "write", "triage", "read", "none"];
+type RepoPermission = (typeof REPO_PERMISSIONS)[number];
+/** Who last applied a label: the actor on its latest `labeled` event. */
+interface LabelActor {
+    login: string;
+    /** GitHub's actor type: `User`, `Bot`, `Organization`, or `Mannequin`. */
+    type: string;
+    permission: RepoPermission;
+}
+/**
+ * Provenance for one sign-off label on the PR (see `SIGN_OFF_LABELS`).
+ * `appliedBy` is absent when no `labeled` event names a live account.
+ */
+interface SignOff {
+    label: string;
+    appliedBy?: LabelActor;
+}
+/** The account that opened a PR, as GitHub reports it (`dependabot[bot]`, `Bot`). */
+interface PullRequestAuthor {
+    login: string;
+    type: 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).
+ * property of the PR's current state — its content and the labels on it, never
+ * its review history, which belongs to the separate lifecycle reconciler
+ * (rmartz/ai-tools#306).
  */
 interface PullRequestFacts {
     title: string;
+    /**
+     * The PR description. Optional so a facts document without one still parses;
+     * `gatherFacts` always sets it (an empty description is `''`).
+     */
+    body?: string;
+    /** Who opened the PR. `gatherFacts` always sets it. */
+    author?: PullRequestAuthor;
     labels: readonly string[];
+    /** Every path the PR touches, including the old path of a rename. */
     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[];
+    /** Who applied each sign-off label present on the PR. */
+    signOffs: readonly SignOff[];
 }
 /**
  * What a finding does to the `pr-policy` check-run:
@@ -71,6 +108,17 @@ interface PolicyCheck {
  * `pr-policy` check-run. See docs/adding-a-check.md.
  */
 declare const CHECKS: readonly PolicyCheck[];
+/**
+ * How a consuming repo tunes the suite. The caller passes these (a CLI flag, an
+ * Action input), never the PR, so a PR can't switch off a gate it would fail.
+ * Every option defaults to the strictest policy.
+ */
+interface PolicyOptions {
+    /** Drop the UAT gate, for a repo with no user-acceptance testing to wait on. */
+    skipUat?: boolean;
+}
+/** The checks to run for a repo configured with `options`, in report order. */
+declare function selectChecks(options?: PolicyOptions): readonly PolicyCheck[];
 
 /**
  * The indicator vocabulary — the classifier's whole output surface.
@@ -127,9 +175,63 @@ declare function classifyWorkflowChanges(changes: readonly WorkflowFileChange[])
 
 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 function decideCiChange(classification: Classification, pr: Pick<PullRequestFacts, 'labels' | 'signOffs'>): CheckResult;
 declare const ciChangeCheck: PolicyCheck;
 
+/**
+ * Check 4: a Dependabot PR changes only the updates it claims. bot-automerge
+ * merges these PRs without a human review, on the premise that the PR is what
+ * the bot says it is. This check enforces that premise: it reads the claim from
+ * the description and blocks on any change the claim doesn't cover — a stray
+ * path, an unclaimed dependency, a version other than the claimed one, or an
+ * edit Dependabot never makes. A mismatch means someone else pushed to the
+ * branch or edited the body; recreating the PR clears it.
+ *
+ * Applies only to PRs opened by `dependabot[bot]`. See docs/checks/dependabot.md.
+ */
+
+declare const DEPENDABOT_CHECK = "dependabot";
+declare const DEPENDABOT_LOGIN = "dependabot[bot]";
+/** Every way this Dependabot PR's content departs from its claimed updates. */
+declare function decideDependabot(pr: PullRequestFacts): CheckResult;
+declare const dependabotCheck: PolicyCheck;
+
+/**
+ * The updates a Dependabot PR claims, read from its description. The body is
+ * Dependabot's own record: a review agent may retitle the PR (`chore(deps):` →
+ * `ci(deps):`), but nothing rewrites the body. Three sentence forms carry every
+ * claim Dependabot makes, plus a summary table:
+ *
+ * - `Bumps [name](url) from A to B.` — a single update.
+ * - `| [name](url) | `A` | `B` |` — a row of the table a large group opens
+ *   with. Dependabot truncates a long description, cutting off the per-package
+ *   lines, but the table comes first and survives.
+ * - ``Updates `name` from A to B`` — one entry of a grouped update, or of a
+ *   single PR that bumps packages together.
+ * - `Updates the requirements on [name](url) to permit ...` — a range change
+ *   with no single target version.
+ *
+ * A group header (`Bumps the npm group with 3 updates: [a](url) and [b](url).`)
+ * names every package but no version. Its names count as claims with no target,
+ * so a truncated body that lost an `Updates` line still covers that package;
+ * wherever a versioned line survives, its version is the one checked.
+ */
+/** One claimed update. `to` is absent for a range change or a removal. */
+interface Claim {
+    name: string;
+    to?: string;
+}
+/**
+ * Every update the description claims, once per package. A package claimed
+ * twice with different targets keeps the last, which is what Dependabot's
+ * per-package `Updates` line states after a summary `Bumps` line.
+ */
+declare function parseClaims(body: string): Claim[];
+
+declare const MERGE_BLOCK_CHECK = "merge-block";
+declare function decideMergeBlock(pr: PullRequestFacts): CheckResult;
+declare const mergeBlockCheck: PolicyCheck;
+
 /**
  * Which files this guard considers "a CI workflow".
  *
@@ -204,6 +306,16 @@ declare const CI_APPROVAL_NEEDED_LABEL = "CI approval needed";
  * applies it.
  */
 declare const CI_CHANGE_APPROVED_LABEL = "CI change approved";
+/**
+ * Labels a person puts on a PR to stop it merging. The merge-block check holds
+ * `pr-policy` while any of them is present, and never applies or removes one.
+ * `dnm` is shorthand for `do not merge`.
+ */
+declare const DO_NOT_MERGE_LABEL = "do not merge";
+declare const DNM_LABEL = "dnm";
+declare const BLOCKED_LABEL = "blocked";
+declare const ESCALATION_NEEDED_LABEL = "escalation needed";
+declare const BLOCKING_LABELS: readonly ["do not merge", "dnm", "blocked", "escalation needed"];
 /**
  * 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,
@@ -247,7 +359,8 @@ declare function evaluatePolicy(pr: PullRequestFacts, checks?: readonly PolicyCh
 
 /**
  * Parse and validate a JSON facts document into `PullRequestFacts`.
- * `workflowChanges` and `manifestChanges` are optional and default to none.
+ * `workflowChanges`, `manifestChanges`, and `signOffs` are optional and default
+ * to none; `body` and `author` are optional and stay absent. With no `signOffs`, no sign-off label counts: trust fails closed.
  */
 declare function parseFacts(raw: string): PullRequestFacts;
 
@@ -272,5 +385,9 @@ declare function applyLabelEdits(target: PullRequestTarget, evaluation: PolicyEv
 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>;
+/** The request body for the `pr-policy` commit status mirroring this evaluation. */
+declare function statusBody(evaluation: PolicyEvaluation, runUrl: string | undefined): Record<string, unknown>;
+/** Post the verdict: the `pr-policy` check-run, then the matching commit status. */
+declare function postVerdict(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 };
+export { AMBIGUOUS_INDICATORS, type AmbiguousIndicator, BLOCKED_LABEL, BLOCKING_LABELS, 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 Claim, type Classification, type CommitType, DEPENDABOT_CHECK, DEPENDABOT_LOGIN, DNM_LABEL, DO_NOT_MERGE_LABEL, ESCALATION_NEEDED_LABEL, FUNCTIONAL_TYPES, type FileChange, type Finding, HOTFIX_LABEL, type Indicator, type IndicatorClass, type IndicatorKind, LOOSENING_INDICATORS, type LooseningIndicator, MERGE_BLOCK_CHECK, POLICY_OUTCOMES, PR_POLICY_CHECK_NAME, type ParsedTitle, type PolicyCheck, type PolicyEvaluation, type PolicyOptions, type PolicyOutcome, type PullRequestAuthor, type PullRequestFacts, type PullRequestTarget, RELEASE_PLEASE_PENDING_LABEL, TITLE_CHECK, type WorkflowFileChange, applyLabelEdits, buildReport, checkRunBody, ciChangeCheck, classifyWorkflowChanges, classifyWorkflowFile, decideCiChange, decideDependabot, decideMergeBlock, decideTitle, dependabotCheck, evaluatePolicy, gatherFacts, isManifestPath, isWorkflowPath, mergeBlockCheck, parseClaims, parseFacts, parseTitle, postCheckRun, postVerdict, selectChecks, sensitiveBumps, statusBody, titleCheck };

package/dist/index.js

@@ -1,5 +1,7 @@
 import {
   AMBIGUOUS_INDICATORS,
+  BLOCKED_LABEL,
+  BLOCKING_LABELS,
   BREAKING_CHANGE_LABEL,
   CHECKS,
   CI_APPROVAL_NEEDED_LABEL,
@@ -8,9 +10,15 @@ import {
   CI_CHANGE_VERDICTS,
   CI_SENSITIVE_PACKAGES,
   COMMIT_TYPES,
+  DEPENDABOT_CHECK,
+  DEPENDABOT_LOGIN,
+  DNM_LABEL,
+  DO_NOT_MERGE_LABEL,
+  ESCALATION_NEEDED_LABEL,
   FUNCTIONAL_TYPES,
   HOTFIX_LABEL,
   LOOSENING_INDICATORS,
+  MERGE_BLOCK_CHECK,
   POLICY_OUTCOMES,
   PR_POLICY_CHECK_NAME,
   RELEASE_PLEASE_PENDING_LABEL,
@@ -22,19 +30,29 @@ import {
   classifyWorkflowChanges,
   classifyWorkflowFile,
   decideCiChange,
+  decideDependabot,
+  decideMergeBlock,
   decideTitle,
+  dependabotCheck,
   evaluatePolicy,
   gatherFacts,
   isManifestPath,
   isWorkflowPath,
+  mergeBlockCheck,
+  parseClaims,
   parseFacts,
   parseTitle,
   postCheckRun,
+  postVerdict,
+  selectChecks,
   sensitiveBumps,
+  statusBody,
   titleCheck
-} from "./chunk-QINHHFJN.js";
+} from "./chunk-5VYRZAUT.js";
 export {
   AMBIGUOUS_INDICATORS,
+  BLOCKED_LABEL,
+  BLOCKING_LABELS,
   BREAKING_CHANGE_LABEL,
   CHECKS,
   CI_APPROVAL_NEEDED_LABEL,
@@ -43,9 +61,15 @@ export {
   CI_CHANGE_VERDICTS,
   CI_SENSITIVE_PACKAGES,
   COMMIT_TYPES,
+  DEPENDABOT_CHECK,
+  DEPENDABOT_LOGIN,
+  DNM_LABEL,
+  DO_NOT_MERGE_LABEL,
+  ESCALATION_NEEDED_LABEL,
   FUNCTIONAL_TYPES,
   HOTFIX_LABEL,
   LOOSENING_INDICATORS,
+  MERGE_BLOCK_CHECK,
   POLICY_OUTCOMES,
   PR_POLICY_CHECK_NAME,
   RELEASE_PLEASE_PENDING_LABEL,
@@ -57,14 +81,22 @@ export {
   classifyWorkflowChanges,
   classifyWorkflowFile,
   decideCiChange,
+  decideDependabot,
+  decideMergeBlock,
   decideTitle,
+  dependabotCheck,
   evaluatePolicy,
   gatherFacts,
   isManifestPath,
   isWorkflowPath,
+  mergeBlockCheck,
+  parseClaims,
   parseFacts,
   parseTitle,
   postCheckRun,
+  postVerdict,
+  selectChecks,
   sensitiveBumps,
+  statusBody,
   titleCheck
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmartz/pr-policy",
-  "version": "0.2.0",
+  "version": "0.8.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",