bindery-cli 0.57.1__tar.gz → 0.59.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 (56) hide show
  1. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/AGENTS.md +50 -7
  2. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/PKG-INFO +1 -1
  3. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/patchnotes.md +139 -0
  4. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/pyproject.toml +1 -1
  5. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/roadmap.md +7 -0
  6. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/spec.md +66 -17
  7. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/src/bindery/__init__.py +1 -1
  8. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/src/bindery/cli.py +36 -6
  9. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/src/bindery/epub.py +388 -18
  10. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/src/bindery/transforms.py +65 -22
  11. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_epub.py +632 -0
  12. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_flags_real_core.py +29 -0
  13. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_flags_wiring.py +1 -0
  14. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_spine_guard.py +5 -2
  15. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_transforms.py +62 -0
  16. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/uv.lock +1 -1
  17. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/.github/FUNDING.yml +0 -0
  18. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/.github/workflows/ci.yml +0 -0
  19. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/.github/workflows/publish.yml +0 -0
  20. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/.gitignore +0 -0
  21. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/LICENSE +0 -0
  22. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/OBSERVE-RESEARCH.md +0 -0
  23. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/README.md +0 -0
  24. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/docs/screenshots/library-sweep.png +0 -0
  25. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/logo.svg +0 -0
  26. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/plugin/__init__.py +0 -0
  27. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/project.done +0 -0
  28. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/run_tests.sh +0 -0
  29. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/scripts/FastSweep.java +0 -0
  30. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/scripts/build_plugin.py +0 -0
  31. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/scripts/fast_sweep.py +0 -0
  32. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/src/bindery/__main__.py +0 -0
  33. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/src/bindery/audit.py +0 -0
  34. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/src/bindery/library.py +0 -0
  35. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/src/bindery/observe.py +0 -0
  36. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/src/bindery/pagination.py +0 -0
  37. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/src/bindery/reserialize.py +0 -0
  38. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/src/bindery/validate.py +0 -0
  39. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/src/bindery/watermark.py +0 -0
  40. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_audit.py +0 -0
  41. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_cli.py +0 -0
  42. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_comment_hyphens.py +0 -0
  43. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_contamination.py +0 -0
  44. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_cover_tocdrift.py +0 -0
  45. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_help.py +0 -0
  46. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_library.py +0 -0
  47. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_matcher_hardening.py +0 -0
  48. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_observe.py +0 -0
  49. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_pagination.py +0 -0
  50. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_plugin.py +0 -0
  51. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_reserialize.py +0 -0
  52. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_space_renames.py +0 -0
  53. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_validate.py +0 -0
  54. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_version.py +0 -0
  55. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_watermark.py +0 -0
  56. {bindery_cli-0.57.1 → bindery_cli-0.59.0}/tests/test_xml_hardening.py +0 -0
@@ -30,13 +30,13 @@ 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-five structural
33
+ visible content. The canonical opt-in inventory lives in spec.md: twenty-six 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`,
37
37
  `--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`,
38
38
  `--prune-missing-resources`, `--declare-missing-items`, `--strip-broken-anchors`,
39
- `--encode-url-spaces`,
39
+ `--prune-dangling-ncx-targets`, `--encode-url-spaces`,
40
40
  `--fix-container`, `--fix-media-types`, `--fix-cover`,
41
41
  `--fix-comment-double-hyphen`, `--fix-svg-dup-ids`, `--fix-duplicate-ids`,
42
42
  `--fix-cdata-terminator`,
@@ -63,7 +63,25 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
63
63
  never percent-encoding (epubcheck decodes references before entry lookup,
64
64
  verified against 5.3), ambiguous renames refused per entry (`space_rename_map`),
65
65
  accepted under `no_worse` because PKG-010 sits on the warning axis the gate
66
- does not measure. `--fix-unbound-prefix` (v0.51.0, issue #9, the Calibre
66
+ does not measure. Since v0.58.0 (issue #19) the rewritten references
67
+ percent-encode `[`/`]` (raw brackets are RSC-020 "Illegal character in
68
+ path segment"; the encoded form decodes to the raw-spelled entry), and
69
+ BOTH halves rewrite only attributes inside real start tags and processing
70
+ instructions (`_START_TAG_OR_PI_RE`, comments/CDATA excluded): a book that
71
+ TEACHES HTML carries `href="..."` in display text, and the bare attribute
72
+ regex paired the phantom quote with the next real tag -- two RSC-016
73
+ parse fatals on Hacking: The Next Generation. `--strip-broken-anchors`
74
+ (v0.58.0, issue #21) also strips broken fragments from OPF guide
75
+ `<reference href>` (the guide is not a content document; its broken
76
+ fragment hid until the target's own links were fixed -- Fools Crow), and
77
+ the always-on playOrder pass re-runs after the NCX fragment strip so
78
+ collapsed navTargets cannot violate the same-target contract (Troubled
79
+ Man). The shared href resolver decodes the five predefined XML entities
80
+ and the OPF item/itemref/reference matchers accept a namespace prefix
81
+ (issue #20: `href="K&amp;C.png"` names the entry `K&C.png`, and the
82
+ `<opf:item>` blindness made the census re-declare whole manifests while
83
+ the prune deleted live declarations on the raw-ampersand D&D books).
84
+ `--fix-unbound-prefix` (v0.51.0, issue #9, the Calibre
67
85
  embed scar; element half v0.57.0, issue #22) binds a prefix the OPF
68
86
  never declares in scope inline on the element that uses it: the
69
87
  attribute half (`<dc:identifier id="ID1" ns0:scheme="calibre">`
@@ -90,7 +108,10 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
90
108
  file it meant is underdetermined); normal `gate`. `--fix-duplicate-ids`
91
109
  (issue #14) is the content-doc half of the SVG duplicate-id rename:
92
110
  same first-keeps-name rule, references resolve to the first definition
93
- and are never rewritten; normal `gate`. The same lane's RSC-001 verdict:
111
+ and are never rewritten; since v0.58.0 (issue #21) commented-out and
112
+ CDATA-hidden tags do not count (counting them renamed the REAL
113
+ definition away from its name and dangled every fragment referencing
114
+ it); normal `gate`. The same lane's RSC-001 verdict:
94
115
  95.3% of its mass is spine documents whose files exist under a
95
116
  different spelling (the spine guard correctly refuses; the mass carrier
96
117
  is `--encode-url-spaces` territory), so the prune's coverage boundary is
@@ -108,6 +129,25 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
108
129
  `--fix-media-types` (font/* blessed on both package versions, magic
109
130
  confirmed, `.eot` never touched) with the flag accepted under `no_worse`
110
131
  (its gain sits on the INFO axis).
132
+ The v0.59.0 one (issue #23, the dangling-NCX class): `--prune-dangling-ncx-targets`
133
+ removes navPoint/pageTarget/navTarget elements whose `<content src>` names a
134
+ document absent from the archive (RSC-007 at toc.ncx; the OPF never declared the
135
+ dropped file, so `--prune-missing-resources` has no item to prune and the navPoint
136
+ survived `--all` as "no applicable fixes"). Node-exact rule over a balanced
137
+ stack scanner (`strip_ncx_dangling_targets`, quote-aware possessive token regex,
138
+ navTarget legacy spelling included): a dead node whose whole subtree dies with it
139
+ drops as one span; a dead node above surviving descendants is SPLICED (tags plus
140
+ its own navLabel/dead `<content>` header go, children re-homed one level up --
141
+ dropping live navigation to repair a dead label is no repair); scheme URLs,
142
+ bare fragments, contentless nodes, and comment-hidden elements are never this
143
+ class; the token walk tracks the navMap/pageList containers too, so an
144
+ unbalanced walk (stray close, wrapper crossing a node's span) aborts AND a
145
+ prune that would empty a container refuses (the NCX wants navPoint+/pageTarget+;
146
+ an empty navMap is itself RSC-005 per epubcheck 5.3, so the gate would otherwise
147
+ apply a TOC-less NCX). When it fires, the
148
+ contract-gated playOrder pass re-runs in the same branch (the survivors' values
149
+ start gapped; the fixture went 0f/1e/0w -> 0f/0e/0w in one gate, one navPoint
150
+ pruned, 389 playOrder values re-sequenced); normal `gate`.
111
151
  They alter markup structure or fabricate minimal content. v0.14–v0.16 ran these unconditionally, which broke this rule;
112
152
  v0.17.0 restored it. `--unwrap-illegal-tags` additionally protects any illegal-tag
113
153
  name that an EPUB stylesheet styles as an element selector (`css_protected_tags`,
@@ -181,19 +221,22 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
181
221
 
182
222
  ## Layout
183
223
 
184
- - `src/bindery/transforms.py`: pure `str -> (str, int)` text transforms (including `strip_broken_tags`). Since v0.55.0 `fix_svg_dup_ids` and `fix_duplicate_ids` share `_rename_duplicate_ids` (first-keeps-name, `_2`/`_3` suffixes, references never rewritten); the SVG flag owns standalone `.svg` entries, the content-doc flag owns `.xhtml`/`.html`/`.htm`/`.xml`. Since v0.32.0: `strip_attrs_in_start_tags` anchors attribute edits on the quote-aware start-tag matcher, `_outside_protected` forwards arguments (context-carrying transforms can be decorated), `fix_id_colons` matches only the bare `id` attribute and only internal fragments (`fix_ncx_src_fragments` carries renames into the NCX), `fix_ncx_playorder` is anchored to `<navPoint>` start tags, and the css selector boundary covers namespaced and functional selector forms. HAZARD (the 0.41.0 spin): the quote-aware tag-prefix alternation (double-quoted | single-quoted | [^>]) OVERLAPS ([^>] matches quotes too), so a plain `*` re-partitions exponentially on failing candidates; every such greedy loop must carry the possessive `*+` (re 3.11+, the plugin's minimum Calibre). Since v0.42.0 the census is complete and pinned by tests/test_matcher_hardening.py: every greedy loop of this family is possessive (the three 0.41.1 rewrites plus _START_TAG_RE, _COVER_META_RE, _GUIDE_REF_RE, prune_dangling_edges' spine|item|itemref matcher, _ITEM_TAG_RE, _SPINE_ITEM_RE; possessive is byte-identical on success because the loop is always followed by a literal `>` the [^>] branch cannot consume), and the five LAZY siblings (_VOID_RE, the transforms <img> matcher, and epub's link/a/img matchers) use the disjoint catch-all `[^>"']` instead: mutually exclusive branches cannot re-partition, and an unterminated quote inside a tag now fails to match rather than pairing across markup. NEW tag matchers: quote-aware possessive for greedy loops, the disjoint catch-all for lazy ones, and the tempered-quote idiom (["'])((?:(?!\1).)*)\1 for attribute values. Since v0.37.0: `fix_ncx_playorder` strips quotes before its already-correct comparison (regex groups carry quote characters; comparing quoted values against bare numbers counted phantom fixes on every sequential NCX and rewrote single-quoted correct attributes to double quotes). Since v0.54.0 (the 2026-10-24 surgery): `fix_ncx_playorder` is CONTRACT-GATED -- it tokenizes navPoint/navTarget/pageTarget start tags plus their `<content src>` targets, returns unchanged when the NCX already satisfies epubcheck's playOrder contract (same target shares one value, distinct targets distinct values, values contiguous 1..K), and re-sequences by first-appearance target order only on a violation; the old unconditional 1..N renumbering rewrote valid TOCs into violations (211 of 579 firings gate-rejected, 17 real fixes, 347 no-ops). The same fix extends `_PROTECTED_RE` with the Calibre `/*<![CDATA[*/ ... /*]]>*/` wrapper as one protected unit (the bare CDATA alternative ends inside the closing `/*]]>`, which exposed the trailing `*/` to strip_prolog_junk's amputation: 111 phantom-fix rejections).
224
+ - `src/bindery/transforms.py`: pure `str -> (str, int)` text transforms (including `strip_broken_tags`). Since v0.55.0 `fix_svg_dup_ids` and `fix_duplicate_ids` share `_rename_duplicate_ids` (first-keeps-name, `_2`/`_3` suffixes, references never rewritten; since v0.58.0 comment/CDATA-hidden tags do not count -- counting them renamed the real definition away, issue #21); the SVG flag owns standalone `.svg` entries, the content-doc flag owns `.xhtml`/`.html`/`.htm`/`.xml`. Since v0.58.0 (issue #19) `encode_url_spaces` anchors on `_START_TAG_OR_PI_RE` (start tags plus xml-stylesheet-style processing instructions, prefix-disjoint branches, possessive loops) instead of the bare attribute regex: display text that TEACHES HTML carries `href="..."`, and the unanchored regex paired the phantom quote with the next real tag, encoding a space into the element name (two RSC-016 fatals on Hacking: The Next Generation); epub.py's `rewrite_space_renames` anchors on the same matcher (its PI branch is what keeps xml-stylesheet hrefs rewritten after the anchoring). Since v0.32.0: `strip_attrs_in_start_tags` anchors attribute edits on the quote-aware start-tag matcher, `_outside_protected` forwards arguments (context-carrying transforms can be decorated), `fix_id_colons` matches only the bare `id` attribute and only internal fragments (`fix_ncx_src_fragments` carries renames into the NCX), `fix_ncx_playorder` is anchored to `<navPoint>` start tags, and the css selector boundary covers namespaced and functional selector forms. HAZARD (the 0.41.0 spin): the quote-aware tag-prefix alternation (double-quoted | single-quoted | [^>]) OVERLAPS ([^>] matches quotes too), so a plain `*` re-partitions exponentially on failing candidates; every such greedy loop must carry the possessive `*+` (re 3.11+, the plugin's minimum Calibre). Since v0.42.0 the census is complete and pinned by tests/test_matcher_hardening.py: every greedy loop of this family is possessive (the three 0.41.1 rewrites plus _START_TAG_RE, _COVER_META_RE, _GUIDE_REF_RE, prune_dangling_edges' spine|item|itemref matcher, _ITEM_TAG_RE, _SPINE_ITEM_RE; possessive is byte-identical on success because the loop is always followed by a literal `>` the [^>] branch cannot consume), and the five LAZY siblings (_VOID_RE, the transforms <img> matcher, and epub's link/a/img matchers) use the disjoint catch-all `[^>"']` instead: mutually exclusive branches cannot re-partition, and an unterminated quote inside a tag now fails to match rather than pairing across markup. NEW tag matchers: quote-aware possessive for greedy loops, the disjoint catch-all for lazy ones, and the tempered-quote idiom (["'])((?:(?!\1).)*)\1 for attribute values. Since v0.37.0: `fix_ncx_playorder` strips quotes before its already-correct comparison (regex groups carry quote characters; comparing quoted values against bare numbers counted phantom fixes on every sequential NCX and rewrote single-quoted correct attributes to double quotes). Since v0.54.0 (the 2026-10-24 surgery): `fix_ncx_playorder` is CONTRACT-GATED -- it tokenizes navPoint/navTarget/pageTarget start tags plus their `<content src>` targets, returns unchanged when the NCX already satisfies epubcheck's playOrder contract (same target shares one value, distinct targets distinct values, values contiguous 1..K), and re-sequences by first-appearance target order only on a violation; the old unconditional 1..N renumbering rewrote valid TOCs into violations (211 of 579 firings gate-rejected, 17 real fixes, 347 no-ops). The same fix extends `_PROTECTED_RE` with the Calibre `/*<![CDATA[*/ ... /*]]>*/` wrapper as one protected unit (the bare CDATA alternative ends inside the closing `/*]]>`, which exposed the trailing `*/` to strip_prolog_junk's amputation: 111 phantom-fix rejections).
185
225
  - `src/bindery/pagination.py`: the opt-in lossy page-number strip (runhead detection, page-layer decision, block-centric removal/merge, safety nets).
186
226
  - `src/bindery/watermark.py`: the opt-in lossy watermark strip (anchored and anchorless signature removal).
187
227
  - `src/bindery/reserialize.py`: structural repair via `html5lib`.
188
228
  - `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).
189
- - `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.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).
229
+ - `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
230
+ character references before the fragment split (attribute text arrives
231
+ escaped; entries are raw; decoding first keeps the `#` inside `&#38;`
232
+ 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).
190
233
  - `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).
191
234
  - `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.
192
235
  - `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
193
236
  custom-rendered and colors itself with the CPython 3.14 argparse theme,
194
237
  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.
195
238
  - `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.
196
- - `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.
239
+ - `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.
197
240
 
198
241
  ## Conventions
199
242
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: bindery-cli
3
- Version: 0.57.1
3
+ Version: 0.59.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,144 @@
1
1
  # bindery-cli Patch Notes
2
2
 
3
+ ## v0.59.0 (2026-10-28)
4
+
5
+ ### Issue #23: the dangling NCX navPoint, pruned and re-sequenced in one gate
6
+
7
+ `--prune-dangling-ncx-targets` is the twenty-sixth structural repair. The
8
+ class: an NCX navPoint (or pageTarget) whose `<content src>` names a document
9
+ the archive never contained. epubcheck answers RSC-007 from toc.ncx, and
10
+ nothing reached it: `--prune-missing-resources` prunes manifest items whose
11
+ FILE is absent, and a producer that drops the document without declaring it
12
+ leaves no item to prune, so the navPoint survived `--all` with "no applicable
13
+ fixes" (the Splintered Harmony fixture, 0f/1e/0w). Hand removal works but
14
+ cascades: every surviving playOrder then reads as starting at 2 (391 RSC-005s
15
+ on the live book), naive renumbering splits the navPoint/pageTarget
16
+ same-target contract (79 more), and the working rescue was a second `--all`
17
+ run to let the contract-gated playOrder pass heal the survivors. The new flag
18
+ folds that whole recipe into one gate.
19
+
20
+ The rule is node-exact, over a balanced stack scanner that tracks navPoint,
21
+ the legacy navTarget spelling, and pageTarget as one family: a navPoint dies
22
+ when its OWN target document is absent from the archive. A dead node whose
23
+ whole subtree dies with it is removed as one element; a dead node above
24
+ surviving descendants is spliced (its tags, its navLabel, and its dead
25
+ `<content>` go; the children are re-homed one level up), because dropping
26
+ live navigation to repair a dead label is no repair. Scheme URLs, bare
27
+ fragments, contentless nodes, comment-hidden elements, and escaped-ampersand
28
+ srcs that resolve (the issue #20 decoder) are never this class. The token
29
+ walk tracks the navMap/pageList containers too: an unbalanced walk (a stray
30
+ close, a wrapper crossing a node's span) aborts the pass unchanged, and so
31
+ does a prune that would EMPTY a container, because the NCX requires
32
+ navPoint+/pageTarget+ and an empty navMap is itself one RSC-005 (verified
33
+ against epubcheck 5.3): without the rule, the gate would happily apply a
34
+ TOC-less NCX, and a wholly dead TOC is the manual list's finding, not a
35
+ repair. When the prune fires, the
36
+ contract-gated playOrder pass re-runs in the same branch, the fragment
37
+ strip's v0.58.0 pattern. On the fixture the one run went 0f/1e/0w to
38
+ 0f/0e/0w: one navPoint pruned, 389 playOrder values re-sequenced across
39
+ navMap and pageList, epubcheck clean, and a second probe reports no
40
+ applicable fixes.
41
+
42
+ Wiring follows the house pattern: the `RepairFlags.prune_ncx_targets` field,
43
+ the `_REPAIR_FLAG_TABLE` row (compact `--help` and `--help-repairs`), the
44
+ `_flags_from_args` mapping, `--all` enabled like every structural flag, and
45
+ the wiring test's dest-to-field pin. Tests: `TestPruneDanglingNcxTargets`
46
+ pins the node-exact rule end to end (dead leaf, splice, dead subtree,
47
+ refusals, the unbalanced abort, the container-emptying refusal, the
48
+ escaped-ampersand resolve, pageTarget and navTarget, and the resequence
49
+ through `repair_epub`), and the real-core
50
+ suite drives the flag through argv. Suite: 820 tests.
51
+
52
+ ## v0.58.0 (2026-10-26)
53
+
54
+ ### Issues #18-#21: the structural dry run's four rejects, read to the root
55
+
56
+ The 2026-10-25 whole-library structural run filed four issues and applied
57
+ nothing; every fix here was bisected on the specimens first, and the
58
+ forensics each turned up a mechanism the issue text had only half of.
59
+
60
+ **Issue #18: one root cause under all 57 "unreadable" books.** The copy
61
+ loop handed the source's own `ZipInfo` objects to `zout.writestr`, and
62
+ `writestr` stamps the info it is given with the DESTINATION offsets
63
+ (`header_offset` and the sizes land on it for the central directory).
64
+ After an entry was copied, `zin`'s own name lookup for it pointed into
65
+ the output file; the media-type peek's by-name open (v0.56.0) then read
66
+ whatever bytes sat at the drifted offset. Fifty-six books died with "Bad
67
+ magic number for file header" and one (Development as Freedom) tripped
68
+ the read-side zip-bomb guard instead ("Overlapped entries ... possible
69
+ zip bomb"): same mutation, different landing spot, which is why the
70
+ issue's proposed disposition (a dedicated rebuild path for the bomb
71
+ book) is unnecessary. The write now always gets a private `ZipInfo` (a
72
+ shallow copy, so output bytes stay identical; a fresh one on renames, as
73
+ before), the stale-container replacement too, and the peek additionally
74
+ catches `zipfile.BadZipFile` per the issue's hardening ask (it subclasses
75
+ `Exception` directly, not `OSError`): one entry with a genuinely corrupt
76
+ local header is now a skipped probe, never an unreadable book. Both new
77
+ tests fail on the pre-fix code.
78
+
79
+ **Issue #19: the renames were only half of what the references needed.**
80
+ Five of the six rejects (Magic Bites, King Beyond the Gate, Lavondyss,
81
+ Sun Sword, Infinite Jest) share one mechanism: the renamed spellings
82
+ still carry `[` and `]`, epubcheck answers RSC-020 "Illegal character in
83
+ path segment" for a raw bracket in a URL path, and every rewritten
84
+ reference re-flagged -- Magic Bites went 25 -> 37 errors with the space
85
+ fix measured as PKG-010 18 -> 0. Renamed-reference spellings now
86
+ percent-encode the brackets (`%5B`/`%5D`); epubcheck decodes before
87
+ lookup, so the encoded form resolves to the raw-spelled entry, and the
88
+ same books now go 25 -> 6, 41 -> 7, 28 -> 3, 48 -> 2 and 108 -> 22
89
+ (RSC-020 85 -> 0 on Infinite Jest). The sixth reject (Hacking: The Next
90
+ Generation) was pure corruption: the book TEACHES HTML, its display text
91
+ carries `href="..."`, and the bare attribute regex paired the phantom
92
+ quote with the next real markup quote, encoding a space into the
93
+ following start tag's element name -- two RSC-016 parse fatals, and its
94
+ seven counted "fixes" were all phantom. Both the space encoder and the
95
+ rename rewrite now anchor on real start tags and processing instructions
96
+ (comments and CDATA excluded; the PI branch is what keeps
97
+ xml-stylesheet hrefs getting fixed), and the fatals are gone with zero
98
+ phantom edits. Both new tests fail pre-fix.
99
+
100
+ **Issue #20: hrefs are XML, entry names are not.** The prune+declare
101
+ clash on the four Designers & Dragons volumes: their file names carry
102
+ raw `&` while the manifest correctly spells `&amp;`, and the href
103
+ resolver never decoded the entity, so the prune judged live declarations
104
+ absent (30 new RSC-008s alone), the census then re-declared the same
105
+ files from the raw-ampersand content references (30 OPF-074 duplicates
106
+ alone), and the two flags literally swapped the items inside one run
107
+ (net zero, by accident). `_resolve_href` now decodes the five predefined
108
+ entities and numeric character references before the fragment split
109
+ (attribute text arrives escaped; entry names are raw bytes; decoding
110
+ first is also what keeps the `#` inside `&#38;` from cutting the
111
+ target), and the OPF item/itemref/reference matchers accept
112
+ an optional namespace prefix -- the second shape, where Sony-style
113
+ `<opf:item>` packages (Roadside Picnic, Twenty Love Poems, Zhuangzi)
114
+ made the census see an empty manifest and duplicate every declaration.
115
+ All seven books now probe as clean no-ops for both flags, and the
116
+ prefix-tolerant matching fixes a latent `--fix-manifest-ids` gap on the
117
+ same packages (a prefixed item's id used to be invisible to the rename
118
+ while its spine idref was not).
119
+
120
+ **Issue #21: three small deltas, three different mechanisms.** Troubled
121
+ Man and Fools Crow both died in the NCX after the anchor pass: the
122
+ always-on playOrder pass validates the contract BEFORE the fragment
123
+ strip runs, and stripped fragments collapse distinct navTargets onto
124
+ their documents, violating the same-target-shares-one-value rule the
125
+ pass had just verified. The pass now re-runs on the final navMap (it is
126
+ contract-gated, so a still-valid NCX re-runs as a no-op). Fools Crow's
127
+ second new error was the OPF guide: its `type="toc"` reference pointed
128
+ at a filepos fragment that never existed anywhere in the book, invisible
129
+ while the target carried its own broken links and surfaced once they
130
+ were fixed; `--strip-broken-anchors` now gives guide references the same
131
+ document-precision fallback the NCX half has (`guide_fragments_stripped`).
132
+ Fools Crow repairs 1e -> 0e, Troubled Man 2e -> 1e. Seven Principles was
133
+ the duplicate-id rename counting a commented-out copy of an id as a
134
+ second definition: epubcheck sees one definition, so renaming the REAL
135
+ one (the only one a reader resolves) dangled the index's cross-document
136
+ fragment. The shared rename now skips comment/CDATA-hidden tags
137
+ entirely; the book's phantom rename is gone, its 11 errors hold, and the
138
+ 38 CSS-007 font normalizations still fire.
139
+
140
+ Suite: 809 tests.
141
+
3
142
  ## v0.57.1 (2026-10-25)
4
143
 
5
144
  ### The prefixed dtb:uid sync: the issue #22 specimen's last finding
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "bindery-cli"
7
- version = "0.57.1"
7
+ version = "0.59.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 = [
@@ -51,6 +51,8 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
51
51
  | 0.55 | The issue-batch release (issues #11-#16, the 2026-10-24 surgery's follow-ups): `--strip-epub3-attrs` extended with `role` + `aria-hidden` (the census killed the DOCTYPE-gate concern: epubcheck is profile-driven; #11), `--fix-duplicate-ids` for content docs (#14), `--declare-missing-items` for RSC-008 (#16, with the prune's RSC-001 boundary documented), the size-scaled epubcheck timeout with one retry and the distinct `OracleTimeout` (#15), observe schema v2 (`codes.messages` rename, true `codes.occurrences`, the `counting` block, v1 `--against` accepted; #13), the #12 content-model ruling (measured, not repaired: the wrap changes layout), and the #17 census lanes (RSC-012/OPF-029 dispositions on existing flags; OPF-030/CSS-007/RSC-004 recorded leave-measured with recipes) | v0.55.0 |
52
52
  | 0.56 | The boxed recipes, built same-day on the follow-up call: `--fix-unique-identifier` (the OPF-030 recipe: wire the package's named id onto the first dc:identifier, refuses every ambiguous shape, and predicts the post-wiring uid so the NCX sync the broken wiring was masking fires in the same run -- eagle 2e -> 1e accept) and the CSS-007 font half inside `--fix-media-types` (font/* blessed on both package versions, magic confirmed, .eot never touched; accepted under no_worse because the gain sits on the INFO axis -- Brave New World 8 fonts normalized, CSS-007 cleared) | v0.56.0 |
53
53
  | 0.57 | The embed scar's element half and the end of the silent equal (issue #22): `--fix-unbound-prefix` now binds an unbound ELEMENT prefix inline (the 9.7.0 writer self-declares xmlns:dc on every dc: element but one; rule 2 for a literal dc: element resolves to the DC namespace itself; Hackers 1f/1e -> 0f/1e with both binds in one run, and the half-repaired intermediate that read equal now repairs), and the masked-axis reclassification generalizes from the v0.51.0 NCX sync to every fired fix: a gate noop on a book that started and stayed fatal reads partial (the manual list) instead of a silent equal; the specimen's residual ncx:-prefixed dtb:uid gap shipped as the v0.57.1 patch (both matchers read a prefixed `<ncx:meta>` carrier; Hackers fully clean 0f/0e/0w) | v0.57.0-v0.57.1 |
54
+ | 0.58 | The structural dry run's four rejects (issues #18-#21), each bisected to the root on its specimens: the private-ZipInfo write contract (issue #18: writestr stamps the info it is handed with the DESTINATION offsets, one shared info repointed zin's own lookups into the output file -- all 57 "unreadable" books, the "possible zip bomb" included, were this one bug; the peek also catches BadZipFile per the issue), bracket-encoded renamed references plus the start-tag/PI anchor on both reference rewriters (issue #19: raw brackets are RSC-020 path-illegal -- IJ 108e -> 22e -- and the unanchored regex corrupted display text that teaches HTML -- Hacking's two RSC-016 fatals), the entity-decoding href resolver and prefix-tolerant OPF matchers (issue #20: `&amp;` hrefs vs raw-`&` entries made prune and declare swap the same items on the D&D four, and `<opf:item>` blindness duplicated whole manifests on the Sony three), and the three #21 mechanisms (guide-fragment strip, the post-anchor playOrder re-run, the comment-blind duplicate-id rename) | v0.58.0 |
55
+ | 0.59 | The dangling-NCX prune (issue #23): `--prune-dangling-ncx-targets` removes navPoint/pageTarget elements whose `<content src>` names a document the archive never contained (RSC-007 the manifest prune cannot reach: no item exists for a file the OPF never declared), node-exact over a balanced stack scanner (dead subtree drops as one span, dead parent spliced above live children, scheme/bare-fragment/comment-hidden/contentless refused, unbalanced walk aborts), with the contract-gated playOrder pass re-run in the same branch -- the hand-surgery-plus-second-run rescue is one gate (fixture 0f/1e/0w -> 0f/0e/0w: one navPoint pruned, 389 playOrder values re-sequenced) | v0.59.0 |
54
56
 
55
57
  ## Open work
56
58
 
@@ -62,6 +64,11 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
62
64
  gate refuses a book that is otherwise repaired. Needs the same
63
65
  entry-and-reference coordination as the space renames, with the
64
66
  decode-before-lookup epubcheck rule verified per character class.
67
+ *(Narrowed v0.58.0: renamed references now percent-encode `[`/`]`
68
+ (issue #19), so a book whose bracket-named entries carry spaces
69
+ repairs cleanly. The no-rename shape remains: entries with brackets
70
+ but no spaces never enter the rename map, and the flag stays a
71
+ no-op on such books.)*
65
72
  - [ ] **Obfuscation-aware encryption.xml repair**: prune stale obfuscation entries
66
73
  when font magic bytes prove the fonts are decrypted in place; drop
67
74
  encryption.xml when only obfuscation entries remain and fonts verify. NEVER
@@ -13,12 +13,12 @@ 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-five
16
+ The deliberate exceptions to "semantics-preserving" come in opt-in groups. The twenty-six
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`, `--declare-missing-items`, `--strip-broken-anchors`,
21
- `--encode-url-spaces`,
21
+ `--prune-dangling-ncx-targets`, `--encode-url-spaces`,
22
22
  `--fix-container`, `--fix-media-types`, `--fix-cover`, `--fix-comment-double-hyphen`,
23
23
  `--fix-svg-dup-ids`, `--fix-duplicate-ids`, `--fix-cdata-terminator`,
24
24
  `--fix-misnested-inline`,
@@ -147,7 +147,7 @@ byte-for-byte. The normal gate applies.
147
147
 
148
148
  ### Opt-in: structural repairs
149
149
 
150
- Twenty-five repairs go past well-formedness and therefore require their own flag; none is ever
150
+ Twenty-six repairs go past well-formedness and therefore require their own flag; none is ever
151
151
  part of the default pipeline:
152
152
 
153
153
  - **`--fix-empty-body`**: `&nbsp;` inside a strictly empty `<body></body>` ("body
@@ -207,8 +207,14 @@ every EPUB3 book in an `--all` sweep taking exactly that damage).
207
207
  alt text when they carry one, dropped otherwise), and orphaned non-spine OPF manifest
208
208
  `<item>` declarations. Spine documents are never pruned: a missing spine document is
209
209
  a damaged fragment for the audit's spine-integrity check, never a silent drop. The
210
- manifest existence check resolves the href the way the resolver does (unquoted,
211
- normalized) and compares it against the layout the OPF text is written in: when
210
+ shared href resolver (v0.58.0, issue #20) decodes the five predefined XML entities
211
+ and numeric character references before the fragment split (an attribute value arrives escaped: `href="K&amp;C.png"` names
212
+ the entry `K&C.png`, and reading the escaped spelling as a path pruned live
213
+ declarations on the raw-ampersand books) and the OPF matchers accept a namespace
214
+ prefix (`<opf:item>` declares exactly what `<item>` does; a prefix-blind census
215
+ re-declared whole manifests). The manifest existence check resolves the href the way
216
+ the resolver does (unquoted, normalized) and compares it against the layout the OPF
217
+ text is written in: when
212
218
  `--encode-url-spaces` is renaming entries, the prune runs ahead of the reference
213
219
  rewrite and reads pre-rename hrefs, so it checks against the pre-rename archive
214
220
  (a raw-space href judged against renamed spellings is how live spine documents came
@@ -237,14 +243,45 @@ every EPUB3 book in an `--all` sweep taking exactly that damage).
237
243
  - **`--strip-broken-anchors`**: strip `href` attributes that cannot resolve, keeping
238
244
  the anchor text byte-for-byte. A `#fragment` the target document does not define
239
245
  (RSC-020 "fragment identifier not defined", RSC-012 "points to the wrong element") is
240
- removed from the anchor; NCX `<content src="doc#frag"/>` falls back to the document
241
- target, keeping chapter navigation at document precision: the fragment is never
242
- re-pointed at a guessed sibling document, because a drifted id (Mobipocket `filepos`
243
- anchors after a converter re-split) may exist nowhere. A target wholly absent from
244
- the archive is left for the spine-integrity report. href values carrying a scheme no
245
- reader resolves (`kindle:embed:`, `file:`, ...) are stripped under the same flag; the
246
- resolvable set is fixed (`http`, `https`, `mailto`) and extends only with a named
247
- finding.
246
+ removed from the anchor; NCX `<content src="doc#frag"/>` and OPF guide
247
+ `<reference href="doc#frag">` fall back to the document target, keeping navigation at
248
+ document precision: the fragment is never re-pointed at a guessed sibling document,
249
+ because a drifted id (Mobipocket `filepos` anchors after a converter re-split) may
250
+ exist nowhere. The guide half (v0.58.0) exists because the guide is not a content
251
+ document: its broken fragment hid while the target carried its own broken links and
252
+ surfaced only once the pass fixed them (issue #21, Fools Crow). When the NCX
253
+ fragments strip, the always-on playOrder pass re-runs on the final navMap: distinct
254
+ fragments that collapsed onto one document would otherwise violate the
255
+ same-target-shares-one-value contract the pass had just validated (issue #21,
256
+ Troubled Man). A target wholly absent from the archive is left for the
257
+ spine-integrity report. href values carrying a scheme no reader resolves
258
+ (`kindle:embed:`, `file:`, ...) are stripped under the same flag; the resolvable set
259
+ is fixed (`http`, `https`, `mailto`) and extends only with a named finding.
260
+ - **`--prune-dangling-ncx-targets`** (v0.59.0, issue #23): remove NCX
261
+ `navPoint`/`pageTarget` elements whose `<content src>` names a document the archive
262
+ does not contain (RSC-007 raised from toc.ncx). This is the class the prune flag
263
+ cannot reach (`--prune-missing-resources` prunes manifest items whose FILE is
264
+ absent; a producer that drops the document without declaring it leaves no item and
265
+ the navPoint survived `--all` as "no applicable fixes") and the class hand removal
266
+ breaks (every surviving playOrder reads as starting at 2, and naive renumbering
267
+ splits the navPoint/pageTarget same-target contract -- the live case ended at
268
+ 391 RSC-005s before the rescue). The rule is node-exact: a navPoint dies when its
269
+ OWN target document is absent; a dead node whose whole subtree dies with it is
270
+ removed as one element, and a dead node above surviving descendants is spliced (its
271
+ tags, label, and dead `<content>` go; the children are re-homed one level up),
272
+ because dropping live navigation to repair a dead label is no repair. Scheme URLs,
273
+ bare fragments, comment-hidden elements, and contentless nodes are never touched,
274
+ and the token walk tracks the navMap/pageList containers: an unbalanced walk (a
275
+ stray close, a wrapper crossing a node's span) aborts the pass unchanged, and so
276
+ does a prune that would EMPTY a container -- the NCX requires navPoint+/pageTarget+
277
+ and trading a wholly dead TOC for no TOC is the manual list's call (an empty navMap
278
+ is itself one RSC-005, verified against epubcheck 5.3, so the gate would happily
279
+ apply the amputation). When the prune fires, the
280
+ always-on playOrder pass re-runs on the final navMap (the same contract-gated
281
+ re-sequencing the fragment strip uses), so the rescue that took hand surgery plus a
282
+ second `--all` run is one gate here. The live specimen went 0f/1e/0w to 0f/0e/0w in
283
+ one run (one navPoint pruned, 389 playOrder values re-sequenced across navMap and
284
+ pageList, epubcheck clean).
248
285
  - **`--encode-url-spaces`**: repairs raw-space URLs two ways. The reference half
249
286
  percent-encodes raw spaces in `src`/`href` attribute values across the package
250
287
  (OPF manifest, NCX `content src`, content documents): a URL with a literal space is
@@ -257,8 +294,16 @@ every EPUB3 book in an `--all` sweep taking exactly that damage).
257
294
  against epubcheck 5.3). Ambiguous renames (a target that already exists, two names
258
295
  converging, a duplicated entry name) are refused per entry, and a book with any
259
296
  non-UTF-8 document refuses all of its renames (those entries pass through
260
- byte-for-byte with no chance to rewrite their references). Scope stays fixed to the
261
- space character: extend only with a named epubcheck finding.
297
+ byte-for-byte with no chance to rewrite their references). '[' and ']' in a renamed
298
+ spelling are percent-encoded in the rewritten reference (v0.58.0, issue #19): a raw
299
+ bracket is not a legal URL character (RSC-020 "Illegal character in path segment"),
300
+ and epubcheck decodes before lookup, so the encoded form resolves to the raw-spelled
301
+ entry. Both halves rewrite only attributes inside real start tags and processing
302
+ instructions, never comments, CDATA, or text: a book that teaches HTML carries
303
+ `href="a b.htm"` in its display text, and a bare attribute regex pairs the phantom
304
+ quote with the next real markup quote, corrupting that tag (issue #19, two RSC-016
305
+ parse fatals on a web-exploitation handbook). Scope stays fixed to the space
306
+ character: extend only with a named epubcheck finding.
262
307
 
263
308
  - **`--fix-container`**: generate `META-INF/container.xml` at the located OPF when the
264
309
  container is missing, unparseable, or names a file the archive does not contain. This is the
@@ -326,7 +371,11 @@ leftovers whose failing OPF is a stale non-rootfile are unreachable by construct
326
371
  anyway, and first-match is what readers actually did (the rule the SVG fix
327
372
  proved). The later duplicates gain `_2`, `_3`, ... and lose whatever invalid
328
373
  double-styling the second definition carried; the book keeps the styling it could
329
- render deterministically.
374
+ render deterministically. Commented-out and CDATA-hidden tags do not count
375
+ (v0.58.0, issue #21): they are invisible to epubcheck's parser and to every reader,
376
+ and counting them renamed the REAL definition away from its name, dangling every
377
+ fragment that referenced it (an index link to an id present once in markup and once
378
+ in a comment).
330
379
  - **`--fix-cdata-terminator`**: complete a truncated CDATA-terminator comment in an
331
380
  inline `<style>` block: `/*]]>` becomes `/*]]>*/` (a comment-wrapped CDATA block
332
381
  whose closing `*/` the converter dropped; epubcheck's CSS parser reads the dangling
@@ -382,7 +431,7 @@ leftovers whose failing OPF is a stale non-rootfile are unreachable by construct
382
431
  byte-identical. Runs on the OPF only: content documents have the
383
432
  invalid-attribute drop (`--strip-bad-attrs`) for the same defect class.
384
433
 
385
- Twenty-three of the twenty-five are evaluated by the normal `gate`: unlike the lossy strips,
434
+ Twenty-three of the twenty-six are evaluated by the normal `gate`: unlike the lossy strips,
386
435
  their benefit is visible to epubcheck (they clear errors), so a run with no measurable
387
436
  improvement is a noop and nothing is applied. The three exceptions are `--fix-cover`, `--encode-url-spaces`, and
388
437
  `--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.57.1"
14
+ VERSION = "0.59.0"
15
15
  __version__ = VERSION
16
16
 
17
17
  from .epub import RepairReport, repair_epub # noqa: E402
@@ -95,6 +95,7 @@ def _flags_from_args(args: argparse.Namespace) -> RepairFlags:
95
95
  prune_missing=args.prune_missing_resources or all_,
96
96
  declare_missing=args.declare_missing_items or all_,
97
97
  strip_anchors=args.strip_broken_anchors or all_,
98
+ prune_ncx_targets=args.prune_dangling_ncx_targets or all_,
98
99
  url_spaces=args.encode_url_spaces or all_,
99
100
  fix_container=args.fix_container or all_,
100
101
  fix_media_types=args.fix_media_types or all_,
@@ -1793,9 +1794,28 @@ _REPAIR_FLAG_TABLE: dict[str, list[tuple[str, str, str]]] = {
1793
1794
  "strip hrefs that cannot resolve; anchor text always preserved",
1794
1795
  "strip href attributes that cannot resolve, keeping the anchor text "
1795
1796
  "byte-for-byte: a #fragment the target document does not define "
1796
- "(RSC-020/RSC-012; NCX navTargets keep the document target, so "
1797
- "chapter navigation survives) and unresolvable URI schemes "
1798
- "(kindle:, file:).",
1797
+ "(RSC-020/RSC-012; NCX navTargets and OPF guide references keep the "
1798
+ "document target, so navigation survives) and unresolvable URI "
1799
+ "schemes (kindle:, file:). When the NCX fragments strip, the "
1800
+ "always-on playOrder pass re-runs on the final navMap so collapsing "
1801
+ "two fragments onto one document cannot leave the same-target-"
1802
+ "shares-one-value contract violated.",
1803
+ ),
1804
+ (
1805
+ "prune_dangling_ncx_targets",
1806
+ "remove NCX navPoints/pageTargets whose content src is absent (RSC-007)",
1807
+ "remove NCX navPoint/pageTarget elements whose <content src> names a "
1808
+ "document the archive does not contain (RSC-007; issue #23) -- the "
1809
+ "class --prune-missing-resources cannot reach, because the OPF never "
1810
+ "declared the dropped file, and whose hand removal breaks the "
1811
+ "playOrder contract (every survivor's value reads as starting at 2). "
1812
+ "A dead navPoint whose whole subtree dies with it is removed as one "
1813
+ "element; a dead navPoint above surviving descendants is spliced: "
1814
+ "its tags go and the children are re-homed one level up, because "
1815
+ "dropping live navigation to repair a dead label is no repair. "
1816
+ "When the prune fires, the always-on playOrder pass re-runs on the "
1817
+ "final navMap, so the rescue that took hand surgery plus a second "
1818
+ "--all run is one gate here.",
1799
1819
  ),
1800
1820
  (
1801
1821
  "encode_url_spaces",
@@ -1805,8 +1825,14 @@ _REPAIR_FLAG_TABLE: dict[str, list[tuple[str, str, str]]] = {
1805
1825
  "not a valid URL, RSC-020), and rename the archive entries whose "
1806
1826
  "names carry raw spaces to their underscore spellings, rewriting "
1807
1827
  "every reference to them (underscore, never percent-encoding: "
1808
- "epubcheck decodes references before entry lookup). Accepted under "
1809
- "the no-worse bar: the rename half's gain sits on the warning axis.",
1828
+ "epubcheck decodes references before entry lookup; '[' and ']' in "
1829
+ "a renamed spelling are percent-encoded in the rewritten reference, "
1830
+ "since epubcheck rejects them raw in a URL path). Both halves "
1831
+ "rewrite only attributes inside real start tags and processing "
1832
+ "instructions: a book that displays HTML in its prose carries "
1833
+ 'href="..." in its text, and a bare attribute regex corrupts the '
1834
+ "next real tag. Accepted under the no-worse bar: the rename half's "
1835
+ "gain sits on the warning axis.",
1810
1836
  ),
1811
1837
  (
1812
1838
  "fix_svg_dup_ids",
@@ -1830,7 +1856,11 @@ _REPAIR_FLAG_TABLE: dict[str, list[tuple[str, str, str]]] = {
1830
1856
  "its name, later ones gain _2/_3, and no reference is rewritten "
1831
1857
  "because href='#x' anchors, CSS '#x' selectors, and cross-document "
1832
1858
  "fragment references all resolve to the first definition exactly "
1833
- "as readers resolved them before. The later duplicates lose "
1859
+ "as readers resolved them before. Commented-out and CDATA-hidden "
1860
+ "tags do not count as duplicates: they are invisible to epubcheck "
1861
+ "and to every reader, and counting them renamed the real "
1862
+ "definition away from its name (issue #21, Seven Principles). "
1863
+ "The later duplicates lose "
1834
1864
  "whatever invalid double-styling the second definition carried.",
1835
1865
  ),
1836
1866
  ],