feat: add NATS lookup function for v1-v2 mapping queries

[emsearcy]

Description

Implements lfx.lookup_v1_mapping NATS function for bidirectional v1↔v2 ID mapping lookups as specified in LFXV2-1011.

Changes

Core Implementation

• NATS Queue Subscription: Uses natsConn.QueueSubscribe pattern for scalable request handling
• Bidirectional Lookup: Supports both v1→v2 and v2→v1 mapping queries based on key format
• Error Handling: Returns "error: {message}" for NATS/service errors, empty string for not found
• Tombstone Support: Handles deleted mappings gracefully by returning empty string

Files Changed

• cmd/lfx-v1-sync-helper/main.go: Added subscription to lfx.lookup_v1_mapping subject
• cmd/lfx-v1-sync-helper/lookup_handler.go: New handler implementing the lookup logic
• README.md: Comprehensive documentation with lookup patterns table and error handling guide

Supported Lookup Patterns

• Projects: project.sfid.{v1_sfid} ↔ project.uid.{v2_uuid}
• Committees: committee.sfid.{v1_sfid} ↔ committee.uid.{v2_uuid}
• Committee Members: committee_member.sfid.{v1_sfid} ↔ committee_member.uid.{v2_uuid}

Technical Details

The function:

1. Receives mapping key as request payload
2. Queries v1-mappings NATS KV bucket
3. Returns mapped value, empty string (not found), or error response
4. Handles tombstoned mappings by returning empty string

Testing

• ✅ Code compiles successfully
• ✅ Follows existing code patterns and error handling
• ✅ Documentation includes comprehensive usage examples

JIRA

LFXV2-1011: Create NATS lookup function for v1-v2 mapping

[Copilot]

Pull request overview

This PR implements a NATS request/reply function (lfx.lookup_v1_mapping) that enables bidirectional lookup of v1↔v2 ID mappings for projects, committees, and committee members. The implementation adds a scalable queue subscription handler that queries the existing v1-mappings NATS KV bucket and returns the mapped value, empty string for not found/deleted cases, or error messages for failures.

Changes:

• Added NATS queue subscription for the lfx.lookup_v1_mapping subject with scalable request handling
• Implemented lookup handler with proper error handling, tombstone support, and consistent logging
• Documented the API with comprehensive lookup pattern tables and response format specifications

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
cmd/lfx-v1-sync-helper/main.go	Added constants for queue and subject names, and registered the QueueSubscribe handler for the lookup function
cmd/lfx-v1-sync-helper/lookup_handler.go	New handler implementing bidirectional mapping lookups with error handling and tombstone support
README.md	Added comprehensive NATS API documentation including request/reply format, lookup patterns table, and error handling guide

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bramwelt]

Overall this looks good. There's two CI issues I see from Megalinter:

1. Missing package comment
2. stdlib security vulnerability: This appears to be an issue with megalinter, as we have Golang set to 1.25.6 in the go.mod file.

The first is a simple fix - I can approve once that's added. The second is unrelated and can be address in a separate PR (may take some fighting with megalinter).

[emsearcy]

Thanks for the review—PTAL again.

(Yeah, I also tried bumping the Megalinter release (this one is pinned) and it still didn't help.)

edited to say - I just realized my push hadn't gone through yet when I requested the review, but the commit is there now (366a48c) for the missing package comment

[emsearcy]

and now grype isn't complaining about stdlib, either. 🤷