@homeflare/alchemy 0.12.0 → 0.14.0

package/src/github/repo-policy-form.test.ts

@@ -0,0 +1,239 @@
+import { describe, expect, test } from 'bun:test';
+import { type RepoPolicyRepositorySettings, repoPolicy } from './repo-policy-form.ts';
+
+const base = { checks: ['ci', 'secret scan'], owner: 'acme', repository: 'widget' } as const;
+
+describe('repoPolicy — the repository half', () => {
+  test('squash only, auto-merge on, head branches deleted', () => {
+    const { repository } = repoPolicy(base);
+
+    expect(repository).toMatchObject({
+      allowAutoMerge: true,
+      allowMergeCommit: false,
+      allowRebaseMerge: false,
+      allowSquashMerge: true,
+      deleteBranchOnMerge: true,
+      name: 'widget',
+      owner: 'acme',
+    });
+  });
+
+  test('caller settings pass through but cannot re-open a merge method', () => {
+    // ⛔ The policy fields are spread AFTER `settings` for exactly this reason. A caller
+    //   who could turn merge commits back on here would defeat the helper silently.
+    // ★ `RepoPolicyRepositorySettings` already OMITS the merge keys, so this cast is the
+    //   only way to write the call at all — the type is the first guard, this is the
+    //   second, for a JavaScript consumer the compiler never sees.
+    const settings = { allowMergeCommit: true, description: 'a widget' } as unknown;
+    const { repository } = repoPolicy({
+      ...base,
+      settings: settings as RepoPolicyRepositorySettings,
+    });
+
+    expect(repository.description).toBe('a widget');
+    expect(repository.allowMergeCommit).toBe(false);
+  });
+});
+
+describe('repoPolicy — the ruleset half', () => {
+  test('covers the default branch, blocks deletion and force pushes, strict off', () => {
+    const { ruleset } = repoPolicy(base);
+
+    expect(ruleset).toMatchObject({
+      enforcement: 'active',
+      name: 'main',
+      owner: 'acme',
+      repository: 'widget',
+      target: 'branch',
+    });
+    expect(ruleset.conditions).toEqual({ exclude: [], include: ['~DEFAULT_BRANCH'] });
+    expect(ruleset.rules?.deletion).toBe(true);
+    expect(ruleset.rules?.nonFastForward).toBe(true);
+    expect(ruleset.rules?.requiredStatusChecks?.strictRequiredStatusChecksPolicy).toBe(false);
+  });
+
+  test('nobody bypasses unless the caller names an actor', () => {
+    expect(repoPolicy(base).ruleset.bypassActors).toEqual([]);
+    expect(
+      repoPolicy({ ...base, bypassActors: [{ actorId: 5, actorType: 'RepositoryRole' }] }).ruleset
+        .bypassActors,
+    ).toEqual([{ actorId: 5, actorType: 'RepositoryRole' }]);
+  });
+
+  test('checks are trimmed, de-duplicated and sorted, so re-ordering is not a diff', () => {
+    // ⚠️ THE NO-OP PROPERTY. GitHub stores the contexts in the order they were sent, so
+    //   an unsorted list would diff against itself the first time someone wrote the same
+    //   two contexts the other way round — a deploy that changes nothing and says it did.
+    const one = repoPolicy({ ...base, checks: ['ci', 'secret scan'] });
+    const other = repoPolicy({ ...base, checks: [' secret scan ', 'ci', 'ci'] });
+
+    expect(other).toEqual(one);
+    expect(one.ruleset.rules?.requiredStatusChecks?.checks).toEqual([
+      { context: 'ci' },
+      { context: 'secret scan' },
+    ]);
+  });
+
+  test('the ruleset name and the refs it covers are the callers', () => {
+    const { ruleset } = repoPolicy({
+      ...base,
+      exclude: ['refs/heads/dev/*'],
+      include: ['refs/heads/release/*'],
+      rulesetName: 'release',
+    });
+
+    expect(ruleset.name).toBe('release');
+    expect(ruleset.conditions).toEqual({
+      exclude: ['refs/heads/dev/*'],
+      include: ['refs/heads/release/*'],
+    });
+  });
+});
+
+describe('repoPolicy — required reviews are opt-in', () => {
+  test('no pull_request rule unless approvals were asked for', () => {
+    expect(repoPolicy(base).ruleset.rules?.pullRequest).toBeUndefined();
+  });
+
+  test('asking for approvals declares the rule and dismisses stale reviews', () => {
+    expect(repoPolicy({ ...base, requiredApprovals: 2 }).ruleset.rules?.pullRequest).toEqual({
+      dismissStaleReviewsOnPush: true,
+      requiredApprovingReviewCount: 2,
+    });
+  });
+
+  test('zero approvals is refused, naming the flag Alchemy cannot send', () => {
+    // ⛔ Not pedantry: 0 is the solo-maintainer shape, and it needs a field the vendor
+    //   resource has no property for. Accepting it would ship a rule that blocks the
+    //   pull requests it was written to allow.
+    expect(() => repoPolicy({ ...base, requiredApprovals: 0 })).toThrow(
+      /require_extra_approval_for_unattributed_changes/,
+    );
+  });
+
+  test('a fractional or negative count is refused too', () => {
+    expect(() => repoPolicy({ ...base, requiredApprovals: 1.5 })).toThrow(/whole number/);
+    expect(() => repoPolicy({ ...base, requiredApprovals: -1 })).toThrow(/whole number/);
+  });
+});
+
+describe('repoPolicy — the auto-merge trap', () => {
+  test('auto-merge with nothing required at all is refused', () => {
+    // ⛔ THE TRAP THIS HELPER EXISTS FOR. `gh pr merge --auto` is a queue only while
+    //   something is outstanding; with nothing required GitHub merges on the spot.
+    expect(() => repoPolicy({ ...base, checks: [] })).toThrow(/immediately/);
+  });
+
+  test('a required review is something outstanding, so an empty checks list is fine', () => {
+    // ⚠️ The guard is not "no checks": auto-merge waits on a required approval too, and
+    //   refusing that combination would block a legitimate review-gated repository.
+    const { repository, ruleset } = repoPolicy({ ...base, checks: [], requiredApprovals: 1 });
+
+    expect(repository.allowAutoMerge).toBe(true);
+    expect(ruleset.rules?.requiredStatusChecks).toBeUndefined();
+    expect(ruleset.rules?.pullRequest?.requiredApprovingReviewCount).toBe(1);
+  });
+
+  test('turning auto-merge off is the only way to declare an empty checks list', () => {
+    const { repository, ruleset } = repoPolicy({ ...base, autoMerge: false, checks: [] });
+
+    expect(repository.allowAutoMerge).toBe(false);
+    expect(ruleset.rules?.requiredStatusChecks).toBeUndefined();
+    // The branch is still protected — that is the point of the bootstrap state.
+    expect(ruleset.rules?.deletion).toBe(true);
+    expect(ruleset.rules?.nonFastForward).toBe(true);
+  });
+
+  test('a blank context is refused rather than stored as a check nothing reports', () => {
+    expect(() => repoPolicy({ ...base, checks: ['ci', '  '] })).toThrow(/blank/);
+  });
+
+  test('auto-merge over a ruleset that is not enforcing is refused', () => {
+    // ⚠️ THE QUIET DOOR. The checks are listed on the ruleset and none of them block
+    //   anything, so auto-merge lands the pull request while the plan looks correct.
+    expect(() => repoPolicy({ ...base, enforcement: 'evaluate' })).toThrow(/enforcement/);
+    expect(() => repoPolicy({ ...base, enforcement: 'disabled' })).toThrow(/immediately/);
+    expect(
+      repoPolicy({ ...base, autoMerge: false, enforcement: 'evaluate' }).ruleset.enforcement,
+    ).toBe('evaluate');
+  });
+
+  test('an explicitly empty include is refused — it would match no ref at all', () => {
+    // ⚠️ THE QUIETEST DOOR. GitHub still shows the ruleset as active; it just covers
+    //   nothing, so every rule on it is decorative.
+    expect(() => repoPolicy({ ...base, include: [] })).toThrow(/matches no ref/);
+  });
+
+  test('a blank ref pattern is refused — length is not coverage', () => {
+    // ⚠️ THE DOOR BESIDE THE GUARD. `['   ']` has length 1, so a guard that counts the
+    //   array passes it; GitHub then stores a condition that matches nothing. Identical
+    //   end state to `include: []`, reached past the check that exists to stop it.
+    expect(() => repoPolicy({ ...base, include: ['   '] })).toThrow(/blank/);
+    expect(() => repoPolicy({ ...base, exclude: [''] })).toThrow(/blank/);
+  });
+
+  test('an exclude that cancels every include is refused', () => {
+    // ⚠️ THE DOOR THAT READS AS A NARROWING. Exclusions win in a GitHub ruleset, so this
+    //   is a ruleset over nothing — but it looks like scoping, not like switching off.
+    expect(() => repoPolicy({ ...base, exclude: ['~DEFAULT_BRANCH'] })).toThrow(
+      /cancels every include/,
+    );
+    expect(() =>
+      repoPolicy({
+        ...base,
+        exclude: ['refs/heads/release/*', 'refs/heads/main'],
+        include: ['refs/heads/main', 'refs/heads/release/*'],
+      }),
+    ).toThrow(/cancels every include/);
+  });
+
+  test('an exclude that leaves an include standing is a narrowing, and allowed', () => {
+    // ★ EXACT CANCELLATION ONLY. Deciding glob overlap in general means reimplementing
+    //   GitHub's matcher; a narrow guard that is always right beats a broad one that
+    //   false-refuses a legitimate scope.
+    const { ruleset } = repoPolicy({
+      ...base,
+      exclude: ['refs/heads/release/*'],
+      include: ['~DEFAULT_BRANCH', 'refs/heads/release/*'],
+    });
+
+    // ★ Sorted, so `refs/…` precedes the `~` tokens — the ordering is normalization, not
+    //   a preference, and it is what keeps a second deploy from diffing against itself.
+    expect(ruleset.conditions).toEqual({
+      exclude: ['refs/heads/release/*'],
+      include: ['refs/heads/release/*', '~DEFAULT_BRANCH'],
+    });
+  });
+
+  test('ref patterns are trimmed, de-duplicated and sorted, so re-ordering is not a diff', () => {
+    const one = repoPolicy({ ...base, include: ['refs/heads/main', 'refs/heads/release/*'] });
+    const other = repoPolicy({
+      ...base,
+      include: [' refs/heads/release/* ', 'refs/heads/main', 'refs/heads/main'],
+    });
+
+    expect(other).toEqual(one);
+  });
+});
+
+describe('repoPolicy — one host for both halves', () => {
+  test('baseUrl reaches the repository and the ruleset, or neither', () => {
+    // ⛔ Setting it on one would point the repository at an Enterprise host and its
+    //   ruleset at github.com — two halves of one policy on two different instances.
+    const { repository, ruleset } = repoPolicy({ ...base, baseUrl: 'github.example.com' });
+
+    expect(repository.baseUrl).toBe('github.example.com');
+    expect(ruleset.baseUrl).toBe('github.example.com');
+
+    const plain = repoPolicy(base);
+    expect('baseUrl' in plain.repository).toBe(false);
+    expect('baseUrl' in plain.ruleset).toBe(false);
+  });
+});
+
+describe('repoPolicy — required inputs', () => {
+  test('an empty owner or repository is refused', () => {
+    expect(() => repoPolicy({ ...base, owner: ' ' })).toThrow(/owner is required/);
+    expect(() => repoPolicy({ ...base, repository: '' })).toThrow(/repository is required/);
+  });
+});

package/src/github/repo-policy-form.ts

@@ -0,0 +1,173 @@
+/**
+ * `repoPolicy` — one repository's house merge policy, as plain Alchemy props.
+ *
+ * ★ PURE ON PURPOSE, AND TYPE-ONLY IMPORTS. The exact shape a stack will deploy can be
+ *   asserted in a unit test with no credentials, no network and no Effect runtime.
+ *   `repo-policy.ts` is the thin half that turns these props into resources, and
+ *   `repo-policy-guards.ts` holds everything this refuses and why.
+ *
+ * ⛔ AUTO-MERGE WITH NOTHING TO WAIT FOR MERGES IMMEDIATELY. `gh pr merge --auto` is a
+ *   queue only while something is outstanding. Five different inputs produce "nothing
+ *   outstanding" — no `checks` and no `requiredApprovals`, an `enforcement` that is not
+ *   `active`, and three ways to land a ruleset that matches no ref (an empty `include`, a
+ *   blank ref pattern, an `exclude` that cancels every `include`). All five are refused.
+ *   See the guards module.
+ *
+ * ⛔ EVERY CONTEXT IN `checks` MUST ALWAYS REPORT. A required context that never reports
+ *   is not "passed", it is "pending", and the pull request waits on it forever —
+ *   auto-merge included. Point this at an aggregate job that runs `if: always()` and
+ *   fails when any upstream job did, never at a job behind a `paths:` filter, a matrix
+ *   leg, or anything a skipped workflow can silence.
+ */
+import type { RepositoryProps, RulesetProps } from 'alchemy/GitHub';
+import {
+  assertAutoMergeWaits,
+  normalizeChecks,
+  normalizeExclude,
+  normalizeInclude,
+  requireName,
+  resolveApprovals,
+} from './repo-policy-guards.ts';
+
+/** Alchemy's own bypass-actor shape, re-exported so a caller imports one module, not two. */
+export type RepoPolicyBypassActor = NonNullable<RulesetProps['bypassActors']>[number];
+
+/**
+ * Repository fields the policy does NOT own — description, topics, visibility, …
+ * ⛔ Merged UNDERNEATH the policy, so a caller can describe their repo but cannot quietly
+ *   re-enable merge commits through this door. The omitted keys are the policy itself.
+ * ⛔ `baseUrl` IS OMITTED TOO, and is a top-level option instead. Setting it on only one
+ *   of the two resources would point the repository at a GitHub Enterprise host and its
+ *   ruleset at github.com — two halves of one policy on two different instances.
+ */
+export type RepoPolicyRepositorySettings = Omit<
+  RepositoryProps,
+  | 'allowAutoMerge'
+  | 'allowMergeCommit'
+  | 'allowRebaseMerge'
+  | 'allowSquashMerge'
+  | 'baseUrl'
+  | 'deleteBranchOnMerge'
+  | 'name'
+  | 'owner'
+>;
+
+export interface RepoPolicyOptions {
+  /** Repository owner — a user or organization login. */
+  readonly owner: string;
+  /** Repository name. */
+  readonly repository: string;
+  /**
+   * Status-check contexts a pull request must pass, named exactly as the job reports
+   * them. Trimmed, de-duplicated and sorted, so re-ordering the list is not a diff.
+   */
+  readonly checks: readonly string[];
+  /** @default true — with nothing required it is refused, not quietly downgraded. */
+  readonly autoMerge?: boolean;
+  /** @default 'main' */
+  readonly rulesetName?: string;
+  /** Ref patterns the ruleset covers. @default ['~DEFAULT_BRANCH'] */
+  readonly include?: readonly string[];
+  /**
+   * Ref patterns exempted from it. @default []
+   * ⛔ Exclusions win over inclusions, so one that cancels every `include` is refused —
+   *   it reads as a narrowing and acts as an off switch.
+   */
+  readonly exclude?: readonly string[];
+  /** Who may bypass the ruleset. @default [] — nobody, administrators included. */
+  readonly bypassActors?: readonly RepoPolicyBypassActor[];
+  /**
+   * Approving reviews a pull request needs. Omit for none — `0` is refused rather than
+   * read as "no reviews"; `resolveApprovals` in the guards module says why.
+   */
+  readonly requiredApprovals?: number;
+  /** @default 'active' — anything else is refused alongside `autoMerge`. */
+  readonly enforcement?: 'active' | 'disabled' | 'evaluate';
+  /** GitHub Enterprise host, applied to BOTH resources or to neither. */
+  readonly baseUrl?: string;
+  /** Everything about the repository that is not merge policy. */
+  readonly settings?: RepoPolicyRepositorySettings;
+}
+
+export interface RepoPolicy {
+  readonly repository: RepositoryProps;
+  readonly ruleset: RulesetProps;
+}
+
+const DEFAULT_RULESET_NAME = 'main';
+/**
+ * ★ `~DEFAULT_BRANCH`, NOT `refs/heads/main`. GitHub resolves it per repository, so one
+ *   policy covers a repo whose default branch is `master` or `trunk`, and renaming the
+ *   default branch later does not silently leave the ruleset pointing at nothing.
+ */
+const DEFAULT_INCLUDE: readonly string[] = ['~DEFAULT_BRANCH'];
+
+/**
+ * The house policy for one repository: squash-only merges, auto-merge on, head branches
+ * deleted, and a ruleset over the default branch that blocks deletion and force pushes
+ * and requires `checks`.
+ *
+ * ★ `strictRequiredStatusChecksPolicy` IS ALWAYS FALSE, AND NOT A PARAMETER. "Require
+ *   branches to be up to date" means every merge to the default branch invalidates every
+ *   other open pull request, which with auto-merge on is a re-run storm that converges
+ *   only when the queue empties. The checks still have to pass; they just do not have to
+ *   have passed against the very tip.
+ */
+export function repoPolicy(options: RepoPolicyOptions): RepoPolicy {
+  const owner = requireName('owner', options.owner);
+  const repository = requireName('repository', options.repository);
+  const checks = normalizeChecks(options.checks);
+  const include = normalizeInclude(options.include, DEFAULT_INCLUDE);
+  const exclude = normalizeExclude(options.exclude, include);
+  const autoMerge = options.autoMerge ?? true;
+  const enforcement = options.enforcement ?? 'active';
+  const approvals = resolveApprovals(options.requiredApprovals);
+  assertAutoMergeWaits({ approvals, autoMerge, checkCount: checks.length, enforcement });
+  const host = options.baseUrl === undefined ? {} : { baseUrl: options.baseUrl };
+
+  return {
+    repository: {
+      ...options.settings,
+      ...host,
+      // ⛔ Squash only. The ruleset's own `allowed_merge_methods` is not reachable through
+      //   Alchemy's `pullRequest` rule, so the repository is the only place this holds.
+      allowAutoMerge: autoMerge,
+      allowMergeCommit: false,
+      allowRebaseMerge: false,
+      allowSquashMerge: true,
+      deleteBranchOnMerge: true,
+      name: repository,
+      owner,
+    },
+    ruleset: {
+      ...host,
+      bypassActors: [...(options.bypassActors ?? [])],
+      conditions: { exclude, include },
+      enforcement,
+      name: options.rulesetName ?? DEFAULT_RULESET_NAME,
+      owner,
+      repository,
+      rules: {
+        deletion: true,
+        nonFastForward: true,
+        ...(approvals === undefined
+          ? {}
+          : {
+              pullRequest: {
+                dismissStaleReviewsOnPush: true,
+                requiredApprovingReviewCount: approvals,
+              },
+            }),
+        ...(checks.length === 0
+          ? {}
+          : {
+              requiredStatusChecks: {
+                checks: checks.map((context) => ({ context })),
+                strictRequiredStatusChecksPolicy: false,
+              },
+            }),
+      },
+      target: 'branch',
+    },
+  };
+}

package/src/github/repo-policy-guards.ts

@@ -0,0 +1,179 @@
+/**
+ * Everything `repoPolicy` refuses, and why. Extracted from repo-policy-form.ts so the
+ * shape stays readable and the reasoning stays whole.
+ *
+ * ⛔ FIVE DIFFERENT DOORS LEAD TO THE SAME FAILURE — auto-merge with nothing to wait for.
+ *   `gh pr merge --auto` is a queue only while something is outstanding; with nothing
+ *   outstanding GitHub merges the pull request on the spot. An empty `checks` is the
+ *   obvious door. `enforcement: 'disabled'` or `'evaluate'` is the quiet one: the ruleset
+ *   exists, the required checks are listed on it, and none of them block anything. Then
+ *   three ways to end up with a ruleset that matches NO REF — which enforces on no ref
+ *   while the GitHub UI still shows it as `active`: an empty `include`, a blank ref
+ *   pattern, and an `exclude` that cancels every `include`. All five are refused.
+ *
+ * ★ THE REF DOORS WERE FOUND BY ADVERSARIAL REVIEW, NOT BY DESIGN. The first cut of this
+ *   module guarded `include.length === 0` and spread `exclude` raw, so
+ *   `include: ['~DEFAULT_BRANCH'], exclude: ['~DEFAULT_BRANCH']` and `include: ['   ']`
+ *   both sailed through with `allowAutoMerge: true` — the exact end state the empty-array
+ *   guard exists to prevent, reached by a door beside it. Checked by execution, not by
+ *   reading: see the `matches no ref` tests in repo-policy-form.test.ts.
+ */
+
+/** A non-empty, trimmed identifier, or an error naming the field. */
+export function requireName(field: string, value: string): string {
+  const trimmed = value.trim();
+  if (trimmed === '') throw new Error(`repoPolicy: ${field} is required`);
+  return trimmed;
+}
+
+/**
+ * Trim, de-duplicate, sort. ★ The sort is what makes a second deploy a no-op: GitHub
+ * stores the contexts in the order they were sent, so an unsorted list would diff against
+ * itself the first time a caller wrote the same contexts in a different order.
+ */
+export function normalizeChecks(checks: readonly string[]): string[] {
+  const seen = new Set<string>();
+  for (const raw of checks) {
+    const context = raw.trim();
+    // ⚠️ A blank context is a typo that reads as coverage: GitHub happily stores it and
+    //   no job ever reports it, so every pull request waits on a check that cannot come.
+    if (context === '') {
+      throw new Error(
+        'repoPolicy: a required check context is blank — name it exactly as the job reports it',
+      );
+    }
+    seen.add(context);
+  }
+  return [...seen].sort();
+}
+
+/**
+ * Trim, de-duplicate, sort one list of ref patterns, refusing a blank one.
+ *
+ * ⚠️ A BLANK PATTERN IS NOT AN EMPTY LIST, AND THAT IS THE WHOLE TRAP. `['   ']` has
+ *   length 1, so a guard that counts the array waves it through; GitHub then stores a ref
+ *   condition that matches nothing. Same end state as `[]`, reached past the guard.
+ * ★ Sorted for the same reason `normalizeChecks` is: GitHub echoes the patterns back in
+ *   the order they were sent, so an unsorted list diffs against itself the first time a
+ *   caller writes the same patterns in a different order.
+ */
+function normalizeRefs(field: string, patterns: readonly string[]): string[] {
+  const seen = new Set<string>();
+  for (const raw of patterns) {
+    const pattern = raw.trim();
+    if (pattern === '') {
+      throw new Error(
+        `repoPolicy: a ${field} ref pattern is blank — a ruleset that matches no ref enforces nothing.`,
+      );
+    }
+    seen.add(pattern);
+  }
+  return [...seen].sort();
+}
+
+/**
+ * ⛔ AN EMPTY `include` IS REFUSED. Alchemy defaults `conditions.include` to `['~ALL']`
+ *   when it is absent, but an explicitly empty array is sent as an empty array, and a
+ *   ruleset that matches no ref protects nothing while still reading as `active` in the
+ *   GitHub UI — the worst possible combination, because it looks like it worked.
+ */
+export function normalizeInclude(
+  include: readonly string[] | undefined,
+  fallback: readonly string[],
+): string[] {
+  if (include === undefined) return [...fallback];
+  if (include.length === 0) {
+    throw new Error(
+      'repoPolicy: include is empty — a ruleset that matches no ref enforces nothing. Omit it for the default branch.',
+    );
+  }
+  return normalizeRefs('include', include);
+}
+
+/**
+ * ⛔ AN `exclude` THAT CANCELS EVERY `include` IS REFUSED. In a GitHub ruleset the
+ *   exclusions win, so `include: ['~DEFAULT_BRANCH'], exclude: ['~DEFAULT_BRANCH']` is a
+ *   ruleset over nothing — and it reads as a narrowing, which is what makes it worse than
+ *   the empty array: the caller believes they scoped the policy, not switched it off.
+ *
+ * ⚠️ EXACT CANCELLATION ONLY, DELIBERATELY. GitHub's patterns are globs, so deciding in
+ *   general whether some exclude swallows some include means implementing GitHub's
+ *   matcher and being wrong about it quietly. This refuses the case that is decidable —
+ *   every include pattern also appears verbatim in `exclude` — and leaves
+ *   `exclude: ['refs/heads/*']` against `include: ['~DEFAULT_BRANCH']` to the operator.
+ *   A narrower guard that is always right beats a broad one that false-refuses.
+ */
+export function normalizeExclude(
+  exclude: readonly string[] | undefined,
+  include: readonly string[],
+): string[] {
+  const patterns = exclude === undefined ? [] : normalizeRefs('exclude', exclude);
+  if (patterns.length === 0) return patterns;
+  const excluded = new Set(patterns);
+  if (include.every((pattern) => excluded.has(pattern))) {
+    throw new Error(
+      [
+        'repoPolicy: exclude cancels every include pattern, so the ruleset matches no ref and enforces nothing.',
+        `include ${JSON.stringify(include)} is fully covered by exclude ${JSON.stringify(patterns)}.`,
+      ].join(' '),
+    );
+  }
+  return patterns;
+}
+
+/**
+ * ⛔ `0` IS REFUSED, NOT TREATED AS "NO REVIEWS". A `pull_request` rule with zero
+ *   approvals is the solo-maintainer shape — every change through a PR, no second person
+ *   — and it only works with `require_extra_approval_for_unattributed_changes: false`.
+ *   alchemy@2.0.0-beta.79's `Ruleset` cannot express that field, and GitHub defaults it
+ *   to `true` when it is omitted (measured 2026-09-17), which blocks the very PRs the
+ *   zero was meant to let through. Omitting `requiredApprovals` declares no rule at all,
+ *   which is a different and honest thing.
+ */
+export function resolveApprovals(requested: number | undefined): number | undefined {
+  if (requested === undefined) return undefined;
+  if (!Number.isInteger(requested) || requested < 1) {
+    throw new Error(
+      [
+        'repoPolicy: requiredApprovals must be a whole number of 1 or more.',
+        'Omit it to declare no pull_request rule.',
+        '0 is not that: it needs require_extra_approval_for_unattributed_changes: false,',
+        'which alchemy@2.0.0-beta.79 cannot send and GitHub defaults to true.',
+      ].join(' '),
+    );
+  }
+  return requested;
+}
+
+/**
+ * ⚠️ THE TEST IS "SOMETHING OUTSTANDING", NOT "SOME CHECKS". A required review holds a
+ *   pull request open just as a required check does, so `requiredApprovals` with an empty
+ *   `checks` is a legitimate policy. What is refused is auto-merge over a ruleset that
+ *   will not hold anything back.
+ */
+export function assertAutoMergeWaits(input: {
+  readonly autoMerge: boolean;
+  readonly checkCount: number;
+  readonly approvals: number | undefined;
+  readonly enforcement: 'active' | 'disabled' | 'evaluate';
+}): void {
+  if (!input.autoMerge) return;
+  if (input.enforcement !== 'active') {
+    throw new Error(
+      [
+        `repoPolicy: autoMerge with enforcement '${input.enforcement}' merges every pull request immediately.`,
+        'A ruleset that is not active enforces none of its rules, so auto-merge has nothing to wait for.',
+        'Pass autoMerge: false while the ruleset is being evaluated.',
+      ].join(' '),
+    );
+  }
+  if (input.checkCount === 0 && input.approvals === undefined) {
+    throw new Error(
+      [
+        'repoPolicy: autoMerge with nothing required merges every pull request immediately.',
+        'Name at least one always-reporting check context, or ask for requiredApprovals,',
+        'or pass autoMerge: false for a repository that has no green run to require yet.',
+      ].join(' '),
+    );
+  }
+}

package/src/github/repo-policy.test.ts

@@ -0,0 +1,58 @@
+/**
+ * The declaring half, and the two docs that carry its traps.
+ *
+ * ★ WHY TEST A DOC. Both files ship in the tarball and are the only place a consumer is
+ *   told that the vendor ruleset adopts nothing and that auto-merge with nothing required
+ *   merges on the spot. A silent edit that drops either warning would fail nothing else
+ *   in this repo, and would cost the consumer a duplicate ruleset or a PR merged on red.
+ * ⛔ THE HAZARDS LIVE IN A SIBLING FILE, AND THE POINTER IS TESTED TOO. Extracting them
+ *   is only safe while `repo-policy.md` still sends the reader there; a dangling pointer
+ *   would read as "no hazard" rather than as a broken link.
+ */
+import { describe, expect, test } from 'bun:test';
+import { declareRepoPolicy } from './index.ts';
+
+const doc = await Bun.file(new URL('../../docs/repo-policy.md', import.meta.url)).text();
+const hazards = await Bun.file(
+  new URL('../../docs/repo-policy-ruleset-hazards.md', import.meta.url),
+).text();
+
+describe('declareRepoPolicy', () => {
+  test('is a function, not a factory that reaches GitHub at import time', () => {
+    // ⚠️ Importing this module must not construct a resource or an Octokit client: the
+    //   barrel is loaded by the consumer smoke test with no credentials in the process.
+    expect(typeof declareRepoPolicy).toBe('function');
+    expect(declareRepoPolicy.length).toBe(2);
+  });
+});
+
+describe('docs/repo-policy.md', () => {
+  test('stays under the 200-line cap', () => {
+    expect(doc.split('\n').length).toBeLessThanOrEqual(200);
+  });
+
+  test('warns that auto-merge with nothing required merges immediately', () => {
+    expect(doc).toContain('auto-merge');
+    expect(doc).toMatch(/merges? (the pull request )?immediately/i);
+  });
+
+  test('sends the reader to the ruleset hazards, which is where they now live', () => {
+    expect(doc).toContain('repo-policy-ruleset-hazards.md');
+    expect(doc).toMatch(/cannot be adopted/i);
+  });
+});
+
+describe('docs/repo-policy-ruleset-hazards.md', () => {
+  test('stays under the 200-line cap', () => {
+    expect(hazards.split('\n').length).toBeLessThanOrEqual(200);
+  });
+
+  test('warns that the vendor ruleset cannot be adopted and duplicates instead', () => {
+    expect(hazards).toContain('createRepoRuleset');
+    expect(hazards).toContain('rulesets');
+  });
+
+  test('carries the preflight that keeps a first deploy from duplicating', () => {
+    expect(hazards).toContain('gh api repos/<owner>/<repo>/rulesets');
+  });
+});