From 99275a2ddb81b0de5cb28266ee8059ab5a09bc7e Mon Sep 17 00:00:00 2001 From: Brandon Casey <2381475+brandonocasey@users.noreply.github.com> Date: Fri, 13 Nov 2026 00:53:10 -0500 Subject: [PATCH] fix(packs): match pack files by folder path (#1701) In a series pack, each book's folder often holds files with the same names, such as `Book 1/001.mp3` and `Book 2/001.mp3`. After download, the files can sit under an extra folder. The reviewed plan's exact paths then miss, and the basename fallback takes the first unclaimed `001.mp3`. That file can belong to another book. `match_plan_to_files` now tries these steps in order: - Release-relative path, as before. - The same path under the release root's name, when that file is unclaimed. - The same-named file that shares the most parent folders with the planned path. It needs at least two shared parts, and a tie falls through. - Basename, then glued-name suffix, as before. Verified with `tests/download/test_packs.py`: 59 passed, including 4 new cases for duplicate names in a reversed plan, path collisions, ties and repeated root names. ## Summary by CodeRabbit * **Bug Fixes** * Improved matching between planned release files and files on disk, including paths prefixed by the release root. Exact path matches take precedence, and ambiguous matches retain predictable ordering. * Unmatched files continue to be grouped heuristically. --- shelfmark/download/postprocess/packs.py | 115 +++++++++++++++++++----- tests/download/test_packs.py | 83 +++++++++++++++++ 2 files changed, 174 insertions(+), 24 deletions(-) diff --git a/shelfmark/download/postprocess/packs.py b/shelfmark/download/postprocess/packs.py index 10728267..ec8bb499 100644 --- a/shelfmark/download/postprocess/packs.py +++ b/shelfmark/download/postprocess/packs.py @@ -425,6 +425,85 @@ def drop_ignored_files(book_files: list[Path], ignored: list[str] | None) -> lis return [p for p in book_files if p not in dropped] +@dataclass(frozen=True) +class _PlanFileIndex: + """On-disk book files, keyed each way an approved plan entry can name them.""" + + root: Path + files: list[Path] + by_rel: dict[str, Path] + by_root_rel: dict[str, Path] + parts_by_path: dict[Path, tuple[str, ...]] + by_name: dict[str, list[Path]] + + @classmethod + def build(cls, book_files: list[Path]) -> _PlanFileIndex: + root, rel_by_path = _relative_paths(book_files) + by_root_rel = {f"{root.name}/{rel}": path for path, rel in rel_by_path.items()} + parts_by_path = { + path: (root.name, *PurePosixPath(rel).parts) for path, rel in rel_by_path.items() + } + # A folder nested under the root with the root's own name repeats a root-relative + # path. Drop such keys so the shared-tail match decides between the copies. + for parts in parts_by_path.values(): + for index in range(1, len(parts) - 1): + if parts[index] == root.name: + by_root_rel.pop("/".join(parts[index:]), None) + by_name: dict[str, list[Path]] = {} + for path in book_files: + by_name.setdefault(path.name, []).append(path) + return cls( + root=root, + files=book_files, + by_rel={rel: path for path, rel in rel_by_path.items()}, + by_root_rel=by_root_rel, + parts_by_path=parts_by_path, + by_name=by_name, + ) + + def match(self, wanted: str, claimed: set[Path]) -> Path | None: + """Find the file a plan entry names, in the order `match_plan_to_files` lists.""" + wanted_rel = wanted.replace("\\", "/").lstrip("./") + exact = self.by_rel.get(wanted_rel) + if exact is not None: + return exact + root_relative = self.by_root_rel.get(wanted_rel) + if root_relative is not None and root_relative not in claimed: + return root_relative + + wanted_path = PurePosixPath(wanted_rel) + same_name = [p for p in self.by_name.get(wanted_path.name, []) if p not in claimed] + shared_tail = _best_shared_tail(wanted_path.parts, same_name, self.parts_by_path) + if shared_tail is not None: + return shared_tail + if same_name: + return same_name[0] + + wanted_name = wanted_path.name.lower() + glued = [p for p in self.files if p not in claimed and wanted_name.endswith(p.name.lower())] + return glued[0] if len(glued) == 1 else None + + +def _best_shared_tail( + wanted_parts: tuple[str, ...], + candidates: list[Path], + parts_by_path: dict[Path, tuple[str, ...]], +) -> Path | None: + """Return the candidate sharing the most trailing components (at least 2) with a path.""" + scores: dict[Path, int] = {} + for path in candidates: + depth = 0 + for actual, expected in zip( + reversed(parts_by_path[path]), reversed(wanted_parts), strict=False + ): + if actual != expected: + break + depth += 1 + if depth > 1: + scores[path] = depth + return _single_best(scores) + + def match_plan_to_files( plan: list[PackBook], book_files: list[Path], @@ -434,40 +513,28 @@ def match_plan_to_files( ) -> list[BookGroup]: """Apply an approved plan to on-disk files. - Files match by release-relative path first, then by basename (archive extraction - and client save paths can shift the root), then by the on-disk basename being a - suffix of the planned name (sources that glue folder and file names together). + Files match in this order: + + - Release-relative path. + - Same path under the release root's name. + - Most trailing path components shared with a same-named file. + - Basename. Archive extraction and client save paths can shift the root. + - On-disk basename that ends the planned name. Some sources glue folder and + file names together. + Book files the plan does not mention fall back to heuristic grouping so nothing is silently dropped. """ if not book_files: return [] - root, rel_by_path = _relative_paths(book_files) - by_rel = {rel: path for path, rel in rel_by_path.items()} - by_name: dict[str, list[Path]] = {} - for path in book_files: - by_name.setdefault(path.name, []).append(path) + files = _PlanFileIndex.build(book_files) claimed: set[Path] = set() groups: list[BookGroup] = [] for book in plan: matched: list[Path] = [] for wanted in book.files: - wanted_rel = wanted.replace("\\", "/").lstrip("./") - candidate = by_rel.get(wanted_rel) - if candidate is None: - candidates = [ - p for p in by_name.get(PurePosixPath(wanted_rel).name, []) if p not in claimed - ] - candidate = candidates[0] if candidates else None - if candidate is None: - wanted_name = PurePosixPath(wanted_rel).name.lower() - candidates = [ - p - for p in book_files - if p not in claimed and wanted_name.endswith(p.name.lower()) - ] - candidate = candidates[0] if len(candidates) == 1 else None + candidate = files.match(wanted, claimed) if candidate is not None and candidate not in claimed: claimed.add(candidate) matched.append(candidate) @@ -504,7 +571,7 @@ def match_plan_to_files( if still_unmatched: groups.extend( group_files_into_books( - still_unmatched, series_name=series_name, author_name=author_name, root=root + still_unmatched, series_name=series_name, author_name=author_name, root=files.root ) ) return groups diff --git a/tests/download/test_packs.py b/tests/download/test_packs.py index 66f0ff0a..cd922a85 100644 --- a/tests/download/test_packs.py +++ b/tests/download/test_packs.py @@ -256,6 +256,89 @@ class TestGroupFilesIntoBooks: class TestMatchPlanToFiles: + def test_release_root_paths_match_duplicate_names_in_reversed_plan(self, tmp_path: Path): + root = tmp_path / "staging" / "Series Pack" + first = root / "Book 1" / "001.mp3" + second = root / "Book 2" / "001.mp3" + for index, file in enumerate((first, second)): + file.parent.mkdir(parents=True) + file.write_bytes(f"audio{index}".encode()) + plan = [ + PackBook( + title="Edited Two", + series_position=2, + year=None, + files=["Series Pack/Book 2/001.mp3"], + ), + PackBook( + title="Edited One", + series_position=1, + year=None, + files=["Series Pack/Book 1/001.mp3"], + ), + ] + groups = match_plan_to_files(plan, [first, second]) + assert [(group.title, group.files) for group in groups] == [ + ("Edited Two", [second]), + ("Edited One", [first]), + ] + assert [[file.read_bytes() for file in group.files] for group in groups] == [ + [b"audio1"], + [b"audio0"], + ] + + def test_relative_path_precedes_root_prefixed_collision(self, tmp_path: Path): + root = tmp_path / "Series" + prefixed = root / "Book" / "audio.m4b" + relative = root / "Series" / "Book" / "audio.m4b" + plan = [ + PackBook( + title="Relative", series_position=None, year=None, files=["Series/Book/audio.m4b"] + ), + PackBook(title="Prefixed", series_position=None, year=None, files=["Book/audio.m4b"]), + ] + groups = match_plan_to_files(plan, [prefixed, relative]) + assert [(group.title, group.files) for group in groups] == [ + ("Relative", [relative]), + ("Prefixed", [prefixed]), + ] + + def test_root_prefixed_tie_retains_basename_order(self, tmp_path: Path): + root = tmp_path / "Series" + exact = root / "Book" / "audio.m4b" + nested = root / "Nested" / "Series" / "Book" / "audio.m4b" + plan = [ + PackBook( + title="First", series_position=None, year=None, files=["Series/Book/audio.m4b"] + ), + PackBook( + title="Second", series_position=None, year=None, files=["Series/Book/audio.m4b"] + ), + ] + groups = match_plan_to_files(plan, [nested, exact]) + assert [(group.title, group.files) for group in groups] == [ + ("First", [nested]), + ("Second", [exact]), + ] + + def test_repeated_root_prefixed_path_uses_unclaimed_fallback(self, tmp_path: Path): + root = tmp_path / "Series" + exact = root / "Book" / "audio.m4b" + other = root / "Other" / "audio.m4b" + plan = [ + PackBook( + title="First", series_position=None, year=None, files=["Series/Book/audio.m4b"] + ), + PackBook( + title="Second", series_position=None, year=None, files=["Series/Book/audio.m4b"] + ), + ] + groups = match_plan_to_files(plan, [exact, other]) + assert [(group.title, group.files) for group in groups] == [ + ("First", [exact]), + ("Second", [other]), + ] + def test_matches_by_relative_path_then_basename(self, tmp_path: Path): root = tmp_path / "staging" / "Sun Eater" a = root / "Book 1 - A" / "a.m4b"