bindery-cli 1.0.0__tar.gz → 1.1.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.0.0 → bindery_cli-1.1.0}/AGENTS.md +48 -4
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/PKG-INFO +1 -1
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/patchnotes.md +58 -5
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/pyproject.toml +1 -1
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/roadmap.md +1 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/spec.md +54 -7
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/src/bindery/__init__.py +1 -1
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/src/bindery/audit.py +38 -2
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/src/bindery/cli.py +49 -1
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/src/bindery/epub.py +207 -3
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_contamination.py +70 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_epub.py +210 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_flags_real_core.py +26 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_flags_wiring.py +1 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_spine_guard.py +121 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/uv.lock +1 -1
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/.github/FUNDING.yml +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/.github/workflows/ci.yml +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/.github/workflows/publish.yml +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/.gitignore +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/LICENSE +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/OBSERVE-RESEARCH.md +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/README.md +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/docs/screenshots/library-sweep.png +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/logo.svg +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/plugin/__init__.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/project.done +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/run_tests.sh +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/scripts/FastSweep.java +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/scripts/build_plugin.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/scripts/fast_sweep.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/src/bindery/__main__.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/src/bindery/library.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/src/bindery/observe.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/src/bindery/pagination.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/src/bindery/reserialize.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/src/bindery/transforms.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/src/bindery/validate.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/src/bindery/watermark.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_audit.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_cli.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_comment_hyphens.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_cover_tocdrift.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_help.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_library.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_matcher_hardening.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_observe.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_pagination.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_plugin.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_reserialize.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_space_renames.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_transforms.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_validate.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_version.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_watermark.py +0 -0
- {bindery_cli-1.0.0 → bindery_cli-1.1.0}/tests/test_xml_hardening.py +0 -0
|
@@ -30,7 +30,7 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
|
|
|
30
30
|
`xmlns`, bare `&`, named entities, void self-closing), the NCX pipeline, and the
|
|
31
31
|
mimetype fix (added/normalized/first-stored, epub.py's archive rewrite); every core
|
|
32
32
|
fix must render identically to the author's intent: never add, remove, or reorder
|
|
33
|
-
visible content. The canonical opt-in inventory lives in spec.md: thirty-
|
|
33
|
+
visible content. The canonical opt-in inventory lives in spec.md: thirty-four structural
|
|
34
34
|
repairs, four lossy strips, five safe opt-ins, plus `--reserialize` (the
|
|
35
35
|
seven v0.62.x/v0.63.0 flags -- `--fix-package-version`, `--fix-doctype`,
|
|
36
36
|
`--prune-invalid-guide-refs`, `--fix-item-properties`,
|
|
@@ -48,6 +48,7 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
|
|
|
48
48
|
`--fix-unbound-prefix`, `--fix-package-version`, `--fix-doctype`,
|
|
49
49
|
`--prune-invalid-guide-refs`, `--fix-item-properties`,
|
|
50
50
|
`--strip-presentational-attrs`, `--encode-ref-brackets`,
|
|
51
|
+
`--encode-ref-delims`,
|
|
51
52
|
`--prune-dead-spine`;
|
|
52
53
|
transforms.py, threaded through epub.py). The v0.47.0 five (the 2026-10-06
|
|
53
54
|
issue batch): `--fix-svg-dup-ids` renames duplicate glyph ids inside
|
|
@@ -155,6 +156,49 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
|
|
|
155
156
|
contract-gated playOrder pass re-runs in the same branch (the survivors' values
|
|
156
157
|
start gapped; the fixture went 0f/1e/0w -> 0f/0e/0w in one gate, one navPoint
|
|
157
158
|
pruned, 389 playOrder values re-sequenced); normal `gate`.
|
|
159
|
+
The v1.1.0 one (issue #26, the Elminster bookmate conversion: 36 of 38
|
|
160
|
+
manifest hrefs carried `#01`, each parsed as file `Elminster_` plus a
|
|
161
|
+
fragment, RSC-001, and the gate's ACCEPTED candidate was the shell prune
|
|
162
|
+
amputating all 36 live documents): `--encode-ref-delims` percent-encodes
|
|
163
|
+
literal `#`/`?` in internal src/href references whose raw delimiter
|
|
164
|
+
defeats their own resolution. Two gates, both required: the reference's
|
|
165
|
+
PATH PORTION (read the way the oracle parses it, first `#`/`?` starts
|
|
166
|
+
fragment/query) must miss the archive -- bindery's own `_resolve_href`
|
|
167
|
+
keeps a raw `?` in the path, so the pass follows the oracle, not the
|
|
168
|
+
spine probe, on that split -- and the delimiter-encoded spelling must
|
|
169
|
+
match an archive entry (the issue #19 decode-before-lookup mechanism);
|
|
170
|
+
a working `doc.xhtml#intro` is never touched, `a`-and-`a#b`-both-exist
|
|
171
|
+
keeps the RFC spelling, a genuinely missing file stays as written, entry
|
|
172
|
+
names stay raw. Anchored on the brackets pass's matcher (start tags/PIs,
|
|
173
|
+
outside comments and CDATA), applied on content docs, the OPF, the NCX,
|
|
174
|
+
and stylesheet url(); runs beside `--encode-ref-brackets` at all four
|
|
175
|
+
sites, and the OPF branch dispatch now lists BOTH bracket and delim
|
|
176
|
+
flags (the dispatch omission was a latent gap: `--encode-ref-brackets`
|
|
177
|
+
documented OPF coverage but a standalone selection never reached the OPF
|
|
178
|
+
branch; the stylesheet decode gained the markup branches' non-UTF-8
|
|
179
|
+
guard for the same reason -- the reference encodes alone select that
|
|
180
|
+
branch). Wholesale refusals (the code-review pass on this fix): any
|
|
181
|
+
value whose attribute text carries a numeric character reference
|
|
182
|
+
(`&#` -- the entity's own spelling holds a raw `#` and the verbatim
|
|
183
|
+
rewrite would corrupt a working reference into a malformed entity),
|
|
184
|
+
and any empty-path value (`#intro` is an in-document anchor, never
|
|
185
|
+
filename damage). The shell census's dead set EXCLUDES delim-recoverable items
|
|
186
|
+
(not flag-gated: a correctness predicate), so the Elminster shape can
|
|
187
|
+
never cross the 50% shell signature and the prune cannot amputate; a
|
|
188
|
+
mixed book (genuine dead + recoverable) prunes only the genuine dead.
|
|
189
|
+
The keyed promotion (`refs_delim_encoded`) carries the acceptance bar
|
|
190
|
+
(the missing-file mask: a manifest item whose file the archive lacks is
|
|
191
|
+
never parsed, so the document's own schema errors stay invisible until
|
|
192
|
+
the encode opens it; the error-cleanup branch's strict decrease reads
|
|
193
|
+
the mask lifting as a regression and the amputation won the gate fight,
|
|
194
|
+
0f/3e -> 0f/1e against the encode's 0f/3e -> 0f/6e): net-new fatals
|
|
195
|
+
reject, still-fatal stays partial, fatal-free accepts whatever the
|
|
196
|
+
unmasking did to the error count; the spine veto still overrides. The
|
|
197
|
+
audit side names the same class honestly: the loader counts
|
|
198
|
+
`spine_missing_delim` (itemrefs whose delim-encoded href variant
|
|
199
|
+
resolves), `analyze_shell` subtracts it (`genuine_missing`/`genuine_frac`
|
|
200
|
+
drive the verdict), and a fully-recoverable book reads ADVISORY naming
|
|
201
|
+
`--encode-ref-delims`, never SHELL/re-source.
|
|
158
202
|
They alter markup structure or fabricate minimal content. v0.14–v0.16 ran these unconditionally, which broke this rule;
|
|
159
203
|
v0.17.0 restored it. `--unwrap-illegal-tags` additionally protects any illegal-tag
|
|
160
204
|
name that an EPUB stylesheet styles as an element selector (`css_protected_tags`,
|
|
@@ -233,18 +277,18 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
|
|
|
233
277
|
- `src/bindery/pagination.py`: the opt-in lossy page-number strip (runhead detection, page-layer decision, block-centric removal/merge, safety nets).
|
|
234
278
|
- `src/bindery/watermark.py`: the opt-in lossy watermark strip (anchored and anchorless signature removal).
|
|
235
279
|
- `src/bindery/reserialize.py`: structural repair via `html5lib`.
|
|
236
|
-
- `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)) 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).
|
|
280
|
+
- `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).
|
|
237
281
|
- `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
|
|
238
282
|
character references before the fragment split (attribute text arrives
|
|
239
283
|
escaped; entries are raw; decoding first keeps the `#` inside `&`
|
|
240
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).
|
|
241
285
|
- `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.
|
|
242
286
|
- `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.
|
|
243
|
-
- `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; since v0.52.0 `process_book` carries the spine-resolution veto (issue #10) above every verdict path, promotions included: a candidate whose spine dangles more than the source's is `reject` with `(spine collapse)` appended to the summary, whatever the counts say. `repair --json` emits the library per-book record vocabulary (2026-09-15; since v0.45.0 every per-book record, the phase1 payload included, also carries the structured fix breakdown: the `fixes` dict plus `ncx_uid_synced`/`watermark_refusals` off the `Outcome`, and `_phase1_decisions` reads that data instead of substring-matching the rendered `summary`, which stays for human eyes; CalibreQuarry's lossy-consent mirror is the waiting consumer, floor `bindery>=0.45.0`); since v0.29.0 also the `run` verbs: `phase1` (pre-import vetting over loose files: the audit battery composed with one gated repair sweep; read-only until `--apply-lossy`, which IS the lossy-strip consent) and `phase3` (the scoped post-import apply step: `library --id --sweep --only all --apply --all --install-to-calibre` plus a pre/post summary; mechanically refuses unscoped sweeps with exit 2; since 2026-09-15 the summary sums applied/equal states only and carries rejected projections as `rejected_projection`). Plus `bindery doctor` (2026-09-15): the environment self-check that imports none of the VirInvictus stack, never raises, and always exits 0. The `observe` verb (v0.53.0) writes schema v2 artifacts since v0.55.0 (issue #13): `codes.messages` (renamed from the mislabeled `occurrences`) counts aggregated epubcheck JSON message entries, `codes.occurrences` now carries the true per-site scale (summed `locations`), a `counting` block states both scales in the artifact, and `--against` accepts v1 or v2 (the trend keys exist in both). Both run verbs take `--non-interactive` and surface open questions as `decisions_needed` in their JSON, never prompts. They drive the shipped `run_library` through the real parser, so no flag can drift between the verb and the subcommand it wraps. Since v0.46.0 `cli._flags_from_args(args)` is the one place the argparse names map onto `RepairFlags` fields (each `or --all`), shared by `run_library` and `run_repair`; the old per-verb ~25-kwarg blocks are gone. Since v0.47.1 the help is two-level (the --help-repairs reference is
|
|
287
|
+
- `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
|
|
244
288
|
custom-rendered and colors itself with the CPython 3.14 argparse theme,
|
|
245
289
|
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.
|
|
246
290
|
- `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.
|
|
247
|
-
- `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`.
|
|
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.
|
|
248
292
|
|
|
249
293
|
## Conventions
|
|
250
294
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: bindery-cli
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.1.0
|
|
4
4
|
Summary: Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library.
|
|
5
5
|
Project-URL: Homepage, https://github.com/VirInvictus/bindery-cli
|
|
6
6
|
Project-URL: Repository, https://github.com/VirInvictus/bindery-cli
|
|
@@ -1,31 +1,84 @@
|
|
|
1
1
|
# bindery-cli Patch Notes
|
|
2
2
|
|
|
3
|
+
## v1.1.0 (2026-11-09)
|
|
4
|
+
|
|
5
|
+
### The delimiter-damage repair (issue #26)
|
|
6
|
+
|
|
7
|
+
A raw `#` in a filename reference defeats its own resolution: the bookmate
|
|
8
|
+
conversion of Elminster: The Making of a Mage stamped `#01` into 36
|
|
9
|
+
filenames, every manifest href parsed as file `Elminster_` plus a fragment,
|
|
10
|
+
epubcheck read RSC-001 'File ... could not be found', and the archive's 38
|
|
11
|
+
documents sat unreachable. The defect's real danger was the gate's answer:
|
|
12
|
+
the ACCEPTED candidate was the shell prune dropping all 36 live documents
|
|
13
|
+
(0f/3e -> 0f/1e by deleting them, against the encode's 0f/3e -> 0f/6e by
|
|
14
|
+
opening them), a 2-doc husk shipping as an error-count win -- the inverse
|
|
15
|
+
of the #10 spine collapse, invisible to the dangle veto because pruning
|
|
16
|
+
LOWERS the dangle count.
|
|
17
|
+
|
|
18
|
+
- **`--encode-ref-delims`** (structural repair #34): percent-encode a
|
|
19
|
+
literal `#`/`?` in internal src/href and stylesheet url() references,
|
|
20
|
+
under two required gates -- the reference must NOT resolve as written
|
|
21
|
+
(its path portion, read the way the oracle parses it: first `#`/`?`
|
|
22
|
+
starts fragment/query) and the delimiter-encoded spelling MUST match an
|
|
23
|
+
archive entry (the issue #19 decode-before-lookup mechanism; entries
|
|
24
|
+
stay raw-spelled). Working fragments are never touched, `a`-and-`a#b`
|
|
25
|
+
both-exist keeps the RFC spelling, genuinely missing files stay as
|
|
26
|
+
written, numeric-entity values are refused wholesale (the entity's own
|
|
27
|
+
spelling carries a raw `#`; the verbatim rewrite would corrupt a working
|
|
28
|
+
reference into a malformed entity), and an empty-path value (`#intro`)
|
|
29
|
+
is an in-document anchor, never filename damage.
|
|
30
|
+
- **The shell census guard**: the `--prune-dead-spine` dead set excludes
|
|
31
|
+
delim-recoverable items (against the output layout AND the raw layout,
|
|
32
|
+
closing the co-fired rename hole where output-layout names would miss
|
|
33
|
+
the raw-spelled variant). The Elminster shape can never cross the 50%
|
|
34
|
+
shell signature again; a mixed book prunes only the genuine dead.
|
|
35
|
+
- **The missing-file mask bar**: when `refs_delim_encoded` fires, the
|
|
36
|
+
keyed promotion replaces the error-cleanup answer -- net-new fatals
|
|
37
|
+
reject, a still-fatal candidate stays partial, a fatal-free candidate
|
|
38
|
+
accepts the unmasking rise (documents epubcheck never parsed surfacing
|
|
39
|
+
their own latent damage); the #10 spine veto still overrides.
|
|
40
|
+
- **The audit says what the archive holds**: the loader counts
|
|
41
|
+
`spine_missing_delim` and the shell verdict runs on the genuine
|
|
42
|
+
fraction -- the Elminster fixture reads ADVISORY naming the encode,
|
|
43
|
+
never SHELL/re-source; a true shell still reads SHELL.
|
|
44
|
+
- **Two latent gaps closed**: the OPF branch dispatch never listed
|
|
45
|
+
`--encode-ref-brackets`, so its documented OPF coverage could not fire
|
|
46
|
+
on a standalone selection (now listed, pinned by a real-core row); and
|
|
47
|
+
the stylesheet decode lacked the markup branches' non-UTF-8 guard once
|
|
48
|
+
the reference encodes select that branch (a windows-1252 stylesheet is
|
|
49
|
+
copied byte-for-byte, `non_utf8_docs_skipped`).
|
|
50
|
+
|
|
51
|
+
On the facility fixture (`elminster-hash-in-href-broken.epub`, kept
|
|
52
|
+
permanently): probe accepts 0f/3e/0w -> 0f/4e/0w with refs_delim_encoded:36,
|
|
53
|
+
no amputation, spine dangles 36 -> 0, all 38 documents resolve, and the
|
|
54
|
+
audit flips SHELL -> ADVISORY. Suite: 943 tests.
|
|
55
|
+
|
|
3
56
|
## v1.0.0 (2026-11-05)
|
|
4
57
|
|
|
5
58
|
### 1.0: the contract is the promise
|
|
6
59
|
|
|
7
60
|
bindery-cli is 1.0. The observatory's final cycle states the mission's
|
|
8
61
|
completion in numbers: the library's default-pass preview answers
|
|
9
|
-
accepted 0 / partial 0 / rejected 0 / equal 46
|
|
10
|
-
left to give on this library
|
|
62
|
+
accepted 0 / partial 0 / rejected 0 / equal 46 -- the arsenal has nothing
|
|
63
|
+
left to give on this library -- clean sits at 4,126 of 7,156, error mass
|
|
11
64
|
at 11,455 (from 16,182 across the session's waves), and the library
|
|
12
65
|
carries ZERO fatal books. 2,055 books were repaired across the session's
|
|
13
66
|
waves; every finding class in the census is dispositioned: repaired,
|
|
14
67
|
detected at intake, or leave-measured with a recorded reason.
|
|
15
68
|
|
|
16
69
|
**What 1.0 means** (the stability contract, now a section in spec.md):
|
|
17
|
-
the flag surface is additive from here
|
|
70
|
+
the flag surface is additive from here -- new opt-in flags may appear,
|
|
18
71
|
existing flags' names and documented semantics do not change; the gate's
|
|
19
72
|
improvement/no-worse bars, the spine-collapse veto, and the shell
|
|
20
73
|
signature's 50% gate are stable; the JSON record vocabulary, the fix
|
|
21
74
|
breakdown, the exit-code contracts, and the observe schema (v2) are
|
|
22
75
|
stable, and downstream consumers can pin `bindery>=1.0`. Predicate
|
|
23
|
-
refinements ship documented in patchnotes with oracle evidence
|
|
76
|
+
refinements ship documented in patchnotes with oracle evidence -- the
|
|
24
77
|
standard this session set (base-free v0.62.0, the doctype narrowing
|
|
25
78
|
v0.63.0, both proven against epubcheck before they moved).
|
|
26
79
|
|
|
27
80
|
**This release carries**: the shell-% denominator fix (a shell now reads
|
|
28
|
-
its true manifest fraction
|
|
81
|
+
its true manifest fraction -- 75% for the Wandering Inn shape -- instead
|
|
29
82
|
of the resolved-spine-only denominator that read shells at over 100%),
|
|
30
83
|
and the 1.0 stability section in spec.md plus the README status line.
|
|
31
84
|
The tool itself is v0.64.0's: `--prune-dead-spine` closed the Wandering
|
|
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "bindery-cli"
|
|
7
|
-
version = "1.
|
|
7
|
+
version = "1.1.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 = [
|
|
@@ -62,6 +62,7 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
|
|
|
62
62
|
| 0.63.1 | Two single-flag live-verification catches: `--encode-ref-brackets` alone was a silent no-op (`present` only filled under the other flags' guard -- The Given Day's 59 NCX bracket srcs encoded, zero raw left, once the guard included the flag), and the audit CLI's `--only` choices lacked `shell` | v0.63.1 |
|
|
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
|
+
| 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 |
|
|
65
66
|
|
|
66
67
|
## Open work
|
|
67
68
|
|
|
@@ -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-four
|
|
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,6 +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
30
|
`--prune-dead-spine`) alter
|
|
30
31
|
markup structure or fabricate minimal content; the four
|
|
31
32
|
**lossy modes** (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`,
|
|
@@ -535,6 +536,32 @@ leftovers whose failing OPF is a stale non-rootfile are unreachable by construct
|
|
|
535
536
|
walk covers content documents, the OPF, the NCX, and stylesheet `url()`
|
|
536
537
|
tokens.
|
|
537
538
|
|
|
539
|
+
- **`--encode-ref-delims`**: percent-encode a literal `#` or `?` inside a
|
|
540
|
+
filename reference whose raw delimiter defeats the reference's own
|
|
541
|
+
resolution (issue #26, the Elminster bookmate conversion: 36 of 38
|
|
542
|
+
manifest hrefs carried `#01`, parsed as file `Elminster_` plus fragment,
|
|
543
|
+
RSC-001 'File ... could not be found', and epubcheck never parsed the
|
|
544
|
+
documents at all). Two gates, both required: the reference must NOT
|
|
545
|
+
resolve as written -- its path portion, read the way the oracle and
|
|
546
|
+
every reader parse it (first `#`/`?` starts fragment/query), must miss
|
|
547
|
+
the archive; a working `doc.xhtml#intro` is never touched, and where
|
|
548
|
+
both `a` and `a#b` exist the RFC spelling wins. And the delimiter-
|
|
549
|
+
encoded spelling MUST match an archive entry (the issue #19 mechanism:
|
|
550
|
+
epubcheck decodes references before entry lookup, so the encoded form
|
|
551
|
+
resolves to the raw-spelled entry). Wholesale refusals: a value whose
|
|
552
|
+
attribute text carries a numeric character reference anywhere (`&#` --
|
|
553
|
+
the entity's own spelling contains a raw `#`, and the verbatim rewrite
|
|
554
|
+
would corrupt it, e.g. `&` into a malformed `&%2338;`), and a value
|
|
555
|
+
whose path portion is empty (`#intro` is an in-document anchor, never
|
|
556
|
+
filename damage). Entry names stay raw-spelled; a
|
|
557
|
+
genuinely missing file stays as written. The walk covers content
|
|
558
|
+
documents, the OPF, the NCX, and stylesheet `url()` tokens, anchored on
|
|
559
|
+
the same start-tag/PI matcher outside comments and CDATA; the
|
|
560
|
+
stylesheet decode now carries the same non-UTF-8 guard as the markup
|
|
561
|
+
branches (a non-UTF-8 stylesheet is copied byte-for-byte, reported
|
|
562
|
+
`non_utf8_docs_skipped` -- the reference encodes alone select that
|
|
563
|
+
branch too).
|
|
564
|
+
|
|
538
565
|
- **`--prune-dead-spine`**: the shell repair -- fires ONLY when half or
|
|
539
566
|
more of the manifest's content hrefs name files the archive does not
|
|
540
567
|
carry (the audit battery's `shell` analyzer names the same shape; the
|
|
@@ -550,15 +577,35 @@ leftovers whose failing OPF is a stale non-rootfile are unreachable by construct
|
|
|
550
577
|
positions never resolved, and the book that remains is the complete,
|
|
551
578
|
coherent chapter range the archive actually carries. A lone missing
|
|
552
579
|
chapter never crosses the signature: the spine non-goal stays in force
|
|
553
|
-
for ordinary damage.
|
|
554
|
-
|
|
555
|
-
|
|
580
|
+
for ordinary damage. Since v1.1.0 the dead census also refuses items
|
|
581
|
+
whose file EXISTS under a delimiter-encoded spelling (issue #26): those
|
|
582
|
+
hrefs are the `--encode-ref-delims` repair class, and pruning them
|
|
583
|
+
would amputate live documents while the counts read it as an error win
|
|
584
|
+
-- the accepted Elminster candidate was `dead_spine_items_pruned: 36`
|
|
585
|
+
on a book whose archive carried all 38 documents. The audit's shell
|
|
586
|
+
analyzer subtracts the same recoverable slice before its verdict: a
|
|
587
|
+
book whose manifest "missing" is all recoverable now reads ADVISORY
|
|
588
|
+
naming the encode, never SHELL/re-source.
|
|
589
|
+
|
|
590
|
+
Thirty of the thirty-four are evaluated by the normal `gate`: unlike the lossy strips,
|
|
556
591
|
their benefit is visible to epubcheck (they clear errors), so a run with no measurable
|
|
557
|
-
improvement is a noop and nothing is applied.
|
|
592
|
+
improvement is a noop and nothing is applied. `--fix-cover`, `--encode-url-spaces`, and
|
|
558
593
|
`--fix-media-types` (whose gains sit on axes epubcheck's counts do not measure:
|
|
559
594
|
cover wiring is not a schema finding; the rename half's PKG-010 gain sits on the
|
|
560
|
-
warning axis; the font half's CSS-007 gain sits on the INFO axis)
|
|
561
|
-
under the same `no_worse` bar the lossy strips use, with the partial rule intact.
|
|
595
|
+
warning axis; the font half's CSS-007 gain sits on the INFO axis) are accepted
|
|
596
|
+
under the same `no_worse` bar the lossy strips use, with the partial rule intact.
|
|
597
|
+
`--encode-ref-delims` carries its own acceptance bar, keyed on its fix having
|
|
598
|
+
fired: the missing-file mask. A manifest item whose file the archive lacks is
|
|
599
|
+
never parsed by epubcheck, so that document's own schema errors stay invisible
|
|
600
|
+
(the fatal branch's masking, one class over: a fatal halts its file's remaining
|
|
601
|
+
checks, a missing file skips the file entirely); the strict error decrease the
|
|
602
|
+
error-cleanup branch demands would read the mask lifting as a regression, and the
|
|
603
|
+
spine-amputating prune would win the gate fight (0f/3e -> 0f/1e by deleting the
|
|
604
|
+
documents, against the encode's 0f/3e -> 0f/6e by opening them). The bar is the
|
|
605
|
+
fatal branch's, one class over: net-new fatals reject, a still-fatal candidate
|
|
606
|
+
stays partial (never auto-applied), a fatal-free candidate accepts whatever the
|
|
607
|
+
unmasking did to the error count; the #10 spine-collapse veto still overrides.
|
|
608
|
+
CDATA sections are never rewritten
|
|
562
609
|
anywhere; comment bodies only by the double-hyphen fix above, and nothing else inside
|
|
563
610
|
them.
|
|
564
611
|
|
|
@@ -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.1.0"
|
|
15
15
|
__version__ = VERSION
|
|
16
16
|
|
|
17
17
|
from .epub import RepairReport, repair_epub # noqa: E402
|
|
@@ -176,6 +176,7 @@ class Book:
|
|
|
176
176
|
"opf",
|
|
177
177
|
"spine",
|
|
178
178
|
"spine_missing",
|
|
179
|
+
"spine_missing_delim",
|
|
179
180
|
"toc_refs",
|
|
180
181
|
"toc_absent",
|
|
181
182
|
)
|
|
@@ -192,6 +193,7 @@ class Book:
|
|
|
192
193
|
toc_absent,
|
|
193
194
|
encrypted=None,
|
|
194
195
|
spine_missing=0,
|
|
196
|
+
spine_missing_delim=0,
|
|
195
197
|
dup_entries=0,
|
|
196
198
|
obfuscated=None,
|
|
197
199
|
obfuscated_declared=None,
|
|
@@ -223,6 +225,12 @@ class Book:
|
|
|
223
225
|
# idref, decoded-href vs stored-name mismatch): a large count on an
|
|
224
226
|
# EMPTY-verdict book is the diagnostic, not a content-less stub.
|
|
225
227
|
self.spine_missing = spine_missing
|
|
228
|
+
# The delim-recoverable slice of spine_missing (issue #26): itemrefs
|
|
229
|
+
# whose href resolves once its raw #/? delimiters are percent-encoded
|
|
230
|
+
# -- the file IS in the archive, the reference spelling is what
|
|
231
|
+
# defeats it. The shell verdict must not call this state a shell
|
|
232
|
+
# (the content is shipped; --encode-ref-delims is the repair).
|
|
233
|
+
self.spine_missing_delim = spine_missing_delim
|
|
226
234
|
# duplicate archive entry names (zip resolves last-wins silently);
|
|
227
235
|
# surfaced in the archive verdict so nothing is silently shadowed
|
|
228
236
|
self.dup_entries = dup_entries
|
|
@@ -307,6 +315,7 @@ def load_book(path: Path) -> Book:
|
|
|
307
315
|
encrypted: list[str] = []
|
|
308
316
|
oversized: list[str] = []
|
|
309
317
|
spine_missing = 0
|
|
318
|
+
spine_missing_delim = 0
|
|
310
319
|
dup_entries = len(names) - len(nameset) # zip resolves last-wins
|
|
311
320
|
raw: dict[str, bytes] = {}
|
|
312
321
|
|
|
@@ -506,6 +515,14 @@ def load_book(path: Path) -> Book:
|
|
|
506
515
|
# on a book full of prose; count it so EMPTY carries the
|
|
507
516
|
# diagnostic.
|
|
508
517
|
spine_missing += 1
|
|
518
|
+
if ("#" in href or "?" in href) and full(
|
|
519
|
+
href.replace("#", "%23").replace("?", "%3F")
|
|
520
|
+
) in nameset:
|
|
521
|
+
# Delim-recoverable (issue #26): the raw #/? in the
|
|
522
|
+
# filename made the href resolve as path + fragment,
|
|
523
|
+
# and the encoded spelling finds the shipped file. The
|
|
524
|
+
# shell verdict subtracts this slice before deciding.
|
|
525
|
+
spine_missing_delim += 1
|
|
509
526
|
nav = full(nav_href) if nav_href else None
|
|
510
527
|
|
|
511
528
|
# The single full pass: every archive entry is fully read here (the
|
|
@@ -608,6 +625,7 @@ def load_book(path: Path) -> Book:
|
|
|
608
625
|
toc_absent,
|
|
609
626
|
encrypted=encrypted,
|
|
610
627
|
spine_missing=spine_missing,
|
|
628
|
+
spine_missing_delim=spine_missing_delim,
|
|
611
629
|
dup_entries=dup_entries,
|
|
612
630
|
obfuscated=obfuscated,
|
|
613
631
|
obfuscated_declared=obfuscated_declared,
|
|
@@ -1524,9 +1542,18 @@ def analyze_shell(book: Book) -> dict:
|
|
|
1524
1542
|
sliver of the archive -- 738 and 736 manifest items missing of 755 and
|
|
1525
1543
|
752 on the two shells. Re-source territory: no repair can fabricate
|
|
1526
1544
|
the missing files, and the spine guard correctly refuses to drop them.
|
|
1527
|
-
|
|
1545
|
+
|
|
1546
|
+
The delim-recoverable slice (`spine_missing_delim`, issue #26) is NOT
|
|
1547
|
+
missing content: the file is in the archive and the raw #/? in the
|
|
1548
|
+
href is what defeats resolution. The shell verdict runs on the
|
|
1549
|
+
GENUINE fraction (missing minus recoverable) -- the Elminster shape
|
|
1550
|
+
(36 of 38 hrefs defeated, all 36 files shipped) read as a shell and
|
|
1551
|
+
said re-source while the repair was one encode away. Advisory by
|
|
1552
|
+
contract, like completeness."""
|
|
1528
1553
|
spine_n = len(book.spine)
|
|
1529
1554
|
missing = book.spine_missing
|
|
1555
|
+
delim = book.spine_missing_delim
|
|
1556
|
+
genuine = max(0, missing - delim)
|
|
1530
1557
|
# the denominator is resolved + missing (the manifest the book claims),
|
|
1531
1558
|
# not the resolved spine alone: on a shell the resolved spine is the
|
|
1532
1559
|
# sliver (14 of 752), so a spine-only denominator read shells at over
|
|
@@ -1538,6 +1565,9 @@ def analyze_shell(book: Book) -> dict:
|
|
|
1538
1565
|
"missing": missing,
|
|
1539
1566
|
"manifest_total": total,
|
|
1540
1567
|
"missing_frac": frac,
|
|
1568
|
+
"delim_recoverable": delim,
|
|
1569
|
+
"genuine_missing": genuine,
|
|
1570
|
+
"genuine_frac": (genuine / total) if total else 0.0,
|
|
1541
1571
|
}
|
|
1542
1572
|
|
|
1543
1573
|
|
|
@@ -1547,11 +1577,17 @@ def _shell_dir(r: dict) -> tuple[bool, str, list[str]]:
|
|
|
1547
1577
|
f"({r['missing_frac'] * 100:.0f}%)"
|
|
1548
1578
|
]
|
|
1549
1579
|
status = "OK"
|
|
1550
|
-
if r["spine_docs"] and r["
|
|
1580
|
+
if r["spine_docs"] and r["genuine_frac"] >= 0.5:
|
|
1551
1581
|
status = (
|
|
1552
1582
|
"SHELL: the manifest names files the archive never carried; "
|
|
1553
1583
|
"re-source, never repair"
|
|
1554
1584
|
)
|
|
1585
|
+
elif r["delim_recoverable"]:
|
|
1586
|
+
status = (
|
|
1587
|
+
f"ADVISORY: {r['delim_recoverable']} of the missing hrefs resolve "
|
|
1588
|
+
"once their raw #/? are percent-encoded (the files are shipped); "
|
|
1589
|
+
"--encode-ref-delims territory, not re-source"
|
|
1590
|
+
)
|
|
1555
1591
|
return (False, status, lines)
|
|
1556
1592
|
|
|
1557
1593
|
|
|
@@ -116,6 +116,7 @@ def _flags_from_args(args: argparse.Namespace) -> RepairFlags:
|
|
|
116
116
|
double_colon_tags=args.fix_double_colon_tags or all_,
|
|
117
117
|
presentational_attrs=args.strip_presentational_attrs or all_,
|
|
118
118
|
encode_ref_brackets=args.encode_ref_brackets or all_,
|
|
119
|
+
encode_ref_delims=args.encode_ref_delims or all_,
|
|
119
120
|
prune_dead_spine=args.prune_dead_spine or all_,
|
|
120
121
|
)
|
|
121
122
|
|
|
@@ -261,6 +262,31 @@ def process_book(
|
|
|
261
262
|
verdict = "partial"
|
|
262
263
|
else:
|
|
263
264
|
verdict = "accept"
|
|
265
|
+
if report.fixes.get("refs_delim_encoded"):
|
|
266
|
+
# The missing-file mask (issue #26, the Elminster shape). A manifest
|
|
267
|
+
# item whose file the archive lacks is never parsed by epubcheck, so
|
|
268
|
+
# that document's own schema errors stay invisible -- the fatal
|
|
269
|
+
# branch's masking, one class over: a fatal halts its file's
|
|
270
|
+
# remaining checks, a missing file skips the file entirely. The
|
|
271
|
+
# error-cleanup branch demands a strict error decrease, and here the
|
|
272
|
+
# encode LOSES that comparison (0f/3e -> 0f/6e: the RSC-001 mass
|
|
273
|
+
# clears while the newly parsed documents surface their latent
|
|
274
|
+
# damage) while the spine-amputating prune wins it (0f/3e -> 0f/1e
|
|
275
|
+
# by deleting the documents). The encode's own gates bound the risk:
|
|
276
|
+
# it only rewrites references whose encoded spelling provably
|
|
277
|
+
# matches an archive entry and never touches a reference that
|
|
278
|
+
# already resolves, so it cannot damage a resolving reference --
|
|
279
|
+
# the rise is the mask lifting, not new damage. Bar: the fatal
|
|
280
|
+
# branch's, one class over -- net-new fatals still reject, a
|
|
281
|
+
# still-fatal candidate stays partial (never auto-applied), a
|
|
282
|
+
# fatal-free candidate accepts whatever the unmasking did to the
|
|
283
|
+
# error count. The spine veto below still overrides everything.
|
|
284
|
+
if after.fatals > before.fatals:
|
|
285
|
+
verdict = "reject"
|
|
286
|
+
elif after.fatals > 0:
|
|
287
|
+
verdict = "partial"
|
|
288
|
+
else:
|
|
289
|
+
verdict = "accept"
|
|
264
290
|
# The spine-resolution veto (issue #10). The epubcheck count is not
|
|
265
291
|
# spine-aware: a repair that orphans live itemrefs (manifest items pruned
|
|
266
292
|
# whose files the archive still carries, idrefs rewritten to forms that
|
|
@@ -1847,7 +1873,11 @@ _REPAIR_FLAG_TABLE: dict[str, list[tuple[str, str, str]]] = {
|
|
|
1847
1873
|
"the spine non-goal stays in force for ordinary damage. The "
|
|
1848
1874
|
"2026-11-04 Wandering Inn shells (738 and 736 of 755/752 items "
|
|
1849
1875
|
"dead) are the design case; proven on the facility copy at "
|
|
1850
|
-
"742e -> 5e with 0 fatals."
|
|
1876
|
+
"742e -> 5e with 0 fatals. The dead census also refuses items "
|
|
1877
|
+
"whose file exists under a delimiter-encoded spelling (issue "
|
|
1878
|
+
"#26): those hrefs are the delim encode's repair class, and "
|
|
1879
|
+
"pruning them would amputate live documents while the counts "
|
|
1880
|
+
"read it as an error win.",
|
|
1851
1881
|
),
|
|
1852
1882
|
(
|
|
1853
1883
|
"encode_ref_brackets",
|
|
@@ -1864,6 +1894,24 @@ _REPAIR_FLAG_TABLE: dict[str, list[tuple[str, str, str]]] = {
|
|
|
1864
1894
|
"as written. Runs on content documents, the OPF, the NCX, and "
|
|
1865
1895
|
"stylesheet url() tokens.",
|
|
1866
1896
|
),
|
|
1897
|
+
(
|
|
1898
|
+
"encode_ref_delims",
|
|
1899
|
+
"percent-encode raw # ? that defeat their own reference's resolution (RSC-001)",
|
|
1900
|
+
"percent-encode a literal # or ? inside a filename reference whose "
|
|
1901
|
+
'raw delimiter defeats resolution: href="Book_#01.htm" parses as '
|
|
1902
|
+
"file 'Book_' plus fragment '01.htm', the manifest item goes "
|
|
1903
|
+
"missing (RSC-001 'File ... could not be found'), and epubcheck "
|
|
1904
|
+
"never parses the document at all (issue #26: the Elminster "
|
|
1905
|
+
"bookmate conversion, 36 of 38 body docs unreachable). Two gates, "
|
|
1906
|
+
"both required: the reference must NOT resolve as written (a "
|
|
1907
|
+
"working doc.xhtml#intro is never touched; where both 'a' and "
|
|
1908
|
+
"'a#b' exist the RFC spelling wins), and the percent-encoded "
|
|
1909
|
+
"spelling must match an archive entry (the issue #19 mechanism: "
|
|
1910
|
+
"epubcheck decodes references before entry lookup, so the encoded "
|
|
1911
|
+
"form resolves to the raw-spelled entry). Entry names stay "
|
|
1912
|
+
"raw-spelled; a genuinely missing file stays as written. Runs on "
|
|
1913
|
+
"content documents, the OPF, the NCX, and stylesheet url() tokens.",
|
|
1914
|
+
),
|
|
1867
1915
|
(
|
|
1868
1916
|
"fix_page_map",
|
|
1869
1917
|
'drop the OPF page-map attribute; class="pages" on NCX pageLists',
|