[#373] 🤖 - Localize Bugbot review publication

[efraespada]

📌 Summary

Localize Bugbot publication surfaces through one destination-aware message catalog. The change keeps en-US as the default, bundles Spanish, supports validated dynamic BCP-47 catalogs with atomic English fallback, and reuses one resolved catalog across each publication run.

---

🎯 Related Issues / Tickets

• Closes [#373] 🤖 - Localize Bugbot review publication #373

---

🧩 Scope of Changes

• Added:
  • A complete Bugbot message catalog for status cards, review snapshots, findings, overflow notices, diagnostics, navigation labels, and resolution notes.
  • Cardinal plural-category validation for localized catalogs.
  • Programmatic API support for locale selection and MessageCatalogResolutionPort injection.
  • Focused catalog, publication, reconciliation, API, architecture, and composition tests.
• Updated:
  • Bugbot analysis, finding publication, reconciliation, and presentation flows to use one resolved catalog.
  • Locale handling to canonicalize issue and pull-request BCP-47 tags independently.
  • Documentation, specifications, coverage budgets, and generated API/action/CLI bundles.
• Removed:
  • Scattered Bugbot publication-specific localization decisions and mixed-catalog rendering paths.
• Refactored:
  • Publication orchestration to resolve presentation copy at the shared boundary and skip unnecessary catalog-provider calls on dry-run, skipped, superseded, and no-mutation paths.

---

🛠️ Technical Details

• English (en-US) and Spanish catalogs are bundled locally. Other valid BCP-47 locales are resolved through the provider-neutral MessageCatalogResolutionPort.
• Dynamic catalogs must contain every message and every cardinal plural category required by the target locale. Missing, invalid, or unavailable catalogs fall back atomically to English so a publication never mixes languages.
• The effective locale is selected by destination: issue-only publication uses the issue locale, while verified pull-request publication uses the pull-request locale. Both inherit the repository default when unset.
• One resolved catalog is passed through the full publication and reconciliation run, including the canonical status card, historical review snapshot, inline findings, overflow details, diagnostics, and resolution notes.
• Structured values such as paths, line numbers, symbols, code, identifiers, commands, links, state values, and hidden markers remain locale-neutral.
• Reviewer-generated findings must echo the canonical effective locale in outputLocale; mismatches are rejected before publication.
• The public Bugbot API exposes locale configuration and the catalog-resolution capability without exposing provider credentials or internal runtime aggregates.

---

🔍 How to Test

1. Install the pinned dependencies with pnpm install using Node.js 24 or newer.

2. Run the focused Bugbot and message-catalog tests, including catalog completeness, pluralization, locale fallback, publication reuse, terminal no-call paths, and API validation cases.

3. Run the repository verification suite:

   corepack pnpm@​10.12.4 run typecheck
   corepack pnpm@​10.12.4 run lint
   corepack pnpm@​10.12.4 run test:coverage
   corepack pnpm@​10.12.4 run eval:bugbot
   corepack pnpm@​10.12.4 run build
   corepack pnpm@​10.12.4 run validate:agent-docs
   corepack pnpm@​10.12.4 run validate:docs-page
   corepack pnpm@​10.12.4 run validate:documentation
   corepack pnpm@​10.12.4 run validate:workflows
   corepack pnpm@​10.12.4 run validate:specifications
   git diff --check

4. Verify that the generated action, CLI, API, declaration, specification catalog, and npm-package artifacts remain synchronized.

---

🧪 Test Coverage

• Unit tests
• Integration tests
• End-to-end (E2E) tests
• Manual testing only (explain why)

The branch reports 429 suites and 3,814 tests passing, with all coverage budgets satisfied, including exhaustive coverage for the message catalog and critical Bugbot policies.

---

📸 Screenshots / Recordings (UI changes only)

Not provided; the affected surfaces are generated GitHub Markdown content rather than a client UI.

---

⚠️ Breaking Changes

None.

---

🚀 Deployment Notes

• Requires database migration
• Requires environment variable changes
• Requires feature flag toggle
• No special deployment steps

Details: The generated bundles and declarations are committed with the source changes. Existing configurations continue to default to en-US; locale providers are optional, and unavailable dynamic resolution falls back atomically to English.

---

🔒 Security Considerations

• No security impact
• Input validation changes
• Authentication / authorization changes
• Sensitive data handling changes

Locale keys, BCP-47 tags, catalog schemas, plural categories, and reviewer output locales are validated before analysis or publication. The public API continues to keep credentials inside provider adapters, and catalog resolution does not expose tokens or provider payloads.

---

📈 Performance Impact

• No performance impact
• Improves performance
• Potential performance regression (explain)

A resolved catalog is reused across the publication run, and terminal, dry-run, superseded, skipped, and no-mutation paths avoid unnecessary catalog-provider calls.

---

📝 Notes for Reviewers

Please pay particular attention to the shared catalog boundary and the distinction between destination locale selection and locale-neutral structured values. The status card, historical review content, findings, overflow notices, diagnostics, and resolution notes should all remain consistent within a single run.

---

✅ Checklist

• I have self-reviewed my code
• Code follows project standards and conventions
• Tests have been added or updated
• Documentation has been updated (if applicable)
• No new warnings or lint errors
• Breaking contract changes and required consumer updates are documented

---

📚 Additional Context

The UX keeps the durable GitHub surface compact and semantic: current status and required action appear first, findings are shown when useful, and coverage and recovery details remain collapsible. Existing historical review content is preserved while its live status block is reconciled in the destination locale.

[docs-page]

To preview the documentation for this pull request, visit the following URL:

docs.page/vypdev/copilot~373

Documentation is deployed and generated using docs.page

[codecov-commenter]

Codecov Report

❌ Patch coverage is 97.64151% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.31%. Comparing base (274db40) to head (c24d0b0).
⚠️ Report is 714 commits behind head on develop.

Files with missing lines	Patch %	Lines
...steps/commit/detect_potential_problems_workflow.ts	72.72%	0 Missing and 3 partials ⚠️
.../commit/bugbot/analyze_bugbot_revision_use_case.ts	50.00%	0 Missing and 1 partial ⚠️
.../steps/commit/bugbot/publish_pr_review_comments.ts	92.85%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #373      +/-   ##
===========================================
+ Coverage    90.94%   92.31%   +1.36%     
===========================================
  Files          135      643     +508     
  Lines         6251    16551   +10300     
  Branches      1338     4243    +2905     
===========================================
+ Hits          5685    15279    +9594     
- Misses         172      510     +338     
- Partials       394      762     +368     

Files with missing lines	Coverage Δ
src/api.ts	68.03% <100.00%> (ø)
...pplication/policies/branch_sync_message_catalog.ts	100.00% <ø> (ø)
...plication/policies/bugbot_finding_marker_policy.ts	98.78% <100.00%> (ø)
src/application/policies/bugbot_message_catalog.ts	100.00% <100.00%> (ø)
...plication/policies/bugbot_reconciliation_policy.ts	100.00% <100.00%> (ø)
...tion/policies/bugbot_review_presentation_policy.ts	100.00% <100.00%> (ø)
...cation/policies/resolved_message_catalog_policy.ts	100.00% <100.00%> (ø)
...s/localization/resolve_message_catalog_use_case.ts	100.00% <100.00%> (ø)
...ses/steps/commit/bugbot/apply_detected_findings.ts	100.00% <ø> (ø)
.../commit/bugbot/bugbot_previous_findings_context.ts	100.00% <100.00%> (ø)
... and 23 more

... and 672 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[vypbot]

Current status: Overall coverage is partial; this snapshot does not prove that all of its findings are resolved.
Last reconciled on c24d0b0. See aggregate Bugbot status.

🤖 Bugbot review snapshot

Bugbot reported 1 potential problem when commit ee2693d was analyzed. This snapshot is historical; use the status block above for current state. 1 finding is linked to changed code.

Findings

• high: Spanish catalog fails its own plural-category validation — src/application/policies/bugbot_message_catalog.ts:196

[vypbot]

Bugbot: review incomplete

Current status: The review of c24d0b0 has partial coverage and cannot declare the whole pull request clean.

Action: Inspect the omitted items or reduce the pull request scope. Rerun the review only after changing the scope, limits, or access.

Incomplete coverage

• selection: complete; retained=1
• issue-comments: complete; retained=3
• pull-request-comments: complete; retained=1
• review-threads: complete; retained=1
• diff: partial; retained=24, omitted=41, truncated=2
• previous-findings: complete; retained=0
• human-conversation: partial; retained=1, truncated=1
• rules: complete; retained=0

Pull request · Verified commit · Workflow run