bindery-cli 0.51.0__tar.gz → 0.52.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.51.0 → bindery_cli-0.52.0}/.github/workflows/ci.yml +1 -1
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/AGENTS.md +11 -3
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/PKG-INFO +1 -1
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/patchnotes.md +63 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/pyproject.toml +1 -1
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/roadmap.md +9 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/spec.md +24 -1
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/src/bindery/__init__.py +1 -1
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/src/bindery/cli.py +22 -1
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/src/bindery/epub.py +61 -7
- bindery_cli-0.52.0/tests/test_spine_guard.py +300 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/uv.lock +1 -1
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/.github/FUNDING.yml +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/.github/workflows/publish.yml +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/.gitignore +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/LICENSE +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/README.md +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/docs/screenshots/library-sweep.png +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/logo.svg +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/plugin/__init__.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/project.done +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/run_tests.sh +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/scripts/FastSweep.java +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/scripts/build_plugin.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/scripts/fast_sweep.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/src/bindery/__main__.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/src/bindery/audit.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/src/bindery/library.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/src/bindery/pagination.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/src/bindery/reserialize.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/src/bindery/transforms.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/src/bindery/validate.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/src/bindery/watermark.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/tests/test_audit.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/tests/test_cli.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/tests/test_comment_hyphens.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/tests/test_contamination.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/tests/test_cover_tocdrift.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/tests/test_epub.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/tests/test_flags_real_core.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/tests/test_flags_wiring.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/tests/test_help.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/tests/test_library.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/tests/test_matcher_hardening.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/tests/test_pagination.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/tests/test_plugin.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/tests/test_reserialize.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/tests/test_space_renames.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/tests/test_transforms.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/tests/test_validate.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/tests/test_version.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/tests/test_watermark.py +0 -0
- {bindery_cli-0.51.0 → bindery_cli-0.52.0}/tests/test_xml_hardening.py +0 -0
|
@@ -61,7 +61,7 @@ jobs:
|
|
|
61
61
|
tests.test_watermark tests.test_reserialize tests.test_version
|
|
62
62
|
tests.test_plugin tests.test_validate
|
|
63
63
|
tests.test_comment_hyphens tests.test_flags_wiring
|
|
64
|
-
tests.test_flags_real_core
|
|
64
|
+
tests.test_flags_real_core tests.test_spine_guard
|
|
65
65
|
plugin-compat:
|
|
66
66
|
name: Parse-check the plugin zip under the interpreters Calibre embeds
|
|
67
67
|
runs-on: ubuntu-latest
|
|
@@ -115,7 +115,15 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
|
|
|
115
115
|
`process_book` reclassifies the verdict to `partial` (a fatal package halts the
|
|
116
116
|
metadata checks, so the dtb:uid comparison never ran in either measurement and the
|
|
117
117
|
real sync measures as no gain); application behavior is unchanged, since still-fatal
|
|
118
|
-
books are never applied.
|
|
118
|
+
books are never applied. One structural veto rides above the counts (v0.52.0,
|
|
119
|
+
issue #10): `process_book` probes source and candidate with `epub.spine_dangles`
|
|
120
|
+
(itemref -> manifest item -> archive entry, resolved through the same helper the
|
|
121
|
+
repair's existence checks use) and rejects any candidate whose dangle count rises
|
|
122
|
+
(`(spine collapse)` in the summary) — a repair that orphans live itemrefs removes
|
|
123
|
+
the broken documents' errors from the measurement, so a destroyed book can read as
|
|
124
|
+
an error reduction. The probe needs evidence on both sides (an unreadable package
|
|
125
|
+
vetoes nothing); `--no-validate` skips it with the rest of the gate. Changing either
|
|
126
|
+
bar (or the veto) means re-running the library dry run.
|
|
119
127
|
- **Library writes are sacred.** Replacement must stay atomic (temp in same dir, then
|
|
120
128
|
`os.replace`), touch only the `.epub`, preserve mode, and be dry-run by default.
|
|
121
129
|
Calibre format installation goes through cquarry's write module (`--install-to-calibre`;
|
|
@@ -129,10 +137,10 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
|
|
|
129
137
|
- `src/bindery/watermark.py`: the opt-in lossy watermark strip (anchored and anchorless signature removal).
|
|
130
138
|
- `src/bindery/reserialize.py`: structural repair via `html5lib`.
|
|
131
139
|
- `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) 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).
|
|
132
|
-
- `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.46.0 the opt-in selection is the `RepairFlags` dataclass (one field per flag, all off by default; the all-off instance IS the default pass): `repair_epub(src, dst, flags)` and `process_book(..., flags)` take one object instead of a ~25-kwarg signature, the EPUB2-targeted fixes' version gate swaps in a `dataclasses.replace` copy (never mutating the caller's instance), and the plugin's bare `repair_epub(src, dst)` call constructs exactly the all-off default pass. Since v0.38.0/v0.39.0 (Phase 16): `generate_container` + the `--fix-container` gateway (insert after mimetype when missing, replace in-loop when stale; constant-epoch timestamp keeps bytes deterministic), `prune_dangling_edges` (prune_missing_manifest_items returns the pruned ids and the edges that pointed at them (spine@toc, media-overlay, fallback, EPUB2 cover meta) are rewritten so pruning cannot manufacture the regression the gate rejects), and `fix_manifest_media_types` (extension map + magic-byte confirmation via a `peek` callable over the open source zip; jpg/png/gif only), and `fix_cover_meta` (the ruling's deterministic half: dangling EPUB2 cover meta re-pointed from the guide's cover reference when exactly one manifest item carries that file, removed otherwise; accepted under no_worse like the lossy strips because cover wiring is invisible to epubcheck).
|
|
140
|
+
- `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.52.0 (issue #10): `spine_dangles(src)` walks itemref -> manifest item -> archive entry through `_resolve_href`+`_norm_path` (None on an unreadable package: the veto needs evidence, never fires on a probe failure), and `prune_missing_manifest_items` derives its spine protection from the text it prunes (no snapshot parameter: fix_manifest_ids renames ids ahead of it, and the existence set it checks against must be the layout its hrefs are written in — `present_src` when space renames are active, matching the content-doc prune). Since v0.46.0 the opt-in selection is the `RepairFlags` dataclass (one field per flag, all off by default; the all-off instance IS the default pass): `repair_epub(src, dst, flags)` and `process_book(..., flags)` take one object instead of a ~25-kwarg signature, the EPUB2-targeted fixes' version gate swaps in a `dataclasses.replace` copy (never mutating the caller's instance), and the plugin's bare `repair_epub(src, dst)` call constructs exactly the all-off default pass. Since v0.38.0/v0.39.0 (Phase 16): `generate_container` + the `--fix-container` gateway (insert after mimetype when missing, replace in-loop when stale; constant-epoch timestamp keeps bytes deterministic), `prune_dangling_edges` (prune_missing_manifest_items returns the pruned ids and the edges that pointed at them (spine@toc, media-overlay, fallback, EPUB2 cover meta) are rewritten so pruning cannot manufacture the regression the gate rejects), and `fix_manifest_media_types` (extension map + magic-byte confirmation via a `peek` callable over the open source zip; jpg/png/gif only), and `fix_cover_meta` (the ruling's deterministic half: dangling EPUB2 cover meta re-pointed from the guide's cover reference when exactly one manifest item carries that file, removed otherwise; accepted under no_worse like the lossy strips because cover wiring is invisible to epubcheck).
|
|
133
141
|
- `src/bindery/validate.py`: epubcheck wrapper, the `gate` (improvement) and `no_worse` (no-regression, for the lossy strips) acceptance bars.
|
|
134
142
|
- `src/bindery/library.py`: Calibre walk, atomic replace, backups, and native format installation. Since v0.19.0 `CalibreIdResolver` resolves the book id from `metadata.db` through cquarry (one lazy path→id map per run; since v0.20.0 the map comes from `CalibreDB.format_path_index()`, re-normalized with `resolve().lower()` for the resolver's symlinked-directory and case-insensitive matching); the `(id)` directory-name regex is only the no-catalog fallback. Since v0.24.0 `install_format()` places the repaired file atomically and updates the `data` row through `cquarry.write.WritableCalibreDB` (since v0.31.0 via `set_format`, cquarry 1.17's sanctioned remove+add in one transaction); the external `calibredb` CLI is gone. Since v0.32.0 a guessed id drives a row update only when metadata.db corroborates it (`_verify_guess`: books row exists, file in the book's own directory, catalogued `data.name` when a row exists); anything else saves in place and leaves the catalog untouched: never reintroduce directory-name guessing as the primary source: renamed/mismatched directories would replace the wrong book. Since 2026-09-15 `make_backup` takes the opt-in `--backup-keep N` ring: at most N backup files per book, the author original `.bak` never deleted, newest content at the highest name; default remains an unbounded rotation.
|
|
135
|
-
- `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; `repair --json` emits the library per-book record vocabulary (2026-09-15; since v0.45.0 every per-book record, the phase1 payload included, also carries the structured fix breakdown: the `fixes` dict plus `ncx_uid_synced`/`watermark_refusals` off the `Outcome`, and `_phase1_decisions` reads that data instead of substring-matching the rendered `summary`, which stays for human eyes; CalibreQuarry's lossy-consent mirror is the waiting consumer, floor `bindery>=0.45.0`); since v0.29.0 also the `run` verbs: `phase1` (pre-import vetting over loose files: the audit battery composed with one gated repair sweep; read-only until `--apply-lossy`, which IS the lossy-strip consent) and `phase3` (the scoped post-import apply step: `library --id --sweep --only all --apply --all --install-to-calibre` plus a pre/post summary; mechanically refuses unscoped sweeps with exit 2; since 2026-09-15 the summary sums applied/equal states only and carries rejected projections as `rejected_projection`). Plus `bindery doctor` (2026-09-15): the environment self-check that imports none of the VirInvictus stack, never raises, and always exits 0. Both run verbs take `--non-interactive` and surface open questions as `decisions_needed` in their JSON, never prompts. They drive the shipped `run_library` through the real parser, so no flag can drift between the verb and the subcommand it wraps. Since v0.46.0 `cli._flags_from_args(args)` is the one place the argparse names map onto `RepairFlags` fields (each `or --all`), shared by `run_library` and `run_repair`; the old per-verb ~25-kwarg blocks are gone. Since v0.47.1 the help is two-level (the --help-repairs reference is
|
|
143
|
+
- `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; since v0.52.0 `process_book` carries the spine-resolution veto (issue #10) above every verdict path, promotions included: a candidate whose spine dangles more than the source's is `reject` with `(spine collapse)` appended to the summary, whatever the counts say. `repair --json` emits the library per-book record vocabulary (2026-09-15; since v0.45.0 every per-book record, the phase1 payload included, also carries the structured fix breakdown: the `fixes` dict plus `ncx_uid_synced`/`watermark_refusals` off the `Outcome`, and `_phase1_decisions` reads that data instead of substring-matching the rendered `summary`, which stays for human eyes; CalibreQuarry's lossy-consent mirror is the waiting consumer, floor `bindery>=0.45.0`); since v0.29.0 also the `run` verbs: `phase1` (pre-import vetting over loose files: the audit battery composed with one gated repair sweep; read-only until `--apply-lossy`, which IS the lossy-strip consent) and `phase3` (the scoped post-import apply step: `library --id --sweep --only all --apply --all --install-to-calibre` plus a pre/post summary; mechanically refuses unscoped sweeps with exit 2; since 2026-09-15 the summary sums applied/equal states only and carries rejected projections as `rejected_projection`). Plus `bindery doctor` (2026-09-15): the environment self-check that imports none of the VirInvictus stack, never raises, and always exits 0. Both run verbs take `--non-interactive` and surface open questions as `decisions_needed` in their JSON, never prompts. They drive the shipped `run_library` through the real parser, so no flag can drift between the verb and the subcommand it wraps. Since v0.46.0 `cli._flags_from_args(args)` is the one place the argparse names map onto `RepairFlags` fields (each `or --all`), shared by `run_library` and `run_repair`; the old per-verb ~25-kwarg blocks are gone. Since v0.47.1 the help is two-level (the --help-repairs reference is
|
|
136
144
|
custom-rendered and colors itself with the CPython 3.14 argparse theme,
|
|
137
145
|
gated by argparse's own _colorize detection so the levels always agree) and the repair-flag inventory is one table: `_REPAIR_FLAG_TABLE` (dest + one-line short help + long reference text) registers the compact grouped `--help` (argparse argument groups, hand-short usage line) and `--help-repairs` renders the long descriptions (a custom argparse Action, deliberately NOT store_true so the wiring test's selection count ignores it); adding a flag means adding a table row. Since v0.48.0 the metadata.db doors are enforced: `_require_closed_calibre` (pgrep fail-closed, exit 1) guards `audit --tag` and `library --apply --install-to-calibre` (run phase3 transitively), and `--help-json` (a custom argparse Action like --help-repairs, never colored) dumps the per-verb exit contract and the door list; since v0.48.1 the per-verb exit contracts tell the code's truth (repair: 0 probed/written incl. partial / 1 trouble, never 2; audit: 0/1/2 plus 3 for findings+write-failure; library and the run slices: the unified 0/2/1); since v0.49.0 the single-file verb's no-output form is a probe (the gate runs, the record's `output` is null and `applied` false, nothing is written anywhere; the old implicit `(repaired).epub` sibling was issue #7's import litter in a vetted tree, and writing now needs an explicit DST). `library --workers N` (v0.30.0) parallelizes only the sweep's candidate pass, in windows of N consumed in order so `--limit` stays lazy; the repair phase is never parallel (shared workdir, atomic-replacement contract). Since v0.40.0 `main()` guards the VirInvictus stack: a `ModuleNotFoundError` naming `vir_tui`/`cquarry` (marker-gated to 3.14+ on the 3.12 floor) becomes one stderr line and trouble exit 2 instead of a traceback; anything else missing still raises.
|
|
138
146
|
- `plugin/__init__.py` + `scripts/build_plugin.py`: the Bindery Repair Calibre plugin (v0.37.0; identity `Bindery Repair` / `bindery_repair`, approved and built per the scoped spec in roadmap.md Phase 3). The builder vendors `transforms.py`, `epub.py`, `pagination.py`, `watermark.py`, `reserialize.py` byte-identically into the zip (the zip root is a package, so their relative imports resolve unchanged; the suite's drift test pins the equality) with the version tuple substituted from the single-source VERSION; `publish.yml` attaches `BinderyRepair-v<VERSION>.zip` to each release. The plugin runs ONLY the default pass (epubcheck cannot gate inside Calibre), never raises, is byte-idempotent (zero fixes returns the original path), testzip()-verifies its output, logs one line per book, and takes JSON config via `site_customization` (`log`, `log_path`, `max_size_mb` default 150, `max_log_mb` rotation cap default 2, `epubcheck_path` experimental validation default OFF). Load it in tests through the `tests/test_plugin.py` stubs: the calibre namespace is installed in sys.modules and the package loads with a two-dir `__path__` (plugin dir first, then src/bindery) exactly like calibre's zipplugin loader shape. **Plugin/interpreter compatibility (v0.40.0):** v0.39.0 shipped PEP 758 unparenthesized except tuples, and the plugin died with a bare SyntaxError on every released Calibre (7.x and the whole 8.x series embed Python 3.11, 9.0+ embeds 3.14; from calibre's bypy sources.json, checked against the upstream clone). The core is now grammar-pinned: parenthesized except tuples everywhere, `ruff`'s `target-version = "py312"` pin (inference from requires-python would rewrite the parens back off), `tests/test_version.py`'s parse guard, and CI's `plugin-compat` job byte-compiling the built zip under 3.11/3.12/3.13/3.14. `minimum_calibre_version` is (7, 0, 0): the oldest series whose interpreter CI covers, replacing the hollow (2, 0, 0); `supported_platforms` stays `["linux"]` (developed and tested on Linux only). Any new syntax in the vendored modules must clear the guard before it ships.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: bindery-cli
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.52.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
|
|
@@ -1,5 +1,68 @@
|
|
|
1
1
|
# bindery-cli Patch Notes
|
|
2
2
|
|
|
3
|
+
## v0.52.0 (2026-10-21)
|
|
4
|
+
|
|
5
|
+
### The repairer's own prune could destroy the book it was repairing (issue #10)
|
|
6
|
+
|
|
7
|
+
The 2026-10-21 re-source wave caught it live: six fan conversions (the Rihannsu
|
|
8
|
+
rips: My Enemy My Ally, three Ascendance rips, two The Final Reflection rips)
|
|
9
|
+
whose content filenames carry raw spaces (`DUANE, Diane - [Star Trek - TOS -
|
|
10
|
+
Rihannsu 1] - My Enemy, My Ally_split_000.htm`) and whose manifest ids carry
|
|
11
|
+
commas and brackets, which are invalid XML name characters. The gated sweep
|
|
12
|
+
accepted `0f/17e/8w -> 0f/10e/0w` and applied `manifest_items_pruned:8`: the
|
|
13
|
+
repair deleted every spine document's manifest item while the archive entry sat
|
|
14
|
+
right there under its new underscore spelling, and left a book whose spine
|
|
15
|
+
resolved to the title page. The gate measured fewer messages because the
|
|
16
|
+
destroyed documents' errors had left the measurement entirely.
|
|
17
|
+
|
|
18
|
+
Two stacked defects, both fixed:
|
|
19
|
+
|
|
20
|
+
- **The prune's existence check read the wrong layout.** With
|
|
21
|
+
`--encode-url-spaces` active, `prune_missing_manifest_items` ran ahead of the
|
|
22
|
+
reference rewrite on hrefs still carrying raw spaces, but checked them
|
|
23
|
+
against the archive's post-rename spellings; every raw-space href read as
|
|
24
|
+
missing. The check now uses the layout the OPF text is actually written in
|
|
25
|
+
(`present_src`, exactly what the content-document prune already did), so an
|
|
26
|
+
href is judged against the archive as the text sees it and the rename half
|
|
27
|
+
handles both sides together.
|
|
28
|
+
- **The spine guard described an earlier spelling of the ids.** The guard that
|
|
29
|
+
keeps spine documents out of the prune was snapshotted from the OPF before
|
|
30
|
+
`--fix-manifest-ids` renamed the item ids and spine idrefs, so by the time
|
|
31
|
+
the prune ran it recognized nothing. The prune now derives its spine set
|
|
32
|
+
from the very text it reads; the snapshot parameter is gone, and the guard
|
|
33
|
+
can never drift from the text again.
|
|
34
|
+
|
|
35
|
+
And the class is guarded, not just this instance: `process_book` now probes
|
|
36
|
+
source and candidate with `epub.spine_dangles` (itemref to manifest item to
|
|
37
|
+
archive entry, resolved through the same helper the repair's own existence
|
|
38
|
+
checks use) and vetoes any candidate whose spine dangles more than the
|
|
39
|
+
source's: `reject` with `(spine collapse)` in the summary, riding above the
|
|
40
|
+
message counts and above every fix-class promotion. A probe that cannot read a
|
|
41
|
+
package vetoes nothing (the veto needs evidence on both sides), and
|
|
42
|
+
`--no-validate` skips it with the rest of the gate.
|
|
43
|
+
|
|
44
|
+
On the issue's fixtures: The Final Reflection now repairs clean and gates
|
|
45
|
+
accept (`0f/30e/22w -> 0f/3e/0w`, twenty-two entries renamed, zero prunes,
|
|
46
|
+
spine fully resolved). My Enemy My Ally still refuses, now for an honest
|
|
47
|
+
reason: the fan conversion's brackets and commas are illegal URL characters
|
|
48
|
+
too, and once the spaces clear, epubcheck re-reports each affected link as its
|
|
49
|
+
own RSC-020 (`17 -> 32` aggregated), so the candidate measures as a regression
|
|
50
|
+
and nothing is applied. That book waits for a manual pass, or a future repair
|
|
51
|
+
class that percent-encodes the remaining illegal characters; refusing is the
|
|
52
|
+
correct outcome for a repair that cannot be made deterministically safe.
|
|
53
|
+
|
|
54
|
+
Eleven tests joined the suite (702 total): the `spine_dangles` probe unit
|
|
55
|
+
tests (healthy spine, the orphaned-itemref shape, the absent-file shape, and
|
|
56
|
+
probe-failure-is-None), the prune guard's renamed-id regression and its
|
|
57
|
+
non-spine prune, the end-to-end raw-space book (renames land, nothing is
|
|
58
|
+
pruned, every itemref walks to a file), the veto wiring in `process_book`
|
|
59
|
+
(collapse rejects improving counts, intact spine keeps the normal verdict,
|
|
60
|
+
unreadable candidate vetoes nothing), and a fixture-backed regression on the
|
|
61
|
+
real My Enemy My Ally pre-repair bytes (skipped where the local fixture is
|
|
62
|
+
absent). The stack-free module joined CI's 3.12/3.13 leg, and the full-corpus
|
|
63
|
+
dry run over the library (6,774 books, repaired candidates measured against
|
|
64
|
+
their sources) confirmed zero veto fires.
|
|
65
|
+
|
|
3
66
|
## v0.51.0 (2026-10-17)
|
|
4
67
|
|
|
5
68
|
### The unbound-prefix repair: the Calibre embed scar comes off the OPF (issue #9)
|
|
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "bindery-cli"
|
|
7
|
-
version = "0.
|
|
7
|
+
version = "0.52.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 = [
|
|
@@ -45,9 +45,18 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
|
|
|
45
45
|
| 0.49 | The probe form (issue #7): single-file repair without an output path runs the gate and writes nothing; writing needs an explicit DST | v0.49.0 |
|
|
46
46
|
| 0.50 | The contamination analyzer (issue #8): foreign-title template stamps, fan-bundle ad signatures, review-paste front matter; advisory by contract, archive-wide corpus (`Book.extra_docs`, capped), and the `_dir_dispatch` map that fixes the v0.44.0 cover/tocdrift ocr misroute in directory/single mode | v0.50.0 |
|
|
47
47
|
| 0.51 | The unbound-prefix repair (issue #9): `--fix-unbound-prefix` binds the Calibre embed scar's undeclared attribute prefix inline (evidence-based URI, scope-tracked, refuse over guess), plus the masked-ncx-gain rule that stops a real dtb:uid sync reading as no measurable gain under a fatal package | v0.51.0 |
|
|
48
|
+
| 0.52 | The spine guard (issue #10): the manifest prune reads the layout its hrefs are written in and derives its spine protection from the text it prunes (the raw-space wave's spine collapse), and `process_book` vetoes any candidate whose spine (itemref -> item -> archive) dangles more than the source's, above the counts and every promotion | v0.52.0 |
|
|
48
49
|
|
|
49
50
|
## Open work
|
|
50
51
|
|
|
52
|
+
- [ ] **Percent-encode illegal URL characters in references**: the RSC-020 class
|
|
53
|
+
beyond spaces. Opened by issue #10's My Enemy My Ally fixture: once
|
|
54
|
+
`--encode-url-spaces` clears the spaces, the fan conversion's brackets and
|
|
55
|
+
commas re-report as 28 individual RSC-020s (previously folded into one
|
|
56
|
+
aggregated RSC-005), so the candidate measures as a regression and the
|
|
57
|
+
gate refuses a book that is otherwise repaired. Needs the same
|
|
58
|
+
entry-and-reference coordination as the space renames, with the
|
|
59
|
+
decode-before-lookup epubcheck rule verified per character class.
|
|
51
60
|
- [ ] **Obfuscation-aware encryption.xml repair**: prune stale obfuscation entries
|
|
52
61
|
when font magic bytes prove the fonts are decrypted in place; drop
|
|
53
62
|
encryption.xml when only obfuscation entries remain and fonts verify. NEVER
|
|
@@ -178,7 +178,16 @@ every EPUB3 book in an `--all` sweep taking exactly that damage).
|
|
|
178
178
|
(the anchor and its text stay), absent `<img>` sources (replaced by their escaped
|
|
179
179
|
alt text when they carry one, dropped otherwise), and orphaned non-spine OPF manifest
|
|
180
180
|
`<item>` declarations. Spine documents are never pruned: a missing spine document is
|
|
181
|
-
a damaged fragment for the audit's spine-integrity check, never a silent drop.
|
|
181
|
+
a damaged fragment for the audit's spine-integrity check, never a silent drop. The
|
|
182
|
+
manifest existence check resolves the href the way the resolver does (unquoted,
|
|
183
|
+
normalized) and compares it against the layout the OPF text is written in: when
|
|
184
|
+
`--encode-url-spaces` is renaming entries, the prune runs ahead of the reference
|
|
185
|
+
rewrite and reads pre-rename hrefs, so it checks against the pre-rename archive
|
|
186
|
+
(a raw-space href judged against renamed spellings is how live spine documents came
|
|
187
|
+
to be pruned, issue #10). The spine protection is derived from the very text the
|
|
188
|
+
prune reads, never snapshotted earlier: `--fix-manifest-ids` may have renamed item
|
|
189
|
+
ids and spine idrefs ahead of it in the OPF pipeline, and a guard describing the old
|
|
190
|
+
spelling protects nothing.
|
|
182
191
|
- **`--strip-broken-anchors`**: strip `href` attributes that cannot resolve, keeping
|
|
183
192
|
the anchor text byte-for-byte. A `#fragment` the target document does not define
|
|
184
193
|
(RSC-020 "fragment identifier not defined", RSC-012 "points to the wrong element") is
|
|
@@ -378,6 +387,20 @@ be run or its output cannot be parsed during a validated run, the book is an `er
|
|
|
378
387
|
the gate has not accepted anything, so nothing is applied or written. With
|
|
379
388
|
`--no-validate`, the gate is skipped and repairs are trusted on the RepairReport alone.
|
|
380
389
|
|
|
390
|
+
One structural veto rides above the count gate: the spine-resolution check. The
|
|
391
|
+
message count is not spine-aware, so a repair that orphans live itemrefs (manifest
|
|
392
|
+
items pruned whose files the archive still carries, idrefs rewritten to forms that
|
|
393
|
+
match nothing) removes the broken documents' errors from the measurement and a
|
|
394
|
+
destroyed book can read as an error reduction (issue #10: a raw-space fan
|
|
395
|
+
conversion's eight spine items pruned as "missing", gate accepted
|
|
396
|
+
`0f/17e/8w -> 0f/10e/0w`). `process_book` therefore probes both packages with
|
|
397
|
+
`spine_dangles` (itemref -> manifest item -> archive entry, resolved through the
|
|
398
|
+
same helper the repair's existence checks use) and vetoes any candidate whose
|
|
399
|
+
dangle count rises: `reject`, regardless of the counts and regardless of which
|
|
400
|
+
bar a fix class promotes under. The probe needs evidence on both sides — a
|
|
401
|
+
package it cannot read (unreadable archive, no locatable OPF) vetoes nothing —
|
|
402
|
+
and `--no-validate` skips it with the rest of the gate.
|
|
403
|
+
|
|
381
404
|
The oracle itself runs two ways: the `epubcheck --json -` subprocess, or a persistent
|
|
382
405
|
daemon (`_EpubcheckDaemon`, a bounded pool sized by `--workers`) that writes
|
|
383
406
|
`FastDaemon.java` at runtime and launches it through Java's single-file source
|
|
@@ -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.52.0"
|
|
15
15
|
__version__ = VERSION
|
|
16
16
|
|
|
17
17
|
from .epub import RepairReport, repair_epub # noqa: E402
|
|
@@ -31,7 +31,7 @@ from .audit import (
|
|
|
31
31
|
from .audit import (
|
|
32
32
|
run_library as run_audit_library,
|
|
33
33
|
)
|
|
34
|
-
from .epub import RepairFlags, ncx_uid_mismatch, repair_epub
|
|
34
|
+
from .epub import RepairFlags, ncx_uid_mismatch, repair_epub, spine_dangles
|
|
35
35
|
from .library import (
|
|
36
36
|
CalibreIdResolver,
|
|
37
37
|
atomic_replace,
|
|
@@ -214,10 +214,31 @@ def process_book(
|
|
|
214
214
|
verdict = "partial"
|
|
215
215
|
else:
|
|
216
216
|
verdict = "accept"
|
|
217
|
+
# The spine-resolution veto (issue #10). The epubcheck count is not
|
|
218
|
+
# spine-aware: a repair that orphans live itemrefs (manifest items pruned
|
|
219
|
+
# whose files the archive still carries, idrefs rewritten to forms that
|
|
220
|
+
# match nothing) removes the broken documents' errors from the
|
|
221
|
+
# measurement, so a destroyed book can read as an error reduction. A
|
|
222
|
+
# spine that resolved before the repair and dangles after it is a
|
|
223
|
+
# regression no message count can buy back: reject, regardless of the
|
|
224
|
+
# counts or the bar any fix class promotes under. The probe runs on both
|
|
225
|
+
# real files; a probe failure (unreadable package, no locatable OPF)
|
|
226
|
+
# carries no evidence and vetoes nothing.
|
|
227
|
+
dangles_before = spine_dangles(epub)
|
|
228
|
+
dangles_after = spine_dangles(repaired)
|
|
229
|
+
spine_collapse = (
|
|
230
|
+
dangles_before is not None
|
|
231
|
+
and dangles_after is not None
|
|
232
|
+
and dangles_after > dangles_before
|
|
233
|
+
)
|
|
234
|
+
if spine_collapse:
|
|
235
|
+
verdict = "reject"
|
|
217
236
|
if verdict == "reject":
|
|
218
237
|
summary += " (REGRESSION)"
|
|
219
238
|
elif verdict == "noop":
|
|
220
239
|
summary += " (no measurable gain)"
|
|
240
|
+
if spine_collapse:
|
|
241
|
+
summary += " (spine collapse)"
|
|
221
242
|
status = "equal" if verdict == "noop" else verdict
|
|
222
243
|
return Outcome(
|
|
223
244
|
epub,
|
|
@@ -873,7 +873,7 @@ _NCX_CONTENT_SRC_RE = re.compile(
|
|
|
873
873
|
|
|
874
874
|
|
|
875
875
|
def prune_missing_manifest_items(
|
|
876
|
-
opf_text: str, opf_dir: str, present: frozenset[str]
|
|
876
|
+
opf_text: str, opf_dir: str, present: frozenset[str]
|
|
877
877
|
) -> tuple[str, int, set[str]]:
|
|
878
878
|
"""Drop `<item>` manifest declarations whose file is absent from the
|
|
879
879
|
archive — unless the item is a spine document.
|
|
@@ -884,9 +884,16 @@ def prune_missing_manifest_items(
|
|
|
884
884
|
dead-declaration removal instead of a stub file. The pruned ids come back
|
|
885
885
|
so the caller can rewrite the edges that pointed at them
|
|
886
886
|
(prune_dangling_edges) instead of leaving dangling idrefs.
|
|
887
|
+
|
|
888
|
+
The spine guard is derived from the very text this pass reads, never
|
|
889
|
+
passed in: the OPF pipeline may have renamed ids (fix_manifest_ids rewrites
|
|
890
|
+
item ids and spine idrefs together) before the prune runs, and a snapshot
|
|
891
|
+
taken from an earlier spelling misses every renamed idref — which is how
|
|
892
|
+
spine documents came to be pruned on the raw-space books (issue #10).
|
|
887
893
|
"""
|
|
888
894
|
count = 0
|
|
889
895
|
pruned: set[str] = set()
|
|
896
|
+
spine_ids = {m.group(3) for m in _IDREF_ATTR_RE.finditer(opf_text)}
|
|
890
897
|
|
|
891
898
|
def repl(m: re.Match) -> str:
|
|
892
899
|
nonlocal count
|
|
@@ -1373,6 +1380,48 @@ def sync_ncx_uid(ncx_text: str, uid: str) -> tuple[str, bool]:
|
|
|
1373
1380
|
return new, True
|
|
1374
1381
|
|
|
1375
1382
|
|
|
1383
|
+
def spine_dangles(src: Path) -> int | None:
|
|
1384
|
+
"""Count spine itemrefs that cannot walk itemref -> manifest item ->
|
|
1385
|
+
archive entry: the spine-resolution axis the epubcheck count cannot see
|
|
1386
|
+
(issue #10). A repair that orphans live itemrefs can measure as an error
|
|
1387
|
+
reduction, so process_book vetoes any candidate whose count rises.
|
|
1388
|
+
|
|
1389
|
+
The last hop resolves through the same helper the repair's own
|
|
1390
|
+
existence checks use (_resolve_href + _norm_path: unquoted, normalized),
|
|
1391
|
+
so both sides of the comparison read the package the same way. None
|
|
1392
|
+
means the package could not be probed (unreadable archive, no locatable
|
|
1393
|
+
OPF): the veto needs evidence and never fires on a probe failure.
|
|
1394
|
+
"""
|
|
1395
|
+
try:
|
|
1396
|
+
with zipfile.ZipFile(src) as z:
|
|
1397
|
+
opf = _locate_opf(z)
|
|
1398
|
+
if not opf:
|
|
1399
|
+
return None
|
|
1400
|
+
text = z.read(opf).decode("utf-8", "replace")
|
|
1401
|
+
opf_dir = posixpath.dirname(opf)
|
|
1402
|
+
present = frozenset(_norm_path(n) for n in z.namelist())
|
|
1403
|
+
items: dict[str, str] = {}
|
|
1404
|
+
for m in _ITEM_TAG_RE.finditer(text):
|
|
1405
|
+
tag = m.group(0)
|
|
1406
|
+
im = _XML_ID_RE.search(tag)
|
|
1407
|
+
hm = _HREF_ATTR_RE.search(tag)
|
|
1408
|
+
if not im or not hm:
|
|
1409
|
+
continue
|
|
1410
|
+
resolved = _resolve_href(opf_dir, hm.group(2))
|
|
1411
|
+
if resolved is not None:
|
|
1412
|
+
items[im.group(3)] = resolved
|
|
1413
|
+
dangles = 0
|
|
1414
|
+
for m in _SPINE_ITEM_RE.finditer(text):
|
|
1415
|
+
rm = _IDREF_ATTR_RE.search(m.group(0))
|
|
1416
|
+
if rm is None or items.get(rm.group(3)) not in present:
|
|
1417
|
+
dangles += 1
|
|
1418
|
+
return dangles
|
|
1419
|
+
except (zipfile.BadZipFile, OSError, RuntimeError):
|
|
1420
|
+
# RuntimeError covers zip-encrypted entries, which raise out of
|
|
1421
|
+
# z.read: like ncx_uid_mismatch, a DRM'd book is not a crash.
|
|
1422
|
+
return None
|
|
1423
|
+
|
|
1424
|
+
|
|
1376
1425
|
def ncx_uid_mismatch(src: Path) -> bool:
|
|
1377
1426
|
"""Cheaply detect NCX-001 (toc.ncx dtb:uid != OPF unique-identifier) without epubcheck."""
|
|
1378
1427
|
try:
|
|
@@ -1571,7 +1620,6 @@ def repair_epub(
|
|
|
1571
1620
|
# opens by its decoded spelling)
|
|
1572
1621
|
norm_to_raw: dict[str, str] = {}
|
|
1573
1622
|
ids_by_doc: dict[str, frozenset[str]] = {}
|
|
1574
|
-
spine_ids: set[str] = set()
|
|
1575
1623
|
opf_dir = posixpath.dirname(opf) if opf else ""
|
|
1576
1624
|
|
|
1577
1625
|
# --encode-url-spaces's rename half, decided up front: every
|
|
@@ -1602,8 +1650,9 @@ def repair_epub(
|
|
|
1602
1650
|
if space_renames
|
|
1603
1651
|
else {}
|
|
1604
1652
|
)
|
|
1605
|
-
# the
|
|
1606
|
-
#
|
|
1653
|
+
# the pre-rename layout, for the passes that read the ORIGINAL
|
|
1654
|
+
# references (the content-doc prune in the id snapshot above, and the
|
|
1655
|
+
# manifest prune, which runs ahead of rewrite_space_renames)
|
|
1607
1656
|
present_src: frozenset[str] = frozenset()
|
|
1608
1657
|
if flags.prune_missing or flags.strip_anchors or flags.fix_media_types:
|
|
1609
1658
|
for n in zin.namelist():
|
|
@@ -1651,8 +1700,6 @@ def repair_epub(
|
|
|
1651
1700
|
ids_by_doc[
|
|
1652
1701
|
_norm_path(space_renames.get(i.filename, i.filename))
|
|
1653
1702
|
] = frozenset(m.group(3) for m in _XML_ID_RE.finditer(t))
|
|
1654
|
-
if flags.prune_missing and opf_text is not None:
|
|
1655
|
-
spine_ids = {m.group(3) for m in _IDREF_ATTR_RE.finditer(opf_text)}
|
|
1656
1703
|
|
|
1657
1704
|
# The mimetype content is an OCF constant, so adding a missing entry and
|
|
1658
1705
|
# normalizing wrong or whitespace-padded content is deterministic and
|
|
@@ -1873,8 +1920,15 @@ def repair_epub(
|
|
|
1873
1920
|
report.add({"epub3_attrs_stripped": n})
|
|
1874
1921
|
opf_changed = True
|
|
1875
1922
|
if flags.prune_missing:
|
|
1923
|
+
# The manifest prune runs before rewrite_space_renames, so
|
|
1924
|
+
# the hrefs it reads are still in the SOURCE spelling: the
|
|
1925
|
+
# existence set must describe the same layout. `present`
|
|
1926
|
+
# carries the renamed spellings, and every raw-space href
|
|
1927
|
+
# resolved against it reads as missing — the issue #10
|
|
1928
|
+
# collapse (present_src mirrors the content-doc prune
|
|
1929
|
+
# above for exactly this reason).
|
|
1876
1930
|
text, n, pruned_ids = prune_missing_manifest_items(
|
|
1877
|
-
text, opf_dir, present
|
|
1931
|
+
text, opf_dir, present_src if space_renames else present
|
|
1878
1932
|
)
|
|
1879
1933
|
if n:
|
|
1880
1934
|
report.add({"manifest_items_pruned": n})
|
|
@@ -0,0 +1,300 @@
|
|
|
1
|
+
"""The spine-resolution guard (issue #10): the manifest prune's existence
|
|
2
|
+
check must read the package in the spelling its own text carries (the pre-
|
|
3
|
+
rename layout when --encode-url-spaces renames entries), the prune's spine
|
|
4
|
+
protection must describe the text as the prune reads it (fix_manifest_ids
|
|
5
|
+
renames ids ahead of it in the OPF pipeline), and process_book must veto any
|
|
6
|
+
candidate whose spine (itemref -> item -> archive) dangles more than the
|
|
7
|
+
source's — the collapse that used to measure as an error reduction."""
|
|
8
|
+
|
|
9
|
+
import shutil
|
|
10
|
+
import tempfile
|
|
11
|
+
import unittest
|
|
12
|
+
import zipfile
|
|
13
|
+
from pathlib import Path
|
|
14
|
+
from unittest import mock
|
|
15
|
+
|
|
16
|
+
from bindery.cli import process_book
|
|
17
|
+
from bindery.epub import (
|
|
18
|
+
RepairFlags,
|
|
19
|
+
RepairReport,
|
|
20
|
+
fix_manifest_ids,
|
|
21
|
+
prune_missing_manifest_items,
|
|
22
|
+
repair_epub,
|
|
23
|
+
spine_dangles,
|
|
24
|
+
)
|
|
25
|
+
from bindery.validate import CheckResult
|
|
26
|
+
|
|
27
|
+
CONTAINER = (
|
|
28
|
+
'<?xml version="1.0"?><container version="1.0" '
|
|
29
|
+
'xmlns="urn:oasis:names:tc:opendocument:xmlns:container">'
|
|
30
|
+
'<rootfiles><rootfile full-path="OEBPS/content.opf" '
|
|
31
|
+
'media-type="application/oebps-package+xml"/></rootfiles></container>'
|
|
32
|
+
)
|
|
33
|
+
|
|
34
|
+
DOC = (
|
|
35
|
+
'<?xml version="1.0" encoding="utf-8"?>'
|
|
36
|
+
'<html xmlns="http://www.w3.org/1999/xhtml"><head>'
|
|
37
|
+
"<title>p</title></head><body><p>word word word word</p></body></html>"
|
|
38
|
+
)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def _opf(items: str, refs: str) -> str:
|
|
42
|
+
return (
|
|
43
|
+
'<?xml version="1.0"?>'
|
|
44
|
+
'<package xmlns="http://www.idpf.org/2007/opf" '
|
|
45
|
+
'unique-identifier="id">'
|
|
46
|
+
'<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">'
|
|
47
|
+
"<dc:title>t</dc:title><dc:language>en</dc:language>"
|
|
48
|
+
'<dc:identifier id="id">u</dc:identifier></metadata>'
|
|
49
|
+
f"<manifest>{items}</manifest>"
|
|
50
|
+
f"<spine>{refs}</spine></package>"
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
class _TempBook(unittest.TestCase):
|
|
55
|
+
def setUp(self):
|
|
56
|
+
self.tmp = tempfile.TemporaryDirectory(prefix="bindery_spine_")
|
|
57
|
+
self.addCleanup(self.tmp.cleanup)
|
|
58
|
+
|
|
59
|
+
def _path(self, name):
|
|
60
|
+
return Path(self.tmp.name) / name
|
|
61
|
+
|
|
62
|
+
def _build(self, name, entries):
|
|
63
|
+
path = self._path(name)
|
|
64
|
+
with zipfile.ZipFile(path, "w", zipfile.ZIP_DEFLATED) as z:
|
|
65
|
+
z.writestr("mimetype", "application/epub+zip", zipfile.ZIP_STORED)
|
|
66
|
+
for entry, data in entries.items():
|
|
67
|
+
z.writestr(entry, data)
|
|
68
|
+
return path
|
|
69
|
+
|
|
70
|
+
def _fan_book(self, splits=3):
|
|
71
|
+
"""The issue #10 shape: fan-conversion filenames with raw spaces and
|
|
72
|
+
manifest ids carrying commas and brackets (invalid XML names)."""
|
|
73
|
+
names = [
|
|
74
|
+
f"Author, Anne - [Series 1] - Title_split_{i:03d}.htm"
|
|
75
|
+
for i in range(splits)
|
|
76
|
+
]
|
|
77
|
+
items = "".join(
|
|
78
|
+
f'<item href="{n}" id="Author,_Anne_-_[Series_1]_-_Title_split_{i:03d}0" '
|
|
79
|
+
'media-type="application/xhtml+xml"/>'
|
|
80
|
+
for i, n in enumerate(names)
|
|
81
|
+
)
|
|
82
|
+
items += '<item href="titlepage.xhtml" id="titlepage" media-type="application/xhtml+xml"/>'
|
|
83
|
+
refs = '<itemref idref="titlepage"/>' + "".join(
|
|
84
|
+
f'<itemref idref="Author,_Anne_-_[Series_1]_-_Title_split_{i:03d}0"/>'
|
|
85
|
+
for i in range(splits)
|
|
86
|
+
)
|
|
87
|
+
entries = {
|
|
88
|
+
"META-INF/container.xml": CONTAINER,
|
|
89
|
+
"OEBPS/content.opf": _opf(items, refs),
|
|
90
|
+
"OEBPS/titlepage.xhtml": DOC,
|
|
91
|
+
}
|
|
92
|
+
for n in names:
|
|
93
|
+
entries[f"OEBPS/{n}"] = DOC
|
|
94
|
+
return self._build("fan.epub", entries)
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
class SpineDanglesTests(_TempBook):
|
|
98
|
+
def test_healthy_spine_dangles_nothing(self):
|
|
99
|
+
self.assertEqual(spine_dangles(self._fan_book()), 0)
|
|
100
|
+
|
|
101
|
+
def test_pruned_manifest_item_orphans_its_itemref(self):
|
|
102
|
+
# The issue's post-repair shape: the item is gone, the itemref stays.
|
|
103
|
+
src = self._fan_book()
|
|
104
|
+
broken = self._path("broken.epub")
|
|
105
|
+
with (
|
|
106
|
+
zipfile.ZipFile(src) as zin,
|
|
107
|
+
zipfile.ZipFile(broken, "w", zipfile.ZIP_DEFLATED) as zout,
|
|
108
|
+
):
|
|
109
|
+
for item in zin.infolist():
|
|
110
|
+
data = zin.read(item)
|
|
111
|
+
if item.filename == "OEBPS/content.opf":
|
|
112
|
+
text = data.decode()
|
|
113
|
+
start = text.index("<item ", text.index("split_000"))
|
|
114
|
+
end = text.index("/>", start) + 2
|
|
115
|
+
text = text[:start] + text[end:]
|
|
116
|
+
data = text.encode()
|
|
117
|
+
zout.writestr(item, data)
|
|
118
|
+
self.assertEqual(spine_dangles(broken), 1)
|
|
119
|
+
|
|
120
|
+
def test_item_whose_file_is_missing_dangles(self):
|
|
121
|
+
src = self._fan_book()
|
|
122
|
+
broken = self._path("missing.epub")
|
|
123
|
+
with (
|
|
124
|
+
zipfile.ZipFile(src) as zin,
|
|
125
|
+
zipfile.ZipFile(broken, "w", zipfile.ZIP_DEFLATED) as zout,
|
|
126
|
+
):
|
|
127
|
+
for item in zin.infolist():
|
|
128
|
+
if item.filename.endswith("split_001.htm"):
|
|
129
|
+
continue
|
|
130
|
+
zout.writestr(item, zin.read(item))
|
|
131
|
+
self.assertEqual(spine_dangles(broken), 1)
|
|
132
|
+
|
|
133
|
+
def test_unreadable_archive_probes_none(self):
|
|
134
|
+
# The veto needs evidence: an unreadable package answers None and
|
|
135
|
+
# never fires the guard.
|
|
136
|
+
self.assertIsNone(spine_dangles(self._path("nope.epub")))
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
class PruneManifestGuardTests(unittest.TestCase):
|
|
140
|
+
def test_spine_item_survives_renamed_ids(self):
|
|
141
|
+
# The regression: fix_manifest_ids renames item ids and idrefs before
|
|
142
|
+
# the prune runs; a spine snapshot taken from the pre-rename spelling
|
|
143
|
+
# missed every renamed idref and spine documents were pruned. The
|
|
144
|
+
# guard is derived from the text the prune reads, so the renamed
|
|
145
|
+
# spine item is protected even with every file "missing".
|
|
146
|
+
text = _opf(
|
|
147
|
+
'<item href="gone1.htm" id="a,1" media-type="application/xhtml+xml"/>'
|
|
148
|
+
'<item href="gone2.htm" id="b,2" media-type="application/xhtml+xml"/>',
|
|
149
|
+
'<itemref idref="a,1"/>',
|
|
150
|
+
)
|
|
151
|
+
text, n = fix_manifest_ids(text)
|
|
152
|
+
self.assertEqual(n, 2)
|
|
153
|
+
out, pruned, pruned_ids = prune_missing_manifest_items(text, "", frozenset())
|
|
154
|
+
self.assertEqual(pruned, 1)
|
|
155
|
+
self.assertEqual(len(pruned_ids), 1)
|
|
156
|
+
# The spine document's item tag survives whatever its id is spelled
|
|
157
|
+
# like now; only the orphaned non-spine declaration goes.
|
|
158
|
+
self.assertIn("gone1.htm", out)
|
|
159
|
+
self.assertNotIn("gone2.htm", out)
|
|
160
|
+
|
|
161
|
+
def test_non_spine_item_with_absent_file_is_pruned(self):
|
|
162
|
+
text = _opf(
|
|
163
|
+
'<item href="font.woff" id="f1" media-type="application/font-woff"/>',
|
|
164
|
+
"",
|
|
165
|
+
)
|
|
166
|
+
out, pruned, pruned_ids = prune_missing_manifest_items(
|
|
167
|
+
text, "", frozenset({"content.opf"})
|
|
168
|
+
)
|
|
169
|
+
self.assertEqual(pruned, 1)
|
|
170
|
+
self.assertEqual(pruned_ids, {"f1"})
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
class RawSpaceManifestRepairTests(_TempBook):
|
|
174
|
+
def test_repair_renames_instead_of_pruning_the_spine(self):
|
|
175
|
+
src = self._fan_book()
|
|
176
|
+
dst = self._path("out.epub")
|
|
177
|
+
report = repair_epub(
|
|
178
|
+
src, dst, RepairFlags(fix_ids=True, prune_missing=True, url_spaces=True)
|
|
179
|
+
)
|
|
180
|
+
self.assertIsNone(report.fixes.get("manifest_items_pruned"))
|
|
181
|
+
self.assertEqual(report.fixes.get("entries_renamed"), 3)
|
|
182
|
+
with zipfile.ZipFile(dst) as z:
|
|
183
|
+
names = set(z.namelist())
|
|
184
|
+
self.assertNotIn(
|
|
185
|
+
"OEBPS/Author, Anne - [Series 1] - Title_split_000.htm", names
|
|
186
|
+
)
|
|
187
|
+
self.assertIn(
|
|
188
|
+
"OEBPS/Author,_Anne_-_[Series_1]_-_Title_split_000.htm", names
|
|
189
|
+
)
|
|
190
|
+
opf = z.read("OEBPS/content.opf").decode()
|
|
191
|
+
# The manifest hrefs follow the entries to the renamed spelling, and
|
|
192
|
+
# every itemref still walks item -> file in the output archive.
|
|
193
|
+
self.assertIn('href="Author,_Anne_-_[Series_1]_-_Title_split_000.htm"', opf)
|
|
194
|
+
self.assertNotIn("manifest_items_pruned", opf)
|
|
195
|
+
self.assertEqual(spine_dangles(dst), 0)
|
|
196
|
+
|
|
197
|
+
|
|
198
|
+
class SpineVetoTests(_TempBook):
|
|
199
|
+
"""process_book wiring: real files for the probe, mocked oracle counts."""
|
|
200
|
+
|
|
201
|
+
def _run(self, src, candidate, fixes, before, after, write_candidate=True):
|
|
202
|
+
work = self._path("work")
|
|
203
|
+
work.mkdir(exist_ok=True)
|
|
204
|
+
|
|
205
|
+
def fake_repair(epub, dst, flags=None):
|
|
206
|
+
if write_candidate:
|
|
207
|
+
shutil.copyfile(candidate, dst)
|
|
208
|
+
return RepairReport(fixes=fixes)
|
|
209
|
+
|
|
210
|
+
with (
|
|
211
|
+
mock.patch("bindery.cli.repair_epub", side_effect=fake_repair),
|
|
212
|
+
mock.patch("bindery.cli.run_epubcheck", side_effect=[before, after]),
|
|
213
|
+
):
|
|
214
|
+
return process_book(src, work, validate=True)
|
|
215
|
+
|
|
216
|
+
def test_spine_collapse_rejects_improving_counts(self):
|
|
217
|
+
# The issue's verdict shape: 0f/17e/8w -> 0f/10e/0w measures as a
|
|
218
|
+
# gain while the spine has been pruned to the title page. The veto
|
|
219
|
+
# must override the counts and the entries_renamed promotion.
|
|
220
|
+
src = self._fan_book()
|
|
221
|
+
collapse = self._path("collapse.epub")
|
|
222
|
+
with (
|
|
223
|
+
zipfile.ZipFile(src) as zin,
|
|
224
|
+
zipfile.ZipFile(collapse, "w", zipfile.ZIP_DEFLATED) as zout,
|
|
225
|
+
):
|
|
226
|
+
for item in zin.infolist():
|
|
227
|
+
data = zin.read(item)
|
|
228
|
+
if item.filename == "OEBPS/content.opf":
|
|
229
|
+
text = data.decode()
|
|
230
|
+
for _ in range(3):
|
|
231
|
+
start = text.index("<item ", text.index("split_"))
|
|
232
|
+
end = text.index("/>", start) + 2
|
|
233
|
+
text = text[:start] + text[end:]
|
|
234
|
+
data = text.encode()
|
|
235
|
+
zout.writestr(item, data)
|
|
236
|
+
o = self._run(
|
|
237
|
+
src,
|
|
238
|
+
collapse,
|
|
239
|
+
{"entries_renamed": 1},
|
|
240
|
+
CheckResult(0, 17, 8),
|
|
241
|
+
CheckResult(0, 10, 0),
|
|
242
|
+
)
|
|
243
|
+
self.assertEqual(o.status, "reject")
|
|
244
|
+
self.assertIn("(spine collapse)", o.summary)
|
|
245
|
+
|
|
246
|
+
def test_intact_spine_keeps_the_normal_verdict(self):
|
|
247
|
+
src = self._fan_book()
|
|
248
|
+
fine = self._path("fine.epub")
|
|
249
|
+
shutil.copyfile(src, fine)
|
|
250
|
+
o = self._run(
|
|
251
|
+
src,
|
|
252
|
+
fine,
|
|
253
|
+
{"entries_renamed": 1},
|
|
254
|
+
CheckResult(0, 17, 8),
|
|
255
|
+
CheckResult(0, 10, 0),
|
|
256
|
+
)
|
|
257
|
+
self.assertEqual(o.status, "accept")
|
|
258
|
+
self.assertNotIn("spine collapse", o.summary)
|
|
259
|
+
|
|
260
|
+
def test_probe_failure_vetoes_nothing(self):
|
|
261
|
+
# A candidate the probe cannot read carries no evidence: the counts
|
|
262
|
+
# alone decide (fail-open, like the probe's contract).
|
|
263
|
+
src = self._fan_book()
|
|
264
|
+
o = self._run(
|
|
265
|
+
src,
|
|
266
|
+
None,
|
|
267
|
+
{"entries_renamed": 1},
|
|
268
|
+
CheckResult(0, 17, 8),
|
|
269
|
+
CheckResult(0, 10, 0),
|
|
270
|
+
write_candidate=False,
|
|
271
|
+
)
|
|
272
|
+
self.assertEqual(o.status, "accept")
|
|
273
|
+
|
|
274
|
+
|
|
275
|
+
try:
|
|
276
|
+
_FIXTURE = Path(__file__).resolve().parent.parent / (
|
|
277
|
+
"testing_facility/books_to_fix/my-enemy-my-ally-raw-space-href-manifest-prune.epub"
|
|
278
|
+
)
|
|
279
|
+
HAVE_FIXTURE = _FIXTURE.exists()
|
|
280
|
+
except OSError:
|
|
281
|
+
HAVE_FIXTURE = False
|
|
282
|
+
|
|
283
|
+
|
|
284
|
+
@unittest.skipUnless(HAVE_FIXTURE, "local issue fixture not present")
|
|
285
|
+
class FixtureRegressionTests(_TempBook):
|
|
286
|
+
def test_fixture_spine_survives_the_rename_pipeline(self):
|
|
287
|
+
# The real pre-repair bytes from the 2026-10-21 re-source wave.
|
|
288
|
+
src = self._path("fixture.epub")
|
|
289
|
+
shutil.copyfile(_FIXTURE, src)
|
|
290
|
+
dst = self._path("fixed.epub")
|
|
291
|
+
report = repair_epub(
|
|
292
|
+
src, dst, RepairFlags(fix_ids=True, prune_missing=True, url_spaces=True)
|
|
293
|
+
)
|
|
294
|
+
self.assertIsNone(report.fixes.get("manifest_items_pruned"))
|
|
295
|
+
self.assertEqual(report.fixes.get("entries_renamed"), 8)
|
|
296
|
+
self.assertEqual(spine_dangles(dst), 0)
|
|
297
|
+
|
|
298
|
+
|
|
299
|
+
if __name__ == "__main__":
|
|
300
|
+
unittest.main()
|
|
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
|
|
File without changes
|