fix(usfm): emit mt1 for the main title

[henrique221]

Closes #268.

Both the streaming USFM export and the chapter-assignment converter now write the main title as \mt1. The book-details API documentation describes the same marker. The title fallback order and the rest of the output stay the same. I checked #264 and #275: both are merged, but neither includes this change.

I updated the golden tests and added a USFM → USJ → USFM test with usfm-grammar 3.2.0. It checks the numbered title and preserves the parsed document. The marker matches the USFM reference. I did not run a manual Paratext round trip in this environment.

Validation on Node 24.14.0: 608 tests pass, including new converter coverage for chapter boundaries, USJ output and legacy \mt imports. Lint, formatting, typecheck, build and docs checks pass. Lint reports only the three existing max-lines warnings in verse-audio files.

Screenshot

This preview is generated from the same export fixture covered by the tests. It preserves the authored book details and table-of-contents fields while emitting the numbered main-title marker.

Summary by CodeRabbit

• Bug Fixes
  • Updated generated USFM book headers to use the standardized \mt1 marker for main titles.
  • Preserved main-title formatting through USFM-to-USJ-to-USFM conversions.
  • Kept title selection consistent when short names or authored book titles are provided.
  • Continued supporting imported documents that use the legacy \mt title marker.
  • Improved consistency across generated USFM, book details, and conversion workflows.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 2412c216-2c7f-4cd9-959a-cd455646f7d5

📥 Commits

Reviewing files that changed from the base of the PR and between 8fd41af and 204e921.

📒 Files selected for processing (2)

• src/domains/book-details/book-details.types.ts
• src/domains/usfm/usfm.types.ts

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The USFM exporters now emit \mt1 for main book titles. Tests cover title selection, ordering, conversion, round trips, and legacy \mt imports. Book-detail documentation describes the updated export behavior.

Changes

USFM title marker

Layer / File(s)	Summary
Emit numbered main title marker src/domains/usfm/usfm.service.ts, src/lib/usfm-converter.ts	Both USFM generators now emit \mt1 instead of \mt. Related comments reference the numbered marker.
Validate title output and compatibility src/domains/usfm/usfm.service.test.ts, src/lib/usfm-converter.test.ts	Tests expect \mt1 across title, ordering, fallback, and preference cases. They also validate USFM-USJ round trips and legacy \mt imports.
Document title export behavior src/domains/book-details/book-details.route.ts, src/domains/book-details/book-details.types.ts, src/domains/usfm/usfm.types.ts	Documentation identifies \mt1 and describes Short Name and preserved bookTitle handling.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: kaseywright

Merge Risk: ⚪ Minimal · up to 0ab8a

The title-marker change preserves fallback behavior and legacy compatibility with no unresolved merge-blocking risk.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 7 files.	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 clearly and concisely describes the main change: emitting the \\mt1 marker for the USFM main title.
Linked Issues check	✅ Passed	Issue #268 requires the exported main title to use \\\\mt1, while preserving title fallback behavior and other output, with updated golden coverage and a round-trip check. The PR changes `createUSFMSt…
Out of Scope Changes check	✅ Passed	The changes remain connected to issue #268. The chapter-assignment converter emits generated USFM and therefore applies the same main-title marker change. Its tests verify title generation, chapter bo…

✨ 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 fix/268-usfm-main-title-mt1

---

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

[kaseywright]

Reviewed this PR. Two related follow-ups that look like they were missed alongside the \mt -> \mt1 fix:

1. src/lib/usfm-converter.ts:85 — generateUSFMText() still emits the legacy \mt marker instead of \mt1. This is a sibling code path (used for chapter-assignment content via chapter-assignments.repository.ts:274, which calls convertUSFMToUSJ(generateUSFMText(verseData))) that doesn't appear to have been updated to match the fix applied in usfm.service.ts. As-is, USFM output will be inconsistent depending on which code path generated it.

2. src/domains/book-details/book-details.route.ts:94 (also ~172-173) — The OpenAPI/Swagger description text for the book-details GET/PATCH routes still documents the exported main title as \mt. Since the actual export now produces \mt1, the generated API docs no longer match the real response body.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VEZuKYs9J7Uu4dpapzddg4

[kaseywright]

Requesting changes per the review comments above — the \mt -> \mt1 fix should also cover usfm-converter.ts and the stale Swagger docs in book-details.route.ts.

[kaseywright]

Re-reviewed the latest changes (head 8fd41af). The previous two issues are fixed — thanks. Found three more instances of the same pattern (marker fixed in code, docs/comments not updated to match):

1. src/domains/book-details/book-details.types.ts:54 — bookTitle field's OpenAPI description still says it "supplies \mt whenever tocShortName is null." The sibling descriptions in route.ts were updated in this PR to say \mt1, so this is now inconsistent with the docs shipping alongside it.

2. src/domains/book-details/book-details.types.ts:63 — tocShortName field's OpenAPI description still says it "supplies the \mt main title." Same inconsistency.

3. src/domains/usfm/usfm.types.ts:22 — BookFields.tocShortName doc comment still says "also supplies \mt," despite usfm.service.ts (which consumes this type) being changed in this same PR to emit \mt1. This one's a bit riskier since it's the doc comment on the type that usfm.service.ts/usfm-converter.ts consume — a future edit could reintroduce the legacy marker by trusting this comment as ground truth.

🤖 Generated with Claude Code

https://claude.ai/code/session_013C7HSaAYgMZffw2CutMCjG

[henrique221]

Updated all three remaining documentation references from \mt to \mt1 in book-details.types.ts and usfm.types.ts. I also merged the current main branch. The 30 focused tests, typecheck, and formatting check pass locally.

[kaseywright]

Re-reviewed the latest changes (head 204e921). All three prior findings are addressed, and a re-review found no remaining correctness, cleanup, or consistency issues — no \mt references were missed outside intentional legacy-format test fixtures, and no downstream consumer depends on the literal marker string. Approving.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FTcDu7558STn5xRaTvKPLt