bindery-cli 1.1.0__tar.gz → 1.2.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-1.1.0 → bindery_cli-1.2.0}/AGENTS.md +11 -6
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/PKG-INFO +7 -6
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/README.md +6 -5
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/patchnotes.md +118 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/pyproject.toml +1 -1
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/roadmap.md +25 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/spec.md +48 -9
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/src/bindery/__init__.py +1 -1
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/src/bindery/cli.py +18 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/src/bindery/epub.py +195 -47
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/src/bindery/pagination.py +5 -1
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/src/bindery/transforms.py +68 -10
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_epub.py +412 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_flags_real_core.py +17 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_flags_wiring.py +1 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_pagination.py +26 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_transforms.py +141 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/uv.lock +1 -1
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/.github/FUNDING.yml +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/.github/workflows/ci.yml +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/.github/workflows/publish.yml +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/.gitignore +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/LICENSE +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/OBSERVE-RESEARCH.md +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/docs/screenshots/library-sweep.png +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/logo.svg +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/plugin/__init__.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/project.done +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/run_tests.sh +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/scripts/FastSweep.java +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/scripts/build_plugin.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/scripts/fast_sweep.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/src/bindery/__main__.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/src/bindery/audit.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/src/bindery/library.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/src/bindery/observe.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/src/bindery/reserialize.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/src/bindery/validate.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/src/bindery/watermark.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_audit.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_cli.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_comment_hyphens.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_contamination.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_cover_tocdrift.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_help.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_library.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_matcher_hardening.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_observe.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_plugin.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_reserialize.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_space_renames.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_spine_guard.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_validate.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_version.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_watermark.py +0 -0
- {bindery_cli-1.1.0 → bindery_cli-1.2.0}/tests/test_xml_hardening.py +0 -0
|
@@ -25,12 +25,17 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
|
|
|
25
25
|
external CLI dependency expected on PATH; `--install-to-calibre` needs no external
|
|
26
26
|
binary, it re-registers the format through cquarry's write module (the calibredb
|
|
27
27
|
subprocess was retired in v0.24.0). Before adding any further Python package, stop and ask.
|
|
28
|
+
- **CLI surface contract.** bindery is a reference implementation of the workspace CLI
|
|
29
|
+
machine-surface contract (`~/.gitrepos/CLAUDE.md`, Throughlines): machine help carries
|
|
30
|
+
exit contracts and gate annotations (`--help-json`), errors are one clean line on stderr
|
|
31
|
+
(never a traceback), missing-input paths are usage-class errors on stderr, and user-facing
|
|
32
|
+
surfaces are additive-only post-1.0 (spec-stated). Keep it that way.
|
|
28
33
|
- **Semantics-preserving transforms by default, everything else fenced behind a flag.**
|
|
29
34
|
The always-on core is exactly five well-formedness fixes (prolog junk, duplicate
|
|
30
35
|
`xmlns`, bare `&`, named entities, void self-closing), the NCX pipeline, and the
|
|
31
36
|
mimetype fix (added/normalized/first-stored, epub.py's archive rewrite); every core
|
|
32
37
|
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-
|
|
38
|
+
visible content. The canonical opt-in inventory lives in spec.md: thirty-five structural
|
|
34
39
|
repairs, four lossy strips, five safe opt-ins, plus `--reserialize` (the
|
|
35
40
|
seven v0.62.x/v0.63.0 flags -- `--fix-package-version`, `--fix-doctype`,
|
|
36
41
|
`--prune-invalid-guide-refs`, `--fix-item-properties`,
|
|
@@ -48,7 +53,7 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
|
|
|
48
53
|
`--fix-unbound-prefix`, `--fix-package-version`, `--fix-doctype`,
|
|
49
54
|
`--prune-invalid-guide-refs`, `--fix-item-properties`,
|
|
50
55
|
`--strip-presentational-attrs`, `--encode-ref-brackets`,
|
|
51
|
-
`--encode-ref-delims`,
|
|
56
|
+
`--encode-ref-delims`, `--strip-dead-font-faces`,
|
|
52
57
|
`--prune-dead-spine`;
|
|
53
58
|
transforms.py, threaded through epub.py). The v0.47.0 five (the 2026-10-06
|
|
54
59
|
issue batch): `--fix-svg-dup-ids` renames duplicate glyph ids inside
|
|
@@ -273,22 +278,22 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
|
|
|
273
278
|
|
|
274
279
|
## Layout
|
|
275
280
|
|
|
276
|
-
- `src/bindery/transforms.py`: pure `str -> (str, int)` text transforms (including `strip_broken_tags`). Since v0.55.0 `fix_svg_dup_ids` and `fix_duplicate_ids` share `_rename_duplicate_ids` (first-keeps-name, `_2`/`_3` suffixes, references never rewritten; since v0.58.0 comment/CDATA-hidden tags do not count -- counting them renamed the real definition away, issue #21); the SVG flag owns standalone `.svg` entries, the content-doc flag owns `.xhtml`/`.html`/`.htm`/`.xml`. Since v0.58.0 (issue #19) `encode_url_spaces` anchors on `_START_TAG_OR_PI_RE` (start tags plus xml-stylesheet-style processing instructions, prefix-disjoint branches, possessive loops) instead of the bare attribute regex: display text that TEACHES HTML carries `href="..."`, and the unanchored regex paired the phantom quote with the next real tag, encoding a space into the element name (two RSC-016 fatals on Hacking: The Next Generation); epub.py's `rewrite_space_renames` anchors on the same matcher (its PI branch is what keeps xml-stylesheet hrefs rewritten after the anchoring). Since v0.32.0: `strip_attrs_in_start_tags` anchors attribute edits on the quote-aware start-tag matcher, `_outside_protected` forwards arguments (context-carrying transforms can be decorated), `fix_id_colons` matches only the bare `id` attribute and only internal fragments (`fix_ncx_src_fragments` carries renames into the NCX), `fix_ncx_playorder` is anchored to `<navPoint>` start tags, and the css selector boundary covers namespaced and functional selector forms. HAZARD (the 0.41.0 spin): the quote-aware tag-prefix alternation (double-quoted | single-quoted | [^>]) OVERLAPS ([^>] matches quotes too), so a plain `*` re-partitions exponentially on failing candidates; every such greedy loop must carry the possessive `*+` (re 3.11+, the plugin's minimum Calibre). Since v0.42.0 the census is complete and pinned by tests/test_matcher_hardening.py: every greedy loop of this family is possessive (the three 0.41.1 rewrites plus _START_TAG_RE, _COVER_META_RE, _GUIDE_REF_RE, prune_dangling_edges' spine|item|itemref matcher, _ITEM_TAG_RE, _SPINE_ITEM_RE; possessive is byte-identical on success because the loop is always followed by a literal `>` the [^>] branch cannot consume), and the five LAZY siblings (_VOID_RE, the transforms <img> matcher, and epub's link/a/img matchers) use the disjoint catch-all `[^>"']` instead: mutually exclusive branches cannot re-partition, and an unterminated quote inside a tag now fails to match rather than pairing across markup. NEW tag matchers: quote-aware possessive for greedy loops, the disjoint catch-all for lazy ones, and the tempered-quote idiom (["'])((?:(?!\1).)*)\1 for attribute values. Since v0.37.0: `fix_ncx_playorder` strips quotes before its already-correct comparison (regex groups carry quote characters; comparing quoted values against bare numbers counted phantom fixes on every sequential NCX and rewrote single-quoted correct attributes to double quotes). Since v0.54.0 (the 2026-10-24 surgery): `fix_ncx_playorder` is CONTRACT-GATED -- it tokenizes navPoint/navTarget/pageTarget start tags plus their `<content src>` targets, returns unchanged when the NCX already satisfies epubcheck's playOrder contract (same target shares one value, distinct targets distinct values, values contiguous 1..K), and re-sequences by first-appearance target order only on a violation; the old unconditional 1..N renumbering rewrote valid TOCs into violations (211 of 579 firings gate-rejected, 17 real fixes, 347 no-ops). The same fix extends `_PROTECTED_RE` with the Calibre `/*<![CDATA[*/ ... /*]]>*/` wrapper as one protected unit (the bare CDATA alternative ends inside the closing `/*]]>`, which exposed the trailing `*/` to strip_prolog_junk's amputation: 111 phantom-fix rejections).
|
|
277
|
-
- `src/bindery/pagination.py`: the opt-in lossy page-number strip (runhead detection, page-layer decision, block-centric removal/merge, safety nets).
|
|
281
|
+
- `src/bindery/transforms.py`: pure `str -> (str, int)` text transforms (including `strip_broken_tags`). Since v0.55.0 `fix_svg_dup_ids` and `fix_duplicate_ids` share `_rename_duplicate_ids` (first-keeps-name, `_2`/`_3` suffixes, references never rewritten; since v0.58.0 comment/CDATA-hidden tags do not count -- counting them renamed the real definition away, issue #21); the SVG flag owns standalone `.svg` entries, the content-doc flag owns `.xhtml`/`.html`/`.htm`/`.xml`. Since v0.58.0 (issue #19) `encode_url_spaces` anchors on `_START_TAG_OR_PI_RE` (start tags plus xml-stylesheet-style processing instructions, prefix-disjoint branches, possessive loops) instead of the bare attribute regex: display text that TEACHES HTML carries `href="..."`, and the unanchored regex paired the phantom quote with the next real tag, encoding a space into the element name (two RSC-016 fatals on Hacking: The Next Generation); epub.py's `rewrite_space_renames` anchors on the same matcher (its PI branch is what keeps xml-stylesheet hrefs rewritten after the anchoring). Since v0.32.0: `strip_attrs_in_start_tags` anchors attribute edits on the quote-aware start-tag matcher, `_outside_protected` forwards arguments (context-carrying transforms can be decorated), `fix_id_colons` matches only the bare `id` attribute and only internal fragments (`fix_ncx_src_fragments` carries renames into the NCX), `fix_ncx_playorder` is anchored to `<navPoint>` start tags, and the css selector boundary covers namespaced and functional selector forms. HAZARD (the 0.41.0 spin): the quote-aware tag-prefix alternation (double-quoted | single-quoted | [^>]) OVERLAPS ([^>] matches quotes too), so a plain `*` re-partitions exponentially on failing candidates; every such greedy loop must carry the possessive `*+` (re 3.11+, the plugin's minimum Calibre). Since v0.42.0 the census is complete and pinned by tests/test_matcher_hardening.py: every greedy loop of this family is possessive (the three 0.41.1 rewrites plus _START_TAG_RE, _COVER_META_RE, _GUIDE_REF_RE, prune_dangling_edges' spine|item|itemref matcher, _ITEM_TAG_RE, _SPINE_ITEM_RE; possessive is byte-identical on success because the loop is always followed by a literal `>` the [^>] branch cannot consume), and the five LAZY siblings (_VOID_RE, the transforms <img> matcher, and epub's link/a/img matchers) use the disjoint catch-all `[^>"']` instead: mutually exclusive branches cannot re-partition, and an unterminated quote inside a tag now fails to match rather than pairing across markup. NEW tag matchers: quote-aware possessive for greedy loops, the disjoint catch-all for lazy ones, and the tempered-quote idiom (["'])((?:(?!\1).)*)\1 for attribute values. Since v0.37.0: `fix_ncx_playorder` strips quotes before its already-correct comparison (regex groups carry quote characters; comparing quoted values against bare numbers counted phantom fixes on every sequential NCX and rewrote single-quoted correct attributes to double quotes). Since v0.54.0 (the 2026-10-24 surgery): `fix_ncx_playorder` is CONTRACT-GATED -- it tokenizes navPoint/navTarget/pageTarget start tags plus their `<content src>` targets, returns unchanged when the NCX already satisfies epubcheck's playOrder contract (same target shares one value, distinct targets distinct values, values contiguous 1..K), and re-sequences by first-appearance target order only on a violation; the old unconditional 1..N renumbering rewrote valid TOCs into violations (211 of 579 firings gate-rejected, 17 real fixes, 347 no-ops). The same fix extends `_PROTECTED_RE` with the Calibre `/*<![CDATA[*/ ... /*]]>*/` wrapper as one protected unit (the bare CDATA alternative ends inside the closing `/*]]>`, which exposed the trailing `*/` to strip_prolog_junk's amputation: 111 phantom-fix rejections). Since v1.1.1 (issue #28) `fix_ncx_src_fragments` follows the FULL `fix_id_colons` predicate (`_is_invalid_ncname` + `_ncname_rename`, not colon-only: a digit-led ToC fragment follows the `id_` rename instead of dangling, a digit-led colon-bearing id translates to the same spelling on both sides) and both fragment passes (NCX `src` and the content `href`) carry the tempered-quote idiom, so an apostrophe in a double-quoted value (`#Lisey's_story`) translates whole instead of truncating at the apostrophe; the matchers are whitespace-anchored with the optional namespace prefix (`xlink:href` in, `data-href`/`data-src` out), and an ESCAPED fragment (a percent-escape or an entity reference) is refused outright -- it names its target under decoding, not NCName spelling, and renaming the encoded form would manufacture a target that exists nowhere, undoing the #29 decode match whenever both flags run (`--all` always does); the same release gives `_SVG_ID_ATTR_RE` the `(?<![\w:.-])` lookbehind (issue #30: `\bid=` fired right after the hyphen of `data-id`, making the real `id="c1"` a "duplicate" and renaming it away from its fragments).
|
|
282
|
+
- `src/bindery/pagination.py`: the opt-in lossy page-number strip (runhead detection, page-layer decision, block-centric removal/merge, safety nets). Since v1.1.1 (issue #31) `_P_RE` refuses a self-closing start tag (`(?<!/)` before the closing `>`): `<p class="divider"/>` has no `</p>` of its own, so a match starting there ran to the NEXT paragraph's close and welded the divider markup into a block whose text could read as a page number.
|
|
278
283
|
- `src/bindery/watermark.py`: the opt-in lossy watermark strip (anchored and anchorless signature removal).
|
|
279
284
|
- `src/bindery/reserialize.py`: structural repair via `html5lib`.
|
|
280
285
|
- `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, v0.64.0 wires `--prune-dead-spine` (the shell repair, 50%-signature-gated, playOrder force re-sequence); since v1.1.0 (issue #26) the loader counts `spine_missing_delim` (itemrefs whose raw `#`/`?` defeated resolution while the delim-encoded spelling finds the shipped file) and the shell verdict runs on the genuine fraction, so a fully-recoverable book reads ADVISORY naming `--encode-ref-delims`, never SHELL/re-source) 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).
|
|
281
286
|
- `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
|
|
282
287
|
character references before the fragment split (attribute text arrives
|
|
283
288
|
escaped; entries are raw; decoding first keeps the `#` inside `&`
|
|
284
|
-
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).
|
|
289
|
+
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). Since v1.1.1 (the audit batch, issues #28-#33): `_norm_fragment` decodes a fragment the way `_resolve_href` decodes a path (XML entities, then RFC 3986 percent) before every anchor-cleaner existence check, so `#caf%C3%A9` matches `id="café"` instead of reading as broken (#29, the content/NCX/guide halves alike); `_ITEM_ID_RE`/`_XML_ID_RE` carry the `(?<![\w:.-])id=` lookbehind (`data-id`/`xml:id` are not ids: the manifest half renamed a `data-id` while the item's real id stayed; #30), while `ids_by_doc` collects through the dedicated `_ANCHOR_ID_RE` (`(?:xml:)?id`) because xml:id is a real XML id the oracle resolves fragments against -- dropping it from the anchor set would strip links the oracle never flagged; `downgrade_epub3_tags` runs through `outside_protected_map` and `_append_class`'s class matcher is whitespace-anchored (the unshielded `re.sub` downgraded commented-out markup and the bare `class=` merged into `data-class`; #32); and `declare_missing_manifest_items` locates the manifest close tag through `_MANIFEST_CLOSE_RE` (`</(?:[\w.-]+:)?manifest\s*>`: the literal `"</manifest>"` check/replace silently no-opped on prefixed and whitespace spellings; #33). Since v1.2.0 (issue #27) `strip_dead_font_faces` is the CSS-side dead `@font-face` drop (`--strip-dead-font-faces`): ebook-convert azw3->epub carries the source's font declarations without the payloads, filling the page_styles sheets with `url(styles/XXXXXXXXXXXXXXXX)` placeholders (one RSC-007 per dead reference; the manifest prune has no item to answer, so `--all` never converges); a block whose EVERY url() misses the archive drops rendering-neutral (the font never loaded), one live url() -- or a scheme/query/fragment/raw-space/local()-only reference (first #/? starts fragment/query, the #26 oracle model), or nested braces the flat-brace matcher cannot read exactly -- keeps it; resolution walks `_resolve_href` against the existence set (`present_src` when renames are licensed: the pass runs FIRST in the CSS branch, before `rewrite_space_renames_css`); XML comments/CDATA (`outside_protected_map`) AND plain CSS comments (`_CSS_COMMENT_SPAN_RE` spans, an INTERSECTION over the whole match: a `}` inside a comment truncates the match and a start-keyed drop would leave comment garbage -- `_PROTECTED_RE` covers XML comments only) are never rewritten; runs on `.css` entries only, and the flag joins the CSS branch gate and the `present`/`present_src` condition list.
|
|
285
290
|
- `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.
|
|
286
291
|
- `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.
|
|
287
292
|
- `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. Since v1.1.0 (issue #26) the `refs_delim_encoded` keyed promotion carries the missing-file mask bar above the gate's error-cleanup answer (net-new fatals reject, still-fatal partial, fatal-free accepts the unmasking rise; the veto still overrides). `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
|
|
288
293
|
custom-rendered and colors itself with the CPython 3.14 argparse theme,
|
|
289
294
|
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.
|
|
290
295
|
- `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.
|
|
291
|
-
- `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`. The v1.1.0 additions (issue #26): `tests/test_epub.py::TestEncodeDelimRefs` (the two gates, CSS/NCX/OPF shapes, display-text and comment exclusion, idempotence, and the repair-level guard+encode end-to-end) plus `TestPruneDeadSpine`'s mixed-census case (genuine dead + recoverable prunes only the genuine), `tests/test_spine_guard.py::DelimPromotionTests` (accept under the unmasking rise, net-new fatals reject, still-fatal partial, the veto still overrides) and `DelimFixtureRegressionTests` over the real facility fixture (no amputation, 36 encoded, spine 0 dangles), and `tests/test_contamination.py::TestShellAnalyzer`'s recoverable/mixed/true-shell trio.
|
|
296
|
+
- `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`. The v1.1.0 additions (issue #26): `tests/test_epub.py::TestEncodeDelimRefs` (the two gates, CSS/NCX/OPF shapes, display-text and comment exclusion, idempotence, and the repair-level guard+encode end-to-end) plus `TestPruneDeadSpine`'s mixed-census case (genuine dead + recoverable prunes only the genuine), `tests/test_spine_guard.py::DelimPromotionTests` (accept under the unmasking rise, net-new fatals reject, still-fatal partial, the veto still overrides) and `DelimFixtureRegressionTests` over the real facility fixture (no amputation, 36 encoded, spine 0 dangles), and `tests/test_contamination.py::TestShellAnalyzer`'s recoverable/mixed/true-shell trio. The v1.1.1 additions (issues #28-#33): `tests/test_transforms.py::TestIssue28FragmentSync` (digit-led/apostrophe NCX and href fragments follow the full predicate; valid and external fragments untouched) and `TestIssue30DataIdLookbehind` (data-id/xml:id never seed a duplicate rename; the real duplicate beside one still renames), `tests/test_epub.py::TestIssue29PercentDecodedFragments` (percent-encoded café/Cyrillic fragments survive across the anchor/NCX/guide halves; the ghost controls still strip, one per cleaner), `TestIssue30OpfIdLookbehind` (manifest/NCX `data-id` not renamed; the real digit-led id renames beside it), `TestIssue32DowngradeGuards` (`data-class` never merged, comment/CDATA untouched beside a real downgrade), `TestIssue33ManifestCloseTag` (prefixed and whitespace close tags declare; the original spelling survives), and `tests/test_pagination.py::TestSelfClosingParagraphs` (a self-closing divider never welds into a stripped block; the conservative path tolerates it). The pre-commit review additions: `tests/test_transforms.py::TestIssue28EscapedFragmentRefusal` (percent-encoded/entity-ref fragments refused in both passes, data-href/data-src out of scope, xlink:href still covered) and `tests/test_epub.py::TestIssue30XmlIdAnchorTarget` (a link targeting an xml:id-declared anchor survives `--strip-broken-anchors`). The v1.2.0 additions (issue #27): `tests/test_epub.py::TestStripDeadFontFaces` (dead block dropped, live/mixed/scheme/local-only/fragment/space blocks kept, nested-brace refusal, XML- and CSS-comment protection, idempotence, the repair-level end-to-end) and `TestStripDeadFontFacesReviewEdges` (query-carrying references refused live or dead, the comment-`}` truncation refusing the drop) plus the fixture + row in `tests/test_flags_real_core.py` and the wiring entry in `tests/test_flags_wiring.py`.
|
|
292
297
|
|
|
293
298
|
## Conventions
|
|
294
299
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: bindery-cli
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.2.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
|
|
@@ -62,19 +62,20 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
|
|
|
62
62
|
- **`--reserialize`**: rebuild content documents that are still malformed by re-parsing them with html5lib and re-emitting XHTML, closing unclosed `<p>`/`<div>`/`<span>`/`<blockquote>` that the regex transforms cannot. Runs only on documents that are not already well-formed, so good files are untouched.
|
|
63
63
|
- **`--strip-bad-attrs`**: drop attributes that are invalid XML (a name starting with a digit, or a namespaced name whose prefix is never declared, like Office VML `v:shapes`). Surgical and a no-op on well-formed files.
|
|
64
64
|
- **`--escape-unknown-entities`**: escape entity names that are not in the HTML5 table (`&foo;` becomes `&foo;`), which renders exactly as browsers already render an unknown entity. Documents whose DOCTYPE carries an internal subset are skipped wholesale, since a subset can declare custom entities.
|
|
65
|
-
- **`--fix-id-colons`**: translates illegal colons in `id="X:Y"` and their matching internal `#X:Y` fragment references to valid underscores. External URL fragments are left verbatim (they name positions in other documents), `data-id` values are never touched, and the NCX's `content src` fragments follow the rename so the table of contents never dangles against the ids it references.
|
|
65
|
+
- **`--fix-id-colons`**: translates illegal colons in `id="X:Y"` and their matching internal `#X:Y` fragment references to valid underscores. External URL fragments are left verbatim (they name positions in other documents), `data-id` values are never touched, and the NCX's `content src` fragments follow the rename (under the same invalid-NCName predicate since v1.1.1) so the table of contents never dangles against the ids it references.
|
|
66
66
|
- **`--fix-empty-body`**: gives a strictly empty `<body></body>` one minimal paragraph (`<p> </p>`) to clear the "body incomplete" error. The numeric character reference needs no DTD and the wrapping `p` is the block element XHTML 1.1's body content model requires.
|
|
67
67
|
- **`--fix-missing-title`**: injects a `<title>Unknown</title>` fallback in the `<head>` if missing, handling both empty `<title/>` self-closing tags and entirely absent tags.
|
|
68
68
|
- **`--unwrap-block-in-inline`**: safely unwraps `<span>` tags that illegally contain a block-level element (e.g. `<div>` or `<p>`), leaving the block element intact.
|
|
69
69
|
- **`--strip-invalid-value`**: systematically strips invalid `value="..."` attributes from elements like `<div>`, `<span>`, `<p>`, etc.
|
|
70
70
|
- **`--fix-page-map`**: normalizes legacy page-map markup: drops the non-standard `page-map="..."` attribute from the OPF `<spine>` and adds `class="pages"` to classless NCX `<pageList>` elements (epubcheck rejects both on older HarperCollins / Anna's Archive conversions).
|
|
71
71
|
- **`--strip-epub3-attrs`**: scrubs the EPUB3-only attributes epubcheck rejects on an EPUB2 package: `page-progression-direction`, `epub:type`, `aria-label`, `role`, `aria-hidden` (a fixed, documented set; rendering is unchanged, and lookalikes like `type` or `aria-labelledby` survive; `hidden` stays, since stripping it would reveal hidden content). The edit is anchored to real start tags, so prose that merely mentions `epub:type="chapter"` is preserved.
|
|
72
|
-
- **`--downgrade-epub3-tags`**: downgrades EPUB3/HTML5 semantic elements to their EPUB2 equivalents (`figure`/`section` to `div`, `figcaption` to `p`), keeping existing classes and appending the semantic name (`class="figure"`) as the styling hook. Tag names a stylesheet styles as an element selector are protected book-wide, so styled formatting is never destroyed. Both EPUB2-targeted fixes are gated on the package version declared in the OPF: on an EPUB 3 book they do nothing, because their target defects only exist below EPUB 3.
|
|
72
|
+
- **`--downgrade-epub3-tags`**: downgrades EPUB3/HTML5 semantic elements to their EPUB2 equivalents (`figure`/`section` to `div`, `figcaption` to `p`), keeping existing classes and appending the semantic name (`class="figure"`) as the styling hook. Tag names a stylesheet styles as an element selector are protected book-wide, so styled formatting is never destroyed. Comments and CDATA are never rewritten, and a `data-class` attribute is never mistaken for the class hook. Both EPUB2-targeted fixes are gated on the package version declared in the OPF: on an EPUB 3 book they do nothing, because their target defects only exist below EPUB 3.
|
|
73
73
|
- **`--unwrap-illegal-tags`**: strips completely invalid or deprecated HTML tags that break EPUB3 validation (`<st>`, `<sentence>`, `<o>`, `<w>`, `<pagebreak>`) while retaining their inner text. Any of those names styled as an *element selector* by an EPUB stylesheet (`.css` entries and inline `<style>` blocks alike; class/id selectors like `.st`/`#w` don't count) is protected for the whole book, guaranteeing format preservation.
|
|
74
|
-
- **`--declare-missing-items`**: the RSC-008 inverse of the prune: adds the manifest `<item>` declarations the OPF never wrote for files the archive carries and the book references (content `<img src>`/`<link href>` targets, CSS `url()` resources, OPF guide references). Deterministic ids, media types from a blessed extension map only, and no `<itemref>` is ever written: the spine is untouched.
|
|
74
|
+
- **`--declare-missing-items`**: the RSC-008 inverse of the prune: adds the manifest `<item>` declarations the OPF never wrote for files the archive carries and the book references (content `<img src>`/`<link href>` targets, CSS `url()` resources, OPF guide references). Deterministic ids, media types from a blessed extension map only, and no `<itemref>` is ever written: the spine is untouched. Namespace-prefixed packages (`</opf:manifest>`) declare too (v1.1.1).
|
|
75
75
|
- **`--fix-unique-identifier`**: wires the dangling OPF unique-identifier (OPF-030): adds the id the package names to the first `dc:identifier` when no element carries it, and aligns the NCX `dtb:uid` the broken wiring was masking in the same run. The `dc:` values are never touched; ambiguous shapes refuse.
|
|
76
76
|
- **`--prune-missing-resources`**: removes references to files the archive does not contain (RSC-007/PKG-010): dead `<link>` elements, anchors' `href` to absent files (anchor text preserved), absent `<img>` sources (replaced by their alt text when they carry one), and orphaned non-spine OPF manifest items (with every package edge that pointed at them rewritten: `spine@toc`, `item@media-overlay`, `item@fallback`, and the EPUB2 cover meta). Spine documents are never pruned: a missing spine document is reported as a damaged fragment, not silently dropped.
|
|
77
|
-
- **`--strip-
|
|
77
|
+
- **`--strip-dead-font-faces`**: drops every `@font-face` block in a stylesheet whose `url()` references ALL miss the archive (v1.2.0, issue #27). ebook-convert's azw3→epub carries the source's font declarations without the font payloads, filling `page_styles.css` with `url(styles/XXXXXXXXXXXXXXXX)` placeholders: hundreds of RSC-007s per book that the manifest prune cannot reach (the OPF never declared the fonts) and where `--all` never converges. The font never loaded, so the fallback rendering is what the file already does and the drop is rendering-neutral. One live `url()` keeps the whole block; scheme, query, fragment, raw-space, and `local()`-only blocks are never guessed at; comments (XML and CSS alike) are never rewritten. Runs on `.css` entries.
|
|
78
|
+
- **`--strip-broken-anchors`**: strips href attributes that cannot resolve, keeping the anchor text byte-for-byte: a `#fragment` the target document does not define (RSC-020/RSC-012; NCX navTargets fall back to the document target, so chapter navigation survives) and unresolvable URI schemes (`kindle:`, `file:`). Fragments are percent-decoded before the existence check, so valid links to non-ASCII ids (`#caf%C3%A9` naming `id="café"`) are kept (v1.1.1).
|
|
78
79
|
- **`--encode-url-spaces`**: percent-encodes raw spaces in `src`/`href` attribute values across the package (OPF manifest, NCX, content documents). A URL with a literal space is not a valid URL (RSC-020) and unresolvable on strict readers; the encoded form denotes the same file. Since v0.44.0 the flag also renames archive entries whose names carry raw spaces to their underscore spellings and rewrites every reference to them (OPF, NCX, content, CSS `url()`), clearing the PKG-010 space-in-filename advisories: underscore, never percent-encoding, because epubcheck decodes references before entry lookup.
|
|
79
80
|
- **`--fix-container`**: generates `META-INF/container.xml` at the located OPF when the container is missing or names a file the archive does not contain. This is the gateway defect: epubcheck stays fatal while the OPF is unfindable, so no repair can be gate-accepted on such a book until the container exists.
|
|
80
81
|
- **`--fix-media-types`**: normalizes wrong manifest media-type declarations (OPF-029, e.g. a jpg stamped `image/png` by an aggregator). Attribute-only and quote-preserving; it fires only when the file's magic bytes confirm the extension, so a misnamed-but-consistent file (a PNG renamed .jpg) is never made worse. Since v0.56.0 it also covers the CSS-007 font slice (a `ttf`/`otf`/`woff`/`woff2` declared outside epubcheck's blessed font set is rewritten to its `font/*` spelling when the magic bytes confirm; `.eot` is never touched), and the flag is accepted under the no-worse bar because that half's gain sits on the INFO axis.
|
|
@@ -96,7 +97,7 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
|
|
|
96
97
|
|
|
97
98
|
- **`--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.
|
|
98
99
|
- **`--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.
|
|
99
|
-
- **`--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.
|
|
100
|
+
- **`--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. Since v1.1.1 the NCX half follows the same predicate (a digit-led ToC fragment follows the `id_` rename instead of dangling against it) and the quote-tempered fragment matchers translate an apostrophe-bearing value (`href="c1.xhtml#Lisey's_story"`) whole. An escaped fragment (a percent-escape like `#caf%C3%A9` or an entity reference) passes through untouched: it names its target under decoding, and renaming the encoded form would manufacture a target that exists nowhere.
|
|
100
101
|
- **`--prune-dead-spine`**: the shell repair — fires ONLY when half or more of the manifest's content hrefs name files the archive never carried (the audit battery's `shell` analyzer names the same shape). Drops the dead manifest items, the spine itemrefs that name them, and the dead NCX navPoints, then re-sequences the surviving playOrders to 1..K. A lone missing chapter never crosses the signature: the spine non-goal stays in force for ordinary damage. The Wandering Inn serial shells (738 and 736 of 755/752 items dead) are the design case; proven at 742e → 5e with 0 fatals.
|
|
101
102
|
|
|
102
103
|
Four opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
|
|
@@ -35,19 +35,20 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
|
|
|
35
35
|
- **`--reserialize`**: rebuild content documents that are still malformed by re-parsing them with html5lib and re-emitting XHTML, closing unclosed `<p>`/`<div>`/`<span>`/`<blockquote>` that the regex transforms cannot. Runs only on documents that are not already well-formed, so good files are untouched.
|
|
36
36
|
- **`--strip-bad-attrs`**: drop attributes that are invalid XML (a name starting with a digit, or a namespaced name whose prefix is never declared, like Office VML `v:shapes`). Surgical and a no-op on well-formed files.
|
|
37
37
|
- **`--escape-unknown-entities`**: escape entity names that are not in the HTML5 table (`&foo;` becomes `&foo;`), which renders exactly as browsers already render an unknown entity. Documents whose DOCTYPE carries an internal subset are skipped wholesale, since a subset can declare custom entities.
|
|
38
|
-
- **`--fix-id-colons`**: translates illegal colons in `id="X:Y"` and their matching internal `#X:Y` fragment references to valid underscores. External URL fragments are left verbatim (they name positions in other documents), `data-id` values are never touched, and the NCX's `content src` fragments follow the rename so the table of contents never dangles against the ids it references.
|
|
38
|
+
- **`--fix-id-colons`**: translates illegal colons in `id="X:Y"` and their matching internal `#X:Y` fragment references to valid underscores. External URL fragments are left verbatim (they name positions in other documents), `data-id` values are never touched, and the NCX's `content src` fragments follow the rename (under the same invalid-NCName predicate since v1.1.1) so the table of contents never dangles against the ids it references.
|
|
39
39
|
- **`--fix-empty-body`**: gives a strictly empty `<body></body>` one minimal paragraph (`<p> </p>`) to clear the "body incomplete" error. The numeric character reference needs no DTD and the wrapping `p` is the block element XHTML 1.1's body content model requires.
|
|
40
40
|
- **`--fix-missing-title`**: injects a `<title>Unknown</title>` fallback in the `<head>` if missing, handling both empty `<title/>` self-closing tags and entirely absent tags.
|
|
41
41
|
- **`--unwrap-block-in-inline`**: safely unwraps `<span>` tags that illegally contain a block-level element (e.g. `<div>` or `<p>`), leaving the block element intact.
|
|
42
42
|
- **`--strip-invalid-value`**: systematically strips invalid `value="..."` attributes from elements like `<div>`, `<span>`, `<p>`, etc.
|
|
43
43
|
- **`--fix-page-map`**: normalizes legacy page-map markup: drops the non-standard `page-map="..."` attribute from the OPF `<spine>` and adds `class="pages"` to classless NCX `<pageList>` elements (epubcheck rejects both on older HarperCollins / Anna's Archive conversions).
|
|
44
44
|
- **`--strip-epub3-attrs`**: scrubs the EPUB3-only attributes epubcheck rejects on an EPUB2 package: `page-progression-direction`, `epub:type`, `aria-label`, `role`, `aria-hidden` (a fixed, documented set; rendering is unchanged, and lookalikes like `type` or `aria-labelledby` survive; `hidden` stays, since stripping it would reveal hidden content). The edit is anchored to real start tags, so prose that merely mentions `epub:type="chapter"` is preserved.
|
|
45
|
-
- **`--downgrade-epub3-tags`**: downgrades EPUB3/HTML5 semantic elements to their EPUB2 equivalents (`figure`/`section` to `div`, `figcaption` to `p`), keeping existing classes and appending the semantic name (`class="figure"`) as the styling hook. Tag names a stylesheet styles as an element selector are protected book-wide, so styled formatting is never destroyed. Both EPUB2-targeted fixes are gated on the package version declared in the OPF: on an EPUB 3 book they do nothing, because their target defects only exist below EPUB 3.
|
|
45
|
+
- **`--downgrade-epub3-tags`**: downgrades EPUB3/HTML5 semantic elements to their EPUB2 equivalents (`figure`/`section` to `div`, `figcaption` to `p`), keeping existing classes and appending the semantic name (`class="figure"`) as the styling hook. Tag names a stylesheet styles as an element selector are protected book-wide, so styled formatting is never destroyed. Comments and CDATA are never rewritten, and a `data-class` attribute is never mistaken for the class hook. Both EPUB2-targeted fixes are gated on the package version declared in the OPF: on an EPUB 3 book they do nothing, because their target defects only exist below EPUB 3.
|
|
46
46
|
- **`--unwrap-illegal-tags`**: strips completely invalid or deprecated HTML tags that break EPUB3 validation (`<st>`, `<sentence>`, `<o>`, `<w>`, `<pagebreak>`) while retaining their inner text. Any of those names styled as an *element selector* by an EPUB stylesheet (`.css` entries and inline `<style>` blocks alike; class/id selectors like `.st`/`#w` don't count) is protected for the whole book, guaranteeing format preservation.
|
|
47
|
-
- **`--declare-missing-items`**: the RSC-008 inverse of the prune: adds the manifest `<item>` declarations the OPF never wrote for files the archive carries and the book references (content `<img src>`/`<link href>` targets, CSS `url()` resources, OPF guide references). Deterministic ids, media types from a blessed extension map only, and no `<itemref>` is ever written: the spine is untouched.
|
|
47
|
+
- **`--declare-missing-items`**: the RSC-008 inverse of the prune: adds the manifest `<item>` declarations the OPF never wrote for files the archive carries and the book references (content `<img src>`/`<link href>` targets, CSS `url()` resources, OPF guide references). Deterministic ids, media types from a blessed extension map only, and no `<itemref>` is ever written: the spine is untouched. Namespace-prefixed packages (`</opf:manifest>`) declare too (v1.1.1).
|
|
48
48
|
- **`--fix-unique-identifier`**: wires the dangling OPF unique-identifier (OPF-030): adds the id the package names to the first `dc:identifier` when no element carries it, and aligns the NCX `dtb:uid` the broken wiring was masking in the same run. The `dc:` values are never touched; ambiguous shapes refuse.
|
|
49
49
|
- **`--prune-missing-resources`**: removes references to files the archive does not contain (RSC-007/PKG-010): dead `<link>` elements, anchors' `href` to absent files (anchor text preserved), absent `<img>` sources (replaced by their alt text when they carry one), and orphaned non-spine OPF manifest items (with every package edge that pointed at them rewritten: `spine@toc`, `item@media-overlay`, `item@fallback`, and the EPUB2 cover meta). Spine documents are never pruned: a missing spine document is reported as a damaged fragment, not silently dropped.
|
|
50
|
-
- **`--strip-
|
|
50
|
+
- **`--strip-dead-font-faces`**: drops every `@font-face` block in a stylesheet whose `url()` references ALL miss the archive (v1.2.0, issue #27). ebook-convert's azw3→epub carries the source's font declarations without the font payloads, filling `page_styles.css` with `url(styles/XXXXXXXXXXXXXXXX)` placeholders: hundreds of RSC-007s per book that the manifest prune cannot reach (the OPF never declared the fonts) and where `--all` never converges. The font never loaded, so the fallback rendering is what the file already does and the drop is rendering-neutral. One live `url()` keeps the whole block; scheme, query, fragment, raw-space, and `local()`-only blocks are never guessed at; comments (XML and CSS alike) are never rewritten. Runs on `.css` entries.
|
|
51
|
+
- **`--strip-broken-anchors`**: strips href attributes that cannot resolve, keeping the anchor text byte-for-byte: a `#fragment` the target document does not define (RSC-020/RSC-012; NCX navTargets fall back to the document target, so chapter navigation survives) and unresolvable URI schemes (`kindle:`, `file:`). Fragments are percent-decoded before the existence check, so valid links to non-ASCII ids (`#caf%C3%A9` naming `id="café"`) are kept (v1.1.1).
|
|
51
52
|
- **`--encode-url-spaces`**: percent-encodes raw spaces in `src`/`href` attribute values across the package (OPF manifest, NCX, content documents). A URL with a literal space is not a valid URL (RSC-020) and unresolvable on strict readers; the encoded form denotes the same file. Since v0.44.0 the flag also renames archive entries whose names carry raw spaces to their underscore spellings and rewrites every reference to them (OPF, NCX, content, CSS `url()`), clearing the PKG-010 space-in-filename advisories: underscore, never percent-encoding, because epubcheck decodes references before entry lookup.
|
|
52
53
|
- **`--fix-container`**: generates `META-INF/container.xml` at the located OPF when the container is missing or names a file the archive does not contain. This is the gateway defect: epubcheck stays fatal while the OPF is unfindable, so no repair can be gate-accepted on such a book until the container exists.
|
|
53
54
|
- **`--fix-media-types`**: normalizes wrong manifest media-type declarations (OPF-029, e.g. a jpg stamped `image/png` by an aggregator). Attribute-only and quote-preserving; it fires only when the file's magic bytes confirm the extension, so a misnamed-but-consistent file (a PNG renamed .jpg) is never made worse. Since v0.56.0 it also covers the CSS-007 font slice (a `ttf`/`otf`/`woff`/`woff2` declared outside epubcheck's blessed font set is rewritten to its `font/*` spelling when the magic bytes confirm; `.eot` is never touched), and the flag is accepted under the no-worse bar because that half's gain sits on the INFO axis.
|
|
@@ -69,7 +70,7 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
|
|
|
69
70
|
|
|
70
71
|
- **`--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.
|
|
71
72
|
- **`--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.
|
|
72
|
-
- **`--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.
|
|
73
|
+
- **`--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. Since v1.1.1 the NCX half follows the same predicate (a digit-led ToC fragment follows the `id_` rename instead of dangling against it) and the quote-tempered fragment matchers translate an apostrophe-bearing value (`href="c1.xhtml#Lisey's_story"`) whole. An escaped fragment (a percent-escape like `#caf%C3%A9` or an entity reference) passes through untouched: it names its target under decoding, and renaming the encoded form would manufacture a target that exists nowhere.
|
|
73
74
|
- **`--prune-dead-spine`**: the shell repair — fires ONLY when half or more of the manifest's content hrefs name files the archive never carried (the audit battery's `shell` analyzer names the same shape). Drops the dead manifest items, the spine itemrefs that name them, and the dead NCX navPoints, then re-sequences the surviving playOrders to 1..K. A lone missing chapter never crosses the signature: the spine non-goal stays in force for ordinary damage. The Wandering Inn serial shells (738 and 736 of 755/752 items dead) are the design case; proven at 742e → 5e with 0 fatals.
|
|
74
75
|
|
|
75
76
|
Four opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
|
|
@@ -1,5 +1,123 @@
|
|
|
1
1
|
# bindery-cli Patch Notes
|
|
2
2
|
|
|
3
|
+
## v1.2.0 (2026-11-16)
|
|
4
|
+
|
|
5
|
+
### The CSS dead-font drop (issue #27)
|
|
6
|
+
|
|
7
|
+
Found 2026-11-13 converting four azw3 cookbooks to epub with ebook-convert
|
|
8
|
+
before import. The converter carries the source's `@font-face` CSS
|
|
9
|
+
declarations but NOT the font payloads they reference: the output's
|
|
10
|
+
`page_styles.css` and `page_styles1.css` fill with blocks whose `src` is the
|
|
11
|
+
literal placeholder `url(styles/XXXXXXXXXXXXXXXX)` -- fonts named in the
|
|
12
|
+
source (Dante, Nexa, SourceHan, FreeSans) but never carried over. epubcheck
|
|
13
|
+
reports each dead reference as RSC-007 (Referenced resource could not be
|
|
14
|
+
found): live counts 149/316/159/450 errors across the four files, 0 fatals.
|
|
15
|
+
The gate's `--all` set never converges them: `--prune-missing-resources`
|
|
16
|
+
works the OPF manifest, and these references live in CSS `url()`, where no
|
|
17
|
+
item exists to prune (the OPF never declared the fonts).
|
|
18
|
+
|
|
19
|
+
- **`--strip-dead-font-faces`** (structural repair #35): for every
|
|
20
|
+
`@font-face` block in a stylesheet, resolve each `url()` reference
|
|
21
|
+
against the archive (the shared href resolver: XML entities, then RFC
|
|
22
|
+
3986 percent-decoding, relative to the stylesheet's directory). A block
|
|
23
|
+
whose every reference misses the archive is dead by construction -- the
|
|
24
|
+
font never loaded, so the fallback rendering is what the file already
|
|
25
|
+
does -- and drops, rendering-neutral. The semantics-preserving guards
|
|
26
|
+
(the last two from the pre-commit review): one live `url()` keeps the
|
|
27
|
+
whole block; a scheme, query, fragment, raw space, or empty reference
|
|
28
|
+
keeps it (never guessed at: first `#`/`?` starts fragment/query, so a
|
|
29
|
+
query-carrying url whose path portion exists is a LIVE reference); a
|
|
30
|
+
`local()`-only block is not this class; a block with nested braces the
|
|
31
|
+
flat-brace matcher cannot read exactly is refused; and comments are
|
|
32
|
+
never rewritten -- XML comments and CDATA through the protected-region
|
|
33
|
+
split, plain CSS comments through a span-intersection check (a `}`
|
|
34
|
+
inside a comment truncates the flat-brace match short, and a drop
|
|
35
|
+
keyed on the match START alone would leave comment garbage in the
|
|
36
|
+
stylesheet), because dropping a commented-out block is a byte change
|
|
37
|
+
epubcheck cannot measure that another flag's gain could carry into an
|
|
38
|
+
applied candidate.
|
|
39
|
+
- **Gate behavior**: normal `gate`, like the other reference repairs --
|
|
40
|
+
the RSC-007 count is the measured gain. Runs on `.css` entries only.
|
|
41
|
+
When `--encode-url-spaces` renames entries, the pass judges references
|
|
42
|
+
against the pre-rename layout (first in the stylesheet branch, before
|
|
43
|
+
the reference rewrites), so a live font under a raw-space name can
|
|
44
|
+
never read as dead.
|
|
45
|
+
- **Facility verification** (the two pristine converter outputs the issue
|
|
46
|
+
attached): scoped-flag gate runs 0f/6e -> 0f/3e (16 blocks dropped) and
|
|
47
|
+
0f/5e -> 0f/2e (25 blocks dropped), both ACCEPT, zero residual
|
|
48
|
+
RSC-007 -- the remaining errors are other flags' classes (`epub:type`
|
|
49
|
+
scrubs, colon ids) and clear under their own flags.
|
|
50
|
+
|
|
51
|
+
Suite: 985 tests.
|
|
52
|
+
|
|
53
|
+
## v1.1.1 (2026-11-16)
|
|
54
|
+
|
|
55
|
+
### The audit batch (issues #28-#33)
|
|
56
|
+
|
|
57
|
+
Six defects filed from the 2026-11-16 deep codebase audit, each one
|
|
58
|
+
live-replicated before the fix. No CLI surface changes: every fix tightens an
|
|
59
|
+
existing flag's behavior to what its documentation already promised.
|
|
60
|
+
|
|
61
|
+
- **`--fix-id-colons` fragment sync (#28)**: `fix_ncx_src_fragments` followed
|
|
62
|
+
the old colon-only predicate, so a digit-led id (`<body id="0-25c121ec">`)
|
|
63
|
+
renamed on the content side left its NCX `content src` fragment untouched
|
|
64
|
+
and the ToC dangled against the id that no longer existed, and a digit-led
|
|
65
|
+
COLON-bearing id translated to two different spellings (`id_1_intro` on the
|
|
66
|
+
content side, `1_intro` in the NCX). The NCX half now uses the same
|
|
67
|
+
`_is_invalid_ncname` predicate and `_ncname_rename` scheme as the content
|
|
68
|
+
ids, and both fragment passes (the NCX `src` and the in-document `href`)
|
|
69
|
+
carry the quote-tempered idiom: an apostrophe inside a double-quoted value
|
|
70
|
+
(`href="c1.xhtml#Lisey's_story"`) translates whole instead of truncating
|
|
71
|
+
at the apostrophe and never translating. Two guard rails came out of the
|
|
72
|
+
pre-commit review: a fragment carrying an escape (a percent-escape like
|
|
73
|
+
`#caf%C3%A9` or an entity reference like `#café`) is refused
|
|
74
|
+
outright, because it names its target under decoding rather than NCName
|
|
75
|
+
spelling and renaming the encoded form would manufacture a target that
|
|
76
|
+
exists nowhere (undoing this release's own #29 decode match whenever both
|
|
77
|
+
flags run, which `--all` always does); and both matchers are
|
|
78
|
+
whitespace-anchored with the optional namespace prefix, so `data-href` and
|
|
79
|
+
`data-src` values are out of scope while `xlink:href` stays covered.
|
|
80
|
+
- **Percent-decoded fragments (#29)**: `--strip-broken-anchors` compared raw
|
|
81
|
+
attribute fragments while the wire spelling of a link to a non-ASCII id is
|
|
82
|
+
percent-encoded (`href="#caf%C3%A9"` naming `<h2 id="café">`), so valid
|
|
83
|
+
links lost their href; the NCX and OPF guide halves dropped the same valid
|
|
84
|
+
ToC entries and landmarks the same way. All three cleaners decode the
|
|
85
|
+
fragment (XML entities, then RFC 3986 percent-decoding -- the same chain
|
|
86
|
+
the href resolver has always applied to the path) before the existence
|
|
87
|
+
check. Cyrillic ids (`#%D1%82%D0%B5%D1%81%D1%82` naming `id="тест"`)
|
|
88
|
+
survive too.
|
|
89
|
+
- **id-attribute lookbehind guards (#30)**: `\bid=` also fires right after a
|
|
90
|
+
hyphen or colon, so `data-id` and `xml:id` read as THE id in three
|
|
91
|
+
matchers: the duplicate-id rename (a `data-id="c1"` made the real
|
|
92
|
+
`id="c1"` a "duplicate" and renamed it away from the fragments pointing at
|
|
93
|
+
it), `fix_manifest_ids` (a manifest item's `data-id` was renamed while its
|
|
94
|
+
real id stayed), and the anchor indexer (`ids_by_doc` collected data
|
|
95
|
+
attributes as link targets). All three now carry the `(?<![\w:.-])` guard
|
|
96
|
+
`fix_id_colons` has had since v0.32.0. The anchor index keeps a deliberate
|
|
97
|
+
exception: `xml:id` is a real XML id the oracle resolves fragments against,
|
|
98
|
+
so the anchor collection still reads it (a dedicated `(?:xml:)?id` pattern)
|
|
99
|
+
while the strict rename matchers exclude it.
|
|
100
|
+
- **Self-closing paragraphs (#31)**: `--strip-pagination`'s paragraph matcher
|
|
101
|
+
matched `<p class="divider"/>` as a block start; with no `</p>` of its own
|
|
102
|
+
the match ran forward to the NEXT paragraph's close tag, welding divider
|
|
103
|
+
and content into one block whose text could read as a page number and
|
|
104
|
+
strip real markup with it. The matcher refuses a `/` immediately before
|
|
105
|
+
the closing `>`.
|
|
106
|
+
- **The downgrade's shields (#32)**: `--downgrade-epub3-tags` ran unshielded
|
|
107
|
+
`re.sub` over the whole document, downgrading markup inside commented-out
|
|
108
|
+
sections and CDATA (phantom transform counts, the CDATA invariant broken);
|
|
109
|
+
it runs through `outside_protected_map` like every other markup transform
|
|
110
|
+
now. Its class merge matched `data-class=` and appended the semantic hook
|
|
111
|
+
to arbitrary data while the element's real class stayed untouched; the
|
|
112
|
+
matcher is whitespace-anchored.
|
|
113
|
+
- **The declarer's close tag (#33)**: `--declare-missing-items` located the
|
|
114
|
+
manifest close tag by the literal string `</manifest>` and silently
|
|
115
|
+
no-opped on prefixed (`</opf:manifest>`) or whitespace (`</manifest >`)
|
|
116
|
+
spellings; the close-tag matcher now carries the same namespace-prefix
|
|
117
|
+
tolerance as every other OPF matcher.
|
|
118
|
+
|
|
119
|
+
Suite: 972 tests.
|
|
120
|
+
|
|
3
121
|
## v1.1.0 (2026-11-09)
|
|
4
122
|
|
|
5
123
|
### The delimiter-damage repair (issue #26)
|
|
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "bindery-cli"
|
|
7
|
-
version = "1.
|
|
7
|
+
version = "1.2.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 = [
|
|
@@ -63,6 +63,8 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
|
|
|
63
63
|
| 1.0 | The milestone: the contract is the promise (spec.md stability section — additive flag surface, stable gate/records, oracle-evidenced predicate refinements), the shell-% denominator fix, the README status line. The observatory's final cycle: preview 0/0/0, clean 4,126/7,156, mass 11,455, ZERO fatals, 2,055 books repaired across the session's waves. Open items carry as 1.x additive work: RSC-011's spine-write policy call, the header-pseudo-tag someday-flag, the observatory cadence | v1.0.0 |
|
|
64
64
|
| 0.64 | `--prune-dead-spine`: the shell repair, shell-gated at the 50% signature (drops dead manifest items + spine itemrefs, coordinates the NCX navPoint prune and an UNCONDITIONAL playOrder re-sequence to 1..K after epubcheck 5.3 flagged the non-1 base on the post-prune shape -- the base-free clause's minimal matrix missed the shell shape); proven at 742e -> 5e on the facility copy | v0.64.0 |
|
|
65
65
|
| 1.1 | The delimiter-damage repair (issue #26): `--encode-ref-delims` (structural repair #34; the two-gate existence-proven encode for raw #/? filename damage: the reference must not resolve as written, the encoded spelling must match an archive entry; entities and empty-path anchors refused), the shell census's delim-recoverable exclusion (output layout AND raw layout; the Elminster shape can never cross the 50% signature), the missing-file mask acceptance bar keyed on `refs_delim_encoded`, and the audit shell verdict on the genuine fraction (`spine_missing_delim`; a fully-recoverable book reads ADVISORY, never SHELL); plus the two latent gaps the flag surfaced (the brackets OPF dispatch, the stylesheet non-UTF-8 guard). Fixture: probe accept 0f/3e -> 0f/4e, 36 encoded, no amputation, dangles 36 -> 0 | v1.1.0 |
|
|
66
|
+
| 1.1.1 | The audit batch (issues #28-#33, filed from the 2026-11-16 deep codebase audit, each live-replicated before the fix; no CLI surface change): the NCX fragment half follows the full `fix_id_colons` NCName predicate and rename and both fragment passes carry the tempered-quote idiom (digit-led and apostrophe-bearing ToC/href fragments no longer dangle or diverge; escaped fragments -- percent-escapes and entity references -- refused outright per the pre-commit review, and the matchers take the whitespace+namespace anchor), the three anchor cleaners percent-decode fragments before the existence check (links to non-ASCII ids survive; xml:id stays in the anchor index via `_ANCHOR_ID_RE`), `data-id`/`xml:id`/`data-class` leave the id and class matchers (the `fix_id_colons` lookbehind generalized), the EPUB3 downgrade never rewrites comments or CDATA, a self-closing paragraph never welds into a pagination block, and the manifest declarer finds prefixed and whitespace close tags | v1.1.1 |
|
|
67
|
+
| 1.2 | The CSS dead-font drop (issue #27): `--strip-dead-font-faces` (structural repair #35) removes every `@font-face` block in a stylesheet whose url() references ALL miss the archive -- the ebook-convert azw3->epub placeholder class (`url(styles/XXXXXXXXXXXXXXXX)`, one RSC-007 per dead reference, 149/316/159/450 errors across the four found cookbooks; the manifest prune has no item to answer and `--all` never converges because the references live in CSS url()). Rendering-neutral by construction (the font never loaded; the fallback is the rendered reality), one live url() keeps the block, scheme/query/fragment/raw-space/local()-only references and nested-brace blocks are never guessed at (the query guard and the comment-span intersection rule are pre-commit-review catches), resolution walks the shared resolver against the pre-rename layout (the pass runs first in the CSS branch), and XML comments/CDATA plus plain CSS comments are never rewritten. Facility verification: scoped-flag gate runs 0f/6e -> 0f/3e and 0f/5e -> 0f/2e, both ACCEPT, zero residual RSC-007 (the residuals are other flags' classes: epub:type, colon ids) | v1.2.0 |
|
|
66
68
|
|
|
67
69
|
## Open work
|
|
68
70
|
|
|
@@ -82,6 +84,29 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
|
|
|
82
84
|
repairs cleanly. The no-rename shape remains: entries with brackets
|
|
83
85
|
but no spaces never enter the rename map, and the flag stays a
|
|
84
86
|
no-op on such books.)*
|
|
87
|
+
- [ ] **Kindle-container conversion support (azw3/mobi -> epub): a possible
|
|
88
|
+
x.0.0 release candidate** (Brandon, 2026-11-13). The acquisition
|
|
89
|
+
pipeline keeps meeting Kindle-container sources (the 2026-11-13
|
|
90
|
+
cookbook batch imported four azw3s that had to go through
|
|
91
|
+
ebook-convert by hand, then through bindery for the converter's own
|
|
92
|
+
artifacts - see issue #27: ebook-convert emits dead @font-face rules
|
|
93
|
+
in page_styles(.1).css for publisher fonts whose payloads it drops,
|
|
94
|
+
RSC-007 from CSS url(), unconverged by --all). The candidate shape:
|
|
95
|
+
KF8/PalmDOC container parsing, HTML/OPF/NCX extraction into bindery's
|
|
96
|
+
existing repair-and-gate pipeline (so converted books get the same
|
|
97
|
+
epubcheck-gated deterministic treatment instead of a second tool's
|
|
98
|
+
artifact classes), metadata passthrough, and the open question of
|
|
99
|
+
font extraction - the sources carry TrueType-signature payloads, but
|
|
100
|
+
whether publisher fonts are recoverable from KF8 (and whether they
|
|
101
|
+
are obfuscated) needs a container parser before the answer is known.
|
|
102
|
+
The dead-font-face repair (issue #27) ships independently and first;
|
|
103
|
+
it is useful against any ebook-convert output, not just ours. Entry
|
|
104
|
+
conditions: a real batch need beyond the four-book proof (the
|
|
105
|
+
acquisition tempo keeps bringing Kindle containers), a KF8 parser
|
|
106
|
+
survey (existing stdlib-parseable state vs new code), and the spec
|
|
107
|
+
question of whether conversion is a bindery verb or a companion tool
|
|
108
|
+
(bindery's charter is repair, not format conversion - this is the
|
|
109
|
+
biggest scope question the project has faced).
|
|
85
110
|
- [ ] **Obfuscation-aware encryption.xml repair**: prune stale obfuscation entries
|
|
86
111
|
when font magic bytes prove the fonts are decrypted in place; drop
|
|
87
112
|
encryption.xml when only obfuscation entries remain and fonts verify. NEVER
|
|
@@ -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-five
|
|
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`,
|
|
@@ -26,7 +26,7 @@ The deliberate exceptions to "semantics-preserving" come in opt-in groups. The t
|
|
|
26
26
|
`--fix-unique-identifier`, `--fix-package-version`, `--fix-doctype`,
|
|
27
27
|
`--prune-invalid-guide-refs`, `--fix-item-properties`,
|
|
28
28
|
`--strip-presentational-attrs`, `--encode-ref-brackets`,
|
|
29
|
-
`--encode-ref-delims`,
|
|
29
|
+
`--encode-ref-delims`, `--strip-dead-font-faces`,
|
|
30
30
|
`--prune-dead-spine`) alter
|
|
31
31
|
markup structure or fabricate minimal content; the four
|
|
32
32
|
**lossy modes** (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`,
|
|
@@ -134,7 +134,8 @@ A safe opt-in: it renames manifest `item` ids that are not valid XML names
|
|
|
134
134
|
deterministic `id_` scheme, and updates every reference to them: spine `idref`
|
|
135
135
|
and `toc`, item `fallback` and `media-overlay`, and the EPUB 2 cover meta, in
|
|
136
136
|
both quote styles. NCX ids are renamed by the same pass (`fix_ncx_ids`);
|
|
137
|
-
|
|
137
|
+
NCName-invalid fragments follow the rename via `--fix-id-colons`' NCX half (the
|
|
138
|
+
same predicate and `id_` rename as the content ids, v1.1.1). Href
|
|
138
139
|
paths and filenames are untouched, and the human-facing `dc:` metadata is never
|
|
139
140
|
altered. Rendering is unchanged (ids are invisible), but the OPF is edited, so it
|
|
140
141
|
is off by default; the normal gate applies.
|
|
@@ -189,8 +190,18 @@ part of the default pipeline:
|
|
|
189
190
|
`id` attribute is in scope (`data-id` values are arbitrary data and are never
|
|
190
191
|
touched), the fragment of an external URL names a position in that other
|
|
191
192
|
document and survives verbatim, and the NCX's `content src` fragments follow
|
|
192
|
-
the rename (`fix_ncx_src_fragments`)
|
|
193
|
-
it references.
|
|
193
|
+
the rename (`fix_ncx_src_fragments`) under the same NCName predicate and
|
|
194
|
+
`id_` scheme, so a ToC never dangles against the ids it references (v1.1.1:
|
|
195
|
+
a digit-led ToC fragment follows the `id_` rename instead of dangling, a
|
|
196
|
+
digit-led colon-bearing id translates to the same spelling on both sides,
|
|
197
|
+
and the quote-tempered fragment matchers translate an apostrophe-bearing
|
|
198
|
+
value like `href="c1.xhtml#Lisey's_story"` whole instead of truncating at
|
|
199
|
+
the apostrophe). A fragment carrying an escape -- a percent-escape
|
|
200
|
+
(`#caf%C3%A9`) or an entity reference (`#café`, `#ю`) -- is
|
|
201
|
+
refused outright: it names its target under decoding, not NCName spelling,
|
|
202
|
+
and renaming the encoded form would manufacture a target that exists
|
|
203
|
+
nowhere. The matchers are whitespace-anchored with the optional namespace
|
|
204
|
+
prefix (`xlink:href` covered, `data-href`/`data-src` out of scope).
|
|
194
205
|
- **`--unwrap-block-in-inline`**: drop a `<span>` that illegally wraps a
|
|
195
206
|
`<div>/<p>/<blockquote>`, keeping the block element and its text.
|
|
196
207
|
- **`--strip-invalid-value`**: remove misplaced `value="..."` attributes from non-form
|
|
@@ -218,7 +229,9 @@ part of the default pipeline:
|
|
|
218
229
|
Names a stylesheet styles as an element selector are protected book-wide
|
|
219
230
|
(`css_protected_tags`/`style_block_tags` are parameterized over the tag set), so
|
|
220
231
|
styled formatting can never be silently destroyed; a protected book keeps its
|
|
221
|
-
RSC-005 findings, which is the correct outcome.
|
|
232
|
+
RSC-005 findings, which is the correct outcome. Comments and CDATA are never
|
|
233
|
+
rewritten and the class merge cannot fire inside a `data-class` attribute
|
|
234
|
+
(v1.1.1).
|
|
222
235
|
|
|
223
236
|
Both EPUB2-targeted fixes are gated on the package version carried in the OPF: they
|
|
224
237
|
fire on EPUB 2 packages (major version 2 or 1) and are inert on EPUB 3 packages and
|
|
@@ -253,6 +266,23 @@ every EPUB3 book in an `--all` sweep taking exactly that damage).
|
|
|
253
266
|
prune reads, never snapshotted earlier: `--fix-manifest-ids` may have renamed item
|
|
254
267
|
ids and spine idrefs ahead of it in the OPF pipeline, and a guard describing the old
|
|
255
268
|
spelling protects nothing.
|
|
269
|
+
- **`--strip-dead-font-faces`** (v1.2.0, issue #27): drop every `@font-face` block in
|
|
270
|
+
a stylesheet whose `url()` references ALL miss the archive (RSC-007 raised from CSS
|
|
271
|
+
url(): ebook-convert azw3->epub carries the source's font declarations without the
|
|
272
|
+
font payloads, filling `page_styles.css` with `url(styles/XXXXXXXXXXXXXXXX)`
|
|
273
|
+
placeholders the manifest prune cannot answer, because the OPF never declared the
|
|
274
|
+
fonts). The font never loaded, so the fallback rendering is what the file already
|
|
275
|
+
does and dropping the block is rendering-neutral. One live url() keeps the whole
|
|
276
|
+
block; a scheme, query, fragment, raw-space, or url()-less (`local()`-only) reference also
|
|
277
|
+
keeps it (never guessed at: first `#`/`?` starts fragment/query, so a query-carrying
|
|
278
|
+
url whose path portion exists is a live reference), as does any block the flat-brace matcher cannot read
|
|
279
|
+
exactly (nested braces). Resolution walks the shared href resolver; XML
|
|
280
|
+
comments/CDATA and plain CSS comments are never rewritten (a commented-out block is
|
|
281
|
+
invisible to the oracle, and dropping it would be a byte change another flag's gain
|
|
282
|
+
could carry into an applied candidate; the span check is an intersection over the
|
|
283
|
+
whole match, because a `}` inside a comment truncates the flat-brace match and a
|
|
284
|
+
start-keyed drop would leave comment garbage in the stylesheet). Runs on `.css`
|
|
285
|
+
entries only.
|
|
256
286
|
- **`--declare-missing-items`**: the RSC-008 inverse of the prune (v0.55.0, issue
|
|
257
287
|
#16): add the manifest `<item>` declarations the OPF never wrote for files the
|
|
258
288
|
archive carries and the book references: content `<img src>` and `<link href>`
|
|
@@ -270,7 +300,10 @@ every EPUB3 book in an `--all` sweep taking exactly that damage).
|
|
|
270
300
|
by design (95.3% of its mass is spine documents whose files exist under a
|
|
271
301
|
different spelling; `--encode-url-spaces` territory) and RSC-008 had zero
|
|
272
302
|
coverage (441 of 452 sampled findings are `<img src>` to present-but-undeclared
|
|
273
|
-
files); this flag is that repair.
|
|
303
|
+
files); this flag is that repair. The insertion point is the manifest close tag
|
|
304
|
+
however it is spelled: prefixed (`</opf:manifest>`) or whitespace-carrying
|
|
305
|
+
(`</manifest >`) declare too; a package whose manifest never closes is not
|
|
306
|
+
repaired (v1.1.1).
|
|
274
307
|
- **`--strip-broken-anchors`**: strip `href` attributes that cannot resolve, keeping
|
|
275
308
|
the anchor text byte-for-byte. A `#fragment` the target document does not define
|
|
276
309
|
(RSC-020 "fragment identifier not defined", RSC-012 "points to the wrong element") is
|
|
@@ -288,6 +321,9 @@ every EPUB3 book in an `--all` sweep taking exactly that damage).
|
|
|
288
321
|
spine-integrity report. href values carrying a scheme no reader resolves
|
|
289
322
|
(`kindle:embed:`, `file:`, ...) are stripped under the same flag; the resolvable set
|
|
290
323
|
is fixed (`http`, `https`, `mailto`) and extends only with a named finding.
|
|
324
|
+
Fragments are compared after the decode chain the href resolver applies to paths
|
|
325
|
+
(XML entities, then RFC 3986 percent-decoding), so a valid link to a non-ASCII id
|
|
326
|
+
(`href="#caf%C3%A9"` naming `<h2 id="café">`) is kept, not stripped (v1.1.1).
|
|
291
327
|
- **`--prune-dangling-ncx-targets`** (v0.59.0, issue #23): remove NCX
|
|
292
328
|
`navPoint`/`pageTarget` elements whose `<content src>` names a document the archive
|
|
293
329
|
does not contain (RSC-007 raised from toc.ncx). This is the class the prune flag
|
|
@@ -587,7 +623,7 @@ leftovers whose failing OPF is a stale non-rootfile are unreachable by construct
|
|
|
587
623
|
book whose manifest "missing" is all recoverable now reads ADVISORY
|
|
588
624
|
naming the encode, never SHELL/re-source.
|
|
589
625
|
|
|
590
|
-
Thirty of the thirty-
|
|
626
|
+
Thirty-one of the thirty-five are evaluated by the normal `gate`: unlike the lossy strips,
|
|
591
627
|
their benefit is visible to epubcheck (they clear errors), so a run with no measurable
|
|
592
628
|
improvement is a noop and nothing is applied. `--fix-cover`, `--encode-url-spaces`, and
|
|
593
629
|
`--fix-media-types` (whose gains sit on axes epubcheck's counts do not measure:
|
|
@@ -726,7 +762,10 @@ conversion baked into the body as literal paragraphs (so they reflow mid-sentenc
|
|
|
726
762
|
"where the hay cart 16 was taking him"). This is the one mode that removes visible
|
|
727
763
|
content; it is off by default and never runs unless requested.
|
|
728
764
|
|
|
729
|
-
Scope is `<p>` elements (where the defect is carried).
|
|
765
|
+
Scope is `<p>` elements (where the defect is carried). A self-closing `<p .../>`
|
|
766
|
+
start tag never opens a block: it has no close tag of its own, so a match starting
|
|
767
|
+
there would run to the NEXT paragraph's close and weld the following markup into
|
|
768
|
+
the block (v1.1.1). For each book:
|
|
730
769
|
|
|
731
770
|
- **Running headers** are short `<p>` blocks repeated >= 8 times across the whole book
|
|
732
771
|
(the title, an author byline, a download watermark); they are page furniture.
|
|
@@ -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 = "1.
|
|
14
|
+
VERSION = "1.2.0"
|
|
15
15
|
__version__ = VERSION
|
|
16
16
|
|
|
17
17
|
from .epub import RepairReport, repair_epub # noqa: E402
|