Skip to content

fix: an intro no longer shifts embedded "Chapter N" chapter names in a merged book - #531

Merged
kikootwo merged 1 commit into
mainfrom
reland/525-chapter-titles
Nov 2, 2026
Merged

kikootwo merged 1 commit into
mainfrom
reland/525-chapter-titles

Conversation

@kikootwo

@kikootwo kikootwo commented Nov 2, 2026

Copy link
Copy Markdown
Owner

Summary

A merged book whose files are tagged Intro & Dedication, Chapter 1, Chapter 2 and whose file names hold no titles now keeps those chapter names. Before, every embedded Chapter N tag counted as generic and was replaced by the file's position, so the intro pushed each chapter up by one (Chapter 1 became Chapter 2). The numbered tags are kept only when the whole book's titles stay distinct, so per-disc sets whose tags restart at Chapter 1 keep Chapter 1..N numbering exactly as before.

Changes

  • src/lib/utils/chapter-merger.ts
    • getChapterTitle takes a keepNumbered flag: with it, an embedded Chapter N tag (any case, zero padding) is used as the file's title. File-name titles still come first, a tag that is the book title is still skipped, and Track N, bare numbers and Part N still fall back to position numbering.
    • analyzeChapterFiles, after ordering, works out the titles both ways. It keeps the numbered tags only if every title in the set is distinct, compared case- and space-folded with the number parsed (Chapter 01 = Chapter 1), counting the fallback names of untagged files. Any repeat gives the whole set position numbering, the same names as on main.
    • One log line when a numbered tag is present: Chapter titles: keeping N embedded "Chapter N" title(s) (every title in the set is distinct) or Chapter titles: "<title>" repeats across the set - dropping embedded "Chapter N" titles, numbering chapters by position.
  • documentation/features/chapter-merging.md: the rule, the repeated-tags fallback, the log line, and a Fixed Issues entry for Bug: Chapter merging renumbers valid embedded chapter titles after an introduction #509. documentation/TABLEOFCONTENTS.md: pointer to it.

Tests

  • tests/utils/chapter-merger.titles.test.ts (new): the reported case (intro plus Chapter 1..4 tags, no titles in file names) keeps the tags and logs the keep line; per-disc Chapter 1, 2, 1, 2 tags give Chapter 1..4 with the multi-disc order (and log the drop line) and without it; an untagged intro beside Chapter 1..3 gives Chapter 1..4 with no repeats; chapter 01 counts as a repeat of Chapter 1; file-name titles and Track/bare/Part tags beside numbered tags; no log line when no file has a numbered tag.
  • tests/utils/chapter-merger.test.ts: the intro case through mergeChapters for Chapter 1/Chapter 2 and Chapter 01/CHAPTER 10, asserting the FFMETADATA chapter titles, in both orders; the book-title fallback also runs with every file tagged Chapter 10.
  • tests/utils/chapter-merger.order.test.ts unchanged and passing.
  • Fails on main (d2f81af src with this branch's tests): 5 tests (the reported case, the mixed case, both merge cases, and the per-disc multi-disc case on its log line). The per-disc, untagged-intro and padding cases pass on main by design: they guard against duplicate names, and fail against a per-file-only version of the fix (5 of 7 in the new file).

Checks

  • vitest related on chapter-merger.ts plus the test files: PASS, 120 files, 1554 passed, 1 skipped
  • tsc --noEmit: clean
  • ESLint on the changed files: nothing new (one existing warning on main, unused CHAPTER_PATTERNS)
  • Full unit suite: PR Tests (CI)

Risk and rollback

  • Only chapter names written into newly merged files change, and only for sets with embedded Chapter N tags whose titles are all distinct. Those names now keep the tag's own case and padding (Chapter 01). Ordering and timing are unchanged. Already merged books are not touched.
  • Kept tags can read out of sequence when they are numbered differently from the files' order (tags Chapter 3, 1, 2 on files played in that order), or when the chosen order is file-name order (track tags have gaps). The names then match what the files say.
  • Rollback: revert this PR. No schema or setting.

Closes #509

Based on #525 by @mvanhorn, with a check across the whole book so per-disc sets keep their numbering.

Release note

🤖 Generated with Claude Code

…a merged book (#509)

A merged book whose files are tagged "Intro", "Chapter 1", "Chapter 2"
and whose file names hold no titles now keeps those names. Every
"Chapter N" tag used to count as generic and was replaced by the file's
position, so the intro pushed each chapter up by one.

The numbered tags are kept only when every title in the set is
distinct (case and spacing folded, "Chapter 01" = "Chapter 1"), the
fallback names of untagged files included. Per-disc sets whose tags
restart at "Chapter 1", or an untagged intro beside "Chapter 1..N",
keep numbering by position as before. One log line says which way the
set went.

Based on #525 by @mvanhorn.

Co-authored-by: mvanhorn <455140+mvanhorn@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kikootwo
kikootwo merged commit abcd464 into main Nov 2, 2026
1 check passed
@kikootwo
kikootwo deleted the reland/525-chapter-titles branch November 2, 2026 15:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Bug: Chapter merging renumbers valid embedded chapter titles after an introduction

1 participant