[henrique221]

QA on eten-tech-foundation/fluent-web#398 found that editing the TOC fields changed two other lines of the exported book. After saving a Short Name, \mt1 came out with that value, and so did \h whenever no running header was set. Whatever those lines held before was gone from the file. Chad confirmed it on the issue: the Short Name should only land in \toc2.

What was going on

The export took \mt1 from tocShortName first and only then from bookTitle, and \h fell back to tocShortName. Both came from the first version of the ticket, which derived \mt1 from the Short Name. Chad crossed that rule out on 20 Aug. #275 still had it when it merged the next day, and #323 kept the same fallback order.

Nothing was lost in the database. The dialog only writes the three TOC columns, so running_header and book_title were never touched. The export just stopped showing them.

The fix

\h is runningHeader, else the book name. \mt1 is bookTitle, else the book name. Each TOC field fills only its own line. There's no migration: the next export shows the old \h and \mt1 again.

I also rewrote the OpenAPI descriptions that explained the old precedence, and replaced the note about pre-filling Short Name from bookTitle. Chad dropped that rule the same day, and eten-tech-foundation/fluent-web#581 takes it out of the dialog.

Tests

Two unit tests replace the ones that pinned the old rule. With all three TOC fields set, an authored \h and \mt1 stay as authored. With only the TOC fields set, both lines keep the book name. The USFM round-trip test now expects the book title in \mt1.

Validation on the PR head:

• 6 E2E export cases pass, 3 per browser in Chromium and Firefox, against an isolated web, API and PostgreSQL with a real project manager login. Each one edits the three TOC fields in the dialog, closes it, exports from the milestone page and reads the downloaded file: with an authored \h and \mt, without them, and a second edit on top of the first. On main all 6 fail on the \h/\mt1 lines: \mt1 comes out as the Short Name, and so does \h when no running header is set. The rest of the suite for both PRs passes too (18 cases, including save and reload in the dialog).
• Lint (0 errors), formatting and TypeScript pass. The full suite passes, 1326 tests. On the first full run, the PGlite workflow-stages suite hit its 10-second hook limit while the machine was busy. It passed an isolated rerun, a second full run and the pre-push hook with the same code.

Tested API dff7bc8f371f4e61889a96ea8cee235d8e578337 with web eten-tech-foundation/fluent-web#581 at b756d73667b743d15964b6c2f21d0654b9e083aa. These are local checks only.

Part of eten-tech-foundation/fluent-web#398.

Summary by CodeRabbit

• Bug Fixes
  • USFM exports now use the authored book title for \mt1 and the running header for \h, falling back to the book’s display name when those fields are blank.
  • TOC fields now affect only their corresponding TOC lines; blank fields are omitted instead of being filled with the display name.
• Documentation
  • Updated book details and export descriptions to reflect these behaviors.

[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: 605158e1-225b-42f5-8f3c-5c4a33f0d0e7

📥 Commits

Reviewing files that changed from the base of the PR and between 715bcda and ac3f86f.

📒 Files selected for processing: 6

• src/db/schema.ts
• src/domains/book-details/book-details.route.ts
• src/domains/book-details/book-details.types.ts
• src/domains/usfm/usfm.service.test.ts
• src/domains/usfm/usfm.service.ts
• src/domains/usfm/usfm.types.ts

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

📝 Walkthrough

USFM export now derives \h from runningHeader or the book display name, and \mt1 from bookTitle or the display name. TOC fields populate only their corresponding TOC lines. The descriptions and tests were updated to reflect these rules.

Changes: USFM export fields

Layer / File(s)	Summary
Export precedence and field documentation src/db/schema.ts, src/domains/book-details/*, src/domains/usfm/*	Export now uses runningHeader or the display name for \h, and bookTitle or the display name for \mt1. TOC fields populate only their corresponding lines. Related descriptions and tests reflect these rules.

Priority: ⬇️ Low

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

Change: Bug fix

Suggested reviewers: anumonachan, kaseywright

Merge Risk: ⚪ Minimal · up to ac3f8

USFM export uses the authored header and title, with the book display name as fallback; TOC fields remain independent. The inspected field mapping and export paths support this behavior, and no actionable merge risk remains.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 6 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly describes the main change: preserving \h and \mt1 during TOC field updates in USFM export.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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