@rmartz/pr-policy 0.2.0

package/README.md

@@ -0,0 +1,52 @@
+# @rmartz/pr-policy
+
+**Is this pull request's content acceptable under policy?** `pr-policy` answers
+that on every PR, statically, from the PR's diff, title, and changed paths. It
+doesn't rely on a reviewer remembering to check.
+
+Each policy rule is a small read-only classifier. All of them report into **one**
+`pr-policy` check-run, which the consumer's ruleset requires. A fixable problem
+(a bad title) turns it red; a PR waiting on a human sign-off shows it as
+pending, not failing. Either holds the merge. Adding a rule later never adds a
+new required-status name.
+
+## Checks
+
+| Check                                                           | Blocks when                                                                                                                                                                                         |
+| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **CI-change classification** ([docs](docs/checks/ci-change.md)) | A `.github/workflows/**` change loosens CI (a removed job, `continue-on-error`, a narrowed trigger, …) and no human has applied `CI change approved` (shows as pending). Owns `CI approval needed`. |
+| **Title-type rules** ([docs](docs/checks/title.md))             | The squash title isn't a valid Conventional Commit, puts `!` on a non-functional type, or types a workflow change as anything but `ci` without the `breaking change` label.                         |
+| Domain labels (backlog)                                         | Never blocks. Additive path-glob → domain-label map.                                                                                                                                                |
+| Milestone inheritance (backlog)                                 | Never blocks. Issue → PR milestone.                                                                                                                                                                 |
+
+The design, and why this is separate from `merge-safety` and `pr-lifecycle`, is
+in [docs/decisions.md](docs/decisions.md).
+
+## Using it
+
+Add the [`rmartz/pr-policy-action`](https://github.com/rmartz/pr-policy-action)
+caller workflow and require the `pr-policy` status on your default branch. Setup
+is in its [consumer guide](https://github.com/rmartz/pr-policy-action/blob/main/docs/consuming.md).
+
+## Library and CLI
+
+Every check is importable. The `ai-pr-policy` CLI is a thin wrapper around them:
+
+```bash
+ai-pr-policy evaluate --pr 12 --repo rmartz/pr-policy          # post the check-run + labels
+ai-pr-policy evaluate --pr 12 --repo rmartz/pr-policy --json   # evaluate only, change nothing
+ai-pr-policy evaluate --facts pr.json                          # offline, from a JSON facts file
+```
+
+## Documentation
+
+- [What pr-policy is](docs/overview.md)
+- [Policy checks](docs/checks/index.md)
+- [The check-run and label contract](docs/check-run-contract.md)
+- [Adding a policy check](docs/adding-a-check.md)
+- [How pr-policy reaches consuming repos](docs/distribution.md)
+- [Design decisions](docs/decisions.md)
+
+---
+
+🤖 Created by Claude Opus 5.5

package/dist/bin/pr-policy.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/bin/pr-policy.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import {
+  applyLabelEdits,
+  evaluatePolicy,
+  gatherFacts,
+  parseFacts,
+  postCheckRun,
+  resolveRepoTarget
+} from "../chunk-QINHHFJN.js";
+
+// src/bin/pr-policy.ts
+import { readFile } from "fs/promises";
+import { parseArgs } from "util";
+var USAGE = `Usage:
+  ai-pr-policy evaluate --pr <n> [--repo <owner/repo>] [--json]
+  ai-pr-policy evaluate --facts <path|->
+
+--pr     Evaluate a live PR, post the pr-policy check-run on its head, and
+         apply the label edits the checks planned. --json prints the
+         evaluation instead and changes nothing.
+--facts  Evaluate an offline JSON facts document ("-" reads stdin) and print
+         the evaluation. Exits 1 only on "failure" ("pending" exits 0).`;
+async function readInput(path) {
+  if (path !== "-") return readFile(path, "utf8");
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function main(argv) {
+  const { values, positionals } = parseArgs({
+    args: [...argv],
+    allowPositionals: true,
+    options: {
+      facts: { type: "string" },
+      pr: { type: "string" },
+      repo: { type: "string" },
+      json: { type: "boolean" },
+      help: { type: "boolean", short: "h" }
+    }
+  });
+  if (values.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (positionals[0] !== "evaluate") {
+    console.error(USAGE);
+    return 2;
+  }
+  if (values.facts !== void 0) {
+    const evaluation2 = await evaluatePolicy(parseFacts(await readInput(values.facts)));
+    console.log(JSON.stringify(evaluation2, null, 2));
+    return evaluation2.outcome === "failure" ? 1 : 0;
+  }
+  const pr = Number(values.pr);
+  if (!Number.isInteger(pr) || pr <= 0) {
+    console.error(USAGE);
+    return 2;
+  }
+  const repo = await resolveRepoTarget({ repo: values.repo });
+  if (!repo) {
+    console.error("Could not resolve owner/repo \u2014 pass --repo <owner/repo>.");
+    return 2;
+  }
+  const target = { repo, pr };
+  const { facts, headSha } = await gatherFacts(target);
+  const evaluation = await evaluatePolicy(facts);
+  if (values.json) {
+    console.log(JSON.stringify(evaluation, null, 2));
+    return 0;
+  }
+  await applyLabelEdits(target, evaluation);
+  await postCheckRun(target, headSha, evaluation);
+  console.log(`${repo}#${pr}: ${evaluation.outcome} \u2014 ${evaluation.title}`);
+  return 0;
+}
+try {
+  process.exitCode = await main(process.argv.slice(2));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 2;
+}