bindery-cli 0.62.1__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.
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/AGENTS.md +12 -6
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/PKG-INFO +12 -2
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/README.md +11 -1
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/patchnotes.md +99 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/pyproject.toml +1 -1
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/roadmap.md +2 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/spec.md +107 -10
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/src/bindery/__init__.py +1 -1
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/src/bindery/audit.py +55 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/src/bindery/cli.py +33 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/src/bindery/epub.py +174 -70
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/src/bindery/transforms.py +150 -14
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_contamination.py +42 -1
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_epub.py +254 -140
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_flags_wiring.py +2 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_transforms.py +84 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/uv.lock +1 -1
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/.github/FUNDING.yml +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/.github/workflows/ci.yml +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/.github/workflows/publish.yml +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/.gitignore +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/LICENSE +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/OBSERVE-RESEARCH.md +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/docs/screenshots/library-sweep.png +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/logo.svg +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/plugin/__init__.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/project.done +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/run_tests.sh +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/scripts/FastSweep.java +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/scripts/build_plugin.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/scripts/fast_sweep.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/src/bindery/__main__.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/src/bindery/library.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/src/bindery/observe.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/src/bindery/pagination.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/src/bindery/reserialize.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/src/bindery/validate.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/src/bindery/watermark.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_audit.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_cli.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_comment_hyphens.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_cover_tocdrift.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_flags_real_core.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_help.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_library.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_matcher_hardening.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_observe.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_pagination.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_plugin.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_reserialize.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_space_renames.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_spine_guard.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_validate.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_version.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_watermark.py +0 -0
- {bindery_cli-0.62.1 → bindery_cli-0.63.0}/tests/test_xml_hardening.py +0 -0
|
@@ -30,8 +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:
|
|
34
|
-
repairs, four lossy strips,
|
|
33
|
+
visible content. The canonical opt-in inventory lives in spec.md: thirty-two structural
|
|
34
|
+
repairs, four lossy strips, five safe opt-ins, plus `--reserialize` (the
|
|
35
|
+
seven v0.62.x/v0.63.0 flags -- `--fix-package-version`, `--fix-doctype`,
|
|
36
|
+
`--prune-invalid-guide-refs`, `--fix-item-properties`,
|
|
37
|
+
`--fix-double-colon-tags`, `--strip-presentational-attrs`,
|
|
38
|
+
`--encode-ref-brackets` -- are in both inventories since v0.62.0+).
|
|
35
39
|
* **Structural repairs** (`--fix-empty-body`, `--fix-missing-title`, `--fix-id-colons`,
|
|
36
40
|
`--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
|
|
37
41
|
`--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`,
|
|
@@ -41,7 +45,9 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
|
|
|
41
45
|
`--fix-comment-double-hyphen`, `--fix-svg-dup-ids`, `--fix-duplicate-ids`,
|
|
42
46
|
`--fix-cdata-terminator`,
|
|
43
47
|
`--fix-misnested-inline`, `--fix-stray-close`, `--fix-unterminated-attr`,
|
|
44
|
-
`--fix-unbound-prefix
|
|
48
|
+
`--fix-unbound-prefix`, `--fix-package-version`, `--fix-doctype`,
|
|
49
|
+
`--prune-invalid-guide-refs`, `--fix-item-properties`,
|
|
50
|
+
`--strip-presentational-attrs`, `--encode-ref-brackets`;
|
|
45
51
|
transforms.py, threaded through epub.py). The v0.47.0 five (the 2026-10-06
|
|
46
52
|
issue batch): `--fix-svg-dup-ids` renames duplicate glyph ids inside
|
|
47
53
|
standalone `.svg` entries (first keeps its name, references resolve to the
|
|
@@ -226,18 +232,18 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
|
|
|
226
232
|
- `src/bindery/pagination.py`: the opt-in lossy page-number strip (runhead detection, page-layer decision, block-centric removal/merge, safety nets).
|
|
227
233
|
- `src/bindery/watermark.py`: the opt-in lossy watermark strip (anchored and anchorless signature removal).
|
|
228
234
|
- `src/bindery/reserialize.py`: structural repair via `html5lib`.
|
|
229
|
-
- `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).
|
|
230
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
|
|
231
237
|
character references before the fragment split (attribute text arrives
|
|
232
238
|
escaped; entries are raw; decoding first keeps the `#` inside `&`
|
|
233
|
-
from cutting the target), `_ITEM_TAG_RE`/`_SPINE_ITEM_RE`/`_GUIDE_REF_RE`/prune_dangling_edges' matcher accept an optional ns prefix (`<opf:item>`), and the renamed-reference spellings percent-encode `[`/`]` (`_encode_ref_path`). Since v0.52.0 (issue #10): `spine_dangles(src)` walks itemref -> manifest item -> archive entry through `_resolve_href`+`_norm_path` (None on an unreadable package: the veto needs evidence, never fires on a probe failure), and `prune_missing_manifest_items` derives its spine protection from the text it prunes (no snapshot parameter: fix_manifest_ids renames ids ahead of it, and the existence set it checks against must be the layout its hrefs are written in — `present_src` when space renames are active, matching the content-doc prune). Since v0.46.0 the opt-in selection is the `RepairFlags` dataclass (one field per flag, all off by default; the all-off instance IS the default pass): `repair_epub(src, dst, flags)` and `process_book(..., flags)` take one object instead of a ~25-kwarg signature, the EPUB2-targeted fixes' version gate swaps in a `dataclasses.replace` copy (never mutating the caller's instance), and the plugin's bare `repair_epub(src, dst)` call constructs exactly the all-off default pass. Since v0.55.0 (issue #16) the RSC-008 half lives beside the prune: `collect_undeclared_resources` (one whole-book census: content img/link, inline `<style>` url(), stylesheet url(), OPF guide refs) + `declare_missing_manifest_items` (sorted `bindery-dN` items before `</manifest>`, `_DECLARE_MEDIA_TYPES` blessed extensions only), gated and threaded through `RepairFlags.declare_missing`. Since v0.38.0/v0.39.0 (Phase 16): `generate_container` + the `--fix-container` gateway (insert after mimetype when missing, replace in-loop when stale; constant-epoch timestamp keeps bytes deterministic), `prune_dangling_edges` (prune_missing_manifest_items returns the pruned ids and the edges that pointed at them (spine@toc, media-overlay, fallback, EPUB2 cover meta) are rewritten so pruning cannot manufacture the regression the gate rejects), and `fix_manifest_media_types` (extension map + magic-byte confirmation via a `peek` callable over the open source zip; jpg/png/gif only), and `fix_cover_meta` (the ruling's deterministic half: dangling EPUB2 cover meta re-pointed from the guide's cover reference when exactly one manifest item carries that file, removed otherwise; accepted under no_worse like the lossy strips because cover wiring is invisible to epubcheck).
|
|
239
|
+
from cutting the target), `_ITEM_TAG_RE`/`_SPINE_ITEM_RE`/`_GUIDE_REF_RE`/prune_dangling_edges' matcher accept an optional ns prefix (`<opf:item>`), and the renamed-reference spellings percent-encode `[`/`]` (`_encode_ref_path`). Since v0.52.0 (issue #10): `spine_dangles(src)` walks itemref -> manifest item -> archive entry through `_resolve_href`+`_norm_path` (None on an unreadable package: the veto needs evidence, never fires on a probe failure), and `prune_missing_manifest_items` derives its spine protection from the text it prunes (no snapshot parameter: fix_manifest_ids renames ids ahead of it, and the existence set it checks against must be the layout its hrefs are written in — `present_src` when space renames are active, matching the content-doc prune). Since v0.46.0 the opt-in selection is the `RepairFlags` dataclass (one field per flag, all off by default; the all-off instance IS the default pass): `repair_epub(src, dst, flags)` and `process_book(..., flags)` take one object instead of a ~25-kwarg signature, the EPUB2-targeted fixes' version gate swaps in a `dataclasses.replace` copy (never mutating the caller's instance), and the plugin's bare `repair_epub(src, dst)` call constructs exactly the all-off default pass. Since v0.55.0 (issue #16) the RSC-008 half lives beside the prune: `collect_undeclared_resources` (one whole-book census: content img/link, inline `<style>` url(), stylesheet url(), OPF guide refs) + `declare_missing_manifest_items` (sorted `bindery-dN` items before `</manifest>`, `_DECLARE_MEDIA_TYPES` blessed extensions only), gated and threaded through `RepairFlags.declare_missing`. Since v0.38.0/v0.39.0 (Phase 16): `generate_container` + the `--fix-container` gateway (insert after mimetype when missing, replace in-loop when stale; constant-epoch timestamp keeps bytes deterministic), `prune_dangling_edges` (prune_missing_manifest_items returns the pruned ids and the edges that pointed at them (spine@toc, media-overlay, fallback, EPUB2 cover meta) are rewritten so pruning cannot manufacture the regression the gate rejects), and `fix_manifest_media_types` (extension map + magic-byte confirmation via a `peek` callable over the open source zip; jpg/png/gif only), and `fix_cover_meta` (the ruling's deterministic half: dangling EPUB2 cover meta re-pointed from the guide's cover reference when exactly one manifest item carries that file, removed otherwise; accepted under no_worse like the lossy strips because cover wiring is invisible to epubcheck). Since v0.62.0/0.62.1 (the 2026-11-03 observatory batch): the playOrder contract is base-free (epubcheck polices sharing/distinctness/gaps, never the base; verified at singleton/pair/offset scales), `fix_pagelist_class` inserts the collision-checked `bindery-pagelist` id beside the class (class-only insertion made epubcheck demand the id it enabled), `fix_missing_title` fills the self-closed `<title/>` head-scoped only (an empty SVG `<title>` is visible text the gate cannot measure), and four new flags live beside them: `fix_package_version` (literal 1.0 -> 2.0 only; `_PACKAGE_VERSION_ONE_RE`), `fix_doctype` (present-but-forbidden declarations only; `_scan_doctype_span` walks bracket depth and refuses unterminated spans), `prune_invalid_guide_refs` (declared-but-not-a-content-doc targets, both element shapes), and `fix_manifest_item_properties` + `collect_item_properties` (EPUB3-only census: scripted from `<script>`/`<form>`, svg from `<svg>`, remote-resources from absolute-scheme src/link/CSS url(); the insert branch appends before a self-closed item's solidus, never after it -- the v0.62.1 review caught the malformed `/ properties` shape). Since v0.62.1 `fix_double_colon_tags` escapes `::`-named pseudo-tags (a QName carries at most one colon, so such a construct is never markup; nested templates escape inner-first until stable; the tail is bounded at 120 chars so an escaped-bracket construct cannot swallow prose).
|
|
234
240
|
- `src/bindery/validate.py`: epubcheck wrapper, the `gate` (improvement) and `no_worse` (no-regression, for the lossy strips) acceptance bars. Since v0.55.0 (issue #15) the default oracle budget is size-scaled (`oracle_timeout_for`: 300s at or under 10 MB, +60s per started 10 MB above, 1800s cap), one subprocess retry follows a timed-out attempt (the daemon path's subprocess fallback is that attempt), and only a double timeout raises `OracleTimeout`, which the gate surfaces as `(epubcheck timeout)` instead of `(epubcheck failed)` (the sweep selectors catch it and keep the book a candidate). Since v0.60.0 (issue #24) the size term counts decimal MB (10,440,245 bytes is 9.96 binary MiB, so the book the docs call 10.4 MB computed the flat 300s base with no size chunk), and the budget also scales on archive entry count (+60s per started 500 entries above 1,000; a path that does not open as a zip falls back to size-only): the Summa Theologica is entry-count-bound, not bytes-bound (3,831 entries / 3,808 spine docs; measured 384s source and 445s candidate), and now computes 720s.
|
|
235
241
|
- `src/bindery/library.py`: Calibre walk, atomic replace, backups, and native format installation. Since v0.19.0 `CalibreIdResolver` resolves the book id from `metadata.db` through cquarry (one lazy path→id map per run; since v0.20.0 the map comes from `CalibreDB.format_path_index()`, re-normalized with `resolve().lower()` for the resolver's symlinked-directory and case-insensitive matching); the `(id)` directory-name regex is only the no-catalog fallback. Since v0.24.0 `install_format()` places the repaired file atomically and updates the `data` row through `cquarry.write.WritableCalibreDB` (since v0.31.0 via `set_format`, cquarry 1.17's sanctioned remove+add in one transaction); the external `calibredb` CLI is gone. Since v0.32.0 a guessed id drives a row update only when metadata.db corroborates it (`_verify_guess`: books row exists, file in the book's own directory, catalogued `data.name` when a row exists); anything else saves in place and leaves the catalog untouched: never reintroduce directory-name guessing as the primary source: renamed/mismatched directories would replace the wrong book. Since 2026-09-15 `make_backup` takes the opt-in `--backup-keep N` ring: at most N backup files per book, the author original `.bak` never deleted, newest content at the highest name; default remains an unbounded rotation.
|
|
236
242
|
- `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; since v0.52.0 `process_book` carries the spine-resolution veto (issue #10) above every verdict path, promotions included: a candidate whose spine dangles more than the source's is `reject` with `(spine collapse)` appended to the summary, whatever the counts say. `repair --json` emits the library per-book record vocabulary (2026-09-15; since v0.45.0 every per-book record, the phase1 payload included, also carries the structured fix breakdown: the `fixes` dict plus `ncx_uid_synced`/`watermark_refusals` off the `Outcome`, and `_phase1_decisions` reads that data instead of substring-matching the rendered `summary`, which stays for human eyes; CalibreQuarry's lossy-consent mirror is the waiting consumer, floor `bindery>=0.45.0`); since v0.29.0 also the `run` verbs: `phase1` (pre-import vetting over loose files: the audit battery composed with one gated repair sweep; read-only until `--apply-lossy`, which IS the lossy-strip consent) and `phase3` (the scoped post-import apply step: `library --id --sweep --only all --apply --all --install-to-calibre` plus a pre/post summary; mechanically refuses unscoped sweeps with exit 2; since 2026-09-15 the summary sums applied/equal states only and carries rejected projections as `rejected_projection`). Plus `bindery doctor` (2026-09-15): the environment self-check that imports none of the VirInvictus stack, never raises, and always exits 0. The `observe` verb (v0.53.0) writes schema v2 artifacts since v0.55.0 (issue #13): `codes.messages` (renamed from the mislabeled `occurrences`) counts aggregated epubcheck JSON message entries, `codes.occurrences` now carries the true per-site scale (summed `locations`), a `counting` block states both scales in the artifact, and `--against` accepts v1 or v2 (the trend keys exist in both). Both run verbs take `--non-interactive` and surface open questions as `decisions_needed` in their JSON, never prompts. They drive the shipped `run_library` through the real parser, so no flag can drift between the verb and the subcommand it wraps. Since v0.46.0 `cli._flags_from_args(args)` is the one place the argparse names map onto `RepairFlags` fields (each `or --all`), shared by `run_library` and `run_repair`; the old per-verb ~25-kwarg blocks are gone. Since v0.47.1 the help is two-level (the --help-repairs reference is
|
|
237
243
|
custom-rendered and colors itself with the CPython 3.14 argparse theme,
|
|
238
244
|
gated by argparse's own _colorize detection so the levels always agree) and the repair-flag inventory is one table: `_REPAIR_FLAG_TABLE` (dest + one-line short help + long reference text) registers the compact grouped `--help` (argparse argument groups, hand-short usage line) and `--help-repairs` renders the long descriptions (a custom argparse Action, deliberately NOT store_true so the wiring test's selection count ignores it); adding a flag means adding a table row. Since v0.48.0 the metadata.db doors are enforced: `_require_closed_calibre` (pgrep fail-closed, exit 1) guards `audit --tag` and `library --apply --install-to-calibre` (run phase3 transitively), and `--help-json` (a custom argparse Action like --help-repairs, never colored) dumps the per-verb exit contract and the door list; since v0.48.1 the per-verb exit contracts tell the code's truth (repair: 0 probed/written incl. partial / 1 trouble, never 2; audit: 0/1/2 plus 3 for findings+write-failure; library and the run slices: the unified 0/2/1); since v0.49.0 the single-file verb's no-output form is a probe (the gate runs, the record's `output` is null and `applied` false, nothing is written anywhere; the old implicit `(repaired).epub` sibling was issue #7's import litter in a vetted tree, and writing now needs an explicit DST). `library --workers N` (v0.30.0) parallelizes only the sweep's candidate pass, in windows of N consumed in order so `--limit` stays lazy; the repair phase is never parallel (shared workdir, atomic-replacement contract). Since v0.40.0 `main()` guards the VirInvictus stack: a `ModuleNotFoundError` naming `vir_tui`/`cquarry` (marker-gated to 3.14+ on the 3.12 floor) becomes one stderr line and trouble exit 2 instead of a traceback; anything else missing still raises.
|
|
239
245
|
- `plugin/__init__.py` + `scripts/build_plugin.py`: the Bindery Repair Calibre plugin (v0.37.0; identity `Bindery Repair` / `bindery_repair`, approved and built per the scoped spec in roadmap.md Phase 3). The builder vendors `transforms.py`, `epub.py`, `pagination.py`, `watermark.py`, `reserialize.py` byte-identically into the zip (the zip root is a package, so their relative imports resolve unchanged; the suite's drift test pins the equality) with the version tuple substituted from the single-source VERSION; `publish.yml` attaches `BinderyRepair-v<VERSION>.zip` to each release. The plugin runs ONLY the default pass (epubcheck cannot gate inside Calibre), never raises, is byte-idempotent (zero fixes returns the original path), testzip()-verifies its output, logs one line per book, and takes JSON config via `site_customization` (`log`, `log_path`, `max_size_mb` default 150, `max_log_mb` rotation cap default 2, `epubcheck_path` experimental validation default OFF). Load it in tests through the `tests/test_plugin.py` stubs: the calibre namespace is installed in sys.modules and the package loads with a two-dir `__path__` (plugin dir first, then src/bindery) exactly like calibre's zipplugin loader shape. **Plugin/interpreter compatibility (v0.40.0):** v0.39.0 shipped PEP 758 unparenthesized except tuples, and the plugin died with a bare SyntaxError on every released Calibre (7.x and the whole 8.x series embed Python 3.11, 9.0+ embeds 3.14; from calibre's bypy sources.json, checked against the upstream clone). The core is now grammar-pinned: parenthesized except tuples everywhere, `ruff`'s `target-version = "py312"` pin (inference from requires-python would rewrite the parens back off), `tests/test_version.py`'s parse guard, and CI's `plugin-compat` job byte-compiling the built zip under 3.11/3.12/3.13/3.14. `minimum_calibre_version` is (7, 0, 0): the oldest series whose interpreter CI covers, replacing the hollow (2, 0, 0); `supported_platforms` stays `["linux"]` (developed and tested on Linux only). Any new syntax in the vendored modules must clear the guard before it ships.
|
|
240
|
-
- `tests/`: transforms (including the shared duplicate-id rename), end-to-end repair, atomic replace, pagination, watermarks, the audit analyzers (content/pagenumbers/emptytext/ocr/monolithic/completeness, archive integrity, spine classification, contamination since v0.50.0), the library sweep and `CalibreIdResolver`, validate, reserialize, CLI wiring, the version pin and the syntax-floor grammar guard, and the Calibre plugin (build drift + run behavior under calibre stubs). Since the v0.46.0 follow-ups: `tests/test_flags_wiring.py` reflectively pins the RepairFlags inventory to the argparse dests and `_flags_from_args` mapping (a flag added without a field, a field without a flag, or a remapped line fails there), the all-off defaults, and the version gate's caller-immutability contract (test_epub's `TestVersionGateKeepsFlagsIntact`); `tests/test_comment_hyphens.py` carries the RSC-016 fix; `tests/test_flags_real_core.py` drives every repair flag from argv through the unmocked core (--no-validate; the gate itself stays pinned by the mocked-oracle tests and runs for real wherever epubcheck exists). `tests/test_contamination.py` (v0.50.0) carries the three contamination sweeps, the advisory contract, the `_dir_dispatch` key pin, and the cover-routing regression. The v0.46.0 trio (test_flags_wiring, test_comment_hyphens, test_flags_real_core) rides CI's core-compat 3.12/3.13 leg; the hand-listed module list there must gain an entry for every new stack-free test module (audit-side test modules like test_contamination stay on the 3.14 leg by convention). The v0.55.0 batch (issues #11-#16): `tests/test_validate.py` pins the size-scaled timeout and the retry-then-OracleTimeout contract, `tests/test_observe.py` the v2 line format (`CODE:messages:occurrences`), the renamed codes block, the counting envelope, and v1 `--against` acceptance, `tests/test_epub.py::TestDeclareMissingItems` the RSC-008 declarer (sorted deterministic items, blessed media types only, id collisions prefixed, schemes/fragments/spaces/declared skipped), `tests/test_transforms.py::TestFixDuplicateIds` the content-doc rename, and `tests/test_flags_real_core.py` drives `--fix-duplicate-ids`, `--declare-missing-items`, and the extended `--strip-epub3-attrs` set through the real argv-to-fix path. The v0.59.0 addition (issue #23): `tests/test_epub.py::TestPruneDanglingNcxTargets` pins the node-exact prune rule (dead leaf dropped, dead parent spliced above live children, dead subtree one span, scheme/bare-fragment/contentless/comment-hidden untouched, escaped-ampersand src resolves, pageTarget and legacy navTarget covered, wrapper-crossing and unclosed walks abort, a wholesale-dead container refuses) plus the end-to-end prune+resequence, and `tests/test_flags_real_core.py` drives `--prune-dangling-ncx-targets` through argv. The v0.60.0 addition (issue #24): `tests/test_validate.py` pins the decimal-MB size term (exactly 10 MiB earns its 360s chunk) and the entry term (the 3,831-entry shape at <= 10 MB computes 660s; the full Summa shape computes 720s; exactly 1,000 entries stays at the size budget; 1,001 adds the first chunk; 2,500 computes 540s).
|
|
246
|
+
- `tests/`: transforms (including the shared duplicate-id rename), end-to-end repair, atomic replace, pagination, watermarks, the audit analyzers (content/pagenumbers/emptytext/ocr/monolithic/completeness, archive integrity, spine classification, contamination since v0.50.0), the library sweep and `CalibreIdResolver`, validate, reserialize, CLI wiring, the version pin and the syntax-floor grammar guard, and the Calibre plugin (build drift + run behavior under calibre stubs). Since the v0.46.0 follow-ups: `tests/test_flags_wiring.py` reflectively pins the RepairFlags inventory to the argparse dests and `_flags_from_args` mapping (a flag added without a field, a field without a flag, or a remapped line fails there), the all-off defaults, and the version gate's caller-immutability contract (test_epub's `TestVersionGateKeepsFlagsIntact`); `tests/test_comment_hyphens.py` carries the RSC-016 fix; `tests/test_flags_real_core.py` drives every repair flag from argv through the unmocked core (--no-validate; the gate itself stays pinned by the mocked-oracle tests and runs for real wherever epubcheck exists). `tests/test_contamination.py` (v0.50.0) carries the three contamination sweeps, the advisory contract, the `_dir_dispatch` key pin, and the cover-routing regression. The v0.46.0 trio (test_flags_wiring, test_comment_hyphens, test_flags_real_core) rides CI's core-compat 3.12/3.13 leg; the hand-listed module list there must gain an entry for every new stack-free test module (audit-side test modules like test_contamination stay on the 3.14 leg by convention). The v0.55.0 batch (issues #11-#16): `tests/test_validate.py` pins the size-scaled timeout and the retry-then-OracleTimeout contract, `tests/test_observe.py` the v2 line format (`CODE:messages:occurrences`), the renamed codes block, the counting envelope, and v1 `--against` acceptance, `tests/test_epub.py::TestDeclareMissingItems` the RSC-008 declarer (sorted deterministic items, blessed media types only, id collisions prefixed, schemes/fragments/spaces/declared skipped), `tests/test_transforms.py::TestFixDuplicateIds` the content-doc rename, and `tests/test_flags_real_core.py` drives `--fix-duplicate-ids`, `--declare-missing-items`, and the extended `--strip-epub3-attrs` set through the real argv-to-fix path. The v0.59.0 addition (issue #23): `tests/test_epub.py::TestPruneDanglingNcxTargets` pins the node-exact prune rule (dead leaf dropped, dead parent spliced above live children, dead subtree one span, scheme/bare-fragment/contentless/comment-hidden untouched, escaped-ampersand src resolves, pageTarget and legacy navTarget covered, wrapper-crossing and unclosed walks abort, a wholesale-dead container refuses) plus the end-to-end prune+resequence, and `tests/test_flags_real_core.py` drives `--prune-dangling-ncx-targets` through argv. The v0.60.0 addition (issue #24): `tests/test_validate.py` pins the decimal-MB size term (exactly 10 MiB earns its 360s chunk) and the entry term (the 3,831-entry shape at <= 10 MB computes 660s; the full Summa shape computes 720s; exactly 1,000 entries stays at the size budget; 1,001 adds the first chunk; 2,500 computes 540s). The v0.62.x additions: `tests/test_transforms.py::TestFixNcxPlayorder`'s base-free clause tests (zero-based/offset untouched, gap fires) and `TestFixMissingTitleSelfClosed`/`TestFixMissingTitleHeadScope` (self-closed fill, SVG-title protection), `tests/test_epub.py::TestItemPropertiesInsertionBranch` (the self-closed well-formedness pin) and the five `TestFlag*EndToEnd` classes, `tests/test_transforms.py::TestFixDoubleColonTags(+Bounds)` (book shape, closing tags, nesting, bounds, raw-ampersand), the four new-flag fixtures + rows in `tests/test_flags_real_core.py`, and the five mapping entries in `tests/test_flags_wiring.py`.
|
|
241
247
|
|
|
242
248
|
## Conventions
|
|
243
249
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: bindery-cli
|
|
3
|
-
Version: 0.
|
|
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
|
|
@@ -80,7 +80,17 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
|
|
|
80
80
|
- **`--fix-misnested-inline`**: rewrites the Mobipocket drop-cap mis-nest `<i><b>X</i></b>` to `<i><b>X</b></i>` (em/strong variants and either tag order). Only the both-open-then-reversed-close shape is touched; a punctuation run caught between the reversed closers (`<i><b>xile</i>,</b>`) survives outside both spans, and a letter run there is refused (which span keeps the letters has no deterministic answer).
|
|
81
81
|
- **`--fix-stray-close`**: removes an end tag whose element has no open start tag anywhere above it (the stray extra `</div>` on a shell page, which cascades into 'body must be terminated by the matching end-tag'). Merely mis-nested pairs are never touched: a close is removed only when nothing by that name is open.
|
|
82
82
|
- **`--fix-unterminated-attr`**: closes an attribute value left open to the tag's own `>` (`<p class="footnote>` becomes `<p class="footnote">`). The parser swallows prose into the value until the next quote and dies on the first `<` it meets. Guards keep it off legal `>`-bearing values: bare-word values only, and no quote may close before the next `<`.
|
|
83
|
-
|
|
83
|
+
- **`--fix-unbound-prefix`**: binds a prefix the OPF never declares in scope inline on the element that uses it (the Calibre embed scar: `ns0:scheme` on a `dc:identifier` whose `xmlns:ns0` sits on a sibling, out of XML scope; the later writer build's unbound `dc:` element names). The declaration is inserted on the user in the shape the file's own healthy siblings use, from URI evidence only (the same prefix declared elsewhere with every declaration agreeing, or the use site's own namespace); anything else refuses the document untouched. Runs on the OPF only.
|
|
84
|
+
- **`--prune-dangling-ncx-targets`**: removes NCX `navPoint`/`navTarget`/`pageTarget` elements whose `<content src>` names a document the archive never contained (RSC-007 at the toc: the OPF never declared the file, so the manifest prune has no item to prune). Node-exact: a dead subtree drops as one span, a dead parent above live children is spliced (its navLabel goes with it, the children re-home one level up), scheme URLs and bare fragments are never this class, an unbalanced walk aborts unchanged, and a prune that would empty a container refuses. The always-on playOrder pass re-runs when it fires.
|
|
85
|
+
- **`--fix-package-version`**: rewrites the literal `version="1.0"` on the `<package>` element to `"2.0"` -- an EPUB version epubcheck cannot parse (OPF-001). Only the exact literal qualifies; a missing attribute (an OEB-1.0-namespace package) or any other spelling refuses the document untouched.
|
|
86
|
+
- **`--fix-doctype`**: replaces a content document's DOCTYPE when it carries a public identifier its package profile forbids (EPUB 3 requires `<!DOCTYPE html>`; EPUB 2's OPS content docs are XHTML 1.1, so an XHTML 1.0 doctype is flagged). Whitespace-equal declarations are no-ops, an absent DOCTYPE is legal and left alone, and an internal subset is never touched.
|
|
87
|
+
- **`--prune-invalid-guide-refs`**: removes guide `<reference>` elements whose target is declared in the manifest but is not an OPS content document (OPF-032: the Random House `msr` guide block pointing cover references at JPEGs is the dominant fingerprint). The guide is furniture, so removal is content-neutral; undeclared targets (OPF-031) and external schemes are left alone.
|
|
88
|
+
- **`--fix-item-properties`**: scans each content document for what epubcheck wants declared (OPF-014: `scripted` from a `<script>` element or a `<form>`, `svg` from an `<svg>`, `remote-resources` from an absolute-scheme src/link/CSS url()) and merges the tokens into the owning manifest item's `properties` attribute, sorted and deduplicated. EPUB 3 packages only: on EPUB 2 the attribute is itself illegal, so those carriers refuse and stay measured.
|
|
89
|
+
- **`--fix-double-colon-tags`**: escapes the `<`/`>` around pseudo-tags whose name contains a double colon -- an XML name can carry at most one colon, so such a construct is never markup and the parser dies on it with a fatal RSC-016 (C++ code samples like `std::vector<std::shared_ptr>`). Escaping both ends restores exactly the text the author wrote; real markup is unreachable because the double colon lives in the name grammar itself.
|
|
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.
|
|
84
94
|
|
|
85
95
|
Four opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
|
|
86
96
|
|
|
@@ -53,7 +53,17 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
|
|
|
53
53
|
- **`--fix-misnested-inline`**: rewrites the Mobipocket drop-cap mis-nest `<i><b>X</i></b>` to `<i><b>X</b></i>` (em/strong variants and either tag order). Only the both-open-then-reversed-close shape is touched; a punctuation run caught between the reversed closers (`<i><b>xile</i>,</b>`) survives outside both spans, and a letter run there is refused (which span keeps the letters has no deterministic answer).
|
|
54
54
|
- **`--fix-stray-close`**: removes an end tag whose element has no open start tag anywhere above it (the stray extra `</div>` on a shell page, which cascades into 'body must be terminated by the matching end-tag'). Merely mis-nested pairs are never touched: a close is removed only when nothing by that name is open.
|
|
55
55
|
- **`--fix-unterminated-attr`**: closes an attribute value left open to the tag's own `>` (`<p class="footnote>` becomes `<p class="footnote">`). The parser swallows prose into the value until the next quote and dies on the first `<` it meets. Guards keep it off legal `>`-bearing values: bare-word values only, and no quote may close before the next `<`.
|
|
56
|
-
|
|
56
|
+
- **`--fix-unbound-prefix`**: binds a prefix the OPF never declares in scope inline on the element that uses it (the Calibre embed scar: `ns0:scheme` on a `dc:identifier` whose `xmlns:ns0` sits on a sibling, out of XML scope; the later writer build's unbound `dc:` element names). The declaration is inserted on the user in the shape the file's own healthy siblings use, from URI evidence only (the same prefix declared elsewhere with every declaration agreeing, or the use site's own namespace); anything else refuses the document untouched. Runs on the OPF only.
|
|
57
|
+
- **`--prune-dangling-ncx-targets`**: removes NCX `navPoint`/`navTarget`/`pageTarget` elements whose `<content src>` names a document the archive never contained (RSC-007 at the toc: the OPF never declared the file, so the manifest prune has no item to prune). Node-exact: a dead subtree drops as one span, a dead parent above live children is spliced (its navLabel goes with it, the children re-home one level up), scheme URLs and bare fragments are never this class, an unbalanced walk aborts unchanged, and a prune that would empty a container refuses. The always-on playOrder pass re-runs when it fires.
|
|
58
|
+
- **`--fix-package-version`**: rewrites the literal `version="1.0"` on the `<package>` element to `"2.0"` -- an EPUB version epubcheck cannot parse (OPF-001). Only the exact literal qualifies; a missing attribute (an OEB-1.0-namespace package) or any other spelling refuses the document untouched.
|
|
59
|
+
- **`--fix-doctype`**: replaces a content document's DOCTYPE when it carries a public identifier its package profile forbids (EPUB 3 requires `<!DOCTYPE html>`; EPUB 2's OPS content docs are XHTML 1.1, so an XHTML 1.0 doctype is flagged). Whitespace-equal declarations are no-ops, an absent DOCTYPE is legal and left alone, and an internal subset is never touched.
|
|
60
|
+
- **`--prune-invalid-guide-refs`**: removes guide `<reference>` elements whose target is declared in the manifest but is not an OPS content document (OPF-032: the Random House `msr` guide block pointing cover references at JPEGs is the dominant fingerprint). The guide is furniture, so removal is content-neutral; undeclared targets (OPF-031) and external schemes are left alone.
|
|
61
|
+
- **`--fix-item-properties`**: scans each content document for what epubcheck wants declared (OPF-014: `scripted` from a `<script>` element or a `<form>`, `svg` from an `<svg>`, `remote-resources` from an absolute-scheme src/link/CSS url()) and merges the tokens into the owning manifest item's `properties` attribute, sorted and deduplicated. EPUB 3 packages only: on EPUB 2 the attribute is itself illegal, so those carriers refuse and stay measured.
|
|
62
|
+
- **`--fix-double-colon-tags`**: escapes the `<`/`>` around pseudo-tags whose name contains a double colon -- an XML name can carry at most one colon, so such a construct is never markup and the parser dies on it with a fatal RSC-016 (C++ code samples like `std::vector<std::shared_ptr>`). Escaping both ends restores exactly the text the author wrote; real markup is unreachable because the double colon lives in the name grammar itself.
|
|
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.
|
|
57
67
|
|
|
58
68
|
Four opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
|
|
59
69
|
|
|
@@ -1,5 +1,104 @@
|
|
|
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
|
+
|
|
53
|
+
## v0.62.2 (2026-11-04)
|
|
54
|
+
|
|
55
|
+
### The review batch: the insert-branch fix and the inventories, closed
|
|
56
|
+
|
|
57
|
+
A three-reviewer pass over the v0.62.x range (code review, test-gap map,
|
|
58
|
+
docs-vs-code audit) converged on one ship-blocking defect and a set of
|
|
59
|
+
smaller findings; this patch carries every fix.
|
|
60
|
+
|
|
61
|
+
- **`--fix-item-properties`'s insertion branch emitted malformed XML**
|
|
62
|
+
(ship-blocking): an item with no `properties` attribute got the new
|
|
63
|
+
attribute appended after its self-closing solidus
|
|
64
|
+
(`<item .../ properties="scripted">` -- a violation of EmptyElemTag), so
|
|
65
|
+
the gate rejected every candidate on exactly the books the flag targets.
|
|
66
|
+
No test had ever driven the branch: every fixture pre-carried
|
|
67
|
+
`properties="nav"`. The branch now appends before the solidus
|
|
68
|
+
(`properties="scripted"/>`), a fixture pins the self-closed well-formedness
|
|
69
|
+
with an ElementTree parse, and the paired-item shape is covered too. The
|
|
70
|
+
affected books will harvest on the next `--all` sweep.
|
|
71
|
+
- **`fix_missing_title`'s empty-title fill is head-scoped**: an empty
|
|
72
|
+
`<title>` inside `<svg>` is the image's accessibility name and hover
|
|
73
|
+
tooltip -- filling it with "Unknown" is a visible text change the gate
|
|
74
|
+
cannot measure. The fill now runs inside the `<head>` section when one
|
|
75
|
+
exists; a document with no head keeps the document-wide behavior.
|
|
76
|
+
- **`--fix-double-colon-tags`' tail is bounded** at 120 characters: a
|
|
77
|
+
pseudo-tag whose own bracket was escaped (`<b::c>`, only the leading
|
|
78
|
+
`<` raw) would run the lazy tail to the next real tag's `>` and swallow
|
|
79
|
+
prose plus markup into display text -- damage the gate cannot always see.
|
|
80
|
+
Real code constructs are short; the bound keeps any failure local.
|
|
81
|
+
- **The on\* handler disjunct is gone from the item-properties census**:
|
|
82
|
+
`\son[a-z]+=` lexically cannot tell a handler from `only=`/`once=`, and
|
|
83
|
+
the handler demand was never verified against the oracle the way the
|
|
84
|
+
`<form>` demand was (tag-off bisection). The census keeps the
|
|
85
|
+
oracle-verified `scripted` triggers (`<script>`, `<form>`).
|
|
86
|
+
- **`_scan_doctype_span` refuses unterminated declarations**: a `<` met at
|
|
87
|
+
bracket depth 0 before any `>` means the next tag has begun and the
|
|
88
|
+
declaration's true end is unknowable -- the span must not swallow it.
|
|
89
|
+
- **The guide-prune docstring matches the code**: both element shapes are
|
|
90
|
+
removed (self-closed and paired), not "self-closed only".
|
|
91
|
+
- **The documentation inventories caught up** (the drift the reviews
|
|
92
|
+
measured): README's opt-in list gains the seven flags it was behind
|
|
93
|
+
(two of them since v0.51/v0.59), spec.md's structural section gains the
|
|
94
|
+
four v0.62.0 behavioral bullets and the safe-opt-in section for
|
|
95
|
+
`--fix-double-colon-tags`, the body counts read thirty/twenty-seven, and
|
|
96
|
+
AGENTS.md's inventory carries the five new flags. The v0.62.1 entry's
|
|
97
|
+
claim that the spec drift was closed was true only of the intro counts;
|
|
98
|
+
this entry closes the rest of it.
|
|
99
|
+
|
|
100
|
+
Suite: 895 tests.
|
|
101
|
+
|
|
3
102
|
## v0.62.1 (2026-11-04)
|
|
4
103
|
|
|
5
104
|
### --fix-double-colon-tags: the pseudo-tag escape, and the last fatal's repair
|
|
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "bindery-cli"
|
|
7
|
-
version = "0.
|
|
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 = [
|
|
@@ -57,6 +57,8 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
|
|
|
57
57
|
| 0.61.1 | The hex-ref href crash and the sweep that survives it: `_NUMERIC_REF_RE` captured the hex ref's `x` into the digits group and `int('x2013', 16)` killed the first whole-library `--all` dry run (2026-11-03 observe lane; 36 hex-ref hrefs across 5 books, every one an external URL the decode reaches before the scheme check discards it; dormant since v0.58.0 because the resolver is opt-in-path-only); the fix strips the prefix before the int, and the sweep's repair loop gains the crash guard -- an unexpected per-book exception is that book's `error` verdict (`crash (Type): ...; not applied`), counted in the existing errors tally, instead of a run-killing traceback (the single-file verb keeps its traceback) | v0.61.1 |
|
|
58
58
|
| 0.62 | The observatory batch (the 2026-11-03 lane's answers): three predicate repairs -- the playOrder contract goes base-free (epubcheck polices sharing/distinctness/gaps, never the base; 107 no-op renumberings silenced), `fix_pagelist_class` inserts the collision-checked id beside the class (class-only made epubcheck demand the id it enabled; the 215-rejection poison), `fix_missing_title` fills the self-closed `<title/>` (the paired-fill branch was dead code; the 70-rejection poison) -- and four new flags for the never-triaged census codes: `--fix-package-version` (OPF-001; literal 1.0 only), `--fix-doctype` (HTM-004; present-but-forbidden declarations only, after the firing census killed insertion), `--prune-invalid-guide-refs` (OPF-032; declared-but-not-a-content-doc targets), `--fix-item-properties` (OPF-014; EPUB3-only, scripted/svg/remote-resources from a whole-book census) | v0.62.0 |
|
|
59
59
|
| 0.62.1 | `--fix-double-colon-tags`: the pseudo-tag escape for the last library fatal -- an XML name carries at most one colon, so a `::`-named pseudo-tag is never markup (fatal RSC-016; the Book of Debugging's C++ samples), and escaping both ends restores the author's text; nested templates escape inner-first, real markup is unreachable by construction; also closes the spec.md drift (the four v0.62.0 flags had not joined the inventory) | v0.62.1 |
|
|
60
|
+
| 0.62.2 | The review batch (three-reviewer pass over the v0.62.x range): the item-properties insertion branch emitted malformed XML on the self-closed shape (attribute after the solidus; no test drove the branch -- every fixture pre-carried properties), now appends before the solidus with an ET-parsed pin; the missing-title empty-fill is head-scoped (an empty SVG `<title>` is visible text); the double-colon tail is bounded at 120 chars (the escaped-bracket runaway); the unverified on\* handler disjunct left the census; `_scan_doctype_span` refuses unterminated declarations; the guide-prune docstring matches the code; and the documentation inventories caught up (README's seven missing flags, spec.md's four behavioral bullets + body counts + the safe-opt-in section, AGENTS.md's inventory) | v0.62.2 |
|
|
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 |
|
|
60
62
|
|
|
61
63
|
## Open work
|
|
62
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
|
|
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
|
|
@@ -147,9 +148,27 @@ edit is anchored to real start tags; CDATA sections and comments are never
|
|
|
147
148
|
rewritten, and everything but the offending attribute is preserved
|
|
148
149
|
byte-for-byte. The normal gate applies.
|
|
149
150
|
|
|
151
|
+
### Opt-in: escape double-colon pseudo-tags (`--fix-double-colon-tags`)
|
|
152
|
+
|
|
153
|
+
An XML name can carry at most one colon (the QName production is
|
|
154
|
+
`(NCName ':')? NCName`), so a pseudo-tag whose name contains `::` is never
|
|
155
|
+
markup -- every occurrence is unescaped author text, and the parser dies on
|
|
156
|
+
it with a fatal RSC-016 (C++ code samples like `std::vector<std::shared_ptr>`
|
|
157
|
+
whose converter escaped the trailing bracket but not the tag itself). With
|
|
158
|
+
this flag both ends of the construct are escaped, restoring exactly the text
|
|
159
|
+
the author wrote; the result renders identically to that intent. Real markup
|
|
160
|
+
is unreachable by construction -- the double colon lives in the name grammar
|
|
161
|
+
-- and prose comparisons (`a < b`) never form the shape. Nested templates
|
|
162
|
+
escape inner-first until stable (capped at sixteen passes) and a fully
|
|
163
|
+
escaped nesting's trailing `>`s stay raw, which is legal text. The tail is
|
|
164
|
+
bounded at 120 characters so an escaped-bracket construct cannot swallow
|
|
165
|
+
prose plus real markup, and CDATA sections and comments are never rewritten.
|
|
166
|
+
The normal gate applies.
|
|
167
|
+
|
|
168
|
+
|
|
150
169
|
### Opt-in: structural repairs
|
|
151
170
|
|
|
152
|
-
|
|
171
|
+
Thirty repairs go past well-formedness and therefore require their own flag; none is ever
|
|
153
172
|
part of the default pipeline:
|
|
154
173
|
|
|
155
174
|
- **`--fix-empty-body`**: `<p> </p>` inside a strictly empty `<body></body>` ("body
|
|
@@ -160,12 +179,16 @@ part of the default pipeline:
|
|
|
160
179
|
Adds visible content, hence opt-in like `--add-img-alt`.
|
|
161
180
|
- **`--fix-missing-title`**: inject `<title>Unknown</title>` when the head has no usable
|
|
162
181
|
title.
|
|
163
|
-
- **`--fix-id-colons`**:
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
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.
|
|
169
192
|
- **`--unwrap-block-in-inline`**: drop a `<span>` that illegally wraps a
|
|
170
193
|
`<div>/<p>/<blockquote>`, keeping the block element and its text.
|
|
171
194
|
- **`--strip-invalid-value`**: remove misplaced `value="..."` attributes from non-form
|
|
@@ -437,7 +460,81 @@ leftovers whose failing OPF is a stale non-rootfile are unreachable by construct
|
|
|
437
460
|
byte-identical. Runs on the OPF only: content documents have the
|
|
438
461
|
invalid-attribute drop (`--strip-bad-attrs`) for the same defect class.
|
|
439
462
|
|
|
440
|
-
|
|
463
|
+
- **`--fix-package-version`**: rewrite a `<package>` element whose `version`
|
|
464
|
+
attribute is the literal `1.0` -- an EPUB version epubcheck cannot parse
|
|
465
|
+
(OPF-001 "error when parsing the EPUB version") -- to `"2.0"`, the
|
|
466
|
+
conformance the census's 25 carriers were all written to. Only the exact
|
|
467
|
+
literal qualifies: a missing attribute (the OEB-1.0-namespace package is a
|
|
468
|
+
migration, not an attribute bump) or any other spelling refuses the
|
|
469
|
+
document untouched, and the gate decides whether the profile
|
|
470
|
+
revalidation the bump buys is a real decrease.
|
|
471
|
+
|
|
472
|
+
- **`--fix-doctype`**: replace a content document's DOCTYPE when it carries a
|
|
473
|
+
public identifier its package profile forbids. EPUB 3 requires any DOCTYPE
|
|
474
|
+
to be `<!DOCTYPE html>` (an XHTML 1.x public doctype is a spec violation);
|
|
475
|
+
EPUB 2's OPS content docs are XHTML 1.1, so an XHTML 1.0 public doctype is
|
|
476
|
+
the census's second flagged shape. A whitespace-variant of the expected
|
|
477
|
+
form is a no-op, an ABSENT DOCTYPE is legal in both profiles and is left
|
|
478
|
+
alone (the first whole-library firing census measured insertion flat on
|
|
479
|
+
~2,400 of 2,545 firing books -- absent is tolerated, so insertion never
|
|
480
|
+
converges), and a DOCTYPE carrying an internal subset is never touched
|
|
481
|
+
(the subset declares entities; swapping it changes what the parser
|
|
482
|
+
resolves). An unterminated declaration refuses: a `<` at bracket depth 0
|
|
483
|
+
before any `>` means the true end is unknowable and the span must not
|
|
484
|
+
swallow the next tag.
|
|
485
|
+
|
|
486
|
+
- **`--prune-invalid-guide-refs`**: remove guide `<reference>` elements whose
|
|
487
|
+
target is declared in the manifest but is not an OPS content document
|
|
488
|
+
(OPF-032; the Random House `msr` guide block pointing cover/thumbimage
|
|
489
|
+
references at JPEGs is the dominant fingerprint). The guide is furniture,
|
|
490
|
+
so removal is content-neutral. A reference to an UNDECLARED file is
|
|
491
|
+
OPF-031 (declare-missing's lane) and is left alone, as are external
|
|
492
|
+
schemes and references with no href at all. Both element shapes are
|
|
493
|
+
removed: self-closed and the paired `<reference>...</reference>`.
|
|
494
|
+
|
|
495
|
+
- **`--fix-item-properties`**: the OPF-014 inverse of the attribute scrub --
|
|
496
|
+
declare what the document contains instead of stripping it. A whole-book
|
|
497
|
+
census reads each content document (`scripted` from a `<script>` element
|
|
498
|
+
or a `<form>`; `svg` from an `<svg>`; `remote-resources` from an
|
|
499
|
+
absolute-scheme `src`, a remote `<link href>`, or a remote CSS `url()`)
|
|
500
|
+
and merges the tokens into the owning manifest item's `properties`
|
|
501
|
+
attribute, sorted and deduplicated; the insertion branch appends the
|
|
502
|
+
attribute before a self-closed item's solidus, never after it. EPUB 3
|
|
503
|
+
packages only: on EPUB 2 the `properties` attribute is itself illegal
|
|
504
|
+
(the oracle demands it and forbids it at once), so those carriers refuse
|
|
505
|
+
and stay measured. on* handler attributes are deliberately not detected:
|
|
506
|
+
`\son[a-z]+=` lexically cannot tell a handler from `only=`/`once=`, and
|
|
507
|
+
the handler demand was never verified against the oracle the way the form
|
|
508
|
+
was.
|
|
509
|
+
|
|
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,
|
|
441
538
|
their benefit is visible to epubcheck (they clear errors), so a run with no measurable
|
|
442
539
|
improvement is a noop and nothing is applied. The three exceptions are `--fix-cover`, `--encode-url-spaces`, and
|
|
443
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.
|
|
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":
|