Skip to content

fix(#6337): add SHA ancestry check to upgrade downgrade guard - #6338

Merged
ggallen merged 3 commits into
mainfrom
agent/6337-sha-downgrade-guard
Aug 18, 2026
Merged

ggallen merged 3 commits into
mainfrom
agent/6337-sha-downgrade-guard

Conversation

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor

Summary

Add SHA-based downgrade detection to the repos upgrade command. The existing semver downgrade guard only applied when both the current and target refs were semver tags — SHA-pinned repos bypassed the guard entirely, allowing silent scaffold downgrades.

Related Issue

Changes

  • Add CompareCommits method to forge.Client interface with implementations for GitHub (REST compare API) and GitLab (repository compare endpoint)
  • Add FakeClient.CommitAncestry map for testing commit ancestry in the test double
  • Add RefResolver.IsAncestor method that uses CompareCommits to check git ancestry on fullsend-ai/fullsend
  • Add SHA downgrade guard in upgradeRepo() after the existing semver guard — resolves both refs to SHAs (if needed) and uses ancestry checking to detect downgrades
  • API errors degrade gracefully: if the compare call fails, the upgrade proceeds rather than blocking
  • The --force flag bypasses the SHA guard, matching the semver guard behavior

Testing

  • TestUpgrade_SHADowngradeBlocked — both refs are SHAs, target is ancestor → skipped with downgrade message
  • TestUpgrade_SHADowngradeForceAllowed — --force bypasses SHA downgrade guard
  • TestUpgrade_SHAUpgradeProceeds — target is descendant of current → upgrade proceeds
  • TestUpgrade_SHADowngradeCompareErrorProceeds — API error degrades gracefully, upgrade proceeds
  • TestUpgrade_SHACurrentTagTargetDowngradeBlocked — SHA current + tag target → tag resolved to SHA, downgrade detected
  • All existing upgrade tests pass (no regressions)

Closes #6337

Post-script verification

  • Branch is not main/master (agent/6337-sha-downgrade-guard)
  • Secret scan passed (gitleaks — 9ecbd9b395b0e00a10f2a959b7e83503ff718bd1..HEAD)
  • PR body secret scan passed (gitleaks — no-git)

@fullsend-ai-coder
fullsend-ai-coder Bot requested a review from a team August 18, 2026 18:57
@fullsend-ai-coder fullsend-ai-coder Bot added the ready-for-review Triggers review agent dispatch label Aug 18, 2026
@fullsend-ai-review

fullsend-ai-review Bot commented Aug 18, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 7:00 PM UTC · Completed 7:18 PM UTC

Commit: cda6ada · View workflow run →

@codecov

codecov Bot commented Aug 18, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 91.30435% with 6 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
internal/forge/github/github.go 77.77% 1 Missing and 1 partial ⚠️
internal/forge/gitlab/repo.go 93.33% 1 Missing and 1 partial ⚠️
internal/repos/ref_resolve.go 71.42% 1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

@fullsend-ai-review

fullsend-ai-review Bot commented Aug 18, 2026 •

Copy link
Copy Markdown

Looks good to me

Previous run

Review

Findings

Low

  • [api-contract] internal/forge/gitlab/repo.go:461 — GitLab CompareCommits returns "ahead" for diverged commits. When both base and head have unique commits (truly diverged history), the forward compare call returns non-empty commits (those reachable from head but not base), causing the method to return "ahead" instead of "diverged". This does not cause a bug in the current codebase because IsAncestor always uses the GitHub client (fullsend-ai/fullsend is hosted on GitHub), but a future caller of GitLab's CompareCommits would get incorrect results when base and head have diverged.
    Remediation: Either always make both forward and reverse calls (returning "diverged" when both directions have commits), or add a doc comment noting that the GitLab implementation may return "ahead" for diverged histories.

  • [incomplete-coverage] docs/guides/getting-started/repo-management.md:321 — Documentation states "Downgrades are blocked unless --force is set" but does not explain the behavior when both current and target refs are SHAs. The PR adds SHA-based downgrade detection via git ancestry checking (CompareCommits + IsAncestor), which provides more sophisticated detection than simple semver comparison. Users upgrading from a SHA-pinned ref to another SHA, or from SHA to tag (or vice versa), now benefit from ancestry-based downgrade protection, but this enhancement is not documented.
    Remediation: Expand the downgrade protection documentation to explain that downgrade detection works for both semver-tagged refs and SHA-pinned refs.


Labels: PR is a bug fix for SHA-pinned scaffold downgrade detection

Previous run (2)

Review

Findings

Medium

  • [api-contract] internal/forge/gitlab/repo.go:449 — GitLab CompareCommits never returns "behind". When head is an ancestor of base, the GitLab compare API returns 0 commits but non-empty diffs, causing the implementation to return "diverged" instead of "behind". The doc comment claims "we make two calls to determine the full relationship when needed" but only one API call is made. Currently the sole consumer (IsAncestor) only checks for "ahead" so this does not cause a runtime bug, but any future consumer distinguishing "behind" from "diverged" would get incorrect results.
    Remediation: Either add the reverse comparison call (from=head, to=base), returning "behind" when commits exist in the reverse direction; or update the interface contract doc to note that GitLab may not distinguish "behind" from "diverged" and remove the misleading "two calls" comment.

Low

  • [error-handling-idiom] internal/repos/ref_resolve.go:70 — IsAncestor returns the raw error from CompareCommits without wrapping. While the underlying implementations already provide context, adding a local wrap (e.g., fmt.Errorf("ancestor check %s...%s: %w", ...)) would aid debugging when the call site is not immediately obvious in stack traces.

  • [test-coverage-gap] internal/repos/upgrade_test.go — No test covers the tag-current/SHA-target case (tag-pinned currentRef with SHA targetRef). The existing TestUpgrade_SHACurrentTagTargetDowngradeBlocked covers the reverse (SHA-current/tag-target), but the tag-current path exercises resolver.Resolve on currentRef which is a distinct code path.


Labels: PR fixes the repos upgrade downgrade guard, which is part of the install/upgrade component

@fullsend-ai-review fullsend-ai-review Bot added requires-manual-review Review requires human judgment component/install CLI install and app setup labels Aug 18, 2026
@ggallen

ggallen commented Aug 18, 2026

Copy link
Copy Markdown
Member

/fs-fix - Rebase. Fix all the review issues, respond to and resolve all conversations, and fix the CI code coverage test.

@fullsend-ai-coder

fullsend-ai-coder Bot commented Aug 18, 2026 •

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 7:22 PM UTC · Completed 7:34 PM UTC

Commit: cda6ada · View workflow run →

The semver downgrade guard in upgradeRepo() was gated on both refs
being semver tags. When either ref is a SHA — the case for
SHA-pinned repos and all GitLab repos — the guard was bypassed
entirely, allowing silent downgrades.

Add a CompareCommits method to the forge.Client interface that
maps to the GitHub Compare API (and GitLab's equivalent). Use it
in a new RefResolver.IsAncestor method to detect when the target
SHA is an ancestor of the current SHA. The upgrade logic now
checks SHA ancestry after the semver guard, skipping with the
same "is a downgrade (use --force to allow)" message. API errors
degrade gracefully — the upgrade proceeds if the comparison fails.

Closes #6337
- Fix GitLab CompareCommits to properly detect "behind" status by adding
  a reverse comparison call when the forward comparison shows diffs but
  no commits, and update the doc comment to accurately describe the
  two-call behavior (api-contract finding)
- Wrap error in RefResolver.IsAncestor with context for easier debugging
  (error-handling-idiom finding)
- Add TestUpgrade_TagCurrentSHATargetDowngradeBlocked to cover the
  tag-current/SHA-target code path (test-coverage-gap finding)
- Add unit tests for CompareCommits in fake, github, and gitlab packages
  to bring patch coverage above the 80% threshold

Addresses review feedback on #6338
@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 Fix agent — iteration 1 (human-triggered)

Addressed all 3 review findings (api-contract, error-handling-idiom, test-coverage-gap) and fixed CI code coverage by adding unit tests for CompareCommits across all forge implementations. Rebased onto main. All functions in changed files show >=83% coverage, well above the 80% threshold.

Fixed (7):

  1. GitLab CompareCommits never returns behind and has misleading two-calls comment (internal/forge/gitlab/repo.go): Added reverse comparison call (from=head, to=base) when forward comparison shows diffs but no commits, enabling proper behind detection. Extracted compareOnce helper and updated doc comment to accurately describe the two-call behavior.
  2. IsAncestor returns raw error without wrapping (internal/repos/ref_resolve.go): Wrapped CompareCommits error with fmt.Errorf providing ancestor check context (potentialAncestor...descendant) for easier debugging.
  3. No test for tag-current/SHA-target downgrade case (internal/repos/upgrade_test.go): Added TestUpgrade_TagCurrentSHATargetDowngradeBlocked covering the code path where currentRef is a semver tag and targetRef is a SHA, exercising resolver.Resolve on currentRef.
  4. CI code coverage at 32.72%, needs 80% (internal/forge/fake_test.go): Added TestFakeClient_CompareCommits with subtests for happy path, missing entry, nil map, and error injection, covering all FakeClient.CompareCommits lines.
  5. CI code coverage at 32.72%, needs 80% (internal/forge/github/github_test.go): Added TestCompareCommits with httptest server subtests for successful response and API failure, covering GitHub LiveClient.CompareCommits lines.
  6. CI code coverage at 32.72%, needs 80% (internal/forge/gitlab/gitlab_test.go): Added TestCompareCommits with httptest server subtests for ahead, identical, behind (two-call), diverged, API failure, and reverse-call degradation, covering all GitLab CompareCommits and compareOnce lines.
  7. Rebase onto main: Rebased branch onto origin/main to incorporate latest changes.

Tests: passed

Next steps:

  • /fs-review — request a re-review of the changes
  • /fs-fix <your instruction> — run another fix pass with specific guidance
  • Push commits directly — review re-runs automatically on push
    Updated by fullsend fix agent

@fullsend-ai-coder
fullsend-ai-coder Bot force-pushed the agent/6337-sha-downgrade-guard branch from cda6ada to 6d066ea Compare August 18, 2026 19:34
@fullsend-ai-review

fullsend-ai-review Bot commented Aug 18, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 7:36 PM UTC · Completed 7:49 PM UTC

Commit: 6d066ea · View workflow run →

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-review fullsend-ai-review Bot added ready-for-merge All reviewers approved — ready to merge type/bug Confirmed defect in existing behavior and removed requires-manual-review Review requires human judgment labels Aug 18, 2026
@ggallen

ggallen commented Aug 18, 2026

Copy link
Copy Markdown
Member

/fs-fix - Rebase. Fix all the review issues, respond to and resolve all conversations.

@fullsend-ai-coder

fullsend-ai-coder Bot commented Aug 18, 2026 •

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 7:55 PM UTC · Completed 8:04 PM UTC

Commit: 6d066ea · View workflow run →

- Fix GitLab CompareCommits to correctly detect diverged commits by
  always making both forward and reverse API calls when the forward
  call returns any diffs or commits. Previously, forward commits caused
  an early "ahead" return, masking truly diverged histories where both
  directions have unique commits.
- Add test for diverged-with-commits-both-directions and update ahead
  test to verify both API calls are made.
- Document SHA-based downgrade detection in repo-management guide,
  explaining that ancestry checking via the forge API covers SHA-pinned
  and mixed (SHA/tag) refs with graceful degradation on API errors.

Addresses review feedback on #6338
@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 Fix agent — iteration 2 (human-triggered)

Addressed all 2 review findings (api-contract, incomplete-coverage). Fixed GitLab CompareCommits to correctly detect diverged commits by always making both forward and reverse API calls, added test coverage for the new behavior, and documented SHA-based downgrade detection in the repo-management guide.

Fixed (3):

  1. GitLab CompareCommits returns ahead for diverged commits (internal/forge/gitlab/repo.go): Restructured CompareCommits to always make both forward and reverse API calls when the forward call returns any diffs or commits. A single forward call cannot distinguish ahead from diverged because both cases return non-empty commits. Now when both directions have commits, the method correctly returns diverged. Updated doc comment to accurately describe the two-call behavior and the ambiguity it resolves.
  2. GitLab CompareCommits diverged test coverage (internal/forge/gitlab/gitlab_test.go): Added diverged-when-both-directions-have-commits test case and updated ahead test to verify both forward and reverse API calls are made, matching the new always-two-call behavior.
  3. Documentation does not explain SHA-based downgrade detection (docs/guides/getting-started/repo-management.md): Expanded the downgrade protection paragraph to explain that when either ref is a SHA (or a mix of SHA and tag), the guard resolves both to commit SHAs and uses git ancestry checking via the forge API, with graceful degradation on API errors.

Tests: passed

Next steps:

  • /fs-review — request a re-review of the changes
  • /fs-fix <your instruction> — run another fix pass with specific guidance
  • Push commits directly — review re-runs automatically on push
    Updated by fullsend fix agent

@fullsend-ai-review

fullsend-ai-review Bot commented Aug 18, 2026 •

Copy link
Copy Markdown

🤖 Review · ❌ Terminated · Started 8:06 PM UTC · Ended 8:20 PM UTC

Commit: bcab803 · View workflow run →

@github-actions

Copy link
Copy Markdown

Site preview

Preview: https://155822f5-site.fullsend-ai.workers.dev

Commit: bcab8034b2e79b1f59f193363459aa2088d33be4

@fullsend-ai-review

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 8:06 PM UTC · Completed 8:20 PM UTC

Commit: bcab803 · View workflow run →

@ggallen
ggallen enabled auto-merge August 18, 2026 20:22
@ggallen
ggallen added this pull request to the merge queue Aug 18, 2026
Merged via the queue into main with commit 37c90aa Aug 18, 2026
21 of 24 checks passed
@ggallen
ggallen deleted the agent/6337-sha-downgrade-guard branch August 18, 2026 20:47
@fullsend-ai-retro

fullsend-ai-retro Bot commented Aug 18, 2026 •

Copy link
Copy Markdown

🤖 Finished Retro · ❌ Failure · Started 8:50 PM UTC · Completed 8:50 PM UTC

Commit: bcab803 · View workflow run →

This branch was successfully deployed

1 active deployment
site-preview — bcab8034 Deployed Aug 18, 2026 by github-actions[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

component/install CLI install and app setup ready-for-merge All reviewers approved — ready to merge ready-for-review Triggers review agent dispatch type/bug Confirmed defect in existing behavior

Projects

None yet

Development

Successfully merging this pull request may close these issues.

repos upgrade silently downgrades SHA-pinned scaffolds (semver guard doesn't cover SHA refs)

1 participant