feat: add conditional merge-ff strategy

[coleleavitt]

Summary

• add mergeMethod: merge-ff
• hard-reset only when the destination has no unique commits
• normally merge genuinely diverged histories
• compare immutable SHAs, refresh PR state, lease ref mutations, and fail closed for unsafe topology or races
• add topology, race, API-failure, schema, and documentation coverage

Verification

• deno task check
• deno task test (43 passed)
• git diff --check

Fixes #448.

Summary by CodeRabbit

• New Features

  • Added support for the merge-ff merge method.
  • Fast-forwards destinations without unique commits and merges normally when histories have diverged.
  • Operations now verify branch state before updating and fail safely when it changes unexpectedly.

• Documentation

  • Documented the merge-ff option, behavior, and configuration guidance.

• Tests

  • Added coverage for fast-forward updates, diverged histories, validation failures, and error handling.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 71f3dd18-d648-4217-b795-bd7de8995b0c

📥 Commits

Reviewing files that changed from the base of the PR and between 197574c and 8f9287e.

📒 Files selected for processing (7)

• .github/CONTRIBUTING.md
• README.md
• deno.json
• src/processor/pull.test.ts
• src/processor/pull.ts
• src/utils/schema.test.ts
• src/utils/schema.ts

Included review availability: Your plan provides up to 8 included reviews per hour; 1 remains after this review.

---

📝 Walkthrough

Walkthrough

Changes

The pull processor now supports merge-ff. It validates the current pull request, compares immutable commit SHAs, atomically resets the destination when possible, and performs a SHA-pinned merge for diverged histories. Configuration, documentation, tests, and test permissions were updated.

merge-ff processing

Layer / File(s)	Summary
merge-ff configuration contract src/utils/schema.ts, src/utils/schema.test.ts, README.md, .github/CONTRIBUTING.md	The configuration schema accepts merge-ff. Documentation describes reset behavior for fast-forwardable histories and normal merges for diverged histories.
merge-ff processing flow src/processor/pull.ts	processMerge routes merge-ff to processMergeFf. The new method validates the PR snapshot, compares immutable SHAs, uses an atomic GraphQL ref update for reset cases, and passes the exact head SHA to diverged merges.
merge-ff validation and test execution src/processor/pull.test.ts, deno.json	Tests cover reset, merge, fail-closed, error, and changed-snapshot paths. The test task adds hostname system permission.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Pull
  participant GitHub
  participant Destination
  Pull->>GitHub: Refresh and validate the open pull request
  Pull->>GitHub: Compare immutable base and destination SHAs
  alt Destination has no unique commits
    Pull->>Destination: Atomically update the ref with beforeOid
  else Histories diverge
    Pull->>GitHub: Merge with the exact head SHA
  end

Loading

Merge Risk: ⚪ Minimal · up to 8f928

The new merge method has no established merge-blocking risk and is ready for normal merge checks.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 4 files. (3 skipped: 3 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: adding a conditional merge-ff merge strategy.
Linked Issues check	✅ Passed	Issue #448 requires merge-ff to hard-reset when the destination has no unique commits and to use a regular merge for diverged histories. The PR adds the merge-ff schema value, documents it, and im…
Out of Scope Changes check	✅ Passed	The changes remain within issue #448 scope. Schema and README updates expose the new method. Tests cover its topology, race, API-failure, and safety behavior. The deno.json permission change support…

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 4 files. (3 skipped: 3 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}