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.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

<!-- coderabbit-ai-generated:v1 -->

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

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
This commit is contained in:
Brandon Casey authored and GitHub committed 2026-11-13 00:53:10 -05:00
1 parent 02597019d5
commit 99275a2ddb
2 files changed
+174 -24

No files matched your search

+91 -24
View File
@@ -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
+83
View File
@@ -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"