Add the pure query core for the analysis catalog

[alex-rawlings-yyc]

Closes #192.

The pure derivation layer for the Analysis Catalog (#186) — no React, no store, no PAPI, no UI.

Modules

• src/utils/search-fold.ts — foldForSearch (NFKD → strip \p{Mn} → NFC → lowercase → fold final letter forms), kept deliberately apart from normalizeSurfaceForm. NFKD folds compatibility distinctions generally — ligatures, width and superscript variants, non-breaking spaces — not just positional shapes.
• src/utils/analysis-query.ts — buildCatalogRows, applyCatalogQuery, deriveFacets.
• src/store/analysisSlice.ts — selectCatalogRows(state, currentBook), memoized on the two token-level arrays plus the analysis language and book.

Three divergences from the issue, agreed before implementing

1. Split build from query. Analysis catalog: pure query core (analysis-query.ts, search fold, memoized selector) #192 specifies buildCatalogRows(analysis, query) but also requires search/sort/filter to run outside the memoized build — those conflict. Shipped as buildCatalogRows(analysis, scope) + applyCatalogQuery(rows, query). buildCatalogRows takes Pick<TextAnalysis, 'tokenAnalyses' | 'tokenAnalysisLinks'> so the selector memoizes on those arrays rather than the whole TextAnalysis.
2. CatalogRow carries pos / features / confidence. The row shape in Analysis catalog: pure query core (analysis-query.ts, search fold, memoized selector) #192 has none of them, so deriveFacets(rows) could not derive the facets it is asked to. status and lexicon refs are deliberately not facets: status is constant by construction (only approved links count as usages) and lexicon-ref presence is a boolean, not a value list.
3. No analysisLanguages in the query. searchText folds every gloss value present, so a gloss in a language the project no longer declares stays findable.

#192 and #186's row model should be amended before #193 starts, since #193 consumes these exports.

Not in the issue, but the data requires it

USJ verse SIDs are verbatim, so a bridged verse arrives as "GEN 1:3-4:0" and Number('3-4') is NaN. Usage parsing goes through the existing firstVerseNumber; there is a test for it.

Testing

Covers every behavior #192 lists, plus the script-specific cases the search fold turns on. Full suite passing, 100% coverage, lint clean.

🤖 Generated with Claude Code

---

This change is 

Summary by CodeRabbit

• New Features

  • Added catalog search across glosses and morphemes.
  • Added filtering by book, usage, gloss, and morphology.
  • Added sorting by usage, text, gloss, and first occurrence.
  • Added catalog facets for books, part of speech, confidence, and feature values.
  • Search supports case- and diacritic-insensitive matching across Greek, Hebrew, Latin, Devanagari, and Arabic text.

• Tests

  • Added comprehensive coverage for catalog queries, filtering, sorting, facets, multilingual search, and catalog updates.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The PR adds a pure analysis catalog query core, search folding, row construction, facets, filters, sorting, and a memoized Redux selector. It also adds tests for catalog behavior, normalization, query operations, and selector memoization.

Changes

Analysis catalog

Layer / File(s)	Summary
Catalog contracts and row construction src/utils/analysis-query.ts, src/utils/search-fold.ts, src/__tests__/utils/analysis-query.test.ts, src/__tests__/utils/search-fold.test.ts, src/__tests__/utils/analysis-identity.test.ts	Adds catalog contracts, approved usage grouping, document ordering, row construction, folded search text, and Unicode search normalization.
Facets, filters, and sorting src/utils/analysis-query.ts, src/__tests__/utils/analysis-query.test.ts	Adds facet derivation, search and filter evaluation, and count-, text-, gloss-, and first-use sorting.
Memoized store selector src/store/analysisSlice.ts, src/__tests__/store/analysisSlice.test.ts	Exports selectCatalogRows and verifies stable references for unchanged state and recomputation after gloss updates.

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

Sequence Diagram(s)

sequenceDiagram
  participant AnalysisState
  participant selectCatalogRows
  participant buildCatalogRows
  AnalysisState->>selectCatalogRows: token analyses, links, language, current book
  selectCatalogRows->>buildCatalogRows: catalog scope
  buildCatalogRows-->>selectCatalogRows: catalog rows
  selectCatalogRows-->>AnalysisState: memoized row collection

Loading

Possibly related issues

• Issue 186: The PR implements the Analysis Catalog v1 objectives, including rows, search folding, facets, filters, sorting, and memoized selection.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	Most [#192] requirements are covered, but the summary specifies compatibility decomposition instead of the required NFD normalization for foldForSearch.	Implement foldForSearch with NFD normalization, combining-mark removal, NFC recomposition, and lowercasing while preserving the required search-only distinctions.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Out of Scope Changes check	✅ Passed	All listed changes support [#192], including implementation, selector integration, and focused tests; no unrelated code changes are identified.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding the pure query core for the analysis catalog.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch analysis-catalog-derivation

---

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

[alex-rawlings-yyc]

@alex-rawlings-yyc resolved 2 discussions.
Reviewable status: 0 of 7 files reviewed, all discussions resolved (waiting on alex-rawlings-yyc).

[imnasnainaec]

Synthesized review, not human-checked.

Authored by Claude Opus 5 (1M context) (claude-opus-5[1m]) running in Claude Code. It is a synthesis of Devin's review of this PR: every finding was re-read against the branch, and the ones that were stale, incorrect, or purely informational were dropped — but no human has verified what remains. Treat each comment as a suggestion to evaluate rather than a request.

Behavioral claims were checked by running the actual fold pipeline and Canon.bookIdToNumber on Node 22; the measured values are quoted inline. Comments prefaced with :pick: are low-priority or optional.

[alex-rawlings-yyc]

Addressed all comments left

@alex-rawlings-yyc made 12 comments.
Reviewable status: 0 of 7 files reviewed, 11 unresolved discussions (waiting on alex-rawlings-yyc and imnasnainaec).

[imnasnainaec]

@imnasnainaec reviewed 4 files and all commit messages, made 2 comments, and resolved 8 discussions.
Reviewable status: 4 of 7 files reviewed, 6 unresolved discussions (waiting on alex-rawlings-yyc).

---

src/utils/search-fold.ts line 11 at r5 (raw file):
I find this comment to be unclear as to whether the mapping is to or away from the word-final form. Perhaps something like:

Letter shapes that are only used at the end of a word, mapped to the default shape used everywhere else.

---

src/__tests__/utils/analysis-query.test.ts line 190 at r5 (raw file):

  });

  // The morpheme form is suppletive, so a match cannot come from the surface form instead.

⛏️ I don't find this comment helpful.

[alex-rawlings-yyc]

@alex-rawlings-yyc made 6 comments.
Reviewable status: 4 of 7 files reviewed, 6 unresolved discussions (waiting on alex-rawlings-yyc and imnasnainaec).

---

src/__tests__/utils/analysis-query.test.ts line 190 at r5 (raw file):

Previously, imnasnainaec (D. Ror.) wrote…

⛏️ I don't find this comment helpful.

Deleted.

---

src/utils/search-fold.ts line 11 at r5 (raw file):

Previously, imnasnainaec (D. Ror.) wrote…

I find this comment to be unclear as to whether the mapping is to or away from the word-final form. Perhaps something like:

Letter shapes that are only used at the end of a word, mapped to the default shape used everywhere else.

Fair — the old subject was the letter, which has both shapes, so it left the key
ambiguous. Making the word-final shapes the subject settles it.

[imnasnainaec]

@imnasnainaec reviewed 3 files and all commit messages, and resolved 6 discussions.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on alex-rawlings-yyc).