Release groups: resolve add-projects target via server-side lookup (CORE-7241)

[lackstein]

Overview

fossa release-group add-projects resolves its target release by first listing
every release group (GET /api/project_group) and then every release in
the matched group with all of their projects (GET /api/project_group/:id/release),
filtering by title client-side. For organizations with large numbers of release groups
and releases, those responses are large enough to time out.

This change makes the CLI resolve the release group + release titles to their numeric
ids in a single request against a new endpoint, GET /api/cli/project_group/release_lookup,
which filters in the database and returns only the ids. The CLI gates on a new
supportsFasterRGAddProject capability flag from GET /api/cli/organization: when the
connected FOSSA instance advertises it, the CLI uses the lookup; otherwise it falls back
to the existing list-and-filter behavior, so older FOSSA instances are unaffected.

It also drops the now-unused projectGroupReleaseId field from the release update
request. Core determines whether each project is new or an update from its own database,
so the CLI no longer needs to fetch the release's current projects to compute it.

Acceptance criteria

• Against a FOSSA instance that advertises supportsFasterRGAddProject,
  fossa release-group add-projects resolves its target with one lookup request instead
  of listing all release groups and releases, so it no longer times out for large orgs.
• Against instances that do not advertise it, behavior is unchanged.

Testing plan

1. Fast path — against a FOSSA instance running the paired Core change
   (fossas/FOSSA#18308, which returns
   supportsFasterRGAddProject: true), using a full-access API token:

   fossa release-group add-projects --debug \
     --endpoint <core-url> --fossa-api-key <FULL_ACCESS_TOKEN> \
     --title '<release group>' --release '<release>' \
     --project-locator '<locator>' --project-revision '<rev>' --project-branch '<branch>'
   

   Confirm from --debug, and by watching the Core server logs, that it calls
   GET /api/cli/project_group/release_lookup rather than the full GET /api/project_group
   list, and that the projects are added.
2. Fallback path — set supportsFasterRGAddProject: false in routes/cli/v0.ts (and restart
   Core), then run the same command; confirm from --debug and the server logs that it uses
   GET /api/project_group + GET /api/project_group/:id/release, and the result is unchanged.

Risks

• The CLI now always omits projectGroupReleaseId from the update body (it previously sent
  the release id for already-present projects). This is safe because Core computes
  add-vs-update from its own database and never read the field; the paired Core PR removes it
  from the request schema. Worth a reviewer sanity check that the update body is accepted.
• The new path is gated behind the org capability flag; instances without it use the
  unchanged fallback, so there is no behavior change for older FOSSA deployments.

Metrics

Not tracked by the CLI. The change reduces API payload size and request count for
add-projects (two list calls -> one id lookup), which is what eliminates the timeouts.

References

• CORE-7241: Faster release-group add-projects.
• Paired Core PR (endpoint + supportsFasterRGAddProject flag): fossas/FOSSA#18308.

Checklist

• I added tests for this PR's change. (AddProjectsSpec covers both the lookup and fallback paths.)
• User-visible docs: no interface change — same command and flags, just faster — so no docs/ change.
• Docs ToC: n/a (no docs added).
• Externally visible -> Changelog.md: added an ## Unreleased entry.
• .fossa.yml / fossa-deps: not changed.
• Subcommand options: release-group add-projects flags are unchanged, so no docs/references/subcommands update.

[coderabbitai]

Walkthrough

Adds a faster server-side lookup path for fossa release-group add-projects that resolves release-group and release IDs via a single API call (resolveReleaseGroupRelease), gated by a new orgSupportsFasterReleaseGroupAddProjects Organization flag obtained via getOrganization. Falls back to existing client-side listing when unsupported. Adds a new ReleaseGroupReleaseLookup type and endpoint, removes targetReleaseGroupId from UpdateReleaseProjectRequest, updates the FossaApiClient effect/carrier, and updates related tests, fixtures, and the changelog.

Changes

Cohort / File(s)	Summary
Types & flag — src/Fossa/API/CoreTypes.hs, src/Fossa/API/Types.hs	Adds ReleaseGroupReleaseLookup type with FromJSON; removes targetReleaseGroupId from UpdateReleaseProjectRequest; adds orgSupportsFasterReleaseGroupAddProjects field to Organization
API client wiring — Control/Effect/FossaApiClient.hs, Control/Carrier/FossaApiClient.hs, Internal/Core.hs, Internal/FossaAPIV1.hs	New ResolveReleaseGroupRelease effect, interpreter case, Core wrapper, and FossaAPIV1 GET endpoint implementation
Command logic — src/App/Fossa/ReleaseGroup/AddProjects.hs, Changelog.md	addProjectsMain branches on org capability; refactors constructUpdateRequest/constructUpdateProjectRequest; adds changelog entry
Tests & fixtures — test/Test/MockApi.hs, test/Test/Fixtures.hs, test/App/Fossa/API/BuildLinkSpec.hs, test/App/Fossa/ReleaseGroup/AddProjectsSpec.hs	Mock support for new effect, fixture updates, and specs covering fast and fallback paths

Sequence Diagram(s)

sequenceDiagram
  participant AddProjectsMain
  participant FossaApiClient
  participant Core
  participant FossaAPIV1

  AddProjectsMain->>FossaApiClient: getOrganization
  FossaApiClient-->>AddProjectsMain: Organization

  alt orgSupportsFasterReleaseGroupAddProjects = True
    AddProjectsMain->>FossaApiClient: resolveReleaseGroupRelease(rgTitle, releaseTitle)
    FossaApiClient->>Core: resolveReleaseGroupRelease
    Core->>FossaAPIV1: resolveReleaseGroupRelease
    FossaAPIV1-->>Core: ReleaseGroupReleaseLookup
    Core-->>AddProjectsMain: releaseGroupId, releaseId
  else fallback
    AddProjectsMain->>FossaApiClient: getReleaseGroups
    AddProjectsMain->>FossaApiClient: getReleaseGroupReleases
    FossaApiClient-->>AddProjectsMain: releaseGroupId, releaseId
  end

  AddProjectsMain->>FossaApiClient: updateReleaseGroupRelease(payload)
  FossaApiClient-->>AddProjectsMain: updated release

Loading

Related PRs: None identified.

Suggested labels: enhancement, api

Suggested reviewers: None identified.

Poem: A rabbit hopped down the lookup road,
one request instead of a heavy load,
groups and releases now found with ease,
a flag says "faster!" whenever you please,
tests hop along, the changelog too — 🐇 all checked and ready for you.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: faster release-group add-projects via server-side lookup.
Description check	✅ Passed	The description includes all required sections with concrete overview, testing, risks, metrics, references, and checklist items.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/App/Fossa/ReleaseGroup/AddProjects.hs`:
- Around line 33-53: Add test coverage for the server-side lookup failure path
in AddProjectsSpec by exercising the orgSupportsFasterReleaseGroupAddProjects
branch in AddProjects and asserting the behavior when resolveReleaseGroupRelease
fails or returns no match. Reuse the existing fast-lookup setup around
ResolveReleaseGroupRelease and verify the error-handling path matches the
intended fatal/context behavior, similar to the existing fallback failure tests
for retrieveReleaseGroupId and retrieveReleaseGroupRelease.

In `@test/App/Fossa/API/BuildLinkSpec.hs`:
- Around line 45-61: The test fixtures in BuildLinkSpec still construct
Organization with a long positional list of fields, which is brittle and
obscures the intent of orgSupportsFasterReleaseGroupAddProjects. Update the org
values in the affected getBuildURLWithOrg tests to use named-field record syntax
for Organization, keeping the same field values but making the relevant flag
explicit and easier to maintain as Organization evolves.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro

Run ID: bc9866f2-dff3-40e1-995c-282fc6958fc2

📥 Commits

Reviewing files that changed from the base of the PR and between af39d82 and 5b6b49f.

📒 Files selected for processing (12)

• Changelog.md
• src/App/Fossa/ReleaseGroup/AddProjects.hs
• src/Control/Carrier/FossaApiClient.hs
• src/Control/Carrier/FossaApiClient/Internal/Core.hs
• src/Control/Carrier/FossaApiClient/Internal/FossaAPIV1.hs
• src/Control/Effect/FossaApiClient.hs
• src/Fossa/API/CoreTypes.hs
• src/Fossa/API/Types.hs
• test/App/Fossa/API/BuildLinkSpec.hs
• test/App/Fossa/ReleaseGroup/AddProjectsSpec.hs
• test/Test/Fixtures.hs
• test/Test/MockApi.hs

[nficca]

Looks good to me.

[nficca]

[nit] is there a reason why we abbreviate this one while the others are fully spelled out?

[lackstein]

It's abbreviated in the API response, but it seemed like most other variables in the CLI are expanded so I just went with the flow.