fix: honor includeReferences parameter

[3rabiii]

Summary

Fixes a spec gap where the vehicles-for-agency endpoint ignored the includeReferences parameter and always populated the references block.

Problem

The spec states that passing includeReferences=false should omit the references block to reduce payload size. The handler was unconditionally building and returning all references (agencies, routes, trips, situations), wasting both bandwidth and server resources.

Changes

• Wrapped the references population logic in the existing ShouldIncludeReferences(r) helper.
• When false, the response now correctly returns empty arrays for the references block using models.NewEmptyReferences().
• Database queries for alerts/situations are now correctly bypassed when references are excluded, improving performance.
• Added test coverage for includeReferences=false (asserting empty references) and true/absent (asserting populated references using table-driven tests).

Closes #1104

Summary by CodeRabbit

• Bug Fixes
  • Vehicle list responses now respect the includeReferences option, returning reference data only when requested.
  • When reference data is disabled, the response still includes vehicles but leaves related reference sections empty.
  • Alerts and situation details are no longer fetched or added unless reference data is included.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: f9a30726-f577-4190-ba1a-54bc06bf5a5a

📥 Commits

Reviewing files that changed from the base of the PR and between c298c6e and e12e3a6.

📒 Files selected for processing (2)

• internal/restapi/vehicles_for_agency_handler.go
• internal/restapi/vehicles_for_agency_handler_test.go

---

📝 Walkthrough

Walkthrough

The vehicles-for-agency handler now conditionally populates references based on includeReferences. When false, the response keeps the vehicle list and returns empty reference collections. Tests cover false, absent, and true query values.

Changes

Vehicles-for-agency reference gating

Layer / File(s)	Summary
Handler reference gating internal/restapi/vehicles_for_agency_handler.go	Reference construction, alert deduplication, and situation references run only when ShouldIncludeReferences(r) is true; otherwise an empty references object is returned.
Query handling tests internal/restapi/vehicles_for_agency_handler_test.go	Tests assert empty references for includeReferences=false and populated references for the absent and true cases.

Sequence Diagram(s)

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• OneBusAway/maglev#1019: Applies the same includeReferences gating pattern in another handler.
• OneBusAway/maglev#1068: Also conditions references population on includeReferences in a REST handler.

Suggested reviewers

• burma-shave
• aaronbrethorst

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	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 is concise and accurately states the main change.
Linked Issues check	✅ Passed	The handler now honors includeReferences=false and returns empty references, with tests covering false, true, and absent cases.
Out of Scope Changes check	✅ Passed	The changes stay focused on includeReferences handling and the associated tests, with no clear unrelated additions.

✨ 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.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud