@homeflare/alchemy 0.26.0 → 0.27.0

package/src/github/repository-ruleset-form.ts

@@ -0,0 +1,212 @@
+/**
+ * Props → wire form, and a canonical form for comparing two wire rulesets.
+ *
+ * ★ THE CANONICALIZATION IS THE NEVER-NOOP FIX. Upstream `GitHub.Ruleset#reconcile` compares
+ *   `desired` against the live GET with a raw `deepEqual` (see repository-ruleset.ts's header).
+ *   GitHub does not promise to echo `rules`, `allowed_merge_methods` or `checks` back in
+ *   request order, and a live `required_status_checks` check carries `integration_id: null`
+ *   where the request never sent the key at all — so an unsorted, un-normalized comparison
+ *   drifts against itself on every single plan. `canonicalizeWireRuleset` sorts every list that
+ *   has no meaningful order and drops nullish `integration_id` before two wire rulesets are
+ *   ever compared.
+ */
+import type {
+  RepositoryRulesetProps,
+  RepositoryRulesetPullRequestRule,
+  RepositoryRulesetRules,
+  RepositoryRulesetStatusChecksRule,
+} from './repository-ruleset.ts';
+import type { CreateRulesetBody, WireRule } from './repository-ruleset-constraints.ts';
+
+/** Fixed, deterministic order — independent of the order keys were set on `props.rules` — so
+ * two declarations of the same policy always produce the same wire array. */
+const RULE_BUILD_ORDER = [
+  'creation',
+  'update',
+  'deletion',
+  'required_linear_history',
+  'required_signatures',
+  'non_fast_forward',
+  'pull_request',
+  'required_status_checks',
+] as const;
+
+function buildPullRequestRule(rule: RepositoryRulesetPullRequestRule): WireRule {
+  return {
+    type: 'pull_request',
+    parameters: {
+      required_approving_review_count: rule.requiredApprovingReviewCount ?? 0,
+      dismiss_stale_reviews_on_push: rule.dismissStaleReviewsOnPush ?? false,
+      require_code_owner_review: rule.requireCodeOwnerReview ?? false,
+      require_last_push_approval: rule.requireLastPushApproval ?? false,
+      required_review_thread_resolution: rule.requiredReviewThreadResolution ?? false,
+      ...(rule.allowedMergeMethods === undefined
+        ? {}
+        : { allowed_merge_methods: [...rule.allowedMergeMethods] }),
+      // Defaulted to `[]`, not omitted — GitHub's own GET always carries this key (empty when
+      // unset), so omitting it here would make every live ruleset diff against itself forever.
+      required_reviewers: (rule.requiredReviewers ?? []).map((r) => ({
+        file_patterns: [...r.filePatterns],
+        minimum_approvals: r.minimumApprovals,
+        reviewer: { id: r.reviewer.actorId, type: r.reviewer.actorType },
+      })),
+      // ⛔ Only ever sent as `false` (H15) — see repository-ruleset.ts for why this exists at
+      //   all and repository-ruleset-wire.test.ts for whether Octokit forwards it untyped.
+      ...(rule.extraApprovalForUnattributedChanges === undefined
+        ? {}
+        : { require_extra_approval_for_unattributed_changes: false }),
+    },
+    // The extension field above has no home in Octokit's own rule union (H15) — the cast is
+    // the only place that gap is bridged.
+  } as WireRule;
+}
+
+function buildStatusChecksRule(rule: RepositoryRulesetStatusChecksRule): WireRule {
+  return {
+    type: 'required_status_checks',
+    parameters: {
+      required_status_checks: rule.checks.map((c) => ({
+        context: c.context,
+        ...(c.integrationId === undefined ? {} : { integration_id: c.integrationId }),
+      })),
+      strict_required_status_checks_policy: rule.strictRequiredStatusChecksPolicy ?? false,
+      do_not_enforce_on_create: rule.doNotEnforceOnCreate ?? false,
+    },
+  };
+}
+
+export function buildWireRules(rules: RepositoryRulesetRules | undefined): WireRule[] {
+  const wire: WireRule[] = [];
+  for (const type of RULE_BUILD_ORDER) {
+    switch (type) {
+      case 'creation':
+        if (rules?.creation) wire.push({ type: 'creation' });
+        break;
+      case 'update':
+        if (rules?.update) {
+          wire.push({ type: 'update', parameters: { update_allows_fetch_and_merge: false } });
+        }
+        break;
+      case 'deletion':
+        if (rules?.deletion) wire.push({ type: 'deletion' });
+        break;
+      case 'required_linear_history':
+        if (rules?.requiredLinearHistory) wire.push({ type: 'required_linear_history' });
+        break;
+      case 'required_signatures':
+        if (rules?.requiredSignatures) wire.push({ type: 'required_signatures' });
+        break;
+      case 'non_fast_forward':
+        if (rules?.nonFastForward) wire.push({ type: 'non_fast_forward' });
+        break;
+      case 'pull_request':
+        if (rules?.pullRequest) wire.push(buildPullRequestRule(rules.pullRequest));
+        break;
+      case 'required_status_checks':
+        if (rules?.requiredStatusChecks) {
+          wire.push(buildStatusChecksRule(rules.requiredStatusChecks));
+        }
+        break;
+    }
+  }
+  return wire;
+}
+
+/** The full desired wire body, minus `owner`/`repo` — sent verbatim to `createRepoRuleset` or
+ * `updateRepoRuleset`. */
+export function desiredWireRuleset(props: RepositoryRulesetProps): CreateRulesetBody {
+  return {
+    name: props.name,
+    target: props.target ?? 'branch',
+    enforcement: props.enforcement ?? 'active',
+    bypass_actors: (props.bypassActors ?? []).map((a) => ({
+      actor_type: a.actorType,
+      // `exactOptionalPropertyTypes`: an always-present `actor_id: number | undefined` is not
+      // assignable to the wire's `actor_id?: number | null` — the key must be ABSENT, not
+      // present-with-`undefined`, when there is no id.
+      ...(a.actorId === undefined ? {} : { actor_id: a.actorId }),
+      bypass_mode: a.bypassMode ?? 'always',
+    })),
+    conditions: {
+      ref_name: {
+        include: [...(props.conditions?.include ?? ['~ALL'])].sort(),
+        exclude: [...(props.conditions?.exclude ?? [])].sort(),
+      },
+    },
+    rules: buildWireRules(props.rules),
+  };
+}
+
+const sortByJson = <T>(items: readonly T[]): T[] =>
+  [...items].sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+
+/** Drop keys whose value is `null` or `undefined`, recursively — GitHub's GET fills
+ * `integration_id: null` where the request never sent the key; this makes both read the same. */
+/**
+ * ⚠️ SORTS OBJECT KEYS TOO, NOT ONLY ARRAY ELEMENTS. `JSON.stringify` preserves insertion
+ *   order, so `{a:1,b:2}` and `{b:2,a:1}` stringify to different text despite being the same
+ *   value — measured directly by this file's own lifecycle test: `desiredWireRuleset` and a
+ *   fixture built by spreading `{...liveRule, ...patch}` produced `parameters` keys in two
+ *   different orders and every downstream `JSON.stringify` equality check failed although the
+ *   values were identical. Sorting keys here is what makes the `JSON.stringify(canonicalize(x))
+ *   === JSON.stringify(canonicalize(y))` comparisons the rest of this family relies on
+ *   (repository-ruleset-reconcile.ts, and every canonicalize-based test) actually compare
+ *   VALUES rather than incidental key order.
+ */
+function stripNullish(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stripNullish);
+  if (value !== null && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const k of Object.keys(value).sort()) {
+      const v = (value as Record<string, unknown>)[k];
+      if (v !== null && v !== undefined) out[k] = stripNullish(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+function canonicalizeRule(rule: Record<string, unknown>): Record<string, unknown> {
+  const stripped = stripNullish(rule) as Record<string, unknown>;
+  const params = stripped.parameters as Record<string, unknown> | undefined;
+  if (params === undefined) return stripped;
+  const next = { ...params };
+  if (Array.isArray(next.allowed_merge_methods)) {
+    next.allowed_merge_methods = [...(next.allowed_merge_methods as string[])].sort();
+  }
+  if (Array.isArray(next.required_status_checks)) {
+    next.required_status_checks = sortByJson(
+      next.required_status_checks as Record<string, unknown>[],
+    );
+  }
+  return { ...stripped, parameters: next };
+}
+
+/**
+ * Normalize a wire ruleset (desired OR observed) so two representations of the same policy
+ * compare equal regardless of the order GitHub happens to echo lists back in.
+ *
+ * ⚠️ `input: unknown`, DELIBERATELY, NOT `CreateRulesetBody | RulesetRecord`. The two real
+ *   callers (our own request body, and GitHub's JSON response) are independently typed and
+ *   under `exactOptionalPropertyTypes` a shared structural interface fights both of them at
+ *   once for no safety this function actually uses — every field below is read defensively,
+ *   the same way a live GET already has to be, so a typed façade here would be decorative.
+ */
+export function canonicalizeWireRuleset(input: unknown): unknown {
+  const r = (input ?? {}) as {
+    name?: unknown;
+    target?: unknown;
+    enforcement?: unknown;
+    bypass_actors?: readonly Record<string, unknown>[];
+    conditions?: unknown;
+    rules?: readonly Record<string, unknown>[];
+  };
+  return stripNullish({
+    name: r.name,
+    target: r.target ?? 'branch',
+    enforcement: r.enforcement,
+    bypass_actors: sortByJson(r.bypass_actors ?? []),
+    conditions: r.conditions,
+    rules: sortByJson((r.rules ?? []).map(canonicalizeRule)),
+  });
+}

package/src/github/repository-ruleset-guards.ts

@@ -0,0 +1,194 @@
+/**
+ * Everything `reconcile` refuses before it writes, and why. Extracted so
+ * repository-ruleset.ts stays the wiring, and the reasoning stays whole — the same split
+ * `repo-policy-guards.ts` uses for `declareRepoPolicy`.
+ */
+import * as Effect from 'effect/Effect';
+import type { RepositoryRulesetProps } from './repository-ruleset.ts';
+import { RULE_TYPE_COVERAGE, type RepositoryRuleType } from './repository-ruleset-constraints.ts';
+import {
+  BypassActorWidened,
+  NeverReportedContext,
+  RequiredChecksOmitted,
+  UndeclaredLiveRule,
+} from './repository-ruleset-errors.ts';
+import type { RulesetOctokit, RulesetRecord } from './repository-ruleset-probe.ts';
+
+const bypassKey = (a: { actor_type: unknown; actor_id: unknown; bypass_mode?: unknown }) =>
+  `${String(a.actor_type)}:${String(a.actor_id ?? '')}:${String(a.bypass_mode ?? 'always')}`;
+
+/**
+ * ⛔ A CREATE REQUIRES `[]`; `undefined` on a create is the same thing (nothing live to widen
+ *   from). On an update/adopt, `undefined` means unmanaged — the caller never sees this guard
+ *   because repository-ruleset.ts sends the LIVE value back unchanged in that case, and this
+ *   function is only called when `props.bypassActors` is explicitly declared.
+ */
+export function bypassWideningRefusal(input: {
+  readonly owner: string;
+  readonly repository: string;
+  readonly name: string;
+  readonly declared: RepositoryRulesetProps['bypassActors'];
+  readonly live: RulesetRecord | undefined;
+}): BypassActorWidened | undefined {
+  // A create may declare any bypass list — nothing live to widen against.
+  if (input.live === undefined) return undefined;
+  const liveActors = (input.live.bypass_actors ?? []) as {
+    actor_type: unknown;
+    actor_id: unknown;
+    bypass_mode?: unknown;
+  }[];
+  const liveKeys = new Set(liveActors.map(bypassKey));
+  const widened = (input.declared ?? [])
+    .map((a) =>
+      bypassKey({
+        actor_type: a.actorType,
+        actor_id: a.actorId,
+        bypass_mode: a.bypassMode ?? 'always',
+      }),
+    )
+    .filter((k) => !liveKeys.has(k));
+  if (widened.length === 0) return undefined;
+  return new BypassActorWidened({
+    owner: input.owner,
+    repository: input.repository,
+    name: input.name,
+    widened,
+  });
+}
+
+const liveRuleTypes = (live: RulesetRecord | undefined): Set<string> =>
+  new Set((live?.rules ?? []).map((r) => String(r.type)));
+
+/**
+ * Refuses (a) any live rule of a REFUSED type — this resource can never represent it, and the
+ * PUT replaces `rules` wholesale, so silence would drop it; and (b) ANY live rule of a MODELED
+ * type the declaration is silent about — same hazard, for every rule this resource owns.
+ *
+ * ⚠️ `declaredTypes` MUST BE PRESENCE, NOT TRUTHINESS — this is the fix for a real bug this
+ *   family's own design first shipped with. A plain `rules?.deletion` check cannot distinguish
+ *   "omitted" from "declared `false`", so `undeclaredLiveRuleRefusal` originally exempted every
+ *   boolean rule (`creation`/`update`/`deletion`/`requiredLinearHistory`/`requiredSignatures`/
+ *   `nonFastForward`) as "fully owned — omission IS the removal". Concretely, that meant: a
+ *   live ruleset has `deletion: true` (blocks branch deletion); a caller declares this resource
+ *   with `rules: { pullRequest: {...}, requiredStatusChecks: {...} }`, simply forgetting
+ *   `deletion: true` — an easy mistake, since omitting an optional boolean is not a type error.
+ *   The wholesale PUT would have sent `rules` without a `deletion` entry, silently REMOVING
+ *   branch-deletion protection on the very next `reconcile` — exactly the hazard this whole
+ *   guard exists to prevent, reached through the one door it left open. Found by a self-review
+ *   pass (no subagent available in this harness), not by a test; there is now one:
+ *   repository-ruleset-write-refusals.test.ts's "an omitted boolean rule" case.
+ *   `required_status_checks` still gets its own, better-worded `RequiredChecksOmitted` from
+ *   {@link requiredChecksOmissionRefusal} and is excluded here so it is not refused twice.
+ */
+export function undeclaredLiveRuleRefusal(input: {
+  readonly owner: string;
+  readonly repository: string;
+  readonly name: string;
+  readonly live: RulesetRecord | undefined;
+  readonly declaredTypes: ReadonlySet<string>;
+}): UndeclaredLiveRule | undefined {
+  for (const type of liveRuleTypes(input.live)) {
+    const coverage = RULE_TYPE_COVERAGE[type as RepositoryRuleType];
+    if (coverage === 'refused') {
+      return new UndeclaredLiveRule({
+        owner: input.owner,
+        repository: input.repository,
+        name: input.name,
+        ruleType: type,
+      });
+    }
+    if (
+      coverage === 'modeled' &&
+      type !== 'required_status_checks' &&
+      !input.declaredTypes.has(type)
+    ) {
+      return new UndeclaredLiveRule({
+        owner: input.owner,
+        repository: input.repository,
+        name: input.name,
+        ruleType: type,
+      });
+    }
+  }
+  return undefined;
+}
+
+/** The wire `type` for every rule key present ON THE DECLARATION OBJECT ITSELF — `Object.hasOwn`,
+ * not truthiness, so `{ deletion: false }` (an explicit, deliberate removal) counts as declared
+ * and a bare omission does not. Feeds `undeclaredLiveRuleRefusal`'s `declaredTypes`. */
+export function declaredRuleTypes(rules: RepositoryRulesetProps['rules']): ReadonlySet<string> {
+  if (rules === undefined) return new Set();
+  const BOOLEAN_KEY_TO_TYPE: Record<string, string> = {
+    creation: 'creation',
+    update: 'update',
+    deletion: 'deletion',
+    requiredLinearHistory: 'required_linear_history',
+    requiredSignatures: 'required_signatures',
+    nonFastForward: 'non_fast_forward',
+  };
+  const types = new Set<string>();
+  for (const [key, type] of Object.entries(BOOLEAN_KEY_TO_TYPE)) {
+    if (Object.hasOwn(rules, key)) types.add(type);
+  }
+  if (Object.hasOwn(rules, 'pullRequest')) types.add('pull_request');
+  return types;
+}
+
+/** `requiredStatusChecks: undefined` while the live ruleset HAS one → refused, naming the live
+ * contexts. `requiredStatusChecks: false` is the declared removal and never reaches here. */
+export function requiredChecksOmissionRefusal(input: {
+  readonly owner: string;
+  readonly repository: string;
+  readonly name: string;
+  readonly declared: RepositoryRulesetProps['rules'];
+  readonly live: RulesetRecord | undefined;
+}): RequiredChecksOmitted | undefined {
+  if (input.declared?.requiredStatusChecks !== undefined) return undefined;
+  const liveRule = (input.live?.rules ?? []).find((r) => r.type === 'required_status_checks');
+  if (liveRule === undefined) return undefined;
+  const params = liveRule.parameters as
+    | { required_status_checks?: { context: string }[] }
+    | undefined;
+  const liveContexts = (params?.required_status_checks ?? []).map((c) => c.context);
+  return new RequiredChecksOmitted({
+    owner: input.owner,
+    repository: input.repository,
+    name: input.name,
+    liveContexts,
+  });
+}
+
+/** Every context in the declared `requiredStatusChecks` that the LIVE ruleset does not already
+ * require — i.e. being added by this plan, the only case a never-reported context can matter. */
+export const newlyRequiredContexts = (
+  declared: RepositoryRulesetProps['rules'],
+  live: RulesetRecord | undefined,
+): readonly string[] => {
+  if (declared?.requiredStatusChecks === false || declared?.requiredStatusChecks === undefined)
+    return [];
+  const liveRule = (live?.rules ?? []).find((r) => r.type === 'required_status_checks');
+  const liveParams = liveRule?.parameters as
+    | { required_status_checks?: { context: string }[] }
+    | undefined;
+  const liveContexts = new Set((liveParams?.required_status_checks ?? []).map((c) => c.context));
+  return declared.requiredStatusChecks.checks
+    .map((c) => c.context)
+    .filter((c) => !liveContexts.has(c));
+};
+
+/** Fails on the first newly-required context that has never reported success on the default
+ * branch — checked once here (reconcile's observe step) and again by the standalone checker. */
+export const refuseUnreportedContexts = <R = never>(
+  octokit: RulesetOctokit<R>,
+  owner: string,
+  repo: string,
+  contexts: readonly string[],
+): Effect.Effect<void, NeverReportedContext | Error, R> =>
+  Effect.gen(function* () {
+    for (const context of contexts) {
+      const reported = yield* octokit.hasContextReportedSuccess({ owner, repo, context });
+      if (!reported) {
+        return yield* Effect.fail(new NeverReportedContext({ owner, repository: repo, context }));
+      }
+    }
+  });

package/src/github/repository-ruleset-lifecycle.test.ts

@@ -0,0 +1,172 @@
+/**
+ * (i) GET-only loopback fake serving the 16 captured rulesets: cold adoption never creates a
+ * duplicate, the house baseline plans real drift against every one of them (none has
+ * `allowed_merge_methods: [squash]` yet), and the canonicalization fix (repository-ruleset-
+ * form.ts) reads a reordered-but-equal live ruleset as a noop while still catching real drift —
+ * the mutation check.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { LIVE_RULESET_FIXTURES } from './repository-ruleset-fixtures.ts';
+import { makeGetOnlyFake } from './repository-ruleset-fake-octokit.ts';
+import { canonicalizeWireRuleset, desiredWireRuleset } from './repository-ruleset-form.ts';
+import { probeByName } from './repository-ruleset-probe.ts';
+import type { RepositoryRulesetProps } from './repository-ruleset.ts';
+
+const run = <A, E>(eff: Effect.Effect<A, E>): Promise<A> => Effect.runPromise(eff);
+
+const baselineProps = (
+  owner: string,
+  repository: string,
+  checks: readonly string[],
+): RepositoryRulesetProps => ({
+  owner,
+  repository,
+  name: 'main',
+  target: 'branch',
+  enforcement: 'active',
+  bypassActors: [],
+  conditions: { include: ['~DEFAULT_BRANCH'], exclude: [] },
+  rules: {
+    deletion: true,
+    nonFastForward: true,
+    pullRequest: {
+      requiredApprovingReviewCount: 0,
+      dismissStaleReviewsOnPush: true,
+      requireCodeOwnerReview: false,
+      requireLastPushApproval: false,
+      requiredReviewThreadResolution: false,
+      allowedMergeMethods: ['squash'],
+      extraApprovalForUnattributedChanges: false,
+    },
+    ...(checks.length === 0
+      ? {}
+      : { requiredStatusChecks: { checks: checks.map((context) => ({ context })) } }),
+  },
+});
+
+const STANDARD_REPOS = Object.entries(LIVE_RULESET_FIXTURES).filter(
+  ([repo]) => !['homeflare', 'anyauth', 'desktop'].includes(repo),
+);
+
+describe('probeByName over the 16 live fixtures', () => {
+  test('finds exactly the one ruleset each repo has, never a duplicate', async () => {
+    const fake = makeGetOnlyFake(LIVE_RULESET_FIXTURES);
+    for (const [repo, live] of Object.entries(LIVE_RULESET_FIXTURES)) {
+      const found = await run(
+        probeByName(fake, { owner: 'taslabs-net', repo, name: 'main', target: 'branch' }),
+      );
+      expect(found?.id).toBe(live.id);
+    }
+  });
+
+  test('a repo with no ruleset probes to undefined, not a create-blocking error', async () => {
+    const fake = makeGetOnlyFake(LIVE_RULESET_FIXTURES);
+    const found = await run(
+      probeByName(fake, { owner: 'taslabs-net', repo: 'builds', name: 'main', target: 'branch' }),
+    );
+    expect(found).toBeUndefined();
+  });
+});
+
+describe('house baseline vs every live fixture', () => {
+  test('all 16 show real drift today: none has allowed_merge_methods narrowed to squash', () => {
+    for (const [repo, live] of Object.entries(LIVE_RULESET_FIXTURES)) {
+      const checks =
+        repo === 'homeflare' || repo === 'anyauth' || repo === 'desktop'
+          ? []
+          : ['ci', 'secret scan'];
+      const desired = desiredWireRuleset(baselineProps('taslabs-net', repo, checks));
+      const same =
+        JSON.stringify(canonicalizeWireRuleset(desired)) ===
+        JSON.stringify(canonicalizeWireRuleset(live));
+      expect(same).toBe(false);
+    }
+  });
+
+  test(`${String(STANDARD_REPOS.length)} standard repos differ ONLY in allowed_merge_methods and the extension flag`, () => {
+    for (const [repo, live] of STANDARD_REPOS) {
+      const desired = desiredWireRuleset(baselineProps('taslabs-net', repo, ['ci', 'secret scan']));
+      // Patch just those two fields onto the live record and expect a match — proves the
+      // 13 "already matching" repos truly match everywhere else the survey claims they do.
+      const patchedRules = (live.rules ?? []).map((r) =>
+        r.type === 'pull_request'
+          ? {
+              ...r,
+              parameters: {
+                ...(r.parameters as Record<string, unknown>),
+                allowed_merge_methods: ['squash'],
+                require_extra_approval_for_unattributed_changes: false,
+              },
+            }
+          : r,
+      );
+      const patched = { ...live, rules: patchedRules };
+      const same =
+        JSON.stringify(canonicalizeWireRuleset(desired)) ===
+        JSON.stringify(canonicalizeWireRuleset(patched));
+      expect(same).toBe(true);
+    }
+  });
+});
+
+describe('canonicalization: reorder is a noop, real drift is not (the never-noop fix)', () => {
+  const repo = 'openbao';
+  const desired = desiredWireRuleset(baselineProps('taslabs-net', repo, ['ci', 'secret scan']));
+  const matching = {
+    ...desired,
+    // Same policy, reordered `rules`, reordered `allowed_merge_methods`/checks, and an
+    // `integration_id: null` GitHub adds that the request never sent.
+    rules: [...(desired.rules ?? [])].reverse().map((r) =>
+      r.type === 'required_status_checks' && r.parameters !== undefined
+        ? {
+            ...r,
+            parameters: {
+              ...r.parameters,
+              required_status_checks: [...r.parameters.required_status_checks]
+                .reverse()
+                .map((c) => ({
+                  ...c,
+                  integration_id: null,
+                })),
+            },
+          }
+        : r,
+    ),
+  };
+
+  test('a reordered-but-equal live ruleset canonicalizes to a noop', () => {
+    expect(JSON.stringify(canonicalizeWireRuleset(desired))).toBe(
+      JSON.stringify(canonicalizeWireRuleset(matching)),
+    );
+    // Sanity: the RAW (un-canonicalized) forms really do differ in order, so this is not a
+    // vacuous "already identical" comparison.
+    expect(JSON.stringify(desired)).not.toBe(JSON.stringify(matching));
+  });
+
+  test('mutation check: 3 independently changed values give 3 independently non-noop results', () => {
+    const mutations: Record<string, unknown> = {
+      'a dismissed check dropped': {
+        ...matching,
+        rules: matching.rules.map((r) =>
+          r.type === 'required_status_checks'
+            ? { ...r, parameters: { ...r.parameters, required_status_checks: [{ context: 'ci' }] } }
+            : r,
+        ),
+      },
+      'enforcement disabled': { ...matching, enforcement: 'disabled' },
+      'a bypass actor added': {
+        ...matching,
+        bypass_actors: [{ actor_type: 'OrganizationAdmin', bypass_mode: 'always' }],
+      },
+    };
+    let nonNoop = 0;
+    for (const value of Object.values(mutations)) {
+      const same =
+        JSON.stringify(canonicalizeWireRuleset(desired)) ===
+        JSON.stringify(canonicalizeWireRuleset(value));
+      if (!same) nonNoop++;
+    }
+    expect(nonNoop).toBe(Object.keys(mutations).length);
+  });
+});