bindery-cli 0.62.2__tar.gz → 0.63.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.62.2 → bindery_cli-0.63.0}/AGENTS.md +7 -5
  2. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/PKG-INFO +4 -1
  3. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/README.md +3 -0
  4. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/patchnotes.md +50 -0
  5. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/pyproject.toml +1 -1
  6. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/roadmap.md +1 -0
  7. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/spec.md +41 -9
  8. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/src/bindery/__init__.py +1 -1
  9. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/src/bindery/audit.py +55 -0
  10. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/src/bindery/cli.py +33 -0
  11. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/src/bindery/epub.py +139 -43
  12. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/src/bindery/transforms.py +121 -8
  13. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_contamination.py +42 -1
  14. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_epub.py +206 -140
  15. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_flags_wiring.py +2 -0
  16. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_transforms.py +33 -0
  17. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/uv.lock +1 -1
  18. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/.github/FUNDING.yml +0 -0
  19. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/.github/workflows/ci.yml +0 -0
  20. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/.github/workflows/publish.yml +0 -0
  21. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/.gitignore +0 -0
  22. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/LICENSE +0 -0
  23. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/OBSERVE-RESEARCH.md +0 -0
  24. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/docs/screenshots/library-sweep.png +0 -0
  25. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/logo.svg +0 -0
  26. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/plugin/__init__.py +0 -0
  27. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/project.done +0 -0
  28. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/run_tests.sh +0 -0
  29. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/scripts/FastSweep.java +0 -0
  30. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/scripts/build_plugin.py +0 -0
  31. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/scripts/fast_sweep.py +0 -0
  32. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/src/bindery/__main__.py +0 -0
  33. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/src/bindery/library.py +0 -0
  34. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/src/bindery/observe.py +0 -0
  35. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/src/bindery/pagination.py +0 -0
  36. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/src/bindery/reserialize.py +0 -0
  37. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/src/bindery/validate.py +0 -0
  38. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/src/bindery/watermark.py +0 -0
  39. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_audit.py +0 -0
  40. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_cli.py +0 -0
  41. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_comment_hyphens.py +0 -0
  42. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_cover_tocdrift.py +0 -0
  43. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_flags_real_core.py +0 -0
  44. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_help.py +0 -0
  45. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_library.py +0 -0
  46. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_matcher_hardening.py +0 -0
  47. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_observe.py +0 -0
  48. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_pagination.py +0 -0
  49. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_plugin.py +0 -0
  50. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_reserialize.py +0 -0
  51. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_space_renames.py +0 -0
  52. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_spine_guard.py +0 -0
  53. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_validate.py +0 -0
  54. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_version.py +0 -0
  55. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_watermark.py +0 -0
  56. {bindery_cli-0.62.2 → bindery_cli-0.63.0}/tests/test_xml_hardening.py +0 -0
@@ -30,11 +30,12 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
30
30
  `xmlns`, bare `&`, named entities, void self-closing), the NCX pipeline, and the
31
31
  mimetype fix (added/normalized/first-stored, epub.py's archive rewrite); every core
32
32
  fix must render identically to the author's intent: never add, remove, or reorder
33
- visible content. The canonical opt-in inventory lives in spec.md: thirty structural
33
+ visible content. The canonical opt-in inventory lives in spec.md: thirty-two structural
34
34
  repairs, four lossy strips, five safe opt-ins, plus `--reserialize` (the
35
- five v0.62.x flags -- `--fix-package-version`, `--fix-doctype`,
35
+ seven v0.62.x/v0.63.0 flags -- `--fix-package-version`, `--fix-doctype`,
36
36
  `--prune-invalid-guide-refs`, `--fix-item-properties`,
37
- `--fix-double-colon-tags` -- are in both inventories since v0.62.0/0.62.1).
37
+ `--fix-double-colon-tags`, `--strip-presentational-attrs`,
38
+ `--encode-ref-brackets` -- are in both inventories since v0.62.0+).
38
39
  * **Structural repairs** (`--fix-empty-body`, `--fix-missing-title`, `--fix-id-colons`,
39
40
  `--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
40
41
  `--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`,
@@ -45,7 +46,8 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
45
46
  `--fix-cdata-terminator`,
46
47
  `--fix-misnested-inline`, `--fix-stray-close`, `--fix-unterminated-attr`,
47
48
  `--fix-unbound-prefix`, `--fix-package-version`, `--fix-doctype`,
48
- `--prune-invalid-guide-refs`, `--fix-item-properties`;
49
+ `--prune-invalid-guide-refs`, `--fix-item-properties`,
50
+ `--strip-presentational-attrs`, `--encode-ref-brackets`;
49
51
  transforms.py, threaded through epub.py). The v0.47.0 five (the 2026-10-06
50
52
  issue batch): `--fix-svg-dup-ids` renames duplicate glyph ids inside
51
53
  standalone `.svg` entries (first keeps its name, references resolve to the
@@ -230,7 +232,7 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
230
232
  - `src/bindery/pagination.py`: the opt-in lossy page-number strip (runhead detection, page-layer decision, block-centric removal/merge, safety nets).
231
233
  - `src/bindery/watermark.py`: the opt-in lossy watermark strip (anchored and anchorless signature removal).
232
234
  - `src/bindery/reserialize.py`: structural repair via `html5lib`.
233
- - `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).
235
+ - `src/bindery/audit.py`: read-only body-text audits (`content`, `pagenumbers`, `emptytext`, `ocr`, `monolithic` since v0.21.0 with `--max-doc-chars N`, and `completeness` since v0.36.0, `shell` since v0.63.0) behind the `audit` subcommand (v0.15.0). Since v0.18.0 library mode resolves EPUB paths through `cquarry.get_format_path()` and can apply a tag to flagged books via `cquarry.write.WritableCalibreDB` (only with explicit `--tag`; the only sanctioned write path). Since v0.19.0 `audit --id BOOK_ID` audits a single library book through cquarry's single-entity `get_book()` fetch (no library-wide cache; supports `--tag`; incompatible with the directory argument; comma lists since v0.23.0). Since v0.22.0 every archive entry is fully read (CRC + decompression) before analysis (a damaged entry reports its own CORRUPT verdict instead of feeding emptytext) and manifest/NCX references to absent files classify as `convention` (bloated ToC, consecutive span) or `fragment` (broken span). Hazard: the scan loop reuses `tag` as its per-book display column, so the `--tag` argument is captured as `audit_tag` at function entry; do not collapse them again. Since v0.29.0 `audit --json FILE` writes per-file analyzer verdicts in the `library --json` shape (directory, library, and single-book modes; with `--id`, exactly one id; emptytext omitted from a record when the archive verdict owns the body-text story). Since v0.44.0 two more advisory analyzers ride the single pass: `cover` (the EPUB3 `properties~="cover-image"` slice of the ruled hybrid: dangling EPUB2 meta, EPUB3 declaration, cover-file presence) and `tocdrift` (the NCX navMap vs EPUB3 nav toc structural diff, fragments included; audit-only, ToC synthesis out of charter permanently); the loader now exposes the parsed OPF, the NCX text, and the nav HTML on `Book`. Since v0.50.0 a ninth analyzer, `contamination` (issue #8, the judge-and-import class, advisory by contract like completeness/cover/tocdrift, never moves the exit code): foreign-title template stamps (head `<title>` repeats or a volume/book marker with named words in front of it, judged against the OPF's own title/creator/publisher/series with a marker-stripped comparison; a part label whose marker leads never flags), fan-bundle ad signatures (jnovels, kokoro connect, zerobooks, a light-novel plug), and review-paste fingerprints (strong flags alone, weak needs corroboration) in the first five content docs; its corpus is spine PLUS `Book.extra_docs` (the archive's non-spine html, retained by the loader in archive order under a 64 MiB cap, because a broken manifest can leave the junk entirely off the spine: Hothouse). Since v0.50.0 `run_directory`/`run_single` dispatch analyzers through `_dir_dispatch` (one entry per ALL key; the old if/elif chain's `else` ran ocr for cover/tocdrift in those modes since v0.44.0) and `tests/test_contamination.py` pins the map's key set to ALL. Since v0.36.0 the completeness analyzer (Phase 15) reports the phase-1 spot-check per book: spine/prose-doc counts (prose = >= 400 visible chars), first/middle/last prose-doc opening/closing excerpts, trailing-ToC classification (`_trailing_toc`: short link lines dominate, no paragraph-length blocks), and the unreadable fraction. It is ADVISORY by contract (problem always False; ADVISORY on a trailing ToC or unreadable fraction >= 10%), never moves the exit code, and is skipped like emptytext when the archive verdict owns the book. Since v0.38.0 the archive verdict distinguishes font obfuscation from DRM (`OBFUSCATION_ALGOS`: IDPF 2008/embedding + both Adobe URIs; readable obfuscated entries are the benign OBFUSCATED advisory, an unreadable one is CORRUPT, and only non-obfuscation algorithms give ENCRYPTED). Since v0.43.0 untrusted metadata XML is parsed through `_safe_xml_parse` (DOCTYPE/ENTITY declarations refused before xml.etree sees them; the stdlib shape of defusedxml's entity protection) and single entries above `_MAX_ENTRY_BYTES` (32 MB) are refused before decompression; a refused metadata file returns the shell book. Since v0.40.0 the vir-tui console renderer loads through the module-level `_LazyUI` proxy (a plain `import vir_tui as ui` at module level would make 3.12/3.13 installs unimportable now that the stack is marker-gated; LOAD_GLOBAL never consults module `__getattr__`, so a proxy object is the lazy shape that works).
234
236
  - `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
235
237
  character references before the fragment split (attribute text arrives
236
238
  escaped; entries are raw; decoding first keeps the `#` inside `&#38;`
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: bindery-cli
3
- Version: 0.62.2
3
+ Version: 0.63.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
@@ -88,6 +88,9 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
88
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
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.
90
90
 
91
+ - **`--strip-presentational-attrs`**: strips the deprecated presentational hints the XHTML 1.1 DTD rejects wherever they appear (`align`, `valign`, `border`, `bgcolor`, `vspace`, `hspace`, `compact`; body's `link`/`vlink`/`alink`/`text`/`background`; `type` on list elements; Amazon `data-AmznRemoved` junk). Honest caveat: these are presentational hints, and readers that honor them render differently after the strip.
92
+ - **`--encode-ref-brackets`**: percent-encodes raw `[`/`]` in the path portion of internal references whose archive target exists with the raw brackets (RSC-020). Fragments, queries, entry names, and unresolvable/external references stay as written. Runs on content documents, the OPF, the NCX, and stylesheet `url()` tokens.
93
+ - **`--fix-id-colons`** also renames any content-document `id` that cannot be an XML NCName (digit-led scraped ids, apostrophe-bearing calibre ids) since v0.63.0, syncing internal fragments with the same `id_` scheme as the manifest half.
91
94
 
92
95
  Four opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
93
96
 
@@ -61,6 +61,9 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
61
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
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.
63
63
 
64
+ - **`--strip-presentational-attrs`**: strips the deprecated presentational hints the XHTML 1.1 DTD rejects wherever they appear (`align`, `valign`, `border`, `bgcolor`, `vspace`, `hspace`, `compact`; body's `link`/`vlink`/`alink`/`text`/`background`; `type` on list elements; Amazon `data-AmznRemoved` junk). Honest caveat: these are presentational hints, and readers that honor them render differently after the strip.
65
+ - **`--encode-ref-brackets`**: percent-encodes raw `[`/`]` in the path portion of internal references whose archive target exists with the raw brackets (RSC-020). Fragments, queries, entry names, and unresolvable/external references stay as written. Runs on content documents, the OPF, the NCX, and stylesheet `url()` tokens.
66
+ - **`--fix-id-colons`** also renames any content-document `id` that cannot be an XML NCName (digit-led scraped ids, apostrophe-bearing calibre ids) since v0.63.0, syncing internal fragments with the same `id_` scheme as the manifest half.
64
67
 
65
68
  Four opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
66
69
 
@@ -1,5 +1,55 @@
1
1
  # bindery-cli Patch Notes
2
2
 
3
+ ## v0.63.0 (2026-11-04)
4
+
5
+ ### The harvest census: two new flags, the id scope, and the shell detector
6
+
7
+ The 2026-11-04 dig asked the honest question about the remaining 14,109
8
+ error mass, and the answer was: not entirely the floor. A stratified
9
+ family census over the RSC-005 carriers plus live diagnosis of the
10
+ RSC-001/RSC-020 populations surfaced three repairable lanes, built here
11
+ with the specimen-first discipline:
12
+
13
+ - **`--strip-presentational-attrs`** (the census's largest attribute
14
+ family): strips the deprecated presentational hints the XHTML 1.1 DTD
15
+ rejects wherever they appear -- `align`, `valign`, `border`, `bgcolor`,
16
+ `vspace`, `hspace`, `compact`; body's `link`/`vlink`/`alink`/`text`/
17
+ `background` (body-scoped; `link` on anything but `<body>` survives);
18
+ `type` on list elements (`style`/`link`/`script` keep theirs); the
19
+ Amazon `data-AmznRemoved` scraper junk. HONEST CAVEAT (Brandon-approved
20
+ 2026-11-04): these are presentational hints, and readers that honor
21
+ them render differently after the strip.
22
+ - **`--encode-ref-brackets`** (RSC-020's 59-book bracket lane, 1,439
23
+ messages): percent-encodes raw `[`/`]` in the PATH portion of internal
24
+ references whose target exists -- the issue #19 mechanism
25
+ (`encode-url-spaces` only does it while renaming space-bearing entries,
26
+ so brackets without spaces were uncovered). Fragments and queries stay
27
+ raw, entry names stay raw, external and unresolvable references stay as
28
+ written; runs on content documents, the OPF, the NCX, and stylesheet
29
+ `url()` tokens.
30
+ - **`--fix-id-colons` broadened**: the predicate goes from colon-bearing
31
+ to every value `_is_invalid_ncname` rejects -- digit-led scraped ids
32
+ (`<body id="0-25c121ec...">`, the census's 72-location family),
33
+ apostrophe-bearing calibre ids (whose content-doc half could never hold
34
+ the apostrophe: the value charset `[^"']+` was the issue #3 blind spot
35
+ again; the matcher is the tempered pattern now). The rename base is the
36
+ manifest scheme's (`id_` + sanitized), fragments sync, and the NCX half
37
+ (`fix_ncx_src_fragments`) broadens identically.
38
+ - **The audit battery gains the `shell` analyzer** (the Wandering Inn
39
+ detector, advisory by contract): the fraction of spine positions whose
40
+ files the archive never carried -- 738/752 and 736/752 on the two
41
+ shells -- at or over 50% reads SHELL: re-source, never repair. The
42
+ manual handling of the two shells (Brandon re-sources; the spine guard
43
+ was CORRECT to refuse) is documented in OBSERVE-RESEARCH.md and the
44
+ report.
45
+
46
+ Also moved: the XML NCName check and sanitize scheme now live in
47
+ transforms.py (the vendored base), shared by the manifest half and the
48
+ broadened content-doc half; `_sanitize_ncname` stays prefix-free with the
49
+ prefix in the callers, so the manifest scheme is single-prefixed.
50
+
51
+ Suite: 913 tests.
52
+
3
53
  ## v0.62.2 (2026-11-04)
4
54
 
5
55
  ### The review batch: the insert-branch fix and the inventories, closed
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "bindery-cli"
7
- version = "0.62.2"
7
+ version = "0.63.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 = [
@@ -58,6 +58,7 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
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
59
  | 0.62.1 | `--fix-double-colon-tags`: the pseudo-tag escape for the last library fatal -- an XML name carries at most one colon, so a `::`-named pseudo-tag is never markup (fatal RSC-016; the Book of Debugging's C++ samples), and escaping both ends restores the author's text; nested templates escape inner-first, real markup is unreachable by construction; also closes the spec.md drift (the four v0.62.0 flags had not joined the inventory) | v0.62.1 |
60
60
  | 0.62.2 | The review batch (three-reviewer pass over the v0.62.x range): the item-properties insertion branch emitted malformed XML on the self-closed shape (attribute after the solidus; no test drove the branch -- every fixture pre-carried properties), now appends before the solidus with an ET-parsed pin; the missing-title empty-fill is head-scoped (an empty SVG `<title>` is visible text); the double-colon tail is bounded at 120 chars (the escaped-bracket runaway); the unverified on\* handler disjunct left the census; `_scan_doctype_span` refuses unterminated declarations; the guide-prune docstring matches the code; and the documentation inventories caught up (README's seven missing flags, spec.md's four behavioral bullets + body counts + the safe-opt-in section, AGENTS.md's inventory) | v0.62.2 |
61
+ | 0.63 | The harvest census (the honest dig into the remaining 14,109): `--strip-presentational-attrs` (the largest attribute family; rendering-caveat approved), `--encode-ref-brackets` (the issue #19 mechanism applied to brackets without spaces; the 59-book RSC-020 lane), `--fix-id-colons` broadened to every NCName failure (digit-led scraped ids; the apostrophe charset blind spot closed), and the audit battery's `shell` analyzer (the Wandering Inn detector: spine-missing fraction at or over 50% reads SHELL, re-source never repair) | v0.63.0 |
61
62
 
62
63
  ## Open work
63
64
 
@@ -13,7 +13,7 @@ restyle, re-compress, or restructure content, and it does not attempt to fix arb
13
13
  schema (RSC-005) violations, which are usually harmless to readers and not safely
14
14
  mechanizable.
15
15
 
16
- The deliberate exceptions to "semantics-preserving" come in opt-in groups. The thirty
16
+ The deliberate exceptions to "semantics-preserving" come in opt-in groups. The thirty-two
17
17
  **structural repairs** (`--fix-empty-body`, `--fix-missing-title`, `--fix-id-colons`,
18
18
  `--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
19
19
  `--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`,
@@ -24,7 +24,8 @@ The deliberate exceptions to "semantics-preserving" come in opt-in groups. The t
24
24
  `--fix-misnested-inline`,
25
25
  `--fix-stray-close`, `--fix-unterminated-attr`, `--fix-unbound-prefix`,
26
26
  `--fix-unique-identifier`, `--fix-package-version`, `--fix-doctype`,
27
- `--prune-invalid-guide-refs`, `--fix-item-properties`) alter
27
+ `--prune-invalid-guide-refs`, `--fix-item-properties`,
28
+ `--strip-presentational-attrs`, `--encode-ref-brackets`) alter
28
29
  markup structure or fabricate minimal content; the four
29
30
  **lossy modes** (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`,
30
31
  `--strip-stub-docs`) remove
@@ -178,12 +179,16 @@ part of the default pipeline:
178
179
  Adds visible content, hence opt-in like `--add-img-alt`.
179
180
  - **`--fix-missing-title`**: inject `<title>Unknown</title>` when the head has no usable
180
181
  title.
181
- - **`--fix-id-colons`**: illegal colons in `id="X:Y"` and their matching internal
182
- `#X:Y` fragment references become `_`. Only the bare `id` attribute is in scope
183
- (`data-id` values are arbitrary data and are never touched), the fragment of an
184
- external URL names a position in that other document and survives verbatim, and the
185
- NCX's `content src` fragments follow the rename (`fix_ncx_src_fragments`), so a ToC
186
- never dangles against the ids it references.
182
+ - **`--fix-id-colons`**: any `id` value that cannot be an XML NCName and its
183
+ matching internal fragment reference are renamed with the deterministic
184
+ `id_`+sanitized scheme (v0.63.0 broadened the predicate from colon-bearing
185
+ to every NCName failure: digit-led scraped ids like
186
+ `<body id="0-25c121ec...">`, apostrophe-bearing calibre ids). Only the bare
187
+ `id` attribute is in scope (`data-id` values are arbitrary data and are never
188
+ touched), the fragment of an external URL names a position in that other
189
+ document and survives verbatim, and the NCX's `content src` fragments follow
190
+ the rename (`fix_ncx_src_fragments`), so a ToC never dangles against the ids
191
+ it references.
187
192
  - **`--unwrap-block-in-inline`**: drop a `<span>` that illegally wraps a
188
193
  `<div>/<p>/<blockquote>`, keeping the block element and its text.
189
194
  - **`--strip-invalid-value`**: remove misplaced `value="..."` attributes from non-form
@@ -502,7 +507,34 @@ leftovers whose failing OPF is a stale non-rootfile are unreachable by construct
502
507
  the handler demand was never verified against the oracle the way the form
503
508
  was.
504
509
 
505
- Twenty-seven of the thirty are evaluated by the normal `gate`: unlike the lossy strips,
510
+ - **`--strip-presentational-attrs`**: strip the deprecated presentational
511
+ hints the XHTML 1.1 DTD rejects wherever they appear -- `align`,
512
+ `valign`, `border`, `bgcolor`, `vspace`, `hspace`, `compact`
513
+ (element-agnostic presentation), body's `link`/`vlink`/`alink`/`text`/
514
+ `background` color family (body-scoped: `link` on anything but `<body>`
515
+ is a different attribute class and survives), `type` on the list
516
+ elements (legal -- and load-bearing -- on `style`/`link`/`script`, which
517
+ are never touched), and the Amazon `data-AmznRemoved` scraper junk.
518
+ HONEST CAVEAT, Brandon-approved 2026-11-04: these are presentational
519
+ hints, and readers that honor them render differently after the strip
520
+ (`bgcolor` stops coloring, `align` stops centering); the edit is
521
+ anchored to real start tags, attribute-counted, and never touches CDATA
522
+ or comments.
523
+
524
+ - **`--encode-ref-brackets`**: percent-encode raw `[`/`]` in the PATH
525
+ portion of internal `src`/`href` references whose archive target exists
526
+ with the raw brackets (RSC-020 'Illegal character in path segment'; the
527
+ 2026-11-04 census's 59-book lane). The issue #19 mechanism: epubcheck
528
+ decodes references before entry lookup, so the encoded spelling resolves
529
+ to the raw-spelled entry; `encode-url-spaces` performs this encoding
530
+ only while renaming space-bearing entries, and brackets WITHOUT spaces
531
+ were uncovered. The fragment and query portions are left untouched
532
+ (brackets there are not path-segment findings), entry names are never
533
+ renamed, unresolvable and external references stay as written, and the
534
+ walk covers content documents, the OPF, the NCX, and stylesheet `url()`
535
+ tokens.
536
+
537
+ Twenty-nine of the thirty-two are evaluated by the normal `gate`: unlike the lossy strips,
506
538
  their benefit is visible to epubcheck (they clear errors), so a run with no measurable
507
539
  improvement is a noop and nothing is applied. The three exceptions are `--fix-cover`, `--encode-url-spaces`, and
508
540
  `--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.2"
14
+ VERSION = "0.63.0"
15
15
  __version__ = VERSION
16
16
 
17
17
  from .epub import RepairReport, repair_epub # noqa: E402
@@ -1515,6 +1515,36 @@ def scan_completeness(path: Path) -> dict:
1515
1515
  return analyze_completeness(load_book(path))
1516
1516
 
1517
1517
 
1518
+ def analyze_shell(book: Book) -> dict:
1519
+ """The shell-book detector (the 2026-11-04 Wandering Inn diagnosis):
1520
+ what fraction of the manifest's content hrefs name files the archive
1521
+ does not contain. The loader's `spine_missing` already counts the
1522
+ itemrefs that could not resolve; a high fraction on a book that still
1523
+ opens means the converter wrote the series-wide manifest and shipped a
1524
+ sliver of the archive -- 738 and 736 manifest items missing of 755 and
1525
+ 752 on the two shells. Re-source territory: no repair can fabricate
1526
+ the missing files, and the spine guard correctly refuses to drop them.
1527
+ Advisory by contract, like completeness."""
1528
+ spine_n = len(book.spine)
1529
+ missing = book.spine_missing
1530
+ frac = (missing / spine_n) if spine_n else 0.0
1531
+ return {"spine_docs": spine_n, "missing": missing, "missing_frac": frac}
1532
+
1533
+
1534
+ def _shell_dir(r: dict) -> tuple[bool, str, list[str]]:
1535
+ lines = [
1536
+ f"spine {r['spine_docs']}, manifest-missing {r['missing']} "
1537
+ f"({r['missing_frac'] * 100:.0f}%)"
1538
+ ]
1539
+ status = "OK"
1540
+ if r["spine_docs"] and r["missing_frac"] >= 0.5:
1541
+ status = (
1542
+ "SHELL: the manifest names files the archive never carried; "
1543
+ "re-source, never repair"
1544
+ )
1545
+ return (False, status, lines)
1546
+
1547
+
1518
1548
  def _completeness_dir(r: dict) -> tuple[bool, str, list[str]]:
1519
1549
  """Advisory by contract: the archive, spine, and emptytext verdicts own
1520
1550
  the flags; completeness reports the shape a human judges."""
@@ -2721,6 +2751,18 @@ def _spine_sections(hits, advisory) -> int:
2721
2751
  return 0
2722
2752
 
2723
2753
 
2754
+ def _shell_sections(advisory) -> int:
2755
+ """Print the shell advisories; the analyzer never fails a run."""
2756
+ if advisory:
2757
+ print(
2758
+ f"{YELLOW}{BOLD}SHELL BOOKS ({len(advisory)} to re-source;"
2759
+ f" reported, not flagged){RESET}"
2760
+ )
2761
+ for book_id, title, tag in sorted(advisory):
2762
+ print(f" {YELLOW}#{book_id}{RESET} [{tag}] {title}")
2763
+ return 0
2764
+
2765
+
2724
2766
  def _completeness_sections(advisory) -> int:
2725
2767
  """Print the completeness advisories; the analyzer never fails a run."""
2726
2768
  if advisory:
@@ -2774,6 +2816,7 @@ ALL: tuple[str, ...] = (
2774
2816
  "cover",
2775
2817
  "tocdrift",
2776
2818
  "contamination",
2819
+ "shell",
2777
2820
  )
2778
2821
 
2779
2822
 
@@ -2806,6 +2849,7 @@ def _dir_dispatch(
2806
2849
  "cover": lambda b: _cover_dir(analyze_cover(b)),
2807
2850
  "tocdrift": lambda b: _tocdrift_dir(analyze_tocdrift(b)),
2808
2851
  "contamination": lambda b: _contamination_dir(analyze_contamination(b)),
2852
+ "shell": lambda b: _shell_dir(analyze_shell(b)),
2809
2853
  }
2810
2854
 
2811
2855
 
@@ -2934,6 +2978,7 @@ def run_library(
2934
2978
  ocr_found: list[tuple] = []
2935
2979
  mono_hits: list[tuple] = []
2936
2980
  completeness_advisory: list[tuple] = []
2981
+ shell_advisory: list[tuple] = []
2937
2982
  cover_advisory: list[tuple] = []
2938
2983
  tocdrift_advisory: list[tuple] = []
2939
2984
  contamination_advisory: list[tuple] = []
@@ -3044,6 +3089,14 @@ def run_library(
3044
3089
  # status and the exit code are never moved by this analyzer
3045
3090
  _record_verdict(record, "completeness", (False, status, lines))
3046
3091
 
3092
+ if "shell" in selected:
3093
+ r = analyze_shell(book)
3094
+ _p, status, lines = _shell_dir(r)
3095
+ if status != "OK":
3096
+ shell_advisory.append((book_id, title, tag, r))
3097
+ # advisory by contract: problem is always False
3098
+ _record_verdict(record, "shell", (False, status, lines))
3099
+
3047
3100
  if "cover" in selected:
3048
3101
  r = analyze_cover(book)
3049
3102
  _p, status, lines = _cover_dir(r)
@@ -3086,6 +3139,8 @@ def run_library(
3086
3139
  rc |= _monolithic_sections(mono_hits)
3087
3140
  elif key == "completeness":
3088
3141
  rc |= _completeness_sections(completeness_advisory)
3142
+ elif key == "shell":
3143
+ rc |= _shell_sections(shell_advisory)
3089
3144
  elif key == "cover":
3090
3145
  rc |= _cover_sections(cover_advisory)
3091
3146
  elif key == "tocdrift":
@@ -114,6 +114,8 @@ def _flags_from_args(args: argparse.Namespace) -> RepairFlags:
114
114
  prune_guide_refs=args.prune_invalid_guide_refs or all_,
115
115
  item_properties=args.fix_item_properties or all_,
116
116
  double_colon_tags=args.fix_double_colon_tags or all_,
117
+ presentational_attrs=args.strip_presentational_attrs or all_,
118
+ encode_ref_brackets=args.encode_ref_brackets or all_,
117
119
  )
118
120
 
119
121
 
@@ -1705,6 +1707,22 @@ _REPAIR_FLAG_TABLE: dict[str, list[tuple[str, str, str]]] = {
1705
1707
  ),
1706
1708
  ],
1707
1709
  "structural repairs: markup and nesting": [
1710
+ (
1711
+ "strip_presentational_attrs",
1712
+ "strip deprecated presentational attributes (align/valign/bgcolor/border, body link/vlink, list type)",
1713
+ "strip the deprecated presentational hints the XHTML 1.1 DTD rejects "
1714
+ "wherever they appear: align, valign, border, bgcolor, vspace, "
1715
+ "hspace, compact (element-agnostic presentation), body's "
1716
+ "link/vlink/alink/text/background color family, type on the list "
1717
+ "elements (legal -- and load-bearing -- on style/link/script, "
1718
+ "which are never touched), and the Amazon data-AmznRemoved "
1719
+ "scraper junk. HONEST CAVEAT (Brandon-approved 2026-11-04): "
1720
+ "these are presentational hints, and readers that honor them "
1721
+ "render differently after the strip -- bgcolor stops coloring, "
1722
+ "align stops centering. The 2026-11-04 census's largest "
1723
+ "attribute family; the edit is anchored to real start tags and "
1724
+ "never touches CDATA or comments.",
1725
+ ),
1708
1726
  (
1709
1727
  "fix_empty_body",
1710
1728
  "fill a strictly empty <body></body> with <p>&#160;</p>",
@@ -1813,6 +1831,21 @@ _REPAIR_FLAG_TABLE: dict[str, list[tuple[str, str, str]]] = {
1813
1831
  ),
1814
1832
  ],
1815
1833
  "structural repairs: references and resources": [
1834
+ (
1835
+ "encode_ref_brackets",
1836
+ "percent-encode raw [ ] in internal references whose target exists (RSC-020)",
1837
+ "percent-encode [ and ] in the path portion of internal src/href "
1838
+ "references whose archive target exists with the raw brackets "
1839
+ "(RSC-020 'Illegal character in path segment'). The issue #19 "
1840
+ "mechanism: epubcheck decodes references before entry lookup, so "
1841
+ "the encoded spelling resolves to the raw-spelled entry; "
1842
+ "encode-url-spaces performs this encoding only while renaming "
1843
+ "space-bearing entries, and brackets WITHOUT spaces were "
1844
+ "uncovered. The fragment and query portions are left untouched, "
1845
+ "entry names are never renamed, and unresolvable references stay "
1846
+ "as written. Runs on content documents, the OPF, the NCX, and "
1847
+ "stylesheet url() tokens.",
1848
+ ),
1816
1849
  (
1817
1850
  "fix_page_map",
1818
1851
  'drop the OPF page-map attribute; class="pages" on NCX pageLists',