feat(medications): smarter catalog search for typos and brand names

[BigSimmo]

Summary

• Medication-mode submitted search (GET /api/medications?q=) now runs a catalog-local query normalizer for common typos, brand↔generic expansion, and conservative edit-distance-1 near-misses.
• Prescription Brand Names are scored at name weight in rankMedicationRecords, so queries like campral / zoloft hit like generics rather than weak content matches.
• Medications typeahead domain uses the same catalog normalizer; clinical-search / RAG analysis tables are untouched.
• API responses may include additive interpretation (correctedQuery / corrections / appliedExpansions) for a future “Did you mean” chip.

Verification

• npm run test — 547 files / 5899 passed | 4 skipped (on feature commit)
• tests/medications.test.ts + tests/medications-route.test.ts — 49 passed after origin/main sync
• git merge-tree --write-tree origin/main HEAD — clean; GitHub mergeable: true after sync
• npm run verify:pr-local — not run; unit suite covers the changed catalog/query/route contracts
• UI verification not run: no production UI chrome/layout change; only the Playwright demo API mock was aligned with the catalog path
• Provider/RAG checks not run: no RAG retrieval/ranking surface changed (ragRanking: false)

Risk and rollout

• Risk: Over-eager typo correction could surface the wrong medication. Mitigated by curated typo map + edit-distance 1 only, token length ≥ 6, and unique-candidate requirement (ties → no correction).
• Rollback: Revert this PR; /api/medications returns to raw-query ranking.
• Provider or production effects: None

Clinical Governance Preflight

• Source-backed claims still require linked source verification before clinical use
• No patient-identifiable document workflow was introduced or expanded without explicit governance approval
• Supabase target remains Clinical KB Database (sjrfecxgysukkwxsowpy)
• Service-role keys and private document access remain server-only
• Demo/synthetic content remains clearly separated from real clinical sources
• Source metadata, review status, and outdated/unknown-source behavior remain conservative
• Deployment classification/TGA SaMD impact was checked when clinical decision-support behavior changed — catalog search recall only; no CDS/answer-generation change

Notes

• Follow-ups not in this PR: “Did you mean” chip in MedicationPrescribingWorkspace, brand subtitle on result rows, growing the local typo map from real misses.

Summary by CodeRabbit

• New Features

  • Improved medication search with brand-name matching, generic and alias expansion, and typo correction.
  • Search results now explain applied corrections and query expansions.
  • Medication index results provide streamlined data while preserving brand information.

• Bug Fixes

  • Reduced false-positive matches for similar medication names.
  • Improved handling of medication brand names and search aliases.
  • Preserved consistent results when shared search corrections are applied.

• Tests

  • Added coverage for brand searches, typo correction, aliases, index responses, and search safeguards.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in:33 minutes

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 9ebdcb27-fe78-495e-b8f8-bf1adb706479

📥 Commits

Reviewing files that changed from the base of the PR and between 88dbdd8 and 2d93557.

📒 Files selected for processing (2)

• docs/branch-review-ledger.md
• tests/ui-tools.spec.ts

📝 Walkthrough

Walkthrough

The medication catalog now supports brand-aware ranking, typo correction, brand–generic expansion, and query interpretation. Medication API and universal search responses use catalog analysis and preserve brand names in indexed projections. Tests cover parsing, ranking, corrections, expansions, and response shapes.

Changes

Medication catalog search

Layer / File(s)	Summary
Brand extraction and ranking src/lib/medications.ts, src/lib/medication-entities.ts, tests/medications.test.ts	Brand names are parsed from formulation sections, added to search fields, ranked with medication names, and reported with the brand reason. Tests cover parsing and brand matching.
Catalog query analysis and search src/lib/medication-query.ts, tests/medications.test.ts	Catalog queries support curated and conservative fuzzy corrections, brand–generic expansion, alias expansion, bounded terms, and interpretation metadata.
API and universal-search integration src/app/api/medications/route.ts, src/lib/universal-search.ts, tests/medications-route.test.ts, tests/ui-smoke.spec.ts, tests/universal-search.test.ts	Medication endpoints and universal search rank full records, return interpretations, and preserve brand-only rows in index projections. Integration tests validate these flows and response shapes.
Review ledger records docs/branch-review-ledger.md	The ledger records the medication search stages and reorders related entries chronologically.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
participant Client
participant MedicationsAPI
participant searchMedicationCatalog
participant analyzeMedicationCatalogQuery
participant MedicationRanker
Client->>MedicationsAPI: Search medication query
MedicationsAPI->>searchMedicationCatalog: Full medication records and query
searchMedicationCatalog->>analyzeMedicationCatalogQuery: Analyze corrections and expansions
analyzeMedicationCatalogQuery-->>searchMedicationCatalog: Query analysis
searchMedicationCatalog->>MedicationRanker: Rank corrected query and expansions
MedicationRanker-->>searchMedicationCatalog: Ranked medication matches
searchMedicationCatalog-->>MedicationsAPI: Matches and interpretation
MedicationsAPI-->>Client: Medication records and query interpretation

Loading

Possibly related PRs

• BigSimmo/Database#658: Both changes modify universal medication-search ranking behavior.
• BigSimmo/Database#1485: Both changes modify medication catalog search and related UI behavior.
• BigSimmo/Database#808: Both changes affect medication search result placement and rendering.

Suggested reviewers:claude

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is well structured but omits the required retrieval-quality evaluation for changed medication search and ranking behavior.	Run npm run eval:retrieval:quality, confirm 36/36, and paste the result or document a specific reason the verification could not run.
Docstring Coverage	⚠️ Warning	Docstring coverage is 24.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the medication catalog search improvements for typos and brand names.
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.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/smarter-meds-search-9c1b

---

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

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:adb437563f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[BigSimmo]

@codex resolve actionable Codex review findings for this pull request and current head using the repository instructions. This is the pull request's single automatic repair pass: do not perform a fresh review, create new standalone findings, or request another review. Work only the existing unresolved Codex threads on the current head. The only repository destination is BigSimmo/Database, and the only branch destination is the pull request head branch cursor/smarter-meds-search-9c1b at starting commit cfb5dc8; never publish fixes to a detached or synthetic work branch and never create a stacked pull request. Use the authenticated GitHub connector to commit each approved fix to BigSimmo/Database:cursor/smarter-meds-search-9c1b, then verify that the pull request head contains the published commit before reporting success. Always fix P0 and P1 findings. For P2 and lower findings, fix only clear, scoped, low-risk issues; otherwise disposition them with a concise reason. For a fixed thread, reply with as the first line and as the second line. For a no-code disposition, use followed by . These result markers authorize the workflow to close that exact thread only after it verifies a fixed commit is the pull request head; a local-only commit is not a fix. If publication or verification fails, do not use either result marker, do not claim success, and leave the thread open with the blocker. If human input or new authorization is required, do the same. Finish only after every actionable thread is fixed or dispositioned and closed, or explicitly left open for a human decision. Do not update the branch from main, address unrelated reviews, broaden scope, or create more than one scoped fix commit. Do not use external APIs, paid services, credentials, dependency changes, or broad refactors unless explicitly authorized. Add targeted tests where behavior changes and run the narrowest relevant validation.

[Copilot]

Pull request overview

Adds catalog-local medication search normalization for typos, brand names, and conservative near-matches.

Changes:

• Adds medication query analysis and brand-aware ranking.
• Applies normalized search to the API and universal search.
• Adds route, catalog, and Playwright mock coverage.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/lib/medication-query.ts	Implements catalog query normalization.
src/lib/medications.ts	Extracts and ranks brand names.
src/app/api/medications/route.ts	Returns normalized matches and interpretation.
src/lib/universal-search.ts	Applies normalization to medication typeahead.
src/lib/medication-entities.ts	Clarifies alias usage.
tests/medications.test.ts	Tests normalization and brand ranking.
tests/medications-route.test.ts	Tests API behavior.
tests/ui-smoke.spec.ts	Aligns the demo API mock.
docs/branch-review-ledger.md	Records review and verification history.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:cfb5dc84e4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cursor]

Babysit / unblock summary (PR #1785)

Tip:abb827b1ae2b0a227617b7bcdba8e1338c71a73d on cursor/smarter-meds-search-9c1b
Sync / merge-tree: behind origin/main by 0; git merge-tree clean (not a content conflict). Auto-merge remains armed (squash); left merge to you.

What blocked

Required CI on the prior tip (938a9cac) was already green, including Production UI and PR required. Merge stayed BLOCKED on 8 unresolved review threads (Codex ×2 passes + Copilot) that were real product defects in the catalog-search path—not advisory noise.

What I fixed (abb827b1)

1. Shared typo base query — medications domain uses clinical-search’s corrected baseQuery (and merges shared expansions) when catalog-local analysis does not change the query (monitring → monitoring).
2. Sibling-brand expansions — expand only canonical identity; no more eleva ⊂ elevated pollution on zoloft.
3. fields=index match projection — ranked matches[].medication slim-projected like top-level records.
4. Brand-list parsing — strip parentheticals before split; drop trailing prose so annotation tokens never enter vocabulary.

Focused proof: npm run test:focused -- --files src/lib/medication-query.ts,src/lib/medications.ts,src/app/api/medications/route.ts,src/lib/universal-search.ts → 169/169 passed.

Threads

All 8 review threads replied + resolved on this tip.

Required CI (this tip)

Re-running after the blocker-fix push (expected cancel/restart of the prior green run). No provider-backed gates run.

Residual risks

• Low-score content hits for the expanded generic (e.g. other SSRIs mentioning sertraline on a zoloft query) remain intentional.
• Ledger row for this unblock tip is recorded locally under scope PR #1785 unblock/fix and not pushed as a ledger-only tip (anti-churn).
• Merge left to you once required checks on abb827b1 finish green.

[cursor]

Babysit / unblock update (PR #1785)

Tip:940653f9a487c68de0906885566555ff7d065050 on cursor/smarter-meds-search-9c1b
Sync / merge-tree: was behind 11 / GitHub DIRTY on abb827b1 with PR mergeability failing; git merge-tree vs origin/main was clean (staleness, not a content fight). Merged origin/main → tip now behind 0, merge-tree clean, mergeable: MERGEABLE. Auto-merge still armed; merge left to you.

What blocked

• Required product CI on abb827b1 was already green (PR required, Production UI, Build, Static PR, etc.).
• Real blocker: PR mergeability FAIL + GitHub CONFLICTING/DIRTY from main advancing after the tip.
• Review threads: still 0 unresolved (prior fix at abb827b1 stands).

What I fixed

• One sync merge of origin/main (no product code changes this round).
• Re-verified catalog-search focused tests after merge: 201/201 passed.
• No new review comments to address.

Required CI (this tip)

Re-running on 940653f9 after the sync push (expected). Prior tip’s green suite should re-establish once this run finishes.

Residual

• Ledger supersede for this tip kept local-only (no ledger-only push).
• Merge left to you when required checks on 940653f9 are green.

[cursor]

Babysit / unblock update (PR #1785)

Tip:a4f57500f6b16a4616e1f84c126c2f787a40766b on cursor/smarter-meds-search-9c1b
Sync / merge-tree: prior tip 940653f9 went DIRTY/CONFLICTING after main advanced by #1782 (document-viewer). git merge-tree was clean (behind-but-clean). Merged origin/main → now behind 0, merge-tree clean, mergeable: MERGEABLE. Auto-merge still armed; merge left to you.

What blocked

• Product CI on 940653f9 was green (PR required, Production UI, Build, Static PR, etc.).
• Real blocker: PR mergeability FAIL from main advancing one commit.
• Review threads: 0 unresolved.

What I fixed

• One sync merge of origin/main (+ ledger supersede for this tip).
• Re-checked catalog-search focused tests after sync: 82/82.

Required CI

Re-running on a4f57500 (in progress). No provider gates.

Residual

• This PR keeps going dirty whenever main moves; a late merge or another sync may be needed if more lands before you merge.
• Merge left to you once required checks on this tip are green.

[BigSimmo]

@cursoragent Unblock the current open PR. Confirm the PR number and GitHub head first from context. If more than one open PR could apply, stop and say which one you would use and why.

Fetch and start from the remote tip that matches that GitHub head. If the named branch ref is missing or stale, use the PR head ref. Preserve unrelated local WIP; do not discard dirty work; do not treat a local-ahead commit as the reviewed tip. Do not merge the PR, force-push, rebase, or arm auto-merge. No provider-backed gates without approval. If you cannot push or resolve threads, diagnose and comment only; if inline replies fail, resolve when possible and put blocker dispositions in the summary comment. If auto-merge is already armed, push only for a real blocker and avoid cancelling in-flight required CI unless the push clears that blocker.

If the PR is already merged or closed: confirm outcome, post one summary, and stop.

Primary job: clear mergeability and required-CI blockers on this tip. Do a full product review only if needed to explain or fix a blocker. Stay light otherwise—no broad verification suites or Playwright unless needed to prove one concrete unblock fix.

Snapshot the GitHub head: tip, behind/ahead, mergeable state, merge-tree versus origin/main (real conflict versus behind-but-clean), required checks on that tip including Production UI when selected, and unresolved threads that block merge or required CI. Missing checks while dirty are not green. Tip moved → re-snapshot.

Ledger-lookup against that GitHub head under an unblock/fix scope for this PR. If already handled at this head for unblock work, merge-tree clean, required checks green, and no blocking threads: summarize, comment, stop.

Unblock once: real conflict → merge origin/main with the smallest correct resolution (prefer main’s shared queues; keep this PR’s notes); behind-but-clean → one sync, late if required CI is in flight; clean → leave. skip-branch-sync and similar labels do not block a manual sync needed to clear a real blocker. No sync thrash. After any sync or push, re-snapshot tip, merge-tree, and required checks before declaring done. Dedupe the ledger if a merge touched it.

Fix only what blocks required checks or mergeability on this tip. Ignore advisory red unless it reveals a real required failure. Prefer the smallest safe fix; if a bot/autofix commit caused the break, prefer revert. Prove with the smallest targeted check only. Format and commit before push.

Push only blocker-fix commits. Append ledger for the final GitHub head under the unblock scope. Never push a ledger-only tip.

One PR comment: tip, sync/merge-tree, what blocked and what you fixed or dispositioned, required CI status, residual risks; merge left to me.

Stop when merge-tree is clean on the current GitHub tip, no blocking threads remain for merge/required CI, and required checks are green or clearly in progress.

[cursor]

❌ Unable to add follow-up after multiple attempts. The agent may be experiencing issues.

Please try again later or Open in Web to view the status.

_{Learn more about Cursor Agents}

[coderabbitai]

Actionable comments posted: 4

🤖 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 `@docs/branch-review-ledger.md`:
- Around line 853-862: Preserve the append-only ordering of
docs/branch-review-ledger.md: do not move or manually edit existing ledger rows
around the PR `#1785` entries. Add any new records only through the established
ledger command, retaining its existing merge-driver behavior.
In `@src/lib/universal-search.ts`:
- Around line 265-272: Update the medication-ranking flow around
analyzeMedicationCatalogQuery so it analyzes args.baseQuery, preserving the
shared correction before applying catalog corrections and composing both into
the ranking query. In tests/universal-search.test.ts lines 439-451, add a
regression for a combined typo such as “sertaline monitring” and assert
medication ranking uses both corrections.
In `@tests/medications-route.test.ts`:
- Around line 243-254: Remove the duplicate members from the response payload
type declarations in the brand and typo test cases. Keep one matches definition
per payload and one interpretation definition in typoPayload, preserving the
existing fields and assertions.
In `@tests/ui-smoke.spec.ts`:
- Around line 305-325: Update medicationIndexRecords and the mock’s fields=index
response path: derive the brand row from medicationBrandNames(record) so
annotation and prose cleanup match production, then project every matched
medication through medicationIndexRecords() instead of returning full
match.medication records. Preserve the existing full-record response for other
fields values.

🪄 Autofix

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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 57fff2b5-937b-4c71-a604-f83abb400369

📥 Commits

Reviewing files that changed from the base of the PR and between fd1e2af and 88dbdd8.

📒 Files selected for processing (10)

• docs/branch-review-ledger.md
• src/app/api/medications/route.ts
• src/lib/medication-entities.ts
• src/lib/medication-query.ts
• src/lib/medications.ts
• src/lib/universal-search.ts
• tests/medications-route.test.ts
• tests/medications.test.ts
• tests/ui-smoke.spec.ts
• tests/universal-search.test.ts

[github-actions]

CI triage

CI failed on this PR. Automated classification of the 2 failed job(s):

• Production UI (3) — needs investigation: inspect the failing step and uploaded diagnostics; rerun only after classifying the cause.
• PR required — needs investigation: inspect the failing step and uploaded diagnostics; rerun only after classifying the cause.

Compared with main CI run #9583 (cancelled).

Classification is evidence routing, not permission to ignore a failure. Exact quarantined Playwright identities remain governed by the flake ledger.

[cursor]

Babysit summary (merged)

• Tip at merge:2d935570c12baaaac94f76c095d46d148adc2ec3 (synced through fix(ci): silence TS5101 baseUrl deprecation for Playwright builds #1798/ci: optimize smart test routing and browser gates #1789/fix same-mode focus restore not stealing deliberate focus #1792)
• Sync/merge-tree: clean after last main sync
• Blocked earlier by: false DIRTY while behind; Production UI flake/failure fixed on branch; unresolved review threads
• Required CI: green
• Merge: squash-merged as 8c632c7f0b72a1983f05dab74f4ec803bca00ff3
• Residual risks: none for medications search on this tip