bindery-cli 0.50.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.
Files changed (53) hide show
  1. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/.github/workflows/ci.yml +1 -1
  2. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/AGENTS.md +28 -6
  3. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/PKG-INFO +1 -1
  4. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/patchnotes.md +105 -0
  5. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/pyproject.toml +1 -1
  6. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/roadmap.md +10 -0
  7. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/spec.md +42 -5
  8. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/src/bindery/__init__.py +1 -1
  9. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/src/bindery/cli.py +51 -2
  10. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/src/bindery/epub.py +81 -7
  11. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/src/bindery/transforms.py +160 -0
  12. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/tests/test_cli.py +42 -0
  13. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/tests/test_epub.py +63 -0
  14. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/tests/test_flags_real_core.py +22 -0
  15. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/tests/test_flags_wiring.py +1 -0
  16. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/tests/test_matcher_hardening.py +57 -0
  17. bindery_cli-0.52.0/tests/test_spine_guard.py +300 -0
  18. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/tests/test_transforms.py +184 -0
  19. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/uv.lock +1 -1
  20. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/.github/FUNDING.yml +0 -0
  21. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/.github/workflows/publish.yml +0 -0
  22. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/.gitignore +0 -0
  23. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/LICENSE +0 -0
  24. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/README.md +0 -0
  25. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/docs/screenshots/library-sweep.png +0 -0
  26. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/logo.svg +0 -0
  27. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/plugin/__init__.py +0 -0
  28. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/project.done +0 -0
  29. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/run_tests.sh +0 -0
  30. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/scripts/FastSweep.java +0 -0
  31. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/scripts/build_plugin.py +0 -0
  32. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/scripts/fast_sweep.py +0 -0
  33. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/src/bindery/__main__.py +0 -0
  34. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/src/bindery/audit.py +0 -0
  35. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/src/bindery/library.py +0 -0
  36. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/src/bindery/pagination.py +0 -0
  37. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/src/bindery/reserialize.py +0 -0
  38. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/src/bindery/validate.py +0 -0
  39. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/src/bindery/watermark.py +0 -0
  40. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/tests/test_audit.py +0 -0
  41. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/tests/test_comment_hyphens.py +0 -0
  42. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/tests/test_contamination.py +0 -0
  43. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/tests/test_cover_tocdrift.py +0 -0
  44. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/tests/test_help.py +0 -0
  45. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/tests/test_library.py +0 -0
  46. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/tests/test_pagination.py +0 -0
  47. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/tests/test_plugin.py +0 -0
  48. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/tests/test_reserialize.py +0 -0
  49. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/tests/test_space_renames.py +0 -0
  50. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/tests/test_validate.py +0 -0
  51. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/tests/test_version.py +0 -0
  52. {bindery_cli-0.50.0 → bindery_cli-0.52.0}/tests/test_watermark.py +0 -0
  53. {bindery_cli-0.50.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
@@ -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: twenty-one structural
33
+ visible content. The canonical opt-in inventory lives in spec.md: twenty-two structural
34
34
  repairs, four lossy strips, four safe opt-ins, plus `--reserialize`.
35
35
  * **Structural repairs** (`--fix-empty-body`, `--fix-missing-title`, `--fix-id-colons`,
36
36
  `--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
@@ -38,7 +38,8 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
38
38
  `--prune-missing-resources`, `--strip-broken-anchors`, `--encode-url-spaces`,
39
39
  `--fix-container`, `--fix-media-types`, `--fix-cover`,
40
40
  `--fix-comment-double-hyphen`, `--fix-svg-dup-ids`, `--fix-cdata-terminator`,
41
- `--fix-misnested-inline`, `--fix-stray-close`, `--fix-unterminated-attr`;
41
+ `--fix-misnested-inline`, `--fix-stray-close`, `--fix-unterminated-attr`,
42
+ `--fix-unbound-prefix`;
42
43
  transforms.py, threaded through epub.py). The v0.47.0 five (the 2026-10-06
43
44
  issue batch): `--fix-svg-dup-ids` renames duplicate glyph ids inside
44
45
  standalone `.svg` entries (first keeps its name, references resolve to the
@@ -60,7 +61,15 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
60
61
  never percent-encoding (epubcheck decodes references before entry lookup,
61
62
  verified against 5.3), ambiguous renames refused per entry (`space_rename_map`),
62
63
  accepted under `no_worse` because PKG-010 sits on the warning axis the gate
63
- does not measure.
64
+ does not measure. `--fix-unbound-prefix` (v0.51.0, issue #9, the Calibre
65
+ embed scar) binds an attribute prefix the OPF never declares inline on the
66
+ element that uses it (`<dc:identifier id="ID1" ns0:scheme="calibre">`
67
+ whose `xmlns:ns0` sits on a sibling, out of XML scope; two RSC-016 fatals
68
+ plus OPF-030): URI evidence is the same prefix declared elsewhere in the
69
+ document (all declarations must agree) or the OPF namespace for a DC
70
+ element under an OPF-namespaced package, anything else refuses the whole
71
+ document; scope-tracked over a comment/CDATA-aware tokenizer, OPF only
72
+ (content docs have the `--strip-bad-attrs` drop); normal `gate`.
64
73
  They alter markup structure or fabricate minimal content. v0.14–v0.16 ran these unconditionally, which broke this rule;
65
74
  v0.17.0 restored it. `--unwrap-illegal-tags` additionally protects any illegal-tag
66
75
  name that an EPUB stylesheet styles as an element selector (`css_protected_tags`,
@@ -101,7 +110,20 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
101
110
  gain IS visible, so a run with no measurable improvement is a noop and nothing is
102
111
  applied) except the two whose gains sit on axes epubcheck does not measure:
103
112
  `--fix-cover` and `--encode-url-spaces`, accepted under the same `no_worse` bar with
104
- the partial rule intact. Changing either bar means re-running the library dry run.
113
+ the partial rule intact. One masked-axis rule (v0.51.0, issue #9): when the gate
114
+ answers noop but `report.ncx_uid_synced` fired on a book that started with fatals,
115
+ `process_book` reclassifies the verdict to `partial` (a fatal package halts the
116
+ metadata checks, so the dtb:uid comparison never ran in either measurement and the
117
+ real sync measures as no gain); application behavior is unchanged, since still-fatal
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.
105
127
  - **Library writes are sacred.** Replacement must stay atomic (temp in same dir, then
106
128
  `os.replace`), touch only the `.epub`, preserve mode, and be dry-run by default.
107
129
  Calibre format installation goes through cquarry's write module (`--install-to-calibre`;
@@ -115,10 +137,10 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
115
137
  - `src/bindery/watermark.py`: the opt-in lossy watermark strip (anchored and anchorless signature removal).
116
138
  - `src/bindery/reserialize.py`: structural repair via `html5lib`.
117
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).
118
- - `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).
119
141
  - `src/bindery/validate.py`: epubcheck wrapper, the `gate` (improvement) and `no_worse` (no-regression, for the lossy strips) acceptance bars.
120
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.
121
- - `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
122
144
  custom-rendered and colors itself with the CPython 3.14 argparse theme,
123
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.
124
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.50.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,110 @@
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
+
66
+ ## v0.51.0 (2026-10-17)
67
+
68
+ ### The unbound-prefix repair: the Calibre embed scar comes off the OPF (issue #9)
69
+
70
+ Century Rain (library book #11104) carried an OPF that repeated
71
+ `calibredb embed_metadata` rounds had scarred: one `dc:identifier`, the package
72
+ unique-identifier itself, carried an `ns0:scheme` attribute whose `xmlns:ns0`
73
+ declaration sat on a sibling element, out of XML scope. epubcheck answered with
74
+ two RSC-016 fatals (unbound prefix) plus OPF-030 (unique-identifier not found),
75
+ and because a fatal package halts the metadata checks, the stale NCX `dtb:uid`
76
+ was invisible to the oracle on both sides of the gate. The old probe report said
77
+ it all: `1f/1e/0w -> 1f/1e/0w, ncx_uid_synced (no measurable gain)`, the ncx
78
+ fix refused with the OPF half.
79
+
80
+ - **`--fix-unbound-prefix`** (new structural repair, twenty-second) binds an
81
+ attribute prefix the OPF never declares inline on the element that uses it,
82
+ the exact shape the file's own healthy siblings already use. The URI is
83
+ evidence-based, never guessed: the same prefix declared elsewhere in the
84
+ document (every declaration must agree, or the document is refused), or the
85
+ OPF namespace for a Dublin Core element under an OPF-namespaced package (the
86
+ canonical EPUB 2 `opf:scheme` shape); anything else refuses the whole
87
+ document untouched. Scope tracking walks the document with a
88
+ comment/CDATA-aware tokenizer over a lenient element stack, so declarations
89
+ that genuinely cover a use satisfy it without an edit and clean documents
90
+ are byte-identical. OPF only: content documents already have the
91
+ invalid-attribute drop (`--strip-bad-attrs`) for this defect class. Normal
92
+ `gate` (clearing the fatal is the measurable gain). On the fixture:
93
+ `1f/1e/0w -> 0f/0e/0w`, epubcheck fully clean.
94
+ - **The masked ncx gain** (the issue's second half) stops lying in reports:
95
+ when the gate answers noop but the NCX uid sync actually fired on a book
96
+ that started with fatals, `process_book` reclassifies the verdict to
97
+ `partial` instead of `equal`/`no measurable gain`. The sync is real,
98
+ deterministic work the oracle could not see; the still-fatal rule is intact,
99
+ so the library sweep still refuses to apply such a book and the single-file
100
+ verb still writes it under the honest PARTIAL label when given an explicit
101
+ destination.
102
+
103
+ Twenty-seven tests joined the suite (691 total): the transform unit tests
104
+ (scope, evidence, refusal, idempotence), the archive-level e2e, the masked-gain
105
+ verdict rules, tokenizer spin guards beside the other matchers, and the argv
106
+ wiring rows.
107
+
3
108
  ## v0.50.0 (2026-10-14)
4
109
 
5
110
  ### The contamination analyzer: fan-bundle cosmetics get reported (issue #8)
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "bindery-cli"
7
- version = "0.50.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 = [
@@ -44,9 +44,19 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
44
44
  | 0.48 | The AI-probe batch: the enforced closed-Calibre gate on both metadata.db doors (`audit --tag`, `library --apply --install-to-calibre`), the stated contracts (exit codes, no-prompt, NCX-001, --id scoping, json envelope keys), and `--help-json` | v0.48.0 |
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
+ | 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 |
47
49
 
48
50
  ## Open work
49
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.
50
60
  - [ ] **Obfuscation-aware encryption.xml repair**: prune stale obfuscation entries
51
61
  when font magic bytes prove the fonts are decrypted in place; drop
52
62
  encryption.xml when only obfuscation entries remain and fonts verify. NEVER
@@ -13,14 +13,14 @@ 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 twenty-one
16
+ The deliberate exceptions to "semantics-preserving" come in opt-in groups. The twenty-two
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`,
20
20
  `--prune-missing-resources`, `--strip-broken-anchors`, `--encode-url-spaces`,
21
21
  `--fix-container`, `--fix-media-types`, `--fix-cover`, `--fix-comment-double-hyphen`,
22
22
  `--fix-svg-dup-ids`, `--fix-cdata-terminator`, `--fix-misnested-inline`,
23
- `--fix-stray-close`, `--fix-unterminated-attr`) alter
23
+ `--fix-stray-close`, `--fix-unterminated-attr`, `--fix-unbound-prefix`) alter
24
24
  markup structure or fabricate minimal content; the four
25
25
  **lossy modes** (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`,
26
26
  `--strip-stub-docs`) remove
@@ -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
@@ -280,8 +289,22 @@ use, with the `partial` rule intact.
280
289
  quote before the next `<` (a real multi-line value closes quote-first), and only
281
290
  double-quoted values are judged. It runs before the other tag-shape readers, which an
282
291
  open value otherwise lies to.
283
-
284
- Nineteen of the twenty-one are evaluated by the normal `gate`: unlike the lossy strips,
292
+ - **`--fix-unbound-prefix`**: bind an attribute prefix the OPF never declares inline on
293
+ the element that uses it (the Calibre embed scar, issue #9: one dc: element carries
294
+ `ns0:scheme` while the `xmlns:ns0` declaration sits on a sibling, out of XML scope;
295
+ the RSC-016 "prefix is not bound" fatals make the whole package unparseable, which
296
+ also costs OPF-030 on the unique-identifier and masks the NCX-001 comparison). The
297
+ declaration is inserted on the user, the shape the file's own healthy siblings
298
+ already use. The URI is evidence-based, never guessed: the same prefix declared
299
+ elsewhere in the document with every declaration agreeing, or the OPF namespace for
300
+ a Dublin Core element under an OPF-namespaced package (the canonical EPUB 2
301
+ `opf:scheme` shape); anything else refuses the document untouched. Scope is tracked
302
+ with a lenient element stack over a comment/CDATA-aware tokenizer, so declarations
303
+ that genuinely cover a use satisfy it without an edit and clean documents are
304
+ byte-identical. Runs on the OPF only: content documents have the
305
+ invalid-attribute drop (`--strip-bad-attrs`) for the same defect class.
306
+
307
+ Twenty of the twenty-two are evaluated by the normal `gate`: unlike the lossy strips,
285
308
  their benefit is visible to epubcheck (they clear errors), so a run with no measurable
286
309
  improvement is a noop and nothing is applied. The two exceptions are `--fix-cover` and
287
310
  `--encode-url-spaces`, whose gains sit on axes epubcheck does not measure (cover
@@ -364,6 +387,20 @@ be run or its output cannot be parsed during a validated run, the book is an `er
364
387
  the gate has not accepted anything, so nothing is applied or written. With
365
388
  `--no-validate`, the gate is skipped and repairs are trusted on the RepairReport alone.
366
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
+
367
404
  The oracle itself runs two ways: the `epubcheck --json -` subprocess, or a persistent
368
405
  daemon (`_EpubcheckDaemon`, a bounded pool sized by `--workers`) that writes
369
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.50.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,
@@ -102,6 +102,7 @@ def _flags_from_args(args: argparse.Namespace) -> RepairFlags:
102
102
  misnested_inline=args.fix_misnested_inline or all_,
103
103
  stray_close=args.fix_stray_close or all_,
104
104
  unterminated_attr=args.fix_unterminated_attr or all_,
105
+ unbound_prefix=args.fix_unbound_prefix or all_,
105
106
  )
106
107
 
107
108
 
@@ -159,6 +160,16 @@ def process_book(
159
160
  watermark_refusals=report.watermark_refusals,
160
161
  )
161
162
  verdict = gate(before, after)
163
+ if verdict == "noop" and report.ncx_uid_synced and before.fatals > 0:
164
+ # The NCX-001 axis was masked in both measurements (issue #9): a fatal
165
+ # in the package halts the metadata checks, so epubcheck never compared
166
+ # dtb:uid to the unique-identifier, and the sync that really fixed it
167
+ # measures as no gain. The sync is semantics-preserving by construction
168
+ # (it writes only a differing dtb:uid content value), so the verdict
169
+ # stops calling real work gainless: partial, with the still-fatal rule
170
+ # intact (the library sweep still refuses to apply it; the single-file
171
+ # verb still writes it under the PARTIAL label when given a DST).
172
+ verdict = "partial"
162
173
  if (
163
174
  report.fixes.get("stripped_pagination")
164
175
  or report.fixes.get("stripped_broken_tags")
@@ -203,10 +214,31 @@ def process_book(
203
214
  verdict = "partial"
204
215
  else:
205
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"
206
236
  if verdict == "reject":
207
237
  summary += " (REGRESSION)"
208
238
  elif verdict == "noop":
209
239
  summary += " (no measurable gain)"
240
+ if spine_collapse:
241
+ summary += " (spine collapse)"
210
242
  status = "equal" if verdict == "noop" else verdict
211
243
  return Outcome(
212
244
  epub,
@@ -1136,7 +1168,9 @@ def _phase1_decisions(books: list[dict], apply: bool) -> list[dict]:
1136
1168
  f"{len(pending)} book(s) have gate-accepted repairs "
1137
1169
  f"pending ({len(watermarked)} watermarked); this run "
1138
1170
  "was read-only. Re-run with --apply-lossy to record "
1139
- "the lossy-strip consent and apply."
1171
+ "the lossy-strip consent and apply. A book still "
1172
+ "carrying fatals stays unapplied until its fatal is "
1173
+ "fixed: the sweep never applies a still-fatal book."
1140
1174
  ),
1141
1175
  "books": sorted(set(pending + watermarked)),
1142
1176
  }
@@ -1777,6 +1811,21 @@ _REPAIR_FLAG_TABLE: dict[str, list[tuple[str, str, str]]] = {
1777
1811
  "stays inside the comment bodies: text nodes and CDATA sections are "
1778
1812
  "never touched, and each comment's terminator is left intact.",
1779
1813
  ),
1814
+ (
1815
+ "fix_unbound_prefix",
1816
+ "bind an undeclared attribute prefix inline (Calibre embed scar)",
1817
+ "bind an attribute prefix the OPF never declares inline on the "
1818
+ "element that uses it (RSC-016 'prefix is not bound'): calibre's "
1819
+ "embed_metadata writer can leave one dc: element carrying "
1820
+ "ns0:scheme while the xmlns declaration sits on a sibling, out of "
1821
+ "XML scope, which fatals the whole package (plus OPF-030 on the "
1822
+ "unique-identifier). The URI is evidence-based, never guessed: "
1823
+ "the same prefix declared elsewhere in the document, or the OPF "
1824
+ "namespace for a Dublin Core element under an OPF-namespaced "
1825
+ "package; anything else refuses the document untouched. Content "
1826
+ "documents are not touched (their unbound prefixes have the "
1827
+ "--strip-bad-attrs drop).",
1828
+ ),
1780
1829
  ],
1781
1830
  "lossy strips (these delete converter-injected content; accepted on a no-worse bar)": [
1782
1831
  (
@@ -44,6 +44,7 @@ from .transforms import (
44
44
  fix_ncx_src_fragments,
45
45
  fix_stray_close,
46
46
  fix_svg_dup_ids,
47
+ fix_unbound_prefixes,
47
48
  fix_unterminated_attr,
48
49
  outside_protected_map,
49
50
  strip_attrs_in_start_tags,
@@ -284,6 +285,7 @@ class RepairFlags:
284
285
  misnested_inline: bool = False
285
286
  stray_close: bool = False
286
287
  unterminated_attr: bool = False
288
+ unbound_prefix: bool = False
287
289
 
288
290
 
289
291
  @dataclass
@@ -871,7 +873,7 @@ _NCX_CONTENT_SRC_RE = re.compile(
871
873
 
872
874
 
873
875
  def prune_missing_manifest_items(
874
- opf_text: str, opf_dir: str, present: frozenset[str], spine_ids: set[str]
876
+ opf_text: str, opf_dir: str, present: frozenset[str]
875
877
  ) -> tuple[str, int, set[str]]:
876
878
  """Drop `<item>` manifest declarations whose file is absent from the
877
879
  archive — unless the item is a spine document.
@@ -882,9 +884,16 @@ def prune_missing_manifest_items(
882
884
  dead-declaration removal instead of a stub file. The pruned ids come back
883
885
  so the caller can rewrite the edges that pointed at them
884
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).
885
893
  """
886
894
  count = 0
887
895
  pruned: set[str] = set()
896
+ spine_ids = {m.group(3) for m in _IDREF_ATTR_RE.finditer(opf_text)}
888
897
 
889
898
  def repl(m: re.Match) -> str:
890
899
  nonlocal count
@@ -1371,6 +1380,48 @@ def sync_ncx_uid(ncx_text: str, uid: str) -> tuple[str, bool]:
1371
1380
  return new, True
1372
1381
 
1373
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
+
1374
1425
  def ncx_uid_mismatch(src: Path) -> bool:
1375
1426
  """Cheaply detect NCX-001 (toc.ncx dtb:uid != OPF unique-identifier) without epubcheck."""
1376
1427
  try:
@@ -1478,6 +1529,15 @@ def repair_epub(
1478
1529
  own `>` (`<p class="footnote>` -> `<p class="footnote">`; the RSC-016
1479
1530
  'must not contain the < character' fatal). It runs before the tag-shape
1480
1531
  readers, which an open value otherwise lies to.
1532
+ With `unbound_prefix`, bind an attribute prefix the OPF never declares
1533
+ inline on the element that uses it (the Calibre embed scar: one dc:
1534
+ element carries `ns0:scheme` while the xmlns declaration sits on a
1535
+ sibling, out of scope; two RSC-016 fatals plus OPF-030 on the
1536
+ unique-identifier). The URI is evidence-based: the same prefix declared
1537
+ elsewhere in the document, or the OPF namespace for a Dublin Core element
1538
+ under an OPF-namespaced package; anything else refuses the whole
1539
+ document. Content documents are not touched (their unbound prefixes have
1540
+ the --strip-bad-attrs drop).
1481
1541
  With `strip_stub_docs` (lossy, the no_worse bar), drop spine documents whose
1482
1542
  entire visible text is one identical short placeholder repeated across the
1483
1543
  spine (the Bookmate/DRM-sample export whose chapters are all the same
@@ -1560,7 +1620,6 @@ def repair_epub(
1560
1620
  # opens by its decoded spelling)
1561
1621
  norm_to_raw: dict[str, str] = {}
1562
1622
  ids_by_doc: dict[str, frozenset[str]] = {}
1563
- spine_ids: set[str] = set()
1564
1623
  opf_dir = posixpath.dirname(opf) if opf else ""
1565
1624
 
1566
1625
  # --encode-url-spaces's rename half, decided up front: every
@@ -1591,8 +1650,9 @@ def repair_epub(
1591
1650
  if space_renames
1592
1651
  else {}
1593
1652
  )
1594
- # the one pre-pass that still reads the ORIGINAL references (the
1595
- # id snapshot's prune runs against the pre-rename layout)
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)
1596
1656
  present_src: frozenset[str] = frozenset()
1597
1657
  if flags.prune_missing or flags.strip_anchors or flags.fix_media_types:
1598
1658
  for n in zin.namelist():
@@ -1640,8 +1700,6 @@ def repair_epub(
1640
1700
  ids_by_doc[
1641
1701
  _norm_path(space_renames.get(i.filename, i.filename))
1642
1702
  ] = frozenset(m.group(3) for m in _XML_ID_RE.finditer(t))
1643
- if flags.prune_missing and opf_text is not None:
1644
- spine_ids = {m.group(3) for m in _IDREF_ATTR_RE.finditer(opf_text)}
1645
1703
 
1646
1704
  # The mimetype content is an OCF constant, so adding a missing entry and
1647
1705
  # normalizing wrong or whitespace-padded content is deterministic and
@@ -1835,8 +1893,17 @@ def repair_epub(
1835
1893
  or flags.fix_cover
1836
1894
  or flags.comment_double_hyphens
1837
1895
  or flags.strip_stub_docs
1896
+ or flags.unbound_prefix
1838
1897
  ):
1839
1898
  opf_changed = False
1899
+ if flags.unbound_prefix:
1900
+ # First in the branch: the unbound prefix makes the whole
1901
+ # package unparseable, so the parseability scar comes off
1902
+ # before the readers that match against the text.
1903
+ text, n = fix_unbound_prefixes(text)
1904
+ if n:
1905
+ report.add({"unbound_prefixes_bound": n})
1906
+ opf_changed = True
1840
1907
  if flags.fix_ids:
1841
1908
  text, n = fix_manifest_ids(text)
1842
1909
  if n:
@@ -1853,8 +1920,15 @@ def repair_epub(
1853
1920
  report.add({"epub3_attrs_stripped": n})
1854
1921
  opf_changed = True
1855
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).
1856
1930
  text, n, pruned_ids = prune_missing_manifest_items(
1857
- text, opf_dir, present, spine_ids
1931
+ text, opf_dir, present_src if space_renames else present
1858
1932
  )
1859
1933
  if n:
1860
1934
  report.add({"manifest_items_pruned": n})