bindery-cli 0.62.0__tar.gz → 0.62.2__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 (56) hide show
  1. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/AGENTS.md +9 -5
  2. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/PKG-INFO +8 -1
  3. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/README.md +7 -0
  4. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/patchnotes.md +81 -0
  5. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/pyproject.toml +1 -1
  6. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/roadmap.md +2 -0
  7. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/spec.md +72 -5
  8. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/src/bindery/__init__.py +1 -1
  9. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/src/bindery/cli.py +15 -0
  10. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/src/bindery/epub.py +41 -27
  11. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/src/bindery/transforms.py +74 -5
  12. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_epub.py +84 -0
  13. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_flags_real_core.py +19 -0
  14. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_flags_wiring.py +1 -0
  15. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_transforms.py +116 -0
  16. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/uv.lock +1 -1
  17. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/.github/FUNDING.yml +0 -0
  18. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/.github/workflows/ci.yml +0 -0
  19. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/.github/workflows/publish.yml +0 -0
  20. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/.gitignore +0 -0
  21. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/LICENSE +0 -0
  22. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/OBSERVE-RESEARCH.md +0 -0
  23. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/docs/screenshots/library-sweep.png +0 -0
  24. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/logo.svg +0 -0
  25. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/plugin/__init__.py +0 -0
  26. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/project.done +0 -0
  27. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/run_tests.sh +0 -0
  28. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/scripts/FastSweep.java +0 -0
  29. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/scripts/build_plugin.py +0 -0
  30. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/scripts/fast_sweep.py +0 -0
  31. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/src/bindery/__main__.py +0 -0
  32. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/src/bindery/audit.py +0 -0
  33. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/src/bindery/library.py +0 -0
  34. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/src/bindery/observe.py +0 -0
  35. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/src/bindery/pagination.py +0 -0
  36. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/src/bindery/reserialize.py +0 -0
  37. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/src/bindery/validate.py +0 -0
  38. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/src/bindery/watermark.py +0 -0
  39. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_audit.py +0 -0
  40. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_cli.py +0 -0
  41. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_comment_hyphens.py +0 -0
  42. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_contamination.py +0 -0
  43. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_cover_tocdrift.py +0 -0
  44. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_help.py +0 -0
  45. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_library.py +0 -0
  46. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_matcher_hardening.py +0 -0
  47. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_observe.py +0 -0
  48. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_pagination.py +0 -0
  49. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_plugin.py +0 -0
  50. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_reserialize.py +0 -0
  51. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_space_renames.py +0 -0
  52. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_spine_guard.py +0 -0
  53. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_validate.py +0 -0
  54. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_version.py +0 -0
  55. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_watermark.py +0 -0
  56. {bindery_cli-0.62.0 → bindery_cli-0.62.2}/tests/test_xml_hardening.py +0 -0
@@ -30,8 +30,11 @@ 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-six structural
34
- repairs, four lossy strips, four safe opt-ins, plus `--reserialize`.
33
+ visible content. The canonical opt-in inventory lives in spec.md: thirty structural
34
+ repairs, four lossy strips, five safe opt-ins, plus `--reserialize` (the
35
+ five v0.62.x flags -- `--fix-package-version`, `--fix-doctype`,
36
+ `--prune-invalid-guide-refs`, `--fix-item-properties`,
37
+ `--fix-double-colon-tags` -- are in both inventories since v0.62.0/0.62.1).
35
38
  * **Structural repairs** (`--fix-empty-body`, `--fix-missing-title`, `--fix-id-colons`,
36
39
  `--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
37
40
  `--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`,
@@ -41,7 +44,8 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
41
44
  `--fix-comment-double-hyphen`, `--fix-svg-dup-ids`, `--fix-duplicate-ids`,
42
45
  `--fix-cdata-terminator`,
43
46
  `--fix-misnested-inline`, `--fix-stray-close`, `--fix-unterminated-attr`,
44
- `--fix-unbound-prefix`;
47
+ `--fix-unbound-prefix`, `--fix-package-version`, `--fix-doctype`,
48
+ `--prune-invalid-guide-refs`, `--fix-item-properties`;
45
49
  transforms.py, threaded through epub.py). The v0.47.0 five (the 2026-10-06
46
50
  issue batch): `--fix-svg-dup-ids` renames duplicate glyph ids inside
47
51
  standalone `.svg` entries (first keeps its name, references resolve to the
@@ -230,14 +234,14 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
230
234
  - `src/bindery/epub.py`: archive rewrite, NCX uid sync, RepairReport, mismatch detection, and the opt-in structural-repair plumbing (including the CSS precondition scan). Since v0.59.0 (issue #23) `strip_ncx_dangling_targets` is the NCX dangling-target prune (`--prune-dangling-ncx-targets`): a balanced stack scanner over navPoint/navTarget/pageTarget tokens (quote-aware possessive regex, `_NcxTargetNode` tree, iterative post-order survival pass; header_end delimits the node's own navLabel+`<content>` so a splice removes the tags AND the dead header while the children re-home; an unbalanced walk aborts the part unchanged) and the NCX branch re-runs `fix_ncx_playorder` when it fires, alongside the anchor pass's own re-run. Since v0.58.0 (issue #18) the copy loop hands every `zout.writestr` a PRIVATE ZipInfo (`copy.copy(item)`, a fresh one on a rename) and the media-type `peek` catches `zipfile.BadZipFile` too. HAZARD: `writestr` STAMPS the ZipInfo it is handed with the DESTINATION offsets (header_offset, sizes land on it for the central directory); sharing the source's info repointed zin's own name lookups into the output file mid-loop, and one drifted probe killed whole books as "unreadable" -- 56 books "Bad magic number for file header" plus the "possible zip bomb" Development as Freedom (the drifted offset landed on a valid header whose data overlaps its neighbor), all one root cause. Since v0.58.0 (issue #21) `strip_broken_guide_fragments` gives the OPF guide the NCX fragment-strip's document-precision fallback, and the NCX branch re-runs `fix_ncx_playorder` after the anchor pass fires (the pre-strip sequence goes stale when fragments collapse onto their document). Since v0.58.0 (issue #20) `_resolve_href` decodes the five predefined XML entities plus numeric
231
235
  character references before the fragment split (attribute text arrives
232
236
  escaped; entries are raw; decoding first keeps the `#` inside `&#38;`
233
- from cutting the target), `_ITEM_TAG_RE`/`_SPINE_ITEM_RE`/`_GUIDE_REF_RE`/prune_dangling_edges' matcher accept an optional ns prefix (`<opf:item>`), and the renamed-reference spellings percent-encode `[`/`]` (`_encode_ref_path`). 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.55.0 (issue #16) the RSC-008 half lives beside the prune: `collect_undeclared_resources` (one whole-book census: content img/link, inline `<style>` url(), stylesheet url(), OPF guide refs) + `declare_missing_manifest_items` (sorted `bindery-dN` items before `</manifest>`, `_DECLARE_MEDIA_TYPES` blessed extensions only), gated and threaded through `RepairFlags.declare_missing`. 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).
237
+ from cutting the target), `_ITEM_TAG_RE`/`_SPINE_ITEM_RE`/`_GUIDE_REF_RE`/prune_dangling_edges' matcher accept an optional ns prefix (`<opf:item>`), and the renamed-reference spellings percent-encode `[`/`]` (`_encode_ref_path`). 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.55.0 (issue #16) the RSC-008 half lives beside the prune: `collect_undeclared_resources` (one whole-book census: content img/link, inline `<style>` url(), stylesheet url(), OPF guide refs) + `declare_missing_manifest_items` (sorted `bindery-dN` items before `</manifest>`, `_DECLARE_MEDIA_TYPES` blessed extensions only), gated and threaded through `RepairFlags.declare_missing`. 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). Since v0.62.0/0.62.1 (the 2026-11-03 observatory batch): the playOrder contract is base-free (epubcheck polices sharing/distinctness/gaps, never the base; verified at singleton/pair/offset scales), `fix_pagelist_class` inserts the collision-checked `bindery-pagelist` id beside the class (class-only insertion made epubcheck demand the id it enabled), `fix_missing_title` fills the self-closed `<title/>` head-scoped only (an empty SVG `<title>` is visible text the gate cannot measure), and four new flags live beside them: `fix_package_version` (literal 1.0 -> 2.0 only; `_PACKAGE_VERSION_ONE_RE`), `fix_doctype` (present-but-forbidden declarations only; `_scan_doctype_span` walks bracket depth and refuses unterminated spans), `prune_invalid_guide_refs` (declared-but-not-a-content-doc targets, both element shapes), and `fix_manifest_item_properties` + `collect_item_properties` (EPUB3-only census: scripted from `<script>`/`<form>`, svg from `<svg>`, remote-resources from absolute-scheme src/link/CSS url(); the insert branch appends before a self-closed item's solidus, never after it -- the v0.62.1 review caught the malformed `/ properties` shape). Since v0.62.1 `fix_double_colon_tags` escapes `::`-named pseudo-tags (a QName carries at most one colon, so such a construct is never markup; nested templates escape inner-first until stable; the tail is bounded at 120 chars so an escaped-bracket construct cannot swallow prose).
234
238
  - `src/bindery/validate.py`: epubcheck wrapper, the `gate` (improvement) and `no_worse` (no-regression, for the lossy strips) acceptance bars. Since v0.55.0 (issue #15) the default oracle budget is size-scaled (`oracle_timeout_for`: 300s at or under 10 MB, +60s per started 10 MB above, 1800s cap), one subprocess retry follows a timed-out attempt (the daemon path's subprocess fallback is that attempt), and only a double timeout raises `OracleTimeout`, which the gate surfaces as `(epubcheck timeout)` instead of `(epubcheck failed)` (the sweep selectors catch it and keep the book a candidate). Since v0.60.0 (issue #24) the size term counts decimal MB (10,440,245 bytes is 9.96 binary MiB, so the book the docs call 10.4 MB computed the flat 300s base with no size chunk), and the budget also scales on archive entry count (+60s per started 500 entries above 1,000; a path that does not open as a zip falls back to size-only): the Summa Theologica is entry-count-bound, not bytes-bound (3,831 entries / 3,808 spine docs; measured 384s source and 445s candidate), and now computes 720s.
235
239
  - `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.
236
240
  - `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. The `observe` verb (v0.53.0) writes schema v2 artifacts since v0.55.0 (issue #13): `codes.messages` (renamed from the mislabeled `occurrences`) counts aggregated epubcheck JSON message entries, `codes.occurrences` now carries the true per-site scale (summed `locations`), a `counting` block states both scales in the artifact, and `--against` accepts v1 or v2 (the trend keys exist in both). 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
237
241
  custom-rendered and colors itself with the CPython 3.14 argparse theme,
238
242
  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.
239
243
  - `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.
240
- - `tests/`: transforms (including the shared duplicate-id rename), end-to-end repair, atomic replace, pagination, watermarks, the audit analyzers (content/pagenumbers/emptytext/ocr/monolithic/completeness, archive integrity, spine classification, contamination since v0.50.0), the library sweep and `CalibreIdResolver`, validate, reserialize, CLI wiring, the version pin and the syntax-floor grammar guard, and the Calibre plugin (build drift + run behavior under calibre stubs). Since the v0.46.0 follow-ups: `tests/test_flags_wiring.py` reflectively pins the RepairFlags inventory to the argparse dests and `_flags_from_args` mapping (a flag added without a field, a field without a flag, or a remapped line fails there), the all-off defaults, and the version gate's caller-immutability contract (test_epub's `TestVersionGateKeepsFlagsIntact`); `tests/test_comment_hyphens.py` carries the RSC-016 fix; `tests/test_flags_real_core.py` drives every repair flag from argv through the unmocked core (--no-validate; the gate itself stays pinned by the mocked-oracle tests and runs for real wherever epubcheck exists). `tests/test_contamination.py` (v0.50.0) carries the three contamination sweeps, the advisory contract, the `_dir_dispatch` key pin, and the cover-routing regression. The v0.46.0 trio (test_flags_wiring, test_comment_hyphens, test_flags_real_core) rides CI's core-compat 3.12/3.13 leg; the hand-listed module list there must gain an entry for every new stack-free test module (audit-side test modules like test_contamination stay on the 3.14 leg by convention). The v0.55.0 batch (issues #11-#16): `tests/test_validate.py` pins the size-scaled timeout and the retry-then-OracleTimeout contract, `tests/test_observe.py` the v2 line format (`CODE:messages:occurrences`), the renamed codes block, the counting envelope, and v1 `--against` acceptance, `tests/test_epub.py::TestDeclareMissingItems` the RSC-008 declarer (sorted deterministic items, blessed media types only, id collisions prefixed, schemes/fragments/spaces/declared skipped), `tests/test_transforms.py::TestFixDuplicateIds` the content-doc rename, and `tests/test_flags_real_core.py` drives `--fix-duplicate-ids`, `--declare-missing-items`, and the extended `--strip-epub3-attrs` set through the real argv-to-fix path. The v0.59.0 addition (issue #23): `tests/test_epub.py::TestPruneDanglingNcxTargets` pins the node-exact prune rule (dead leaf dropped, dead parent spliced above live children, dead subtree one span, scheme/bare-fragment/contentless/comment-hidden untouched, escaped-ampersand src resolves, pageTarget and legacy navTarget covered, wrapper-crossing and unclosed walks abort, a wholesale-dead container refuses) plus the end-to-end prune+resequence, and `tests/test_flags_real_core.py` drives `--prune-dangling-ncx-targets` through argv. The v0.60.0 addition (issue #24): `tests/test_validate.py` pins the decimal-MB size term (exactly 10 MiB earns its 360s chunk) and the entry term (the 3,831-entry shape at <= 10 MB computes 660s; the full Summa shape computes 720s; exactly 1,000 entries stays at the size budget; 1,001 adds the first chunk; 2,500 computes 540s).
244
+ - `tests/`: transforms (including the shared duplicate-id rename), end-to-end repair, atomic replace, pagination, watermarks, the audit analyzers (content/pagenumbers/emptytext/ocr/monolithic/completeness, archive integrity, spine classification, contamination since v0.50.0), the library sweep and `CalibreIdResolver`, validate, reserialize, CLI wiring, the version pin and the syntax-floor grammar guard, and the Calibre plugin (build drift + run behavior under calibre stubs). Since the v0.46.0 follow-ups: `tests/test_flags_wiring.py` reflectively pins the RepairFlags inventory to the argparse dests and `_flags_from_args` mapping (a flag added without a field, a field without a flag, or a remapped line fails there), the all-off defaults, and the version gate's caller-immutability contract (test_epub's `TestVersionGateKeepsFlagsIntact`); `tests/test_comment_hyphens.py` carries the RSC-016 fix; `tests/test_flags_real_core.py` drives every repair flag from argv through the unmocked core (--no-validate; the gate itself stays pinned by the mocked-oracle tests and runs for real wherever epubcheck exists). `tests/test_contamination.py` (v0.50.0) carries the three contamination sweeps, the advisory contract, the `_dir_dispatch` key pin, and the cover-routing regression. The v0.46.0 trio (test_flags_wiring, test_comment_hyphens, test_flags_real_core) rides CI's core-compat 3.12/3.13 leg; the hand-listed module list there must gain an entry for every new stack-free test module (audit-side test modules like test_contamination stay on the 3.14 leg by convention). The v0.55.0 batch (issues #11-#16): `tests/test_validate.py` pins the size-scaled timeout and the retry-then-OracleTimeout contract, `tests/test_observe.py` the v2 line format (`CODE:messages:occurrences`), the renamed codes block, the counting envelope, and v1 `--against` acceptance, `tests/test_epub.py::TestDeclareMissingItems` the RSC-008 declarer (sorted deterministic items, blessed media types only, id collisions prefixed, schemes/fragments/spaces/declared skipped), `tests/test_transforms.py::TestFixDuplicateIds` the content-doc rename, and `tests/test_flags_real_core.py` drives `--fix-duplicate-ids`, `--declare-missing-items`, and the extended `--strip-epub3-attrs` set through the real argv-to-fix path. The v0.59.0 addition (issue #23): `tests/test_epub.py::TestPruneDanglingNcxTargets` pins the node-exact prune rule (dead leaf dropped, dead parent spliced above live children, dead subtree one span, scheme/bare-fragment/contentless/comment-hidden untouched, escaped-ampersand src resolves, pageTarget and legacy navTarget covered, wrapper-crossing and unclosed walks abort, a wholesale-dead container refuses) plus the end-to-end prune+resequence, and `tests/test_flags_real_core.py` drives `--prune-dangling-ncx-targets` through argv. The v0.60.0 addition (issue #24): `tests/test_validate.py` pins the decimal-MB size term (exactly 10 MiB earns its 360s chunk) and the entry term (the 3,831-entry shape at <= 10 MB computes 660s; the full Summa shape computes 720s; exactly 1,000 entries stays at the size budget; 1,001 adds the first chunk; 2,500 computes 540s). The v0.62.x additions: `tests/test_transforms.py::TestFixNcxPlayorder`'s base-free clause tests (zero-based/offset untouched, gap fires) and `TestFixMissingTitleSelfClosed`/`TestFixMissingTitleHeadScope` (self-closed fill, SVG-title protection), `tests/test_epub.py::TestItemPropertiesInsertionBranch` (the self-closed well-formedness pin) and the five `TestFlag*EndToEnd` classes, `tests/test_transforms.py::TestFixDoubleColonTags(+Bounds)` (book shape, closing tags, nesting, bounds, raw-ampersand), the four new-flag fixtures + rows in `tests/test_flags_real_core.py`, and the five mapping entries in `tests/test_flags_wiring.py`.
241
245
 
242
246
  ## Conventions
243
247
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: bindery-cli
3
- Version: 0.62.0
3
+ Version: 0.62.2
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
@@ -80,6 +80,13 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
80
80
  - **`--fix-misnested-inline`**: rewrites the Mobipocket drop-cap mis-nest `<i><b>X</i></b>` to `<i><b>X</b></i>` (em/strong variants and either tag order). Only the both-open-then-reversed-close shape is touched; a punctuation run caught between the reversed closers (`<i><b>xile</i>,</b>`) survives outside both spans, and a letter run there is refused (which span keeps the letters has no deterministic answer).
81
81
  - **`--fix-stray-close`**: removes an end tag whose element has no open start tag anywhere above it (the stray extra `</div>` on a shell page, which cascades into 'body must be terminated by the matching end-tag'). Merely mis-nested pairs are never touched: a close is removed only when nothing by that name is open.
82
82
  - **`--fix-unterminated-attr`**: closes an attribute value left open to the tag's own `>` (`<p class="footnote>` becomes `<p class="footnote">`). The parser swallows prose into the value until the next quote and dies on the first `<` it meets. Guards keep it off legal `>`-bearing values: bare-word values only, and no quote may close before the next `<`.
83
+ - **`--fix-unbound-prefix`**: binds a prefix the OPF never declares in scope inline on the element that uses it (the Calibre embed scar: `ns0:scheme` on a `dc:identifier` whose `xmlns:ns0` sits on a sibling, out of XML scope; the later writer build's unbound `dc:` element names). The declaration is inserted on the user in the shape the file's own healthy siblings use, from URI evidence only (the same prefix declared elsewhere with every declaration agreeing, or the use site's own namespace); anything else refuses the document untouched. Runs on the OPF only.
84
+ - **`--prune-dangling-ncx-targets`**: removes NCX `navPoint`/`navTarget`/`pageTarget` elements whose `<content src>` names a document the archive never contained (RSC-007 at the toc: the OPF never declared the file, so the manifest prune has no item to prune). Node-exact: a dead subtree drops as one span, a dead parent above live children is spliced (its navLabel goes with it, the children re-home one level up), scheme URLs and bare fragments are never this class, an unbalanced walk aborts unchanged, and a prune that would empty a container refuses. The always-on playOrder pass re-runs when it fires.
85
+ - **`--fix-package-version`**: rewrites the literal `version="1.0"` on the `<package>` element to `"2.0"` -- an EPUB version epubcheck cannot parse (OPF-001). Only the exact literal qualifies; a missing attribute (an OEB-1.0-namespace package) or any other spelling refuses the document untouched.
86
+ - **`--fix-doctype`**: replaces a content document's DOCTYPE when it carries a public identifier its package profile forbids (EPUB 3 requires `<!DOCTYPE html>`; EPUB 2's OPS content docs are XHTML 1.1, so an XHTML 1.0 doctype is flagged). Whitespace-equal declarations are no-ops, an absent DOCTYPE is legal and left alone, and an internal subset is never touched.
87
+ - **`--prune-invalid-guide-refs`**: removes guide `<reference>` elements whose target is declared in the manifest but is not an OPS content document (OPF-032: the Random House `msr` guide block pointing cover references at JPEGs is the dominant fingerprint). The guide is furniture, so removal is content-neutral; undeclared targets (OPF-031) and external schemes are left alone.
88
+ - **`--fix-item-properties`**: scans each content document for what epubcheck wants declared (OPF-014: `scripted` from a `<script>` element or a `<form>`, `svg` from an `<svg>`, `remote-resources` from an absolute-scheme src/link/CSS url()) and merges the tokens into the owning manifest item's `properties` attribute, sorted and deduplicated. EPUB 3 packages only: on EPUB 2 the attribute is itself illegal, so those carriers refuse and stay measured.
89
+ - **`--fix-double-colon-tags`**: escapes the `<`/`>` around pseudo-tags whose name contains a double colon -- an XML name can carry at most one colon, so such a construct is never markup and the parser dies on it with a fatal RSC-016 (C++ code samples like `std::vector<std::shared_ptr>`). Escaping both ends restores exactly the text the author wrote; real markup is unreachable because the double colon lives in the name grammar itself.
83
90
 
84
91
 
85
92
  Four opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
@@ -53,6 +53,13 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
53
53
  - **`--fix-misnested-inline`**: rewrites the Mobipocket drop-cap mis-nest `<i><b>X</i></b>` to `<i><b>X</b></i>` (em/strong variants and either tag order). Only the both-open-then-reversed-close shape is touched; a punctuation run caught between the reversed closers (`<i><b>xile</i>,</b>`) survives outside both spans, and a letter run there is refused (which span keeps the letters has no deterministic answer).
54
54
  - **`--fix-stray-close`**: removes an end tag whose element has no open start tag anywhere above it (the stray extra `</div>` on a shell page, which cascades into 'body must be terminated by the matching end-tag'). Merely mis-nested pairs are never touched: a close is removed only when nothing by that name is open.
55
55
  - **`--fix-unterminated-attr`**: closes an attribute value left open to the tag's own `>` (`<p class="footnote>` becomes `<p class="footnote">`). The parser swallows prose into the value until the next quote and dies on the first `<` it meets. Guards keep it off legal `>`-bearing values: bare-word values only, and no quote may close before the next `<`.
56
+ - **`--fix-unbound-prefix`**: binds a prefix the OPF never declares in scope inline on the element that uses it (the Calibre embed scar: `ns0:scheme` on a `dc:identifier` whose `xmlns:ns0` sits on a sibling, out of XML scope; the later writer build's unbound `dc:` element names). The declaration is inserted on the user in the shape the file's own healthy siblings use, from URI evidence only (the same prefix declared elsewhere with every declaration agreeing, or the use site's own namespace); anything else refuses the document untouched. Runs on the OPF only.
57
+ - **`--prune-dangling-ncx-targets`**: removes NCX `navPoint`/`navTarget`/`pageTarget` elements whose `<content src>` names a document the archive never contained (RSC-007 at the toc: the OPF never declared the file, so the manifest prune has no item to prune). Node-exact: a dead subtree drops as one span, a dead parent above live children is spliced (its navLabel goes with it, the children re-home one level up), scheme URLs and bare fragments are never this class, an unbalanced walk aborts unchanged, and a prune that would empty a container refuses. The always-on playOrder pass re-runs when it fires.
58
+ - **`--fix-package-version`**: rewrites the literal `version="1.0"` on the `<package>` element to `"2.0"` -- an EPUB version epubcheck cannot parse (OPF-001). Only the exact literal qualifies; a missing attribute (an OEB-1.0-namespace package) or any other spelling refuses the document untouched.
59
+ - **`--fix-doctype`**: replaces a content document's DOCTYPE when it carries a public identifier its package profile forbids (EPUB 3 requires `<!DOCTYPE html>`; EPUB 2's OPS content docs are XHTML 1.1, so an XHTML 1.0 doctype is flagged). Whitespace-equal declarations are no-ops, an absent DOCTYPE is legal and left alone, and an internal subset is never touched.
60
+ - **`--prune-invalid-guide-refs`**: removes guide `<reference>` elements whose target is declared in the manifest but is not an OPS content document (OPF-032: the Random House `msr` guide block pointing cover references at JPEGs is the dominant fingerprint). The guide is furniture, so removal is content-neutral; undeclared targets (OPF-031) and external schemes are left alone.
61
+ - **`--fix-item-properties`**: scans each content document for what epubcheck wants declared (OPF-014: `scripted` from a `<script>` element or a `<form>`, `svg` from an `<svg>`, `remote-resources` from an absolute-scheme src/link/CSS url()) and merges the tokens into the owning manifest item's `properties` attribute, sorted and deduplicated. EPUB 3 packages only: on EPUB 2 the attribute is itself illegal, so those carriers refuse and stay measured.
62
+ - **`--fix-double-colon-tags`**: escapes the `<`/`>` around pseudo-tags whose name contains a double colon -- an XML name can carry at most one colon, so such a construct is never markup and the parser dies on it with a fatal RSC-016 (C++ code samples like `std::vector<std::shared_ptr>`). Escaping both ends restores exactly the text the author wrote; real markup is unreachable because the double colon lives in the name grammar itself.
56
63
 
57
64
 
58
65
  Four opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
@@ -1,5 +1,86 @@
1
1
  # bindery-cli Patch Notes
2
2
 
3
+ ## v0.62.2 (2026-11-04)
4
+
5
+ ### The review batch: the insert-branch fix and the inventories, closed
6
+
7
+ A three-reviewer pass over the v0.62.x range (code review, test-gap map,
8
+ docs-vs-code audit) converged on one ship-blocking defect and a set of
9
+ smaller findings; this patch carries every fix.
10
+
11
+ - **`--fix-item-properties`'s insertion branch emitted malformed XML**
12
+ (ship-blocking): an item with no `properties` attribute got the new
13
+ attribute appended after its self-closing solidus
14
+ (`<item .../ properties="scripted">` -- a violation of EmptyElemTag), so
15
+ the gate rejected every candidate on exactly the books the flag targets.
16
+ No test had ever driven the branch: every fixture pre-carried
17
+ `properties="nav"`. The branch now appends before the solidus
18
+ (`properties="scripted"/>`), a fixture pins the self-closed well-formedness
19
+ with an ElementTree parse, and the paired-item shape is covered too. The
20
+ affected books will harvest on the next `--all` sweep.
21
+ - **`fix_missing_title`'s empty-title fill is head-scoped**: an empty
22
+ `<title>` inside `<svg>` is the image's accessibility name and hover
23
+ tooltip -- filling it with "Unknown" is a visible text change the gate
24
+ cannot measure. The fill now runs inside the `<head>` section when one
25
+ exists; a document with no head keeps the document-wide behavior.
26
+ - **`--fix-double-colon-tags`' tail is bounded** at 120 characters: a
27
+ pseudo-tag whose own bracket was escaped (`<b::c&gt;`, only the leading
28
+ `<` raw) would run the lazy tail to the next real tag's `>` and swallow
29
+ prose plus markup into display text -- damage the gate cannot always see.
30
+ Real code constructs are short; the bound keeps any failure local.
31
+ - **The on\* handler disjunct is gone from the item-properties census**:
32
+ `\son[a-z]+=` lexically cannot tell a handler from `only=`/`once=`, and
33
+ the handler demand was never verified against the oracle the way the
34
+ `<form>` demand was (tag-off bisection). The census keeps the
35
+ oracle-verified `scripted` triggers (`<script>`, `<form>`).
36
+ - **`_scan_doctype_span` refuses unterminated declarations**: a `<` met at
37
+ bracket depth 0 before any `>` means the next tag has begun and the
38
+ declaration's true end is unknowable -- the span must not swallow it.
39
+ - **The guide-prune docstring matches the code**: both element shapes are
40
+ removed (self-closed and paired), not "self-closed only".
41
+ - **The documentation inventories caught up** (the drift the reviews
42
+ measured): README's opt-in list gains the seven flags it was behind
43
+ (two of them since v0.51/v0.59), spec.md's structural section gains the
44
+ four v0.62.0 behavioral bullets and the safe-opt-in section for
45
+ `--fix-double-colon-tags`, the body counts read thirty/twenty-seven, and
46
+ AGENTS.md's inventory carries the five new flags. The v0.62.1 entry's
47
+ claim that the spec drift was closed was true only of the intro counts;
48
+ this entry closes the rest of it.
49
+
50
+ Suite: 895 tests.
51
+
52
+ ## v0.62.1 (2026-11-04)
53
+
54
+ ### --fix-double-colon-tags: the pseudo-tag escape, and the last fatal's repair
55
+
56
+ An XML name can carry at most one colon (the QName production is
57
+ `(NCName ':')? NCName`), so a pseudo-tag whose name contains `::` is
58
+ never markup -- every occurrence is unescaped author text, and the
59
+ parser dies on it with a fatal RSC-016. The Book of Debugging's C++
60
+ code samples carried exactly that: `std::vector<std::shared_ptr>` with
61
+ the template's closing bracket escaped as `&gt;` but the pseudo-tag
62
+ itself raw, at `EPUB/xhtml/part3.xhtml:399`. It was the library's one
63
+ remaining fatal after the 2026-11-03 wave.
64
+
65
+ The new opt-in flag escapes both ends of the construct, restoring
66
+ exactly the text the author wrote. Real markup is unreachable by
67
+ construction: the double colon lives in the name grammar itself, so no
68
+ legal tag can match, and prose comparisons (`a < b`) never form the
69
+ shape. Nested templates escape inner-first until stable, and the
70
+ trailing `>`s of a fully-escaped nesting stay raw -- legal text that
71
+ renders as `>`. Live on the facility specimen: `1f/15e/0w -> 0f/14e/0w`,
72
+ the gate accepts, and the book opens again. The unmasked residue
73
+ (the OPF-030/048 uid-empty family, the XHTML 1.1 strictness findings
74
+ the fatal was masking, and the `<int>`/`<dbghelp.h>` header-name
75
+ pseudo-tags, which are legal QNames and ride the content-model lane
76
+ rather than this one) is the manual list the observatory tracks.
77
+
78
+ Also closes a spec.md drift the release audit noted: the four v0.62.0
79
+ flags join the structural-repairs inventory (now thirty) and this flag
80
+ joins the safe opt-ins (now five).
81
+
82
+ Suite: 887 tests.
83
+
3
84
  ## v0.62.0 (2026-11-03)
4
85
 
5
86
  ### The observatory batch: three predicate repairs and four new flags
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "bindery-cli"
7
- version = "0.62.0"
7
+ version = "0.62.2"
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 = [
@@ -56,6 +56,8 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
56
56
  | 0.60 | The oracle budget scales on decimal MB and archive entry count (issue #24): the Summa Theologica (10,440,245 bytes = 9.96 binary MiB, 3,831 entries, 3,808 spine docs, 16,456 playOrder findings) is entry-count-bound, not bytes-bound -- measured 384s source and 445s candidate against the flat 300s its bytes computed (the binary 10 MiB divisor ate the size chunk; the book the docs call 10.4 MB never earned one) -- so every sweep double-timed-out and misfiled it as `(epubcheck timeout)`; the size term counts decimal MB now, the entry term adds +60s per started 500 entries above 1,000 (same 1800s cap), the book computes 720s, and a non-zip path falls back to size-only. epubcheck does police the playOrder contract (2 of the source's 6 RSC-005 error entries): default-pass candidate measures 0f/6e -> 0f/4e (accept), scoped `--all` candidate 0f/0e/0w | v0.60.0 |
57
57
  | 0.61.1 | The hex-ref href crash and the sweep that survives it: `_NUMERIC_REF_RE` captured the hex ref's `x` into the digits group and `int('x2013', 16)` killed the first whole-library `--all` dry run (2026-11-03 observe lane; 36 hex-ref hrefs across 5 books, every one an external URL the decode reaches before the scheme check discards it; dormant since v0.58.0 because the resolver is opt-in-path-only); the fix strips the prefix before the int, and the sweep's repair loop gains the crash guard -- an unexpected per-book exception is that book's `error` verdict (`crash (Type): ...; not applied`), counted in the existing errors tally, instead of a run-killing traceback (the single-file verb keeps its traceback) | v0.61.1 |
58
58
  | 0.62 | The observatory batch (the 2026-11-03 lane's answers): three predicate repairs -- the playOrder contract goes base-free (epubcheck polices sharing/distinctness/gaps, never the base; 107 no-op renumberings silenced), `fix_pagelist_class` inserts the collision-checked id beside the class (class-only made epubcheck demand the id it enabled; the 215-rejection poison), `fix_missing_title` fills the self-closed `<title/>` (the paired-fill branch was dead code; the 70-rejection poison) -- and four new flags for the never-triaged census codes: `--fix-package-version` (OPF-001; literal 1.0 only), `--fix-doctype` (HTM-004; present-but-forbidden declarations only, after the firing census killed insertion), `--prune-invalid-guide-refs` (OPF-032; declared-but-not-a-content-doc targets), `--fix-item-properties` (OPF-014; EPUB3-only, scripted/svg/remote-resources from a whole-book census) | v0.62.0 |
59
+ | 0.62.1 | `--fix-double-colon-tags`: the pseudo-tag escape for the last library fatal -- an XML name carries at most one colon, so a `::`-named pseudo-tag is never markup (fatal RSC-016; the Book of Debugging's C++ samples), and escaping both ends restores the author's text; nested templates escape inner-first, real markup is unreachable by construction; also closes the spec.md drift (the four v0.62.0 flags had not joined the inventory) | v0.62.1 |
60
+ | 0.62.2 | The review batch (three-reviewer pass over the v0.62.x range): the item-properties insertion branch emitted malformed XML on the self-closed shape (attribute after the solidus; no test drove the branch -- every fixture pre-carried properties), now appends before the solidus with an ET-parsed pin; the missing-title empty-fill is head-scoped (an empty SVG `<title>` is visible text); the double-colon tail is bounded at 120 chars (the escaped-bracket runaway); the unverified on\* handler disjunct left the census; `_scan_doctype_span` refuses unterminated declarations; the guide-prune docstring matches the code; and the documentation inventories caught up (README's seven missing flags, spec.md's four behavioral bullets + body counts + the safe-opt-in section, AGENTS.md's inventory) | v0.62.2 |
59
61
 
60
62
  ## Open work
61
63
 
@@ -13,7 +13,7 @@ restyle, re-compress, or restructure content, and it does not attempt to fix arb
13
13
  schema (RSC-005) violations, which are usually harmless to readers and not safely
14
14
  mechanizable.
15
15
 
16
- The deliberate exceptions to "semantics-preserving" come in opt-in groups. The twenty-six
16
+ The deliberate exceptions to "semantics-preserving" come in opt-in groups. The thirty
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`,
@@ -23,13 +23,15 @@ The deliberate exceptions to "semantics-preserving" come in opt-in groups. The t
23
23
  `--fix-svg-dup-ids`, `--fix-duplicate-ids`, `--fix-cdata-terminator`,
24
24
  `--fix-misnested-inline`,
25
25
  `--fix-stray-close`, `--fix-unterminated-attr`, `--fix-unbound-prefix`,
26
- `--fix-unique-identifier`) alter
26
+ `--fix-unique-identifier`, `--fix-package-version`, `--fix-doctype`,
27
+ `--prune-invalid-guide-refs`, `--fix-item-properties`) alter
27
28
  markup structure or fabricate minimal content; the four
28
29
  **lossy modes** (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`,
29
30
  `--strip-stub-docs`) remove
30
31
  content a converter injected rather than content the author wrote. A fourth group of
31
32
  **safe opt-ins** (`--fix-ids`, `--add-img-alt`, `--strip-bad-attrs`,
32
- `--escape-unknown-entities`) repairs without altering visible markup, and
33
+ `--escape-unknown-entities`, `--fix-double-colon-tags`) repairs without altering
34
+ visible markup, and
33
35
  `--reserialize` re-parses still-malformed documents whole. The default pass runs
34
36
  ONLY the five well-formedness transforms above, the NCX pipeline, and the mimetype
35
37
  fix: nothing else. (v0.14–v0.16 briefly
@@ -145,9 +147,27 @@ edit is anchored to real start tags; CDATA sections and comments are never
145
147
  rewritten, and everything but the offending attribute is preserved
146
148
  byte-for-byte. The normal gate applies.
147
149
 
150
+ ### Opt-in: escape double-colon pseudo-tags (`--fix-double-colon-tags`)
151
+
152
+ An XML name can carry at most one colon (the QName production is
153
+ `(NCName ':')? NCName`), so a pseudo-tag whose name contains `::` is never
154
+ markup -- every occurrence is unescaped author text, and the parser dies on
155
+ it with a fatal RSC-016 (C++ code samples like `std::vector<std::shared_ptr>`
156
+ whose converter escaped the trailing bracket but not the tag itself). With
157
+ this flag both ends of the construct are escaped, restoring exactly the text
158
+ the author wrote; the result renders identically to that intent. Real markup
159
+ is unreachable by construction -- the double colon lives in the name grammar
160
+ -- and prose comparisons (`a < b`) never form the shape. Nested templates
161
+ escape inner-first until stable (capped at sixteen passes) and a fully
162
+ escaped nesting's trailing `>`s stay raw, which is legal text. The tail is
163
+ bounded at 120 characters so an escaped-bracket construct cannot swallow
164
+ prose plus real markup, and CDATA sections and comments are never rewritten.
165
+ The normal gate applies.
166
+
167
+
148
168
  ### Opt-in: structural repairs
149
169
 
150
- Twenty-six repairs go past well-formedness and therefore require their own flag; none is ever
170
+ Thirty repairs go past well-formedness and therefore require their own flag; none is ever
151
171
  part of the default pipeline:
152
172
 
153
173
  - **`--fix-empty-body`**: `<p>&#160;</p>` inside a strictly empty `<body></body>` ("body
@@ -435,7 +455,54 @@ leftovers whose failing OPF is a stale non-rootfile are unreachable by construct
435
455
  byte-identical. Runs on the OPF only: content documents have the
436
456
  invalid-attribute drop (`--strip-bad-attrs`) for the same defect class.
437
457
 
438
- Twenty-three of the twenty-six are evaluated by the normal `gate`: unlike the lossy strips,
458
+ - **`--fix-package-version`**: rewrite a `<package>` element whose `version`
459
+ attribute is the literal `1.0` -- an EPUB version epubcheck cannot parse
460
+ (OPF-001 "error when parsing the EPUB version") -- to `"2.0"`, the
461
+ conformance the census's 25 carriers were all written to. Only the exact
462
+ literal qualifies: a missing attribute (the OEB-1.0-namespace package is a
463
+ migration, not an attribute bump) or any other spelling refuses the
464
+ document untouched, and the gate decides whether the profile
465
+ revalidation the bump buys is a real decrease.
466
+
467
+ - **`--fix-doctype`**: replace a content document's DOCTYPE when it carries a
468
+ public identifier its package profile forbids. EPUB 3 requires any DOCTYPE
469
+ to be `<!DOCTYPE html>` (an XHTML 1.x public doctype is a spec violation);
470
+ EPUB 2's OPS content docs are XHTML 1.1, so an XHTML 1.0 public doctype is
471
+ the census's second flagged shape. A whitespace-variant of the expected
472
+ form is a no-op, an ABSENT DOCTYPE is legal in both profiles and is left
473
+ alone (the first whole-library firing census measured insertion flat on
474
+ ~2,400 of 2,545 firing books -- absent is tolerated, so insertion never
475
+ converges), and a DOCTYPE carrying an internal subset is never touched
476
+ (the subset declares entities; swapping it changes what the parser
477
+ resolves). An unterminated declaration refuses: a `<` at bracket depth 0
478
+ before any `>` means the true end is unknowable and the span must not
479
+ swallow the next tag.
480
+
481
+ - **`--prune-invalid-guide-refs`**: remove guide `<reference>` elements whose
482
+ target is declared in the manifest but is not an OPS content document
483
+ (OPF-032; the Random House `msr` guide block pointing cover/thumbimage
484
+ references at JPEGs is the dominant fingerprint). The guide is furniture,
485
+ so removal is content-neutral. A reference to an UNDECLARED file is
486
+ OPF-031 (declare-missing's lane) and is left alone, as are external
487
+ schemes and references with no href at all. Both element shapes are
488
+ removed: self-closed and the paired `<reference>...</reference>`.
489
+
490
+ - **`--fix-item-properties`**: the OPF-014 inverse of the attribute scrub --
491
+ declare what the document contains instead of stripping it. A whole-book
492
+ census reads each content document (`scripted` from a `<script>` element
493
+ or a `<form>`; `svg` from an `<svg>`; `remote-resources` from an
494
+ absolute-scheme `src`, a remote `<link href>`, or a remote CSS `url()`)
495
+ and merges the tokens into the owning manifest item's `properties`
496
+ attribute, sorted and deduplicated; the insertion branch appends the
497
+ attribute before a self-closed item's solidus, never after it. EPUB 3
498
+ packages only: on EPUB 2 the `properties` attribute is itself illegal
499
+ (the oracle demands it and forbids it at once), so those carriers refuse
500
+ and stay measured. on* handler attributes are deliberately not detected:
501
+ `\son[a-z]+=` lexically cannot tell a handler from `only=`/`once=`, and
502
+ the handler demand was never verified against the oracle the way the form
503
+ was.
504
+
505
+ Twenty-seven of the thirty are evaluated by the normal `gate`: unlike the lossy strips,
439
506
  their benefit is visible to epubcheck (they clear errors), so a run with no measurable
440
507
  improvement is a noop and nothing is applied. The three exceptions are `--fix-cover`, `--encode-url-spaces`, and
441
508
  `--fix-media-types` (whose gains sit on axes epubcheck's counts do not measure:
@@ -11,7 +11,7 @@ Calibre plugin built from this core.
11
11
  Single source of truth for the version. pyproject.toml must match VERSION below.
12
12
  """
13
13
 
14
- VERSION = "0.62.0"
14
+ VERSION = "0.62.2"
15
15
  __version__ = VERSION
16
16
 
17
17
  from .epub import RepairReport, repair_epub # noqa: E402
@@ -113,6 +113,7 @@ def _flags_from_args(args: argparse.Namespace) -> RepairFlags:
113
113
  doctype=args.fix_doctype or all_,
114
114
  prune_guide_refs=args.prune_invalid_guide_refs or all_,
115
115
  item_properties=args.fix_item_properties or all_,
116
+ double_colon_tags=args.fix_double_colon_tags or all_,
116
117
  )
117
118
 
118
119
 
@@ -1688,6 +1689,20 @@ _REPAIR_FLAG_TABLE: dict[str, list[tuple[str, str, str]]] = {
1688
1689
  "DOCTYPE carries an internal subset (which can declare custom "
1689
1690
  "entities) are skipped wholesale.",
1690
1691
  ),
1692
+ (
1693
+ "fix_double_colon_tags",
1694
+ "escape unescaped pseudo-tags whose name carries :: (a fatal QName break)",
1695
+ "escape the < and > around pseudo-tags whose name contains a double "
1696
+ "colon -- an XML name can carry at most one colon (the QName "
1697
+ "production), so such a construct is never markup and the parser "
1698
+ "dies on it with a fatal RSC-016 (C++ code samples like "
1699
+ "`std::vector<std::shared_ptr>` whose converter escaped the "
1700
+ "trailing bracket but not the tag; the Book of Debugging's last "
1701
+ "library fatal). Escaping both ends restores exactly the text the "
1702
+ "author wrote. Real markup is unreachable by construction: the "
1703
+ "double colon lives in the name grammar itself. Nested templates "
1704
+ "escape inner-first until stable.",
1705
+ ),
1691
1706
  ],
1692
1707
  "structural repairs: markup and nesting": [
1693
1708
  (
@@ -40,6 +40,7 @@ from .transforms import (
40
40
  escape_unknown_entities,
41
41
  fix_cdata_terminator,
42
42
  fix_comment_double_hyphen,
43
+ fix_double_colon_tags,
43
44
  fix_duplicate_ids,
44
45
  fix_empty_body,
45
46
  fix_id_colons,
@@ -308,6 +309,7 @@ class RepairFlags:
308
309
  doctype: bool = False
309
310
  prune_guide_refs: bool = False
310
311
  item_properties: bool = False
312
+ double_colon_tags: bool = False
311
313
 
312
314
 
313
315
  @dataclass
@@ -442,7 +444,10 @@ _XHTML11_DOCTYPE = (
442
444
  def _scan_doctype_span(text: str) -> tuple[int, int] | None:
443
445
  """The exact (start, end) span of a DOCTYPE declaration, honouring the
444
446
  bracketed internal subset: a naive `[^>]*` stops at the first `>`, which
445
- a subset's conditional sections can carry. None when unterminated."""
447
+ a subset's conditional sections can carry. None when unterminated -- and
448
+ a `<` met at bracket depth 0 before the closing `>` IS unterminated (the
449
+ next tag has begun, so the declaration's true end is unknowable and the
450
+ span must not swallow it)."""
446
451
  m = re.search(r"<!DOCTYPE", text, re.IGNORECASE)
447
452
  if m is None:
448
453
  return None
@@ -456,6 +461,8 @@ def _scan_doctype_span(text: str) -> tuple[int, int] | None:
456
461
  depth -= 1
457
462
  elif ch == ">" and depth <= 0:
458
463
  return m.start(), i + 1
464
+ elif ch == "<" and depth <= 0:
465
+ return None
459
466
  i += 1
460
467
  return None
461
468
 
@@ -545,10 +552,13 @@ def prune_invalid_guide_refs(opf_text: str, opf_dir: str) -> tuple[str, int]:
545
552
  not an OPS content document (OPF-032).
546
553
 
547
554
  The predicate is deliberate: a reference to an UNDECLARED file is
548
- OPF-031, declare-missing's lane; an external scheme is nobody's guide;
549
- a self-closed element is the only shape removed (a paired reference
550
- with children is unheard of in the census, and a botched span would
551
- eat the guide). Nothing else about the guide is rewritten.
555
+ OPF-031, declare-missing's lane; an external scheme is nobody's guide.
556
+ Both element shapes are removed -- self-closed and the paired
557
+ `<reference>...</reference>` (the census never saw a paired one, but
558
+ the guide is furniture either way; the lazy paired span's
559
+ bridge-into-the-next-reference risk is bounded by references being
560
+ siblings in one small block). Nothing else about the guide is
561
+ rewritten.
552
562
  """
553
563
  media_types = _manifest_media_type_map(opf_text, opf_dir)
554
564
  count = 0
@@ -573,16 +583,18 @@ def prune_invalid_guide_refs(opf_text: str, opf_dir: str) -> tuple[str, int]:
573
583
 
574
584
  # --fix-item-properties: the OPF-014 lane (the 2026-11-03 triage, 74 books).
575
585
  # EPUB3 manifest items must declare what their documents contain: `scripted`
576
- # when the document carries scripting (a <script> element, an on* handler,
577
- # or a <form> — epubcheck 5.3 demands scripted for form documents, verified
578
- # on the Rustonomicon's scraped GitHub page where tag-off bisection isolated
579
- # the form), `svg` when the document carries an <svg>, and
580
- # `remote-resources` when it loads resources from outside the container
581
- # (src=/href= attributes and CSS url() values with an absolute scheme).
582
- # Declaring reality changes no content.
586
+ # when the document carries scripting (a <script> element or a <form> —
587
+ # epubcheck 5.3 demands scripted for form documents, verified on the
588
+ # Rustonomicon's scraped GitHub page where tag-off bisection isolated the
589
+ # form), `svg` when the document carries an <svg>, and `remote-resources`
590
+ # when it loads resources from outside the container (src=/href= attributes
591
+ # and CSS url() values with an absolute scheme). Deliberately NOT detected:
592
+ # on* handler attributes -- `\son[a-z]+=` lexically cannot tell a handler
593
+ # from `only=`/`once=` (the v0.62.1 review's false-positive finding), and
594
+ # the handler demand was never verified against the oracle the way the form
595
+ # was. Declaring reality changes no content.
583
596
  _SCRIPT_TAG_RE = re.compile(r"<script\b", re.IGNORECASE)
584
597
  _FORM_TAG_RE = re.compile(r"<form\b", re.IGNORECASE)
585
- _HANDLER_ATTR_RE = re.compile(r"""\son[a-z]+\s*=\s*["']""", re.IGNORECASE)
586
598
  _SVG_TAG_RE = re.compile(r"<svg\b", re.IGNORECASE)
587
599
  _REMOTE_SRC_RE = re.compile(r"""\ssrc\s*=\s*(["'])https?://""", re.IGNORECASE)
588
600
  _REMOTE_LINK_HREF_RE = re.compile(
@@ -597,10 +609,10 @@ _ITEM_PROPERTIES_RE = re.compile(
597
609
  def collect_item_properties(zin: zipfile.ZipFile) -> dict[str, frozenset[str]]:
598
610
  """The item-properties census: resolved content-doc path -> the EPUB3
599
611
  property tokens the document's own bytes demand. `scripted` from a
600
- `<script>` element, an on* handler attribute, or a `<form>`; `svg` from
601
- an `<svg>` element; `remote-resources` from an absolute-scheme src
602
- attribute, a remote `<link href>`, or a remote CSS url(). Non-UTF-8
603
- documents are skipped (their contents are nobody's guess)."""
612
+ `<script>` element or a `<form>`; `svg` from an `<svg>` element;
613
+ `remote-resources` from an absolute-scheme src attribute, a remote
614
+ `<link href>`, or a remote CSS url(). Non-UTF-8 documents are skipped
615
+ (their contents are nobody's guess)."""
604
616
  props: dict[str, set[str]] = {}
605
617
  for item in zin.infolist():
606
618
  low = item.filename.lower()
@@ -611,11 +623,7 @@ def collect_item_properties(zin: zipfile.ZipFile) -> dict[str, frozenset[str]]:
611
623
  except (UnicodeDecodeError, RuntimeError):
612
624
  continue
613
625
  found: set[str] = set()
614
- if (
615
- _SCRIPT_TAG_RE.search(text)
616
- or _FORM_TAG_RE.search(text)
617
- or _HANDLER_ATTR_RE.search(text)
618
- ):
626
+ if _SCRIPT_TAG_RE.search(text) or _FORM_TAG_RE.search(text):
619
627
  found.add("scripted")
620
628
  if _SVG_TAG_RE.search(text):
621
629
  found.add("svg")
@@ -663,11 +671,13 @@ def fix_manifest_item_properties(
663
671
  if pm is None:
664
672
  merged = " ".join(sorted(needed))
665
673
  count += 1
666
- return (
667
- tag[: tag.rindex(">")]
668
- + f' properties="{merged}"'
669
- + tag[tag.rindex(">") :]
670
- )
674
+ head = tag[: tag.rindex(">")]
675
+ if head.endswith("/"):
676
+ # self-closed: the solidus must sit immediately before `>`
677
+ # (an attribute after it violates EmptyElemTag and the
678
+ # candidate dies as a fatal of our own making)
679
+ return head[:-1] + f' properties="{merged}"' + "/>"
680
+ return head + f' properties="{merged}"' + ">"
671
681
  existing = set(pm.group(3).split())
672
682
  if existing >= needed:
673
683
  return tag
@@ -3074,6 +3084,10 @@ def repair_epub(
3074
3084
  text, n = fix_missing_title(text)
3075
3085
  if n:
3076
3086
  counts["fix_missing_title"] = n
3087
+ if flags.double_colon_tags:
3088
+ text, n = fix_double_colon_tags(text)
3089
+ if n:
3090
+ counts["double_colon_tags_escaped"] = n
3077
3091
  if flags.doctype:
3078
3092
  text, n = fix_doctype(text, pkg_major)
3079
3093
  if n:
@@ -692,11 +692,29 @@ def fix_missing_title(s: str) -> tuple[str, int]:
692
692
  count += 1
693
693
  return "<title>Unknown</title>"
694
694
 
695
- s, n = re.subn(
696
- r"<title\b[^>]*/>|<title\b[^>]*>\s*</title>", repl, s, flags=re.IGNORECASE
697
- )
698
- if n > 0:
699
- return s, n
695
+ # Head-scoped (v0.62.2): an empty <title> inside <svg> is the image's
696
+ # accessibility name / hover tooltip -- filling it with "Unknown" is a
697
+ # VISIBLE text change the gate cannot measure, so the fill only runs
698
+ # inside the head section when one exists. A document with no head at
699
+ # all keeps the document-wide behavior (nothing scoped to protect).
700
+ head_m = re.search(r"<head\b[^>]*>.*?</head>", s, re.IGNORECASE | re.DOTALL)
701
+ if head_m is not None:
702
+ head = head_m.group(0)
703
+ filled, n = re.subn(
704
+ r"<title\b[^>]*/>|<title\b[^>]*>\s*</title>",
705
+ repl,
706
+ head,
707
+ flags=re.IGNORECASE,
708
+ )
709
+ if n > 0:
710
+ return s[: head_m.start()] + filled + s[head_m.end() :], n
711
+ # nothing empty in the head; fall through to the checks below
712
+ else:
713
+ s, n = re.subn(
714
+ r"<title\b[^>]*/>|<title\b[^>]*>\s*</title>", repl, s, flags=re.IGNORECASE
715
+ )
716
+ if n > 0:
717
+ return s, n
700
718
 
701
719
  if re.search(r"<title\b[^>]*>.*?</title>", s, re.IGNORECASE | re.DOTALL):
702
720
  return s, 0
@@ -718,6 +736,57 @@ def fix_missing_title(s: str) -> tuple[str, int]:
718
736
  _EXTERNAL_TARGET_RE = re.compile(r"^(?:[a-zA-Z][\w+.-]*:|//)")
719
737
 
720
738
 
739
+ # --fix-double-colon-tags: an XML name can carry at most one colon (the QName
740
+ # production is (NCName ':')? NCName), so a pseudo-tag whose name contains
741
+ # `::` can never be markup -- every occurrence is unescaped author text, and
742
+ # the parser reads it as a fatal RSC-016 (the Book of Debugging's C++ code
743
+ # samples: `std::vector<std::shared_ptr>` with the template's closing bracket
744
+ # escaped as `&gt;` but the pseudo-tag itself raw). Escaping both ends
745
+ # restores exactly the text the author wrote.
746
+ # The tail is bounded (v0.62.2, 120 chars): a pseudo-tag whose own bracket
747
+ # was escaped (`<b::c&gt;` -- only the leading `<` raw) would otherwise run
748
+ # the lazy tail to the next REAL tag's `>` and swallow prose plus markup
749
+ # into display text, damage the gate cannot always see. Real code
750
+ # constructs are short; the bound keeps any failure local.
751
+ _DOUBLE_COLON_TAG_RE = re.compile(r"</?[A-Za-z_][\w.-]*(?:::[\w.-]+)+[^>]{0,120}?>")
752
+
753
+
754
+ @_outside_protected
755
+ def fix_double_colon_tags(s: str) -> tuple[str, int]:
756
+ """Escape `<`/`>` around pseudo-tags whose name contains `::`.
757
+
758
+ Opt-in (--fix-double-colon-tags): it rewrites document bytes, though the
759
+ result renders exactly the text the author intended. The `::` lives in
760
+ the NAME grammar, which no real tag can carry (a legal QName holds at
761
+ most one colon), so real markup is unreachable by construction; prose
762
+ comparisons (`a < b`) never match because the name must start the
763
+ construct and carry the double colon. A nested template
764
+ (`std::vector<std::string>`) leaves the innermost pseudo-tag for the
765
+ next pass -- the sub runs until stable (capped), and the trailing
766
+ `>`s of a fully-escaped nesting stay raw, which is legal text. The
767
+ `[^>]*?` tail crosses a nested `<` on purpose and stops at the first
768
+ `>`: a `<b::c` with no closing `>` anywhere would run to the next
769
+ tag's end -- the same single-class runaway shape every tag matcher
770
+ here documents, and the gate rejects any escape that measures worse.
771
+ """
772
+ count = 0
773
+
774
+ def repl(m: re.Match) -> str:
775
+ nonlocal count
776
+ count += 1
777
+ body = m.group(0)
778
+ # body[0] is the leading `<` (and the `/` of a closing construct
779
+ # stays): escape both ends, plus any raw & or nested < the tail
780
+ # crossed
781
+ return "&lt;" + body[1:-1].replace("&", "&amp;").replace("<", "&lt;") + "&gt;"
782
+
783
+ for _ in range(16):
784
+ s, n = _DOUBLE_COLON_TAG_RE.subn(repl, s)
785
+ if not n:
786
+ break
787
+ return s, count
788
+
789
+
721
790
  @_outside_protected
722
791
  def fix_id_colons(s: str) -> tuple[str, int]:
723
792
  """Translate illegal colons in `id="X:Y"` and matching internal `#X:Y`
@@ -3656,3 +3656,87 @@ class TestFlagItemPropertiesEndToEnd(unittest.TestCase):
3656
3656
  out = z.read("OEBPS/content.opf").decode()
3657
3657
  self.assertIn('properties="nav"', out)
3658
3658
  self.assertNotIn("scripted", out)
3659
+
3660
+
3661
+ class TestFlagDoubleColonTagsEndToEnd(unittest.TestCase):
3662
+ """--fix-double-colon-tags through the real repair: the Book of
3663
+ Debugging's C++ sample shape (the library's last fatal) escapes and
3664
+ the count lands in fixes."""
3665
+
3666
+ def test_repair_epub_escapes_the_pseudo_tag(self):
3667
+ opf = (
3668
+ '<?xml version="1.0"?>'
3669
+ '<package xmlns="http://www.idpf.org/2007/opf" version="2.0" '
3670
+ 'unique-identifier="id"><metadata xmlns:dc="http://purl.org/dc/elements/1.1/">'
3671
+ '<dc:identifier id="id">x</dc:identifier>'
3672
+ "<dc:title>t</dc:title><dc:language>en</dc:language></metadata>"
3673
+ '<manifest><item id="c1" href="c1.xhtml" '
3674
+ 'media-type="application/xhtml+xml"/></manifest>'
3675
+ "<spine><itemref idref='c1'/></spine></package>"
3676
+ )
3677
+ doc = (
3678
+ '<?xml version="1.0"?><html xmlns="http://www.w3.org/1999/xhtml">'
3679
+ "<head><title>t</title></head><body><pre><code><span>"
3680
+ "std::vector<std::shared_ptr>&gt; data;</span>"
3681
+ "</code></pre></body></html>"
3682
+ )
3683
+ with tempfile.TemporaryDirectory() as td:
3684
+ s, d = Path(td) / "in.epub", Path(td) / "out.epub"
3685
+ with zipfile.ZipFile(s, "w", zipfile.ZIP_DEFLATED) as z:
3686
+ z.writestr("mimetype", "application/epub+zip")
3687
+ z.writestr("OEBPS/content.opf", opf)
3688
+ z.writestr("OEBPS/c1.xhtml", doc)
3689
+ report = repair_epub(s, d, RepairFlags(double_colon_tags=True))
3690
+ self.assertEqual(report.fixes.get("double_colon_tags_escaped"), 1)
3691
+ with zipfile.ZipFile(d) as z:
3692
+ out = z.read("OEBPS/c1.xhtml").decode()
3693
+ self.assertIn("&lt;std::shared_ptr&gt;", out)
3694
+ self.assertNotIn("<std::shared_ptr>", out)
3695
+
3696
+
3697
+ class TestItemPropertiesInsertionBranch(unittest.TestCase):
3698
+ """v0.62.1's insertion branch (an item with NO properties attribute)
3699
+ emitted `<item .../ properties="...">` on the universal self-closed
3700
+ shape -- an attribute after the solidus violates EmptyElemTag, so the
3701
+ gate rejected every candidate on exactly the books the flag targets,
3702
+ and no test drove the branch because every fixture pre-carried
3703
+ properties="nav" (the v0.62.1 review's ship-blocking finding)."""
3704
+
3705
+ OPF = (
3706
+ '<?xml version="1.0"?><package '
3707
+ 'xmlns="http://www.idpf.org/2007/opf" version="3.0" '
3708
+ 'unique-identifier="id"><metadata/>'
3709
+ '<manifest><item id="c1" href="c1.xhtml" '
3710
+ 'media-type="application/xhtml+xml"/></manifest>'
3711
+ "<spine><itemref idref='c1'/></spine></package>"
3712
+ )
3713
+
3714
+ def test_self_closed_item_inserts_well_formed(self):
3715
+ out, n = fix_manifest_item_properties(
3716
+ self.OPF, "OEBPS", {"OEBPS/c1.xhtml": frozenset({"scripted"})}
3717
+ )
3718
+ self.assertEqual(n, 1)
3719
+ self.assertIn('properties="scripted"', out)
3720
+ # the solidus must sit immediately before `>`
3721
+ self.assertIn('properties="scripted"/>', out)
3722
+ self.assertNotIn("/ properties=", out)
3723
+ ET.fromstring(out)
3724
+
3725
+ def test_paired_item_inserts_well_formed(self):
3726
+ opf = self.OPF.replace(
3727
+ 'media-type="application/xhtml+xml"/>',
3728
+ 'media-type="application/xhtml+xml">',
3729
+ )
3730
+ opf = opf.replace(
3731
+ '<item id="c1" href="c1.xhtml" media-type="application/xhtml+xml">',
3732
+ '<item id="c1" href="c1.xhtml" media-type="application/xhtml+xml"></item>',
3733
+ )
3734
+ out, n = fix_manifest_item_properties(
3735
+ opf, "OEBPS", {"OEBPS/c1.xhtml": frozenset({"scripted"})}
3736
+ )
3737
+ self.assertEqual(n, 1)
3738
+ ET.fromstring(out)
3739
+
3740
+ def test_doctype_unterminated_declaration_is_left_alone(self):
3741
+ text = "<!DOCTYPE html\n<html></html>"
3742
+ self.assertEqual(fix_doctype(text, 2), (text, 0))
@@ -529,6 +529,19 @@ def _fixtures() -> dict:
529
529
  },
530
530
  "item_properties_added",
531
531
  ),
532
+ "--fix-double-colon-tags": (
533
+ {
534
+ "OEBPS/content.opf": _opf([c1], [r1]),
535
+ "OEBPS/c1.xhtml": (
536
+ '<?xml version="1.0"?><html '
537
+ 'xmlns="http://www.w3.org/1999/xhtml">'
538
+ "<head><title>t</title></head><body><pre><code><span>"
539
+ "std::vector<std::shared_ptr>&gt; data;</span>"
540
+ "</code></pre></body></html>"
541
+ ),
542
+ },
543
+ "double_colon_tags_escaped",
544
+ ),
532
545
  }
533
546
 
534
547
 
@@ -759,6 +772,12 @@ class FlagEndToEndTests(unittest.TestCase):
759
772
  self._fixes_for("--fix-item-properties")["item_properties_added"], 1
760
773
  )
761
774
 
775
+ def test_fix_double_colon_tags(self):
776
+ self.assertGreaterEqual(
777
+ self._fixes_for("--fix-double-colon-tags")["double_colon_tags_escaped"],
778
+ 1,
779
+ )
780
+
762
781
 
763
782
  if __name__ == "__main__":
764
783
  unittest.main()
@@ -55,6 +55,7 @@ DEST_TO_FIELD = {
55
55
  "fix_doctype": "doctype",
56
56
  "prune_invalid_guide_refs": "prune_guide_refs",
57
57
  "fix_item_properties": "item_properties",
58
+ "fix_double_colon_tags": "double_colon_tags",
58
59
  "strip_pagination": "strip_pagination",
59
60
  "strip_broken_tags": "strip_brokentags",
60
61
  "strip_watermarks": "strip_watermarks",
@@ -15,6 +15,7 @@ from bindery.transforms import (
15
15
  escape_bare_amp,
16
16
  escape_unknown_entities,
17
17
  fix_cdata_terminator,
18
+ fix_double_colon_tags,
18
19
  fix_duplicate_ids,
19
20
  fix_empty_body,
20
21
  fix_id_colons,
@@ -1581,3 +1582,118 @@ class TestFixDuplicateIds(unittest.TestCase):
1581
1582
 
1582
1583
  if __name__ == "__main__":
1583
1584
  unittest.main()
1585
+
1586
+
1587
+ class TestFixDoubleColonTags(unittest.TestCase):
1588
+ """--fix-double-colon-tags: an XML name can carry at most one colon, so
1589
+ a pseudo-tag whose name contains `::` is never markup -- every
1590
+ occurrence is unescaped author text and the parser dies on it with a
1591
+ fatal RSC-016 (the Book of Debugging's C++ samples, the library's last
1592
+ fatal). Escaping both ends restores the author's text; real markup is
1593
+ unreachable because the double colon lives in the name grammar."""
1594
+
1595
+ def test_escapes_the_book_of_debugging_shape(self):
1596
+ doc = (
1597
+ '<html xmlns="http://www.w3.org/1999/xhtml"><head><title>t</title>'
1598
+ "</head><body><pre><code><span>std::vector"
1599
+ "<std::shared_ptr>&gt; data;</span></code></pre></body></html>"
1600
+ )
1601
+ out, n = fix_double_colon_tags(doc)
1602
+ self.assertEqual(n, 1)
1603
+ self.assertIn("std::vector&lt;std::shared_ptr&gt;&gt; data;", out)
1604
+
1605
+ def test_closing_pseudo_tags_escape_too(self):
1606
+ out, n = fix_double_colon_tags("<p>begin <b::c> x </b::c> end</p>")
1607
+ self.assertEqual(n, 2)
1608
+ self.assertIn("&lt;b::c&gt;", out)
1609
+ self.assertIn("&lt;/b::c&gt;", out)
1610
+
1611
+ def test_real_tags_are_never_touched(self):
1612
+ doc = (
1613
+ '<html xmlns="http://www.w3.org/1999/xhtml"><head><title>t</title>'
1614
+ "</head><body><p>a:b</p><p>plain</p></body></html>"
1615
+ )
1616
+ self.assertEqual(fix_double_colon_tags(doc), (doc, 0))
1617
+
1618
+ def test_prose_comparison_never_matches(self):
1619
+ doc = (
1620
+ "<html><head><title>t</title></head><body><p>if a &lt; b</p></body></html>"
1621
+ )
1622
+ self.assertEqual(fix_double_colon_tags(doc), (doc, 0))
1623
+
1624
+ def test_nested_template_escapes_inner_first_then_outer(self):
1625
+ # `std::vector<std::string>` fully raw: the first pass escapes the
1626
+ # innermost construct, the second the outer one; the trailing `>`s
1627
+ # stay raw, which is legal text
1628
+ doc = (
1629
+ "<html><head><title>t</title></head><body><p>x"
1630
+ "<std::vector<std::string>>y</p></body></html>"
1631
+ )
1632
+ out, n = fix_double_colon_tags(doc)
1633
+ # one pass suffices: the tail crosses the nested `<` and the match
1634
+ # ends at the first raw `>`; the second trailing `>` stays raw,
1635
+ # which is legal text and renders as `>`
1636
+ self.assertEqual(n, 1)
1637
+ self.assertIn("x&lt;std::vector&lt;std::string&gt;>y", out)
1638
+ # the result carries no raw `<` from the pseudo-tags
1639
+ self.assertNotIn("<std::", out)
1640
+
1641
+ def test_triple_colon_name_escapes(self):
1642
+ out, n = fix_double_colon_tags("<p><a::b::c></p>")
1643
+ self.assertEqual(n, 1)
1644
+ self.assertIn("&lt;a::b::c&gt;", out)
1645
+
1646
+ def test_escaped_constructs_are_stable(self):
1647
+ doc = "<p>std::vector&lt;std::shared_ptr&gt;&gt; data;</p>"
1648
+ self.assertEqual(fix_double_colon_tags(doc), (doc, 0))
1649
+
1650
+
1651
+ class TestFixDoubleColonTagsBounds(unittest.TestCase):
1652
+ """The v0.62.1 review's content-level risk, closed by the bounded tail:
1653
+ a pseudo-tag whose own bracket was escaped (only the leading `<` raw)
1654
+ used to run the lazy tail to the next REAL tag's `>` and swallow prose
1655
+ plus markup into display text -- damage the gate cannot always see."""
1656
+
1657
+ def test_escaped_bracket_construct_does_not_run_away(self):
1658
+ doc = (
1659
+ "<html><head><title>t</title></head><body><p>x &lt; b::c stuff "
1660
+ "<p>real</p></body></html>"
1661
+ )
1662
+ out, n = fix_double_colon_tags(doc)
1663
+ self.assertEqual(n, 0)
1664
+ self.assertEqual(out, doc)
1665
+
1666
+ def test_tail_over_one_hundred_twenty_chars_does_not_match(self):
1667
+ filler = "x" * 130
1668
+ doc = f"<html><head><title>t</title></head><body><p><a::b {filler}>y</p></body></html>"
1669
+ self.assertEqual(fix_double_colon_tags(doc), (doc, 0))
1670
+
1671
+ def test_raw_ampersand_in_the_tail_is_escaped(self):
1672
+ out, n = fix_double_colon_tags("<p><b::c & d>x</p>")
1673
+ self.assertEqual(n, 1)
1674
+ self.assertIn("&lt;b::c &amp; d&gt;", out)
1675
+
1676
+
1677
+ class TestFixMissingTitleHeadScope(unittest.TestCase):
1678
+ """v0.62.2: the empty-title fill is head-scoped -- an empty <title>
1679
+ inside <svg> is the image's accessibility name / hover tooltip, and
1680
+ filling it with "Unknown" is a visible text change the gate cannot
1681
+ measure."""
1682
+
1683
+ def test_empty_svg_title_is_protected_when_a_head_exists(self):
1684
+ doc = (
1685
+ "<html><head><title>Real</title></head><body>"
1686
+ "<svg><title/></svg></body></html>"
1687
+ )
1688
+ self.assertEqual(fix_double_colon_tags(doc), (doc, 0))
1689
+ self.assertEqual(fix_missing_title(doc), (doc, 0))
1690
+
1691
+ def test_head_empty_title_still_fills(self):
1692
+ doc = (
1693
+ "<html><head><title/></head><body>"
1694
+ "<svg><title>name</title></svg></body></html>"
1695
+ )
1696
+ out, n = fix_missing_title(doc)
1697
+ self.assertEqual(n, 1)
1698
+ self.assertIn("<head><title>Unknown</title>", out)
1699
+ self.assertIn("<svg><title>name</title></svg>", out)
@@ -8,7 +8,7 @@ resolution-markers = [
8
8
 
9
9
  [[package]]
10
10
  name = "bindery-cli"
11
- version = "0.62.0"
11
+ version = "0.62.2"
12
12
  source = { editable = "." }
13
13
  dependencies = [
14
14
  { name = "cquarry", marker = "python_full_version >= '3.14'" },
File without changes
File without changes
File without changes
File without changes
File without changes