bindery-cli 0.63.0__tar.gz → 0.64.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/AGENTS.md +4 -3
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/OBSERVE-RESEARCH.md +69 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/PKG-INFO +2 -1
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/README.md +1 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/patchnotes.md +66 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/pyproject.toml +1 -1
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/roadmap.md +5 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/spec.md +21 -3
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/__init__.py +1 -1
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/cli.py +19 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/epub.py +91 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/transforms.py +11 -2
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_epub.py +119 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_flags_real_core.py +19 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_flags_wiring.py +1 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/uv.lock +1 -1
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/.github/FUNDING.yml +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/.github/workflows/ci.yml +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/.github/workflows/publish.yml +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/.gitignore +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/LICENSE +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/docs/screenshots/library-sweep.png +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/logo.svg +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/plugin/__init__.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/project.done +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/run_tests.sh +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/scripts/FastSweep.java +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/scripts/build_plugin.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/scripts/fast_sweep.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/__main__.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/audit.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/library.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/observe.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/pagination.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/reserialize.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/validate.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/src/bindery/watermark.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_audit.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_cli.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_comment_hyphens.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_contamination.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_cover_tocdrift.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_help.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_library.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_matcher_hardening.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_observe.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_pagination.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_plugin.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_reserialize.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_space_renames.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_spine_guard.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_transforms.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_validate.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_version.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_watermark.py +0 -0
- {bindery_cli-0.63.0 → bindery_cli-0.64.0}/tests/test_xml_hardening.py +0 -0
|
@@ -30,7 +30,7 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
|
|
|
30
30
|
`xmlns`, bare `&`, named entities, void self-closing), the NCX pipeline, and the
|
|
31
31
|
mimetype fix (added/normalized/first-stored, epub.py's archive rewrite); every core
|
|
32
32
|
fix must render identically to the author's intent: never add, remove, or reorder
|
|
33
|
-
visible content. The canonical opt-in inventory lives in spec.md: thirty-
|
|
33
|
+
visible content. The canonical opt-in inventory lives in spec.md: thirty-three structural
|
|
34
34
|
repairs, four lossy strips, five safe opt-ins, plus `--reserialize` (the
|
|
35
35
|
seven v0.62.x/v0.63.0 flags -- `--fix-package-version`, `--fix-doctype`,
|
|
36
36
|
`--prune-invalid-guide-refs`, `--fix-item-properties`,
|
|
@@ -47,7 +47,8 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
|
|
|
47
47
|
`--fix-misnested-inline`, `--fix-stray-close`, `--fix-unterminated-attr`,
|
|
48
48
|
`--fix-unbound-prefix`, `--fix-package-version`, `--fix-doctype`,
|
|
49
49
|
`--prune-invalid-guide-refs`, `--fix-item-properties`,
|
|
50
|
-
`--strip-presentational-attrs`, `--encode-ref-brackets
|
|
50
|
+
`--strip-presentational-attrs`, `--encode-ref-brackets`,
|
|
51
|
+
`--prune-dead-spine`;
|
|
51
52
|
transforms.py, threaded through epub.py). The v0.47.0 five (the 2026-10-06
|
|
52
53
|
issue batch): `--fix-svg-dup-ids` renames duplicate glyph ids inside
|
|
53
54
|
standalone `.svg` entries (first keeps its name, references resolve to the
|
|
@@ -232,7 +233,7 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
|
|
|
232
233
|
- `src/bindery/pagination.py`: the opt-in lossy page-number strip (runhead detection, page-layer decision, block-centric removal/merge, safety nets).
|
|
233
234
|
- `src/bindery/watermark.py`: the opt-in lossy watermark strip (anchored and anchorless signature removal).
|
|
234
235
|
- `src/bindery/reserialize.py`: structural repair via `html5lib`.
|
|
235
|
-
- `src/bindery/audit.py`: read-only body-text audits (`content`, `pagenumbers`, `emptytext`, `ocr`, `monolithic` since v0.21.0 with `--max-doc-chars N`, and `completeness` since v0.36.0, `shell` since v0.63.0) behind the `audit` subcommand (v0.15.0). Since v0.18.0 library mode resolves EPUB paths through `cquarry.get_format_path()` and can apply a tag to flagged books via `cquarry.write.WritableCalibreDB` (only with explicit `--tag`; the only sanctioned write path). Since v0.19.0 `audit --id BOOK_ID` audits a single library book through cquarry's single-entity `get_book()` fetch (no library-wide cache; supports `--tag`; incompatible with the directory argument; comma lists since v0.23.0). Since v0.22.0 every archive entry is fully read (CRC + decompression) before analysis (a damaged entry reports its own CORRUPT verdict instead of feeding emptytext) and manifest/NCX references to absent files classify as `convention` (bloated ToC, consecutive span) or `fragment` (broken span). Hazard: the scan loop reuses `tag` as its per-book display column, so the `--tag` argument is captured as `audit_tag` at function entry; do not collapse them again. Since v0.29.0 `audit --json FILE` writes per-file analyzer verdicts in the `library --json` shape (directory, library, and single-book modes; with `--id`, exactly one id; emptytext omitted from a record when the archive verdict owns the body-text story). Since v0.44.0 two more advisory analyzers ride the single pass: `cover` (the EPUB3 `properties~="cover-image"` slice of the ruled hybrid: dangling EPUB2 meta, EPUB3 declaration, cover-file presence) and `tocdrift` (the NCX navMap vs EPUB3 nav toc structural diff, fragments included; audit-only, ToC synthesis out of charter permanently); the loader now exposes the parsed OPF, the NCX text, and the nav HTML on `Book`. Since v0.50.0 a ninth analyzer, `contamination` (issue #8, the judge-and-import class, advisory by contract like completeness/cover/tocdrift, never moves the exit code): foreign-title template stamps (head `<title>` repeats or a volume/book marker with named words in front of it, judged against the OPF's own title/creator/publisher/series with a marker-stripped comparison; a part label whose marker leads never flags), fan-bundle ad signatures (jnovels, kokoro connect, zerobooks, a light-novel plug), and review-paste fingerprints (strong flags alone, weak needs corroboration) in the first five content docs; its corpus is spine PLUS `Book.extra_docs` (the archive's non-spine html, retained by the loader in archive order under a 64 MiB cap, because a broken manifest can leave the junk entirely off the spine: Hothouse). Since v0.50.0 `run_directory`/`run_single` dispatch analyzers through `_dir_dispatch` (one entry per ALL key; the old if/elif chain's `else` ran ocr for cover/tocdrift in those modes since v0.44.0) and `tests/test_contamination.py` pins the map's key set to ALL. Since v0.36.0 the completeness analyzer (Phase 15) reports the phase-1 spot-check per book: spine/prose-doc counts (prose = >= 400 visible chars), first/middle/last prose-doc opening/closing excerpts, trailing-ToC classification (`_trailing_toc`: short link lines dominate, no paragraph-length blocks), and the unreadable fraction. It is ADVISORY by contract (problem always False; ADVISORY on a trailing ToC or unreadable fraction >= 10%), never moves the exit code, and is skipped like emptytext when the archive verdict owns the book. Since v0.38.0 the archive verdict distinguishes font obfuscation from DRM (`OBFUSCATION_ALGOS`: IDPF 2008/embedding + both Adobe URIs; readable obfuscated entries are the benign OBFUSCATED advisory, an unreadable one is CORRUPT, and only non-obfuscation algorithms give ENCRYPTED). Since v0.43.0 untrusted metadata XML is parsed through `_safe_xml_parse` (DOCTYPE/ENTITY declarations refused before xml.etree sees them; the stdlib shape of defusedxml's entity protection) and single entries above `_MAX_ENTRY_BYTES` (32 MB) are refused before decompression; a refused metadata file returns the shell book. Since v0.40.0 the vir-tui console renderer loads through the module-level `_LazyUI` proxy (a plain `import vir_tui as ui` at module level would make 3.12/3.13 installs unimportable now that the stack is marker-gated; LOAD_GLOBAL never consults module `__getattr__`, so a proxy object is the lazy shape that works).
|
|
236
|
+
- `src/bindery/audit.py`: read-only body-text audits (`content`, `pagenumbers`, `emptytext`, `ocr`, `monolithic` since v0.21.0 with `--max-doc-chars N`, and `completeness` since v0.36.0, `shell` since v0.63.0, v0.64.0 wires `--prune-dead-spine` (the shell repair, 50%-signature-gated, playOrder force re-sequence)) behind the `audit` subcommand (v0.15.0). Since v0.18.0 library mode resolves EPUB paths through `cquarry.get_format_path()` and can apply a tag to flagged books via `cquarry.write.WritableCalibreDB` (only with explicit `--tag`; the only sanctioned write path). Since v0.19.0 `audit --id BOOK_ID` audits a single library book through cquarry's single-entity `get_book()` fetch (no library-wide cache; supports `--tag`; incompatible with the directory argument; comma lists since v0.23.0). Since v0.22.0 every archive entry is fully read (CRC + decompression) before analysis (a damaged entry reports its own CORRUPT verdict instead of feeding emptytext) and manifest/NCX references to absent files classify as `convention` (bloated ToC, consecutive span) or `fragment` (broken span). Hazard: the scan loop reuses `tag` as its per-book display column, so the `--tag` argument is captured as `audit_tag` at function entry; do not collapse them again. Since v0.29.0 `audit --json FILE` writes per-file analyzer verdicts in the `library --json` shape (directory, library, and single-book modes; with `--id`, exactly one id; emptytext omitted from a record when the archive verdict owns the body-text story). Since v0.44.0 two more advisory analyzers ride the single pass: `cover` (the EPUB3 `properties~="cover-image"` slice of the ruled hybrid: dangling EPUB2 meta, EPUB3 declaration, cover-file presence) and `tocdrift` (the NCX navMap vs EPUB3 nav toc structural diff, fragments included; audit-only, ToC synthesis out of charter permanently); the loader now exposes the parsed OPF, the NCX text, and the nav HTML on `Book`. Since v0.50.0 a ninth analyzer, `contamination` (issue #8, the judge-and-import class, advisory by contract like completeness/cover/tocdrift, never moves the exit code): foreign-title template stamps (head `<title>` repeats or a volume/book marker with named words in front of it, judged against the OPF's own title/creator/publisher/series with a marker-stripped comparison; a part label whose marker leads never flags), fan-bundle ad signatures (jnovels, kokoro connect, zerobooks, a light-novel plug), and review-paste fingerprints (strong flags alone, weak needs corroboration) in the first five content docs; its corpus is spine PLUS `Book.extra_docs` (the archive's non-spine html, retained by the loader in archive order under a 64 MiB cap, because a broken manifest can leave the junk entirely off the spine: Hothouse). Since v0.50.0 `run_directory`/`run_single` dispatch analyzers through `_dir_dispatch` (one entry per ALL key; the old if/elif chain's `else` ran ocr for cover/tocdrift in those modes since v0.44.0) and `tests/test_contamination.py` pins the map's key set to ALL. Since v0.36.0 the completeness analyzer (Phase 15) reports the phase-1 spot-check per book: spine/prose-doc counts (prose = >= 400 visible chars), first/middle/last prose-doc opening/closing excerpts, trailing-ToC classification (`_trailing_toc`: short link lines dominate, no paragraph-length blocks), and the unreadable fraction. It is ADVISORY by contract (problem always False; ADVISORY on a trailing ToC or unreadable fraction >= 10%), never moves the exit code, and is skipped like emptytext when the archive verdict owns the book. Since v0.38.0 the archive verdict distinguishes font obfuscation from DRM (`OBFUSCATION_ALGOS`: IDPF 2008/embedding + both Adobe URIs; readable obfuscated entries are the benign OBFUSCATED advisory, an unreadable one is CORRUPT, and only non-obfuscation algorithms give ENCRYPTED). Since v0.43.0 untrusted metadata XML is parsed through `_safe_xml_parse` (DOCTYPE/ENTITY declarations refused before xml.etree sees them; the stdlib shape of defusedxml's entity protection) and single entries above `_MAX_ENTRY_BYTES` (32 MB) are refused before decompression; a refused metadata file returns the shell book. Since v0.40.0 the vir-tui console renderer loads through the module-level `_LazyUI` proxy (a plain `import vir_tui as ui` at module level would make 3.12/3.13 installs unimportable now that the stack is marker-gated; LOAD_GLOBAL never consults module `__getattr__`, so a proxy object is the lazy shape that works).
|
|
236
237
|
- `src/bindery/epub.py`: archive rewrite, NCX uid sync, RepairReport, mismatch detection, and the opt-in structural-repair plumbing (including the CSS precondition scan). Since v0.59.0 (issue #23) `strip_ncx_dangling_targets` is the NCX dangling-target prune (`--prune-dangling-ncx-targets`): a balanced stack scanner over navPoint/navTarget/pageTarget tokens (quote-aware possessive regex, `_NcxTargetNode` tree, iterative post-order survival pass; header_end delimits the node's own navLabel+`<content>` so a splice removes the tags AND the dead header while the children re-home; an unbalanced walk aborts the part unchanged) and the NCX branch re-runs `fix_ncx_playorder` when it fires, alongside the anchor pass's own re-run. Since v0.58.0 (issue #18) the copy loop hands every `zout.writestr` a PRIVATE ZipInfo (`copy.copy(item)`, a fresh one on a rename) and the media-type `peek` catches `zipfile.BadZipFile` too. HAZARD: `writestr` STAMPS the ZipInfo it is handed with the DESTINATION offsets (header_offset, sizes land on it for the central directory); sharing the source's info repointed zin's own name lookups into the output file mid-loop, and one drifted probe killed whole books as "unreadable" -- 56 books "Bad magic number for file header" plus the "possible zip bomb" Development as Freedom (the drifted offset landed on a valid header whose data overlaps its neighbor), all one root cause. Since v0.58.0 (issue #21) `strip_broken_guide_fragments` gives the OPF guide the NCX fragment-strip's document-precision fallback, and the NCX branch re-runs `fix_ncx_playorder` after the anchor pass fires (the pre-strip sequence goes stale when fragments collapse onto their document). Since v0.58.0 (issue #20) `_resolve_href` decodes the five predefined XML entities plus numeric
|
|
237
238
|
character references before the fragment split (attribute text arrives
|
|
238
239
|
escaped; entries are raw; decoding first keeps the `#` inside `&`
|
|
@@ -675,3 +675,72 @@ rejection is package-profile-driven, not DOCTYPE-driven (7 EPUB3 packages
|
|
|
675
675
|
carrying XHTML 1.1 doctypes: zero attribute findings; every role/
|
|
676
676
|
aria-hidden carrier is version="2.0"), so `package_version()` gating is
|
|
677
677
|
correct as built and only the set grew (`role`, `aria-hidden`).
|
|
678
|
+
|
|
679
|
+
## The Wandering Inn shells: documented, detected, handled manually (2026-11-04)
|
|
680
|
+
|
|
681
|
+
The two Pirateaba serial compilations (Book 18, Book 19) are the library's
|
|
682
|
+
RSC-001 mass: 738 and 736 of their 755/752 manifest items name files the
|
|
683
|
+
archive never carried (98% of the manifest; verified by content walk, NOT a
|
|
684
|
+
spelling mismatch — the 2026-10-25 "different spelling" hypothesis is
|
|
685
|
+
falsified for these two). The archive is a shell: the converter wrote the
|
|
686
|
+
series-wide manifest and shipped a sliver. The spine guard was CORRECT to
|
|
687
|
+
refuse — a repair cannot fabricate 738 files, and dropping the dead spine
|
|
688
|
+
positions would remove the errors from the measurement while the reader
|
|
689
|
+
loses nothing it ever had. Brandon's ruling: these are the best copies
|
|
690
|
+
available; handle manually, document the signature, detect future shells.
|
|
691
|
+
|
|
692
|
+
The detector ships as the audit battery's `shell` analyzer (v0.63.0):
|
|
693
|
+
spine-missing fraction at or over 50% reads `SHELL: re-source, never
|
|
694
|
+
repair`, advisory by contract. Live: `bindery audit all --id 8889` names
|
|
695
|
+
the shell. Known display quirk: the percentage divides by the RESOLVED
|
|
696
|
+
spine count (14), not resolved+missing (752), so shells read over 100%
|
|
697
|
+
— cosmetic, the verdict fires correctly. Manual handling pending:
|
|
698
|
+
re-source both books when a better copy surfaces.
|
|
699
|
+
|
|
700
|
+
### The shell-repair feasibility dig (2026-11-05, facility copies)
|
|
701
|
+
|
|
702
|
+
Falsified the "different spelling" hypothesis for good: Book 19's archive
|
|
703
|
+
carries 14 REAL full-size chapters (0448_743 through 0461_755 — the
|
|
704
|
+
book's exact serial range, 118-156KB each of real prose), and Book 18
|
|
705
|
+
likewise (19 docs, chapters 730-742). The converter shipped the correct
|
|
706
|
+
chapter range but wrote the ENTIRE serial manifest: 738/755 and 736/758
|
|
707
|
+
manifest items name files that were never this book's chapters. The
|
|
708
|
+
"missing" files were never missing from anything — they belong to the
|
|
709
|
+
other books.
|
|
710
|
+
|
|
711
|
+
Feasibility verdict for a suite repair: PROVEN by hand-surgery on the
|
|
712
|
+
Book 19 copy. The recipe (NCX prune via the existing flag + drop the
|
|
713
|
+
dead manifest items and dangling itemrefs + playOrder re-sequence to
|
|
714
|
+
1..K + the doctype/title fixes) lands the book at 0f/5e — from
|
|
715
|
+
0f/742e — as a complete, coherent EPUB of its own chapters. All
|
|
716
|
+
deterministic. The flag design (`--prune-dead-spine`, shell-gated at
|
|
717
|
+
the audit's 50% signature so a lone missing chapter never fires it):
|
|
718
|
+
dead manifest content items + dangling itemrefs dropped, then the
|
|
719
|
+
existing fix_ncx_playorder coordination, then the guide-empty
|
|
720
|
+
coordination with prune_invalid_guide_refs.
|
|
721
|
+
|
|
722
|
+
TWO live discoveries the surgery surfaced, both suite-relevant:
|
|
723
|
+
|
|
724
|
+
1. **The playOrder contract mismatch is REAL and base-free is wrong for
|
|
725
|
+
shell-shaped NCXs**: after the prune, the 14 surviving navPoints keep
|
|
726
|
+
playOrder 448..461 (contiguous run, base 448). The v0.62.0 base-free
|
|
727
|
+
contract reads that satisfied — but epubcheck 5.3 flags BOTH
|
|
728
|
+
"playOrder sequence has gaps" AND "the first playOrder value is not
|
|
729
|
+
1" on this exact NCX. The v0.62.0 minimal matrix (offset-5-8,
|
|
730
|
+
singleton-2) was too minimal: epubcheck demands the 1-base once the
|
|
731
|
+
NCX carries findings it validates deeply (or the shape differs in a
|
|
732
|
+
way the matrix missed). fix_ncx_playorder returning 0 on an NCX
|
|
733
|
+
epubcheck flags is the mismatch, verbatim. A shell repair must
|
|
734
|
+
re-sequence to 1..K unconditionally (not contract-gated), and the
|
|
735
|
+
contract's base-free clause needs this shape added to its test
|
|
736
|
+
matrix.
|
|
737
|
+
2. **The empty-guide coordination**: dropping dead items can empty the
|
|
738
|
+
guide (or prune_invalid_guide_refs can), and an empty `<guide>` is
|
|
739
|
+
itself an RSC-005. The flag design needs the drop-or-fill decision
|
|
740
|
+
for an emptied guide.
|
|
741
|
+
|
|
742
|
+
Manual handling note: both books open fine AS SHIPPED (0 fatals; the
|
|
743
|
+
742/739 RSC-001s are noise to readers). The surgical recipe above is
|
|
744
|
+
the documented manual path; the regex-renumber experiment corrupted a
|
|
745
|
+
test NCX once (greedy `[^>]*` across attributes) — use bindery's own
|
|
746
|
+
transforms, not hand regex, for any real re-sequence.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: bindery-cli
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.64.0
|
|
4
4
|
Summary: Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library.
|
|
5
5
|
Project-URL: Homepage, https://github.com/VirInvictus/bindery-cli
|
|
6
6
|
Project-URL: Repository, https://github.com/VirInvictus/bindery-cli
|
|
@@ -91,6 +91,7 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
|
|
|
91
91
|
- **`--strip-presentational-attrs`**: strips the deprecated presentational hints the XHTML 1.1 DTD rejects wherever they appear (`align`, `valign`, `border`, `bgcolor`, `vspace`, `hspace`, `compact`; body's `link`/`vlink`/`alink`/`text`/`background`; `type` on list elements; Amazon `data-AmznRemoved` junk). Honest caveat: these are presentational hints, and readers that honor them render differently after the strip.
|
|
92
92
|
- **`--encode-ref-brackets`**: percent-encodes raw `[`/`]` in the path portion of internal references whose archive target exists with the raw brackets (RSC-020). Fragments, queries, entry names, and unresolvable/external references stay as written. Runs on content documents, the OPF, the NCX, and stylesheet `url()` tokens.
|
|
93
93
|
- **`--fix-id-colons`** also renames any content-document `id` that cannot be an XML NCName (digit-led scraped ids, apostrophe-bearing calibre ids) since v0.63.0, syncing internal fragments with the same `id_` scheme as the manifest half.
|
|
94
|
+
- **`--prune-dead-spine`**: the shell repair — fires ONLY when half or more of the manifest's content hrefs name files the archive never carried (the audit battery's `shell` analyzer names the same shape). Drops the dead manifest items, the spine itemrefs that name them, and the dead NCX navPoints, then re-sequences the surviving playOrders to 1..K. A lone missing chapter never crosses the signature: the spine non-goal stays in force for ordinary damage. The Wandering Inn serial shells (738 and 736 of 755/752 items dead) are the design case; proven at 742e → 5e with 0 fatals.
|
|
94
95
|
|
|
95
96
|
Four opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
|
|
96
97
|
|
|
@@ -64,6 +64,7 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
|
|
|
64
64
|
- **`--strip-presentational-attrs`**: strips the deprecated presentational hints the XHTML 1.1 DTD rejects wherever they appear (`align`, `valign`, `border`, `bgcolor`, `vspace`, `hspace`, `compact`; body's `link`/`vlink`/`alink`/`text`/`background`; `type` on list elements; Amazon `data-AmznRemoved` junk). Honest caveat: these are presentational hints, and readers that honor them render differently after the strip.
|
|
65
65
|
- **`--encode-ref-brackets`**: percent-encodes raw `[`/`]` in the path portion of internal references whose archive target exists with the raw brackets (RSC-020). Fragments, queries, entry names, and unresolvable/external references stay as written. Runs on content documents, the OPF, the NCX, and stylesheet `url()` tokens.
|
|
66
66
|
- **`--fix-id-colons`** also renames any content-document `id` that cannot be an XML NCName (digit-led scraped ids, apostrophe-bearing calibre ids) since v0.63.0, syncing internal fragments with the same `id_` scheme as the manifest half.
|
|
67
|
+
- **`--prune-dead-spine`**: the shell repair — fires ONLY when half or more of the manifest's content hrefs name files the archive never carried (the audit battery's `shell` analyzer names the same shape). Drops the dead manifest items, the spine itemrefs that name them, and the dead NCX navPoints, then re-sequences the surviving playOrders to 1..K. A lone missing chapter never crosses the signature: the spine non-goal stays in force for ordinary damage. The Wandering Inn serial shells (738 and 736 of 755/752 items dead) are the design case; proven at 742e → 5e with 0 fatals.
|
|
67
68
|
|
|
68
69
|
Four opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
|
|
69
70
|
|
|
@@ -1,5 +1,71 @@
|
|
|
1
1
|
# bindery-cli Patch Notes
|
|
2
2
|
|
|
3
|
+
## v0.64.0 (2026-11-05)
|
|
4
|
+
|
|
5
|
+
### --prune-dead-spine: the shell repair
|
|
6
|
+
|
|
7
|
+
The Wandering Inn feasibility dig proved the recipe on the facility
|
|
8
|
+
copies (0f/742e -> 0f/5e, 0 fatals, a complete coherent book of its own
|
|
9
|
+
chapters); this release builds it as a flag. The diagnosis falsified the
|
|
10
|
+
2026-10-25 "different spelling" hypothesis: Book 18 and Book 19 carry
|
|
11
|
+
their REAL, complete chapter ranges (730-742 and 743-755, full-size
|
|
12
|
+
prose docs) -- the converter shipped the right chapters and wrote the
|
|
13
|
+
ENTIRE serial manifest, so 738 and 736 of 755/752 manifest items name
|
|
14
|
+
files that were never this book's chapters. The books are not damaged
|
|
15
|
+
goods: they are complete books wrapped in another book's manifest.
|
|
16
|
+
|
|
17
|
+
`--prune-dead-spine` fires ONLY at the shell signature -- half or more
|
|
18
|
+
of the manifest's content hrefs name files the archive does not carry
|
|
19
|
+
(the audit battery's `shell` analyzer, v0.63.0, names the same shape).
|
|
20
|
+
At the signature it drops the dead manifest items and the spine itemrefs
|
|
21
|
+
that name them, prunes the dead NCX navPoints (the existing
|
|
22
|
+
dangling-target prune, coordinated on via a dataclasses.replace), and
|
|
23
|
+
re-sequences the surviving playOrders to 1..K. Below the signature --
|
|
24
|
+
a lone missing chapter, a broken fragment -- it never fires: the spine
|
|
25
|
+
non-goal ("missing spine documents mean corrupt archives or broken
|
|
26
|
+
fragments") stays in force for ordinary damage, now with a third,
|
|
27
|
+
measured exception: the wholesale shell.
|
|
28
|
+
|
|
29
|
+
Two live findings the build closed out:
|
|
30
|
+
|
|
31
|
+
- **The playOrder contract is not base-free on the shell shape.** The
|
|
32
|
+
v0.62.0 base-free clause was built from a minimal matrix that validated
|
|
33
|
+
offset runs (448..461-shaped) clean -- but epubcheck 5.3 flagged BOTH
|
|
34
|
+
"playOrder sequence has gaps" AND "the first playOrder value is not 1"
|
|
35
|
+
on the post-prune Wandering Inn NCX. The oracle rules: the shell
|
|
36
|
+
repair re-sequences to 1..K unconditionally (a `force` parameter on
|
|
37
|
+
`fix_ncx_playorder`), and the base-free clause's test matrix gains the
|
|
38
|
+
shell shape as a known divergence.
|
|
39
|
+
- **fix_ncx_playorder gains `force`**: the shell repair's playOrder
|
|
40
|
+
half must re-sequence even where the contract reads satisfied.
|
|
41
|
+
|
|
42
|
+
The proven end state on the facility copy: 0f/5e (from 0f/742e), a
|
|
43
|
+
complete readable book of its own chapters -- nothing real is lost; the
|
|
44
|
+
dropped positions never resolved in any reader.
|
|
45
|
+
|
|
46
|
+
Suite: 917 tests.
|
|
47
|
+
|
|
48
|
+
## v0.63.1 (2026-11-04)
|
|
49
|
+
|
|
50
|
+
### Two single-flag live-verification catches
|
|
51
|
+
|
|
52
|
+
Running each v0.63.0 flag alone against its real carriers caught two
|
|
53
|
+
wiring slips the --all-sized sweeps could never see:
|
|
54
|
+
|
|
55
|
+
- **`--encode-ref-brackets` alone was a silent no-op**: the encode reads
|
|
56
|
+
`present` (the archive existence set), but `present` only fills when
|
|
57
|
+
one of the prune/anchors/media-types/declare/prune-NCX flags asked for
|
|
58
|
+
it -- the new flag wasn't in that guard, so the set stayed empty, every
|
|
59
|
+
reference resolved to nothing, and the flag answered "no applicable
|
|
60
|
+
fixes" on a book whose NCX carries 59 bracket srcs (The Given Day:
|
|
61
|
+
`Dennis_Lehane_-_The_Given_Day_[html]_split_000.html`). The guard now
|
|
62
|
+
includes the flag; the live apply encodes 59 NCX srcs, zero raw left.
|
|
63
|
+
- **The audit CLI's `--only` choices lacked `shell`**: the analyzer
|
|
64
|
+
shipped in v0.63.0 but `bindery audit --only shell` died at argparse
|
|
65
|
+
(invalid choice). The choice is registered.
|
|
66
|
+
|
|
67
|
+
Suite: 913 tests.
|
|
68
|
+
|
|
3
69
|
## v0.63.0 (2026-11-04)
|
|
4
70
|
|
|
5
71
|
### The harvest census: two new flags, the id scope, and the shell detector
|
|
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "bindery-cli"
|
|
7
|
-
version = "0.
|
|
7
|
+
version = "0.64.0"
|
|
8
8
|
description = "Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
classifiers = [
|
|
@@ -59,6 +59,8 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
|
|
|
59
59
|
| 0.62.1 | `--fix-double-colon-tags`: the pseudo-tag escape for the last library fatal -- an XML name carries at most one colon, so a `::`-named pseudo-tag is never markup (fatal RSC-016; the Book of Debugging's C++ samples), and escaping both ends restores the author's text; nested templates escape inner-first, real markup is unreachable by construction; also closes the spec.md drift (the four v0.62.0 flags had not joined the inventory) | v0.62.1 |
|
|
60
60
|
| 0.62.2 | The review batch (three-reviewer pass over the v0.62.x range): the item-properties insertion branch emitted malformed XML on the self-closed shape (attribute after the solidus; no test drove the branch -- every fixture pre-carried properties), now appends before the solidus with an ET-parsed pin; the missing-title empty-fill is head-scoped (an empty SVG `<title>` is visible text); the double-colon tail is bounded at 120 chars (the escaped-bracket runaway); the unverified on\* handler disjunct left the census; `_scan_doctype_span` refuses unterminated declarations; the guide-prune docstring matches the code; and the documentation inventories caught up (README's seven missing flags, spec.md's four behavioral bullets + body counts + the safe-opt-in section, AGENTS.md's inventory) | v0.62.2 |
|
|
61
61
|
| 0.63 | The harvest census (the honest dig into the remaining 14,109): `--strip-presentational-attrs` (the largest attribute family; rendering-caveat approved), `--encode-ref-brackets` (the issue #19 mechanism applied to brackets without spaces; the 59-book RSC-020 lane), `--fix-id-colons` broadened to every NCName failure (digit-led scraped ids; the apostrophe charset blind spot closed), and the audit battery's `shell` analyzer (the Wandering Inn detector: spine-missing fraction at or over 50% reads SHELL, re-source never repair) | v0.63.0 |
|
|
62
|
+
| 0.63.1 | Two single-flag live-verification catches: `--encode-ref-brackets` alone was a silent no-op (`present` only filled under the other flags' guard -- The Given Day's 59 NCX bracket srcs encoded, zero raw left, once the guard included the flag), and the audit CLI's `--only` choices lacked `shell` | v0.63.1 |
|
|
63
|
+
| 0.64 | `--prune-dead-spine`: the shell repair, shell-gated at the 50% signature (drops dead manifest items + spine itemrefs, coordinates the NCX navPoint prune and an UNCONDITIONAL playOrder re-sequence to 1..K after epubcheck 5.3 flagged the non-1 base on the post-prune shape -- the base-free clause's minimal matrix missed the shell shape); proven at 742e -> 5e on the facility copy | v0.64.0 |
|
|
62
64
|
|
|
63
65
|
## Open work
|
|
64
66
|
|
|
@@ -70,6 +72,9 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
|
|
|
70
72
|
gate refuses a book that is otherwise repaired. Needs the same
|
|
71
73
|
entry-and-reference coordination as the space renames, with the
|
|
72
74
|
decode-before-lookup epubcheck rule verified per character class.
|
|
75
|
+
*v0.63.0 narrowed this: `--encode-ref-brackets` ships the bracket
|
|
76
|
+
slice (the decode-before-lookup rule verified for `%5B`/`%5D`); the
|
|
77
|
+
comma and remaining classes stay open.*
|
|
73
78
|
*(Narrowed v0.58.0: renamed references now percent-encode `[`/`]`
|
|
74
79
|
(issue #19), so a book whose bracket-named entries carry spaces
|
|
75
80
|
repairs cleanly. The no-rename shape remains: entries with brackets
|
|
@@ -13,7 +13,7 @@ restyle, re-compress, or restructure content, and it does not attempt to fix arb
|
|
|
13
13
|
schema (RSC-005) violations, which are usually harmless to readers and not safely
|
|
14
14
|
mechanizable.
|
|
15
15
|
|
|
16
|
-
The deliberate exceptions to "semantics-preserving" come in opt-in groups. The thirty-
|
|
16
|
+
The deliberate exceptions to "semantics-preserving" come in opt-in groups. The thirty-three
|
|
17
17
|
**structural repairs** (`--fix-empty-body`, `--fix-missing-title`, `--fix-id-colons`,
|
|
18
18
|
`--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
|
|
19
19
|
`--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`,
|
|
@@ -25,7 +25,8 @@ The deliberate exceptions to "semantics-preserving" come in opt-in groups. The t
|
|
|
25
25
|
`--fix-stray-close`, `--fix-unterminated-attr`, `--fix-unbound-prefix`,
|
|
26
26
|
`--fix-unique-identifier`, `--fix-package-version`, `--fix-doctype`,
|
|
27
27
|
`--prune-invalid-guide-refs`, `--fix-item-properties`,
|
|
28
|
-
`--strip-presentational-attrs`, `--encode-ref-brackets
|
|
28
|
+
`--strip-presentational-attrs`, `--encode-ref-brackets`,
|
|
29
|
+
`--prune-dead-spine`) alter
|
|
29
30
|
markup structure or fabricate minimal content; the four
|
|
30
31
|
**lossy modes** (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`,
|
|
31
32
|
`--strip-stub-docs`) remove
|
|
@@ -534,7 +535,24 @@ leftovers whose failing OPF is a stale non-rootfile are unreachable by construct
|
|
|
534
535
|
walk covers content documents, the OPF, the NCX, and stylesheet `url()`
|
|
535
536
|
tokens.
|
|
536
537
|
|
|
537
|
-
|
|
538
|
+
- **`--prune-dead-spine`**: the shell repair -- fires ONLY when half or
|
|
539
|
+
more of the manifest's content hrefs name files the archive does not
|
|
540
|
+
carry (the audit battery's `shell` analyzer names the same shape; the
|
|
541
|
+
2026-11-04 Wandering Inn shells: 738 and 736 of 755/752 items dead --
|
|
542
|
+
verified by content walk as the OTHER books' chapters, never a spelling
|
|
543
|
+
mismatch). Drops the dead manifest items and the spine itemrefs that
|
|
544
|
+
name them, prunes the dead NCX navPoints (the existing dangling-target
|
|
545
|
+
prune, coordinated on), and re-sequences the surviving playOrders to
|
|
546
|
+
1..K UNCONDITIONALLY -- epubcheck 5.3 flagged "the first playOrder
|
|
547
|
+
value is not 1" on the post-prune 448..461 run even though the
|
|
548
|
+
base-free contract read it satisfied (the minimal matrix missed the
|
|
549
|
+
shell shape; the oracle rules). Nothing real is lost: the dropped
|
|
550
|
+
positions never resolved, and the book that remains is the complete,
|
|
551
|
+
coherent chapter range the archive actually carries. A lone missing
|
|
552
|
+
chapter never crosses the signature: the spine non-goal stays in force
|
|
553
|
+
for ordinary damage.
|
|
554
|
+
|
|
555
|
+
Thirty of the thirty-three are evaluated by the normal `gate`: unlike the lossy strips,
|
|
538
556
|
their benefit is visible to epubcheck (they clear errors), so a run with no measurable
|
|
539
557
|
improvement is a noop and nothing is applied. The three exceptions are `--fix-cover`, `--encode-url-spaces`, and
|
|
540
558
|
`--fix-media-types` (whose gains sit on axes epubcheck's counts do not measure:
|
|
@@ -11,7 +11,7 @@ Calibre plugin built from this core.
|
|
|
11
11
|
Single source of truth for the version. pyproject.toml must match VERSION below.
|
|
12
12
|
"""
|
|
13
13
|
|
|
14
|
-
VERSION = "0.
|
|
14
|
+
VERSION = "0.64.0"
|
|
15
15
|
__version__ = VERSION
|
|
16
16
|
|
|
17
17
|
from .epub import RepairReport, repair_epub # noqa: E402
|
|
@@ -116,6 +116,7 @@ def _flags_from_args(args: argparse.Namespace) -> RepairFlags:
|
|
|
116
116
|
double_colon_tags=args.fix_double_colon_tags or all_,
|
|
117
117
|
presentational_attrs=args.strip_presentational_attrs or all_,
|
|
118
118
|
encode_ref_brackets=args.encode_ref_brackets or all_,
|
|
119
|
+
prune_dead_spine=args.prune_dead_spine or all_,
|
|
119
120
|
)
|
|
120
121
|
|
|
121
122
|
|
|
@@ -1831,6 +1832,23 @@ _REPAIR_FLAG_TABLE: dict[str, list[tuple[str, str, str]]] = {
|
|
|
1831
1832
|
),
|
|
1832
1833
|
],
|
|
1833
1834
|
"structural repairs: references and resources": [
|
|
1835
|
+
(
|
|
1836
|
+
"prune_dead_spine",
|
|
1837
|
+
"the shell repair: drop manifest items and spine positions whose files the archive never carried",
|
|
1838
|
+
"fires ONLY at the shell signature -- half or more of the "
|
|
1839
|
+
"manifest's content hrefs name files the archive does not carry "
|
|
1840
|
+
"(the audit battery's `shell` analyzer names the same shape). "
|
|
1841
|
+
"Drops the dead manifest items, the spine itemrefs that name "
|
|
1842
|
+
"them, and (coordinated) the dead NCX navPoints, then "
|
|
1843
|
+
"re-sequences the surviving playOrders to 1..K unconditionally: "
|
|
1844
|
+
"epubcheck 5.3 demands the 1-base on the post-prune shape even "
|
|
1845
|
+
"where the base-free contract reads a contiguous offset run "
|
|
1846
|
+
"satisfied. A lone missing chapter NEVER crosses the signature: "
|
|
1847
|
+
"the spine non-goal stays in force for ordinary damage. The "
|
|
1848
|
+
"2026-11-04 Wandering Inn shells (738 and 736 of 755/752 items "
|
|
1849
|
+
"dead) are the design case; proven on the facility copy at "
|
|
1850
|
+
"742e -> 5e with 0 fatals.",
|
|
1851
|
+
),
|
|
1834
1852
|
(
|
|
1835
1853
|
"encode_ref_brackets",
|
|
1836
1854
|
"percent-encode raw [ ] in internal references whose target exists (RSC-020)",
|
|
@@ -2484,6 +2502,7 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
2484
2502
|
"cover",
|
|
2485
2503
|
"tocdrift",
|
|
2486
2504
|
"contamination",
|
|
2505
|
+
"shell",
|
|
2487
2506
|
"all",
|
|
2488
2507
|
),
|
|
2489
2508
|
help="which audit to run",
|
|
@@ -285,6 +285,7 @@ class RepairFlags:
|
|
|
285
285
|
double_colon_tags: bool = False
|
|
286
286
|
presentational_attrs: bool = False
|
|
287
287
|
encode_ref_brackets: bool = False
|
|
288
|
+
prune_dead_spine: bool = False
|
|
288
289
|
|
|
289
290
|
|
|
290
291
|
@dataclass
|
|
@@ -522,6 +523,37 @@ def _manifest_media_type_map(opf_text: str, opf_dir: str) -> dict[str, str]:
|
|
|
522
523
|
return out
|
|
523
524
|
|
|
524
525
|
|
|
526
|
+
def prune_dead_spine_items(
|
|
527
|
+
opf_text: str, dead_ids: frozenset[str] | set[str]
|
|
528
|
+
) -> tuple[str, int]:
|
|
529
|
+
"""Drop manifest items whose ids are in `dead_ids` (content items whose
|
|
530
|
+
files the archive never carried) and the spine itemrefs that name them
|
|
531
|
+
-- the shell repair's manifest half, gated upstream on the >= 50%
|
|
532
|
+
signature. Document order survives: everything not dropped passes
|
|
533
|
+
through byte-identical, and the `spine toc` attribute is untouched.
|
|
534
|
+
Returns the number of ITEMS dropped (the itemrefs follow silently)."""
|
|
535
|
+
count = 0
|
|
536
|
+
|
|
537
|
+
def drop_item(m: re.Match) -> str:
|
|
538
|
+
nonlocal count
|
|
539
|
+
im = _XML_ID_RE.search(m.group(0))
|
|
540
|
+
if im and im.group(3) in dead_ids:
|
|
541
|
+
count += 1
|
|
542
|
+
return ""
|
|
543
|
+
return m.group(0)
|
|
544
|
+
|
|
545
|
+
out = _ITEM_TAG_RE.sub(drop_item, opf_text)
|
|
546
|
+
|
|
547
|
+
def drop_ref(m: re.Match) -> str:
|
|
548
|
+
rm = _IDREF_ATTR_RE.search(m.group(0))
|
|
549
|
+
if rm and rm.group(3) in dead_ids:
|
|
550
|
+
return ""
|
|
551
|
+
return m.group(0)
|
|
552
|
+
|
|
553
|
+
out = _SPINE_ITEM_RE.sub(drop_ref, out)
|
|
554
|
+
return out, count
|
|
555
|
+
|
|
556
|
+
|
|
525
557
|
def prune_invalid_guide_refs(opf_text: str, opf_dir: str) -> tuple[str, int]:
|
|
526
558
|
"""Remove guide ``<reference>`` elements whose target is declared but is
|
|
527
559
|
not an OPS content document (OPF-032).
|
|
@@ -2531,6 +2563,8 @@ def repair_epub(
|
|
|
2531
2563
|
or flags.fix_media_types
|
|
2532
2564
|
or flags.declare_missing
|
|
2533
2565
|
or flags.prune_ncx_targets
|
|
2566
|
+
or flags.encode_ref_brackets
|
|
2567
|
+
or flags.prune_dead_spine
|
|
2534
2568
|
):
|
|
2535
2569
|
for n in zin.namelist():
|
|
2536
2570
|
norm_to_raw.setdefault(_norm_path(space_renames.get(n, n)), n)
|
|
@@ -2543,6 +2577,40 @@ def repair_epub(
|
|
|
2543
2577
|
undeclared: frozenset[str] = frozenset()
|
|
2544
2578
|
if flags.declare_missing and opf_text is not None:
|
|
2545
2579
|
undeclared = collect_undeclared_resources(zin, opf_text, opf_dir, present)
|
|
2580
|
+
# --prune-dead-spine: the shell signature, computed once like the
|
|
2581
|
+
# prune's existence set. Dead = manifest CONTENT items whose href
|
|
2582
|
+
# file the archive does not carry; the flag only fires at the
|
|
2583
|
+
# audit's shell signature (>= 50% of the content manifest missing),
|
|
2584
|
+
# so a lone missing chapter never crosses it and the spine
|
|
2585
|
+
# non-goal stays in force for ordinary damage (the 2026-11-04
|
|
2586
|
+
# Wandering Inn diagnosis: 738 and 736 of 755/752 items dead).
|
|
2587
|
+
shell_ok = False
|
|
2588
|
+
dead_spine_ids: frozenset[str] = frozenset()
|
|
2589
|
+
if flags.prune_dead_spine and opf_text is not None and present:
|
|
2590
|
+
total_content = 0
|
|
2591
|
+
dead: set[str] = set()
|
|
2592
|
+
for m in _ITEM_TAG_RE.finditer(opf_text):
|
|
2593
|
+
tag = m.group(0)
|
|
2594
|
+
hm = _HREF_ATTR_RE.search(tag)
|
|
2595
|
+
im = _XML_ID_RE.search(tag)
|
|
2596
|
+
if not hm or not im:
|
|
2597
|
+
continue
|
|
2598
|
+
href = hm.group(2)
|
|
2599
|
+
if not href.lower().endswith((".xhtml", ".html", ".htm")):
|
|
2600
|
+
continue
|
|
2601
|
+
total_content += 1
|
|
2602
|
+
resolved = _resolve_href(opf_dir, href)
|
|
2603
|
+
if resolved is None or resolved not in present:
|
|
2604
|
+
dead.add(im.group(3))
|
|
2605
|
+
if total_content and len(dead) / total_content >= 0.5:
|
|
2606
|
+
shell_ok = True
|
|
2607
|
+
dead_spine_ids = frozenset(dead)
|
|
2608
|
+
# the NCX half coordinates: the navPoint prune drops the
|
|
2609
|
+
# dead navPoints and the playOrders re-sequence to 1..K
|
|
2610
|
+
# (forced -- epubcheck 5.3 demands the 1-base on the
|
|
2611
|
+
# post-prune shape even where the minimal matrix said the
|
|
2612
|
+
# base was free)
|
|
2613
|
+
flags = replace(flags, prune_ncx_targets=True)
|
|
2546
2614
|
item_props: dict[str, frozenset[str]] = {}
|
|
2547
2615
|
if flags.item_properties:
|
|
2548
2616
|
item_props = collect_item_properties(zin)
|
|
@@ -2812,6 +2880,18 @@ def repair_epub(
|
|
|
2812
2880
|
counts["fix_ncx_playorder"] = (
|
|
2813
2881
|
counts.get("fix_ncx_playorder", 0) + n2
|
|
2814
2882
|
)
|
|
2883
|
+
if shell_ok:
|
|
2884
|
+
# The shell repair's playOrder half, UNCONDITIONAL (not
|
|
2885
|
+
# contract-gated): epubcheck 5.3 flagged "the first
|
|
2886
|
+
# playOrder value is not 1" on the post-prune 448..461
|
|
2887
|
+
# run -- the base-free clause reads that satisfied, but
|
|
2888
|
+
# on the shell shape the oracle demands the 1-base.
|
|
2889
|
+
# Re-sequence to 1..K in document order.
|
|
2890
|
+
text, n2 = fix_ncx_playorder(text, force=True)
|
|
2891
|
+
if n2:
|
|
2892
|
+
counts["fix_ncx_playorder"] = (
|
|
2893
|
+
counts.get("fix_ncx_playorder", 0) + n2
|
|
2894
|
+
)
|
|
2815
2895
|
synced = False
|
|
2816
2896
|
sync_uid = uid if uid else wired_uid
|
|
2817
2897
|
if sync_uid:
|
|
@@ -2839,6 +2919,7 @@ def repair_epub(
|
|
|
2839
2919
|
or flags.package_version
|
|
2840
2920
|
or flags.prune_guide_refs
|
|
2841
2921
|
or flags.item_properties
|
|
2922
|
+
or flags.prune_dead_spine
|
|
2842
2923
|
):
|
|
2843
2924
|
opf_changed = False
|
|
2844
2925
|
if flags.package_version:
|
|
@@ -2849,6 +2930,16 @@ def repair_epub(
|
|
|
2849
2930
|
if n:
|
|
2850
2931
|
report.add({"package_version_fixed": n})
|
|
2851
2932
|
opf_changed = True
|
|
2933
|
+
if flags.prune_dead_spine and shell_ok and dead_spine_ids:
|
|
2934
|
+
# The shell repair's manifest half (gated on the >= 50%
|
|
2935
|
+
# signature computed above): dead content items and the
|
|
2936
|
+
# spine itemrefs that name them drop together. The NCX
|
|
2937
|
+
# half (navPoint prune + forced playOrder re-sequence)
|
|
2938
|
+
# runs in the NCX branch.
|
|
2939
|
+
text, n = prune_dead_spine_items(text, dead_spine_ids)
|
|
2940
|
+
if n:
|
|
2941
|
+
report.add({"dead_spine_items_pruned": n})
|
|
2942
|
+
opf_changed = True
|
|
2852
2943
|
if flags.unbound_prefix:
|
|
2853
2944
|
# First in the branch: the unbound prefix makes the whole
|
|
2854
2945
|
# package unparseable, so the parseability scar comes off
|
|
@@ -351,10 +351,19 @@ _CONTENT_SRC_RE = re.compile(
|
|
|
351
351
|
|
|
352
352
|
|
|
353
353
|
@_outside_protected
|
|
354
|
-
def fix_ncx_playorder(s: str) -> tuple[str, int]:
|
|
354
|
+
def fix_ncx_playorder(s: str, *, force: bool = False) -> tuple[str, int]:
|
|
355
355
|
"""Re-sequence `playOrder` values so the NCX satisfies epubcheck's playOrder
|
|
356
356
|
contract, and touch nothing when it already does.
|
|
357
357
|
|
|
358
|
+
`force` (v0.64.0, the shell repair's coordination) skips the
|
|
359
|
+
satisfied-contract early return and re-sequences to 1..K
|
|
360
|
+
unconditionally. The prune-dead-spine flag needs it: epubcheck 5.3
|
|
361
|
+
flagged "the first playOrder value is not 1" on the surviving 448..461
|
|
362
|
+
run of a shell NCX whose dead navPoints had just been pruned -- the
|
|
363
|
+
base-free clause reads that run satisfied, but on the post-prune shape
|
|
364
|
+
the oracle demands the 1-base (the v0.62.0 minimal matrix missed this
|
|
365
|
+
shape; the contract is base-free only where the oracle says so).
|
|
366
|
+
|
|
358
367
|
Contract-gated (the 2026-10-24 whole-library surgery): the previous form
|
|
359
368
|
renumbered every `<navPoint>` to document-order 1..N unconditionally, which
|
|
360
369
|
rewrote VALID TOCs into violations -- navPoints whose `<content src>` share
|
|
@@ -435,7 +444,7 @@ def fix_ncx_playorder(s: str) -> tuple[str, int]:
|
|
|
435
444
|
contract_ok = False
|
|
436
445
|
break
|
|
437
446
|
used |= vals
|
|
438
|
-
if contract_ok and used and len(used) == len(groups):
|
|
447
|
+
if not force and contract_ok and used and len(used) == len(groups):
|
|
439
448
|
lo = min(used)
|
|
440
449
|
if used == set(range(lo, lo + len(used))):
|
|
441
450
|
return s, 0
|
|
@@ -3806,3 +3806,122 @@ class TestEncodeRefBrackets(unittest.TestCase):
|
|
|
3806
3806
|
)
|
|
3807
3807
|
self.assertEqual(n, 1)
|
|
3808
3808
|
self.assertIn("url(img%5B3%5D.png)", out)
|
|
3809
|
+
|
|
3810
|
+
|
|
3811
|
+
class TestPruneDeadSpine(unittest.TestCase):
|
|
3812
|
+
"""--prune-dead-spine: the shell repair. Fires ONLY at the shell
|
|
3813
|
+
signature (>= 50% of the manifest's content hrefs name files the
|
|
3814
|
+
archive does not carry) -- a lone missing chapter never crosses it,
|
|
3815
|
+
so the spine non-goal stays in force for ordinary damage. Proven on
|
|
3816
|
+
the Wandering Inn facility copies at 742e -> 5e with 0 fatals."""
|
|
3817
|
+
|
|
3818
|
+
def _opf(self, version="2.0", items=()):
|
|
3819
|
+
manifest = "".join(
|
|
3820
|
+
f'<item id="{iid}" href="{href}" media-type="application/xhtml+xml"/>'
|
|
3821
|
+
for iid, href in items
|
|
3822
|
+
)
|
|
3823
|
+
spine = "".join(f'<itemref idref="{iid}"/>' for iid, _ in items)
|
|
3824
|
+
return (
|
|
3825
|
+
'<?xml version="1.0"?>'
|
|
3826
|
+
'<package xmlns="http://www.idpf.org/2007/opf" '
|
|
3827
|
+
f'version="{version}" unique-identifier="id">'
|
|
3828
|
+
'<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">'
|
|
3829
|
+
'<dc:identifier id="id">x</dc:identifier>'
|
|
3830
|
+
"<dc:title>t</dc:title><dc:language>en</dc:language></metadata>"
|
|
3831
|
+
f"<manifest>{manifest}</manifest>"
|
|
3832
|
+
f"<spine>{spine}</spine></package>"
|
|
3833
|
+
)
|
|
3834
|
+
|
|
3835
|
+
def _doc(self, title):
|
|
3836
|
+
return (
|
|
3837
|
+
'<?xml version="1.0"?><html xmlns="http://www.w3.org/1999/xhtml">'
|
|
3838
|
+
f"<head><title>{title}</title></head><body><p>{title}</p></body></html>"
|
|
3839
|
+
)
|
|
3840
|
+
|
|
3841
|
+
def _build(self, td, opf, docs):
|
|
3842
|
+
s = Path(td) / "in.epub"
|
|
3843
|
+
with zipfile.ZipFile(s, "w", zipfile.ZIP_DEFLATED) as z:
|
|
3844
|
+
z.writestr("mimetype", "application/epub+zip")
|
|
3845
|
+
z.writestr("OEBPS/content.opf", opf)
|
|
3846
|
+
for name, data in docs.items():
|
|
3847
|
+
z.writestr(name, data)
|
|
3848
|
+
return s
|
|
3849
|
+
|
|
3850
|
+
def test_shell_signature_prunes_items_and_refs(self):
|
|
3851
|
+
# 4 content items, only 1 file shipped: 75% missing = shell
|
|
3852
|
+
opf = self._opf(
|
|
3853
|
+
version="2.0",
|
|
3854
|
+
items=[
|
|
3855
|
+
("live", "live.xhtml"),
|
|
3856
|
+
("d1", "ghost1.xhtml"),
|
|
3857
|
+
("d2", "ghost2.xhtml"),
|
|
3858
|
+
("d3", "ghost3.xhtml"),
|
|
3859
|
+
],
|
|
3860
|
+
)
|
|
3861
|
+
with tempfile.TemporaryDirectory() as td:
|
|
3862
|
+
s = self._build(td, opf, {"OEBPS/live.xhtml": self._doc("L")})
|
|
3863
|
+
d = Path(td) / "out.epub"
|
|
3864
|
+
report = repair_epub(s, d, RepairFlags(prune_dead_spine=True))
|
|
3865
|
+
self.assertGreaterEqual(report.fixes.get("dead_spine_items_pruned"), 3)
|
|
3866
|
+
with zipfile.ZipFile(d) as z:
|
|
3867
|
+
out = z.read("OEBPS/content.opf").decode()
|
|
3868
|
+
self.assertNotIn("ghost1.xhtml", out)
|
|
3869
|
+
self.assertNotIn('idref="d1"', out)
|
|
3870
|
+
self.assertIn('idref="live"', out)
|
|
3871
|
+
ET.fromstring(out)
|
|
3872
|
+
|
|
3873
|
+
def test_sub_shell_fraction_refuses(self):
|
|
3874
|
+
# 1 of 4 missing: 25% — a lone missing chapter never crosses the
|
|
3875
|
+
# signature and the spine non-goal stays in force
|
|
3876
|
+
opf = self._opf(
|
|
3877
|
+
version="2.0",
|
|
3878
|
+
items=[
|
|
3879
|
+
("live", "live.xhtml"),
|
|
3880
|
+
("b", "b.xhtml"),
|
|
3881
|
+
("c", "c.xhtml"),
|
|
3882
|
+
("ghost", "ghost.xhtml"),
|
|
3883
|
+
],
|
|
3884
|
+
)
|
|
3885
|
+
with tempfile.TemporaryDirectory() as td:
|
|
3886
|
+
docs = {
|
|
3887
|
+
"OEBPS/live.xhtml": self._doc("L"),
|
|
3888
|
+
"OEBPS/b.xhtml": self._doc("B"),
|
|
3889
|
+
"OEBPS/c.xhtml": self._doc("C"),
|
|
3890
|
+
}
|
|
3891
|
+
s = self._build(td, opf, docs)
|
|
3892
|
+
d = Path(td) / "out.epub"
|
|
3893
|
+
report = repair_epub(s, d, RepairFlags(prune_dead_spine=True))
|
|
3894
|
+
self.assertNotIn("dead_spine_items_pruned", report.fixes)
|
|
3895
|
+
with zipfile.ZipFile(d) as z:
|
|
3896
|
+
out = z.read("OEBPS/content.opf").decode()
|
|
3897
|
+
self.assertIn("ghost.xhtml", out)
|
|
3898
|
+
|
|
3899
|
+
def test_images_and_ncx_items_are_never_dead(self):
|
|
3900
|
+
# the dead set is content-doc items only: the NCX/CSS/images keep
|
|
3901
|
+
# their manifest entries whatever their files' fate
|
|
3902
|
+
opf = self._opf(
|
|
3903
|
+
version="2.0",
|
|
3904
|
+
items=[
|
|
3905
|
+
("live", "live.xhtml"),
|
|
3906
|
+
("d1", "g1.xhtml"),
|
|
3907
|
+
("d2", "g2.xhtml"),
|
|
3908
|
+
("d3", "g3.xhtml"),
|
|
3909
|
+
],
|
|
3910
|
+
)
|
|
3911
|
+
opf = opf.replace(
|
|
3912
|
+
"</manifest>",
|
|
3913
|
+
'<item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml"/>'
|
|
3914
|
+
'<item id="css" href="s.css" media-type="text/css"/>'
|
|
3915
|
+
'<item id="img" href="i.jpg" media-type="image/jpeg"/>'
|
|
3916
|
+
"</manifest>",
|
|
3917
|
+
)
|
|
3918
|
+
with tempfile.TemporaryDirectory() as td:
|
|
3919
|
+
docs = {"OEBPS/live.xhtml": self._doc("L")}
|
|
3920
|
+
s = self._build(td, opf, docs)
|
|
3921
|
+
d = Path(td) / "out.epub"
|
|
3922
|
+
repair_epub(s, d, RepairFlags(prune_dead_spine=True))
|
|
3923
|
+
with zipfile.ZipFile(d) as z:
|
|
3924
|
+
out = z.read("OEBPS/content.opf").decode()
|
|
3925
|
+
self.assertIn('id="ncx"', out)
|
|
3926
|
+
self.assertIn('id="css"', out)
|
|
3927
|
+
self.assertIn('id="img"', out)
|
|
@@ -529,6 +529,20 @@ def _fixtures() -> dict:
|
|
|
529
529
|
},
|
|
530
530
|
"item_properties_added",
|
|
531
531
|
),
|
|
532
|
+
"--prune-dead-spine": (
|
|
533
|
+
{
|
|
534
|
+
"OEBPS/content.opf": _opf(
|
|
535
|
+
[
|
|
536
|
+
_item("live", "live.xhtml"),
|
|
537
|
+
_item("d1", "ghost1.xhtml"),
|
|
538
|
+
_item("d2", "ghost2.xhtml"),
|
|
539
|
+
],
|
|
540
|
+
[_ref("live"), _ref("d1"), _ref("d2")],
|
|
541
|
+
),
|
|
542
|
+
"OEBPS/live.xhtml": _doc("<p>word word word word</p>"),
|
|
543
|
+
},
|
|
544
|
+
"dead_spine_items_pruned",
|
|
545
|
+
),
|
|
532
546
|
"--fix-double-colon-tags": (
|
|
533
547
|
{
|
|
534
548
|
"OEBPS/content.opf": _opf([c1], [r1]),
|
|
@@ -772,6 +786,11 @@ class FlagEndToEndTests(unittest.TestCase):
|
|
|
772
786
|
self._fixes_for("--fix-item-properties")["item_properties_added"], 1
|
|
773
787
|
)
|
|
774
788
|
|
|
789
|
+
def test_prune_dead_spine(self):
|
|
790
|
+
self.assertGreaterEqual(
|
|
791
|
+
self._fixes_for("--prune-dead-spine")["dead_spine_items_pruned"], 2
|
|
792
|
+
)
|
|
793
|
+
|
|
775
794
|
def test_fix_double_colon_tags(self):
|
|
776
795
|
self.assertGreaterEqual(
|
|
777
796
|
self._fixes_for("--fix-double-colon-tags")["double_colon_tags_escaped"],
|
|
@@ -58,6 +58,7 @@ DEST_TO_FIELD = {
|
|
|
58
58
|
"fix_double_colon_tags": "double_colon_tags",
|
|
59
59
|
"strip_presentational_attrs": "presentational_attrs",
|
|
60
60
|
"encode_ref_brackets": "encode_ref_brackets",
|
|
61
|
+
"prune_dead_spine": "prune_dead_spine",
|
|
61
62
|
"strip_pagination": "strip_pagination",
|
|
62
63
|
"strip_broken_tags": "strip_brokentags",
|
|
63
64
|
"strip_watermarks": "strip_watermarks",
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|