bindery-cli 0.60.0__tar.gz → 0.61.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/PKG-INFO +2 -2
  2. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/README.md +1 -1
  3. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/patchnotes.md +90 -0
  4. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/pyproject.toml +1 -1
  5. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/roadmap.md +1 -0
  6. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/spec.md +6 -2
  7. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/src/bindery/__init__.py +1 -1
  8. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/src/bindery/cli.py +28 -4
  9. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/src/bindery/epub.py +8 -2
  10. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/src/bindery/transforms.py +14 -2
  11. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_cli.py +33 -0
  12. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_epub.py +62 -0
  13. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_transforms.py +47 -0
  14. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/uv.lock +1 -1
  15. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/.github/FUNDING.yml +0 -0
  16. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/.github/workflows/ci.yml +0 -0
  17. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/.github/workflows/publish.yml +0 -0
  18. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/.gitignore +0 -0
  19. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/AGENTS.md +0 -0
  20. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/LICENSE +0 -0
  21. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/OBSERVE-RESEARCH.md +0 -0
  22. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/docs/screenshots/library-sweep.png +0 -0
  23. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/logo.svg +0 -0
  24. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/plugin/__init__.py +0 -0
  25. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/project.done +0 -0
  26. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/run_tests.sh +0 -0
  27. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/scripts/FastSweep.java +0 -0
  28. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/scripts/build_plugin.py +0 -0
  29. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/scripts/fast_sweep.py +0 -0
  30. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/src/bindery/__main__.py +0 -0
  31. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/src/bindery/audit.py +0 -0
  32. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/src/bindery/library.py +0 -0
  33. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/src/bindery/observe.py +0 -0
  34. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/src/bindery/pagination.py +0 -0
  35. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/src/bindery/reserialize.py +0 -0
  36. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/src/bindery/validate.py +0 -0
  37. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/src/bindery/watermark.py +0 -0
  38. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_audit.py +0 -0
  39. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_comment_hyphens.py +0 -0
  40. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_contamination.py +0 -0
  41. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_cover_tocdrift.py +0 -0
  42. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_flags_real_core.py +0 -0
  43. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_flags_wiring.py +0 -0
  44. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_help.py +0 -0
  45. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_library.py +0 -0
  46. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_matcher_hardening.py +0 -0
  47. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_observe.py +0 -0
  48. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_pagination.py +0 -0
  49. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_plugin.py +0 -0
  50. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_reserialize.py +0 -0
  51. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_space_renames.py +0 -0
  52. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_spine_guard.py +0 -0
  53. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_validate.py +0 -0
  54. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_version.py +0 -0
  55. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_watermark.py +0 -0
  56. {bindery_cli-0.60.0 → bindery_cli-0.61.1}/tests/test_xml_hardening.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: bindery-cli
3
- Version: 0.60.0
3
+ Version: 0.61.1
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
@@ -57,7 +57,7 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
57
57
  - **`--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.
58
58
  - **`--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.
59
59
  - **`--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.
60
- - **`--fix-empty-body`**: appends a non-breaking space ` ` to strictly empty body tags to satisfy parser requirements.
60
+ - **`--fix-empty-body`**: gives a strictly empty `<body></body>` one minimal paragraph (`<p>&#160;</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.
61
61
  - **`--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.
62
62
  - **`--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.
63
63
  - **`--strip-invalid-value`**: systematically strips invalid `value="..."` attributes from elements like `<div>`, `<span>`, `<p>`, etc.
@@ -30,7 +30,7 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
30
30
  - **`--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.
31
31
  - **`--escape-unknown-entities`**: escape entity names that are not in the HTML5 table (`&foo;` becomes `&amp;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.
32
32
  - **`--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.
33
- - **`--fix-empty-body`**: appends a non-breaking space `&nbsp;` to strictly empty body tags to satisfy parser requirements.
33
+ - **`--fix-empty-body`**: gives a strictly empty `<body></body>` one minimal paragraph (`<p>&#160;</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.
34
34
  - **`--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.
35
35
  - **`--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.
36
36
  - **`--strip-invalid-value`**: systematically strips invalid `value="..."` attributes from elements like `<div>`, `<span>`, `<p>`, etc.
@@ -1,5 +1,95 @@
1
1
  # bindery-cli Patch Notes
2
2
 
3
+ ## v0.61.1 (2026-11-03)
4
+
5
+ ### The hex-ref href crash, and the sweep that survives it
6
+
7
+ The first whole-library `--all` dry run (the 2026-11-03 observe lane)
8
+ crashed with exit 1 forty minutes in: `_decode_numeric_refs` raised
9
+ `ValueError: invalid literal for int() with base 16: 'x2013'` inside the
10
+ prune's content-doc pass, and the exception escaped the sweep's repair
11
+ loop, killing the run and its report.
12
+
13
+ Two fixes:
14
+
15
+ - **The decoder** (epub.py): `_NUMERIC_REF_RE` captured the hex ref's `x`
16
+ into the digits group (`&#x2013;` -> `'x2013'`) and the repl fed the
17
+ whole capture to `int(_, 16)`. XML spells hex character references with
18
+ a lowercase x only, so the regex was right and the int call ate the x;
19
+ the fix strips the prefix before the int. The bug sat dormant since
20
+ v0.58.0 shipped the decode because the resolver runs only on the opt-in
21
+ paths (prune, anchor strip), so the default pass never met it. Library
22
+ census: 36 hex-ref hrefs across 5 books, every one an external URL
23
+ (en-dashes and ampersands in macmillan/tor/techcrunch query strings)
24
+ that the decode reaches before the scheme check discards it. Five new
25
+ tests pin the decode, the internal-href contract extended to hex, and
26
+ the crash shape end-to-end through `strip_missing_file_hrefs`.
27
+ - **The sweep crash guard** (cli.py): an unexpected per-book exception is
28
+ now that book's `error` verdict (`crash (ValueError): ...; not
29
+ applied`), counted in the existing errors tally and flowing to --json
30
+ like every other record, instead of a run-killing traceback. The
31
+ unified trouble exit contract is unchanged. The single-file repair
32
+ verb keeps its traceback: there an operator is watching one book.
33
+
34
+ Suite: 838 tests.
35
+
36
+ ## v0.61.0 (2026-11-02)
37
+
38
+ ### Issue #25: fix-empty-body injects `<p>&#160;</p>`, not bare `&nbsp;`
39
+
40
+ Space Prison (Calibre book #11556, the Pyramid 1960 scan-conversion rip)
41
+ surfaced the defect in a phase-3 sweep: the book's 205-byte shell page
42
+ (`OEBPS/text00001.html`, `<body></body>` under an XHTML 1.0 Strict
43
+ DOCTYPE) made `--fix-empty-body` flip its own `--all` candidate from a
44
+ clean decrease (`0f/6e/0w -> 0f/5e/0w` core) into a regression the gate
45
+ had to refuse (`0f/6e/0w -> 1f/4e/0w --all`), the delta exactly
46
+ `fix_empty_body:1` and the new count a FATAL RSC-016, "The entity nbsp
47
+ was referenced, but not declared".
48
+
49
+ The root cause has two halves, both verified against epubcheck 5.3 with
50
+ a minimal-EPUB matrix across XHTML 1.0 Strict / Transitional / XHTML
51
+ 1.1 / no-DOCTYPE shapes on EPUB2 packages and plain `<!DOCTYPE html>`
52
+ on EPUB3:
53
+
54
+ - epubcheck validates EPUB2 content docs against the XHTML 1.1 DTD and
55
+ resolves named entities only from DTDs it carries locally (the XHTML
56
+ 1.1 one). `&nbsp;` is not one of XML's five predefined entities, so
57
+ under every DOCTYPE epubcheck does not resolve locally -- XHTML 1.0
58
+ Strict and Transitional, and no DOCTYPE at all -- the injection was
59
+ an undeclared-entity parse fatal. EPUB3 is no refuge: XHTML content
60
+ documents are validated as XML there too, and `&nbsp;` is fatal
61
+ under every DOCTYPE shape tested.
62
+ - The XHTML 1.1 body content model is block elements only, so bare
63
+ character data (named or numeric) never satisfied it anywhere: the
64
+ error the fix was named for ("element body incomplete") never
65
+ cleared. The old injection therefore never once applied under
66
+ epubcheck 5.x -- every run was either a fatal-regression reject or
67
+ an equal-noop -- which is why hardening it breaks no user: there was
68
+ no working behavior to preserve, only a dead flag whose only live
69
+ behavior was flipping candidates into rejects.
70
+
71
+ The injection is now the exact literal `<p>&#160;</p>`. The numeric
72
+ character reference needs no DTD in any validation path, and the
73
+ wrapping `<p>` is the block element the content model demands; the
74
+ matrix shows it clearing "body incomplete" on every EPUB2 DOCTYPE
75
+ shape with zero fatals and zero new errors, while on EPUB3 books
76
+ (where an empty body raises nothing) the gate answers equal and
77
+ nothing applies. The gate now accepts the fixture honestly:
78
+ `0f/6e/0w -> 0f/4e/0w` (body incomplete and the NCX playOrder error
79
+ both fixed; the book's four pre-existing error-nits stay), applied
80
+ under `--all`.
81
+
82
+ The flag's name, selection rule, opt-in status, and count key are
83
+ unchanged; only the injected bytes differ. `--fix-empty-body` and the
84
+ plugin's default pass never overlapped (the plugin runs the default
85
+ pass only), so the Bindery Repair zip in this release just carries the
86
+ updated transform. Tests: `TestFixEmptyBody` (test_transforms.py) pins
87
+ the literal, the no-named-entity invariant, whitespace/attribute/case
88
+ shapes, and untouched non-empty bodies; test_epub.py carries the
89
+ issue #25 regression shape (a Strict-DOCTYPE shell doc whose candidate
90
+ must show the numeric-in-block injection and never `&nbsp;`). Suite:
91
+ 832 tests.
92
+
3
93
  ## v0.60.0 (2026-11-01)
4
94
 
5
95
  ### Issue #24: the oracle budget also scales on archive entry count
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "bindery-cli"
7
- version = "0.60.0"
7
+ version = "0.61.1"
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 = [
@@ -54,6 +54,7 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
54
54
  | 0.58 | The structural dry run's four rejects (issues #18-#21), each bisected to the root on its specimens: the private-ZipInfo write contract (issue #18: writestr stamps the info it is handed with the DESTINATION offsets, one shared info repointed zin's own lookups into the output file -- all 57 "unreadable" books, the "possible zip bomb" included, were this one bug; the peek also catches BadZipFile per the issue), bracket-encoded renamed references plus the start-tag/PI anchor on both reference rewriters (issue #19: raw brackets are RSC-020 path-illegal -- IJ 108e -> 22e -- and the unanchored regex corrupted display text that teaches HTML -- Hacking's two RSC-016 fatals), the entity-decoding href resolver and prefix-tolerant OPF matchers (issue #20: `&amp;` hrefs vs raw-`&` entries made prune and declare swap the same items on the D&D four, and `<opf:item>` blindness duplicated whole manifests on the Sony three), and the three #21 mechanisms (guide-fragment strip, the post-anchor playOrder re-run, the comment-blind duplicate-id rename) | v0.58.0 |
55
55
  | 0.59 | The dangling-NCX prune (issue #23): `--prune-dangling-ncx-targets` removes navPoint/pageTarget elements whose `<content src>` names a document the archive never contained (RSC-007 the manifest prune cannot reach: no item exists for a file the OPF never declared), node-exact over a balanced stack scanner (dead subtree drops as one span, dead parent spliced above live children, scheme/bare-fragment/comment-hidden/contentless refused, unbalanced walk aborts), with the contract-gated playOrder pass re-run in the same branch -- the hand-surgery-plus-second-run rescue is one gate (fixture 0f/1e/0w -> 0f/0e/0w: one navPoint pruned, 389 playOrder values re-sequenced) | v0.59.0 |
56
56
  | 0.60 | The oracle budget scales on decimal MB and archive entry count (issue #24): the Summa Theologica (10,440,245 bytes = 9.96 binary MiB, 3,831 entries, 3,808 spine docs, 16,456 playOrder findings) is entry-count-bound, not bytes-bound -- measured 384s source and 445s candidate against the flat 300s its bytes computed (the binary 10 MiB divisor ate the size chunk; the book the docs call 10.4 MB never earned one) -- so every sweep double-timed-out and misfiled it as `(epubcheck timeout)`; the size term counts decimal MB now, the entry term adds +60s per started 500 entries above 1,000 (same 1800s cap), the book computes 720s, and a non-zip path falls back to size-only. epubcheck does police the playOrder contract (2 of the source's 6 RSC-005 error entries): default-pass candidate measures 0f/6e -> 0f/4e (accept), scoped `--all` candidate 0f/0e/0w | v0.60.0 |
57
+ | 0.61.1 | The hex-ref href crash and the sweep that survives it: `_NUMERIC_REF_RE` captured the hex ref's `x` into the digits group and `int('x2013', 16)` killed the first whole-library `--all` dry run (2026-11-03 observe lane; 36 hex-ref hrefs across 5 books, every one an external URL the decode reaches before the scheme check discards it; dormant since v0.58.0 because the resolver is opt-in-path-only); the fix strips the prefix before the int, and the sweep's repair loop gains the crash guard -- an unexpected per-book exception is that book's `error` verdict (`crash (Type): ...; not applied`), counted in the existing errors tally, instead of a run-killing traceback (the single-file verb keeps its traceback) | v0.61.1 |
57
58
 
58
59
  ## Open work
59
60
 
@@ -150,8 +150,12 @@ byte-for-byte. The normal gate applies.
150
150
  Twenty-six repairs go past well-formedness and therefore require their own flag; none is ever
151
151
  part of the default pipeline:
152
152
 
153
- - **`--fix-empty-body`**: `&nbsp;` inside a strictly empty `<body></body>` ("body
154
- incomplete"). Adds visible content, hence opt-in like `--add-img-alt`.
153
+ - **`--fix-empty-body`**: `<p>&#160;</p>` inside a strictly empty `<body></body>` ("body
154
+ incomplete"). The numeric character reference needs no DTD and the wrapping `p` is the
155
+ block element XHTML 1.1's body content model demands (issue #25: the `&nbsp;` this fix
156
+ originally injected was an undeclared-entity parse fatal under every DOCTYPE epubcheck
157
+ does not resolve locally, and bare character data never satisfied the content model).
158
+ Adds visible content, hence opt-in like `--add-img-alt`.
155
159
  - **`--fix-missing-title`**: inject `<title>Unknown</title>` when the head has no usable
156
160
  title.
157
161
  - **`--fix-id-colons`**: illegal colons in `id="X:Y"` and their matching internal
@@ -11,7 +11,7 @@ Calibre plugin built from this core.
11
11
  Single source of truth for the version. pyproject.toml must match VERSION below.
12
12
  """
13
13
 
14
- VERSION = "0.60.0"
14
+ VERSION = "0.61.1"
15
15
  __version__ = VERSION
16
16
 
17
17
  from .epub import RepairReport, repair_epub # noqa: E402
@@ -843,6 +843,26 @@ def run_library(args) -> int:
843
843
  )
844
844
  tqdm.write(f" ERROR {rel}\n unreadable ({reason}): {e}")
845
845
  continue
846
+ except Exception as e:
847
+ # The crash guard (v0.61.1): an unexpected per-book exception (a
848
+ # transform meeting an input shape no test imagined) used to
849
+ # escape as a run-killing traceback that cost a multi-hour sweep
850
+ # its whole report (the 2026-11-03 hex-ref href crash). One
851
+ # book's bug is that book's error verdict, not the run's.
852
+ errors += 1
853
+ records.append(
854
+ Outcome(
855
+ epub,
856
+ "error",
857
+ None,
858
+ None,
859
+ f"crash ({type(e).__name__}): {e}; not applied",
860
+ )
861
+ )
862
+ tqdm.write(
863
+ f" ERROR {rel}\n crash ({type(e).__name__}): {e}; not applied"
864
+ )
865
+ continue
846
866
  records.append(o)
847
867
  if o.status == "nochange":
848
868
  nochange += 1
@@ -1668,10 +1688,14 @@ _REPAIR_FLAG_TABLE: dict[str, list[tuple[str, str, str]]] = {
1668
1688
  "structural repairs: markup and nesting": [
1669
1689
  (
1670
1690
  "fix_empty_body",
1671
- "append &nbsp; to a strictly empty <body></body>",
1672
- "append &nbsp; inside a strictly empty <body></body> (the 'body "
1673
- "incomplete' error). Adds visible content the author never wrote; "
1674
- "hence opt-in.",
1691
+ "fill a strictly empty <body></body> with <p>&#160;</p>",
1692
+ "inject <p>&#160;</p> inside a strictly empty <body></body> (the "
1693
+ "'body incomplete' error). The numeric character reference needs "
1694
+ "no DTD (a named &nbsp; is an undeclared-entity parse fatal under "
1695
+ "every DOCTYPE epubcheck does not resolve locally) and the "
1696
+ "wrapping p is the block element XHTML 1.1's body content model "
1697
+ "demands, which bare text never satisfied. Adds visible content "
1698
+ "the author never wrote; hence opt-in.",
1675
1699
  ),
1676
1700
  (
1677
1701
  "fix_missing_title",
@@ -753,7 +753,10 @@ def _decode_numeric_refs(s: str) -> str:
753
753
 
754
754
  def repl(m: re.Match) -> str:
755
755
  digits = m.group(1)
756
- cp = int(digits, 16 if digits[0] in "xX" else 10)
756
+ # The hex alternative captures its lowercase x (XML's only spelling):
757
+ # strip it here. Feeding it to int() raised ValueError on the first
758
+ # href carrying &#x2013; and killed the whole-library sweep (2026-11-03).
759
+ cp = int(digits[1:], 16) if digits[0] in "xX" else int(digits, 10)
757
760
  return chr(cp) if 0 < cp <= 0x10FFFF else m.group(0)
758
761
 
759
762
  return _NUMERIC_REF_RE.sub(repl, s)
@@ -1994,7 +1997,10 @@ def repair_epub(
1994
1997
  With `strip_watermarks`, remove known producer watermarks (e.g. OceanofPDF).
1995
1998
 
1996
1999
  The structural repairs are all opt-in, never part of the core pass:
1997
- with `empty_body`, append &nbsp; to a strictly empty <body>; with `missing_title`,
2000
+ with `empty_body`, inject the exact literal `<p>&#160;</p>` into a strictly
2001
+ empty <body> (the numeric reference needs no DTD and the wrapping p is
2002
+ the block epubcheck's XHTML 1.1 body content model demands — issue #25);
2003
+ with `missing_title`,
1998
2004
  inject a <title>Unknown</title> fallback; with `id_colons`, translate illegal
1999
2005
  colons in id attributes and their #fragment references; with `block_in_inline`,
2000
2006
  unwrap a <span> that illegally wraps a block element; with `invalid_value`, strip
@@ -631,7 +631,19 @@ def unwrap_illegal_tags(
631
631
 
632
632
  @_outside_protected
633
633
  def fix_empty_body(s: str) -> tuple[str, int]:
634
- """Append `&nbsp;` to a strictly empty `<body></body>` ("body incomplete").
634
+ """Give a strictly empty `<body></body>` one minimal paragraph, the exact
635
+ literal `<p>&#160;</p>` ("body incomplete").
636
+
637
+ That literal, not the bare `&nbsp;` this fix shipped with (issue #25):
638
+ epubcheck validates EPUB2 content docs against the
639
+ with (issue #25): epubcheck validates EPUB2 content docs against the
640
+ XHTML 1.1 DTD, whose body content model is block elements only, so bare
641
+ character data never cleared the error, and `&nbsp;` is not one of XML's
642
+ five predefined entities, so under every DOCTYPE whose DTD epubcheck does
643
+ not load locally the injection was itself a parse-fatal RSC-016 ("The
644
+ entity "nbsp" was referenced, but not declared"). The numeric
645
+ character reference needs no DTD at all, and the wrapping `<p>` is the
646
+ block the content model demands.
635
647
 
636
648
  Opt-in (--fix-empty-body): this ADDS visible content the author never wrote,
637
649
  the same reason --add-img-alt is opt-in; it is never part of the core pass.
@@ -641,7 +653,7 @@ def fix_empty_body(s: str) -> tuple[str, int]:
641
653
  def repl(m: re.Match) -> str:
642
654
  nonlocal count
643
655
  count += 1
644
- return m.group(1) + "&nbsp;" + m.group(2)
656
+ return m.group(1) + "<p>&#160;</p>" + m.group(2)
645
657
 
646
658
  s, n = re.subn(r"(<body[^>]*>\s*)(</body>)", repl, s, flags=re.IGNORECASE)
647
659
  return s, n
@@ -160,6 +160,39 @@ class TestLibrarySurvivesCorruptEpub(unittest.TestCase):
160
160
  self.assertIn("cannot read", err.getvalue())
161
161
 
162
162
 
163
+ class TestLibrarySurvivesUnexpectedCrash(unittest.TestCase):
164
+ def test_sweep_converts_a_crashing_book_to_an_error_verdict(self):
165
+ # v0.61.1's crash guard: an unexpected exception inside the per-book
166
+ # repair used to escape as a run-killing traceback (the 2026-11-03
167
+ # hex-ref href crash cost a whole-library --all sweep its report).
168
+ # One book's bug is that book's error verdict, not the run's.
169
+ with tempfile.TemporaryDirectory() as td:
170
+ root = Path(td)
171
+ crasher = root / "Author" / "Crash (1)" / "crash.epub"
172
+ crasher.parent.mkdir(parents=True)
173
+ build(crasher)
174
+ good = root / "Author" / "Book (2)" / "book.epub"
175
+ good.parent.mkdir(parents=True)
176
+ build(good)
177
+ real = process_book
178
+
179
+ def flaky(src, *a, **k):
180
+ if src.name == "crash.epub":
181
+ raise ValueError("int('x2013', 16)")
182
+ return real(src, *a, **k)
183
+
184
+ out, err = io.StringIO(), io.StringIO()
185
+ with (
186
+ mock.patch("bindery.cli.process_book", side_effect=flaky),
187
+ redirect_stdout(out),
188
+ redirect_stderr(err),
189
+ ):
190
+ rc = main(["library", td, "--no-validate"])
191
+ self.assertEqual(rc, 2)
192
+ self.assertIn("crash (ValueError)", out.getvalue())
193
+ self.assertIn("ACCEPT", out.getvalue())
194
+
195
+
163
196
  class TestRepairPartialLabel(unittest.TestCase):
164
197
  def test_partial_output_is_labeled_not_repaired(self):
165
198
  # The file is worth writing (fewer fatals), but the old "repaired:" line read
@@ -10,7 +10,9 @@ from xml.etree import ElementTree as ET
10
10
 
11
11
  from bindery.epub import (
12
12
  RepairFlags,
13
+ _decode_numeric_refs,
13
14
  _locate_opf,
15
+ _resolve_href,
14
16
  collect_undeclared_resources,
15
17
  declare_missing_manifest_items,
16
18
  downgrade_epub3_tags,
@@ -24,6 +26,7 @@ from bindery.epub import (
24
26
  package_version,
25
27
  repair_epub,
26
28
  strip_epub3_attributes,
29
+ strip_missing_file_hrefs,
27
30
  strip_ncx_dangling_targets,
28
31
  strip_page_map,
29
32
  sync_ncx_uid,
@@ -1012,6 +1015,28 @@ class TestOptInStructuralRepairs(unittest.TestCase):
1012
1015
  report = repair_epub(self.src, self.dst, RepairFlags(empty_body=True))
1013
1016
  self.assertIn("fix_empty_body", report.fixes)
1014
1017
 
1018
+ def test_empty_body_injection_is_numeric_in_a_block(self):
1019
+ # issue #25 (Space Prison #11556): the shell doc declares XHTML 1.0
1020
+ # Strict, whose DTD epubcheck does not resolve locally, so the old
1021
+ # bare `&nbsp;` injection was an undeclared-entity parse fatal
1022
+ # (RSC-016) and the candidate died in the gate as a regression. The
1023
+ # injection must be the DTD-independent numeric reference inside the
1024
+ # block element XHTML 1.1's body content model demands.
1025
+ self._build(
1026
+ css="p { margin: 0 }",
1027
+ content=(
1028
+ '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" '
1029
+ '"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">'
1030
+ '<html xmlns="http://www.w3.org/1999/xhtml">\r'
1031
+ "<head><title></title>\r</head>\r<body></body>\r</html>\r"
1032
+ ),
1033
+ )
1034
+ repair_epub(self.src, self.dst, RepairFlags(empty_body=True))
1035
+ with zipfile.ZipFile(self.dst) as z:
1036
+ c = z.read("OEBPS/c1.xhtml").decode()
1037
+ self.assertIn("<body><p>&#160;</p></body>", c)
1038
+ self.assertNotIn("&nbsp;", c)
1039
+
1015
1040
 
1016
1041
  class TestPruneMissingResources(unittest.TestCase):
1017
1042
  """--prune-missing-resources: references to files the archive does not
@@ -3120,3 +3145,40 @@ class TestUnboundPrefix(unittest.TestCase):
3120
3145
  src, dst = self._build_embed_scar(td)
3121
3146
  report = repair_epub(src, dst)
3122
3147
  self.assertNotIn("unbound_prefixes_bound", report.fixes)
3148
+
3149
+
3150
+ class TestNumericRefHrefDecode(unittest.TestCase):
3151
+ """The hex branch of the issue #20 decode: the regex captured the x into
3152
+ the digits group and int('x2013', 16) raised ValueError on the first href
3153
+ carrying &#x2013;, killing the whole-library --all sweep (2026-11-03; 36
3154
+ hrefs across 5 books, every one an external URL the decode reaches before
3155
+ the scheme check). XML spells hex refs with a lowercase x only; the regex
3156
+ was right, the int call ate the x."""
3157
+
3158
+ def test_hex_ref_decodes(self):
3159
+ self.assertEqual(_decode_numeric_refs("8&#x2013;5-million"), "8–5-million")
3160
+
3161
+ def test_decimal_ref_unchanged(self):
3162
+ self.assertEqual(_decode_numeric_refs("K&#38;C.png"), "K&C.png")
3163
+
3164
+ def test_out_of_range_ref_stays_encoded(self):
3165
+ self.assertEqual(_decode_numeric_refs("a&#x110000;b"), "a&#x110000;b")
3166
+
3167
+ def test_internal_hex_ref_href_resolves_to_its_entry(self):
3168
+ # the issue #20 contract extended to hex: href="a&#x2013;b.xhtml"
3169
+ # names the raw entry a–b.xhtml
3170
+ self.assertEqual(_resolve_href("OEBPS", "a&#x2013;b.xhtml"), "OEBPS/a–b.xhtml")
3171
+
3172
+ def test_external_hex_ref_href_survives_the_anchor_prune(self):
3173
+ # the crash shape end-to-end: an <a> href carrying &#x2013; (an
3174
+ # external URL) went through _resolve_href inside
3175
+ # strip_missing_file_hrefs and raised, killing the sweep
3176
+ text = (
3177
+ '<html xmlns="http://www.w3.org/1999/xhtml"><body><p>'
3178
+ '<a href="http://techcrunch.com/2011/02/01kleiner-perkins-leads'
3179
+ '-8&#x2013;5-million-round-for-path/">x</a>'
3180
+ "</p></body></html>"
3181
+ )
3182
+ out, n = strip_missing_file_hrefs(text, "OEBPS", frozenset({"OEBPS/c1.xhtml"}))
3183
+ self.assertEqual(n, 0)
3184
+ self.assertEqual(out, text)
@@ -550,6 +550,53 @@ class TestStructuralRepairsAreOptIn(unittest.TestCase):
550
550
  self.assertGreaterEqual(n, 1)
551
551
 
552
552
 
553
+ class TestFixEmptyBody(unittest.TestCase):
554
+ """The injection is `<p>&#160;</p>` (issue #25): epubcheck validates EPUB2
555
+ content docs against the XHTML 1.1 DTD, whose body content model is block
556
+ elements only, so the bare `&nbsp;` this fix shipped with never cleared
557
+ the error and was itself an undeclared-entity parse fatal (RSC-016) under
558
+ every DOCTYPE epubcheck does not resolve locally."""
559
+
560
+ def test_injects_numeric_entity_in_a_block(self):
561
+ out, n = fix_empty_body("<html><body></body></html>")
562
+ self.assertEqual(n, 1)
563
+ self.assertEqual(out, "<html><body><p>&#160;</p></body></html>")
564
+
565
+ def test_never_emits_the_named_entity(self):
566
+ # the issue #25 regression class: &nbsp; is not one of XML's five
567
+ # predefined entities, so it is a parse fatal under a DOCTYPE whose
568
+ # DTD declares no HTML entity set
569
+ out, _ = fix_empty_body("<body></body>")
570
+ self.assertNotIn("&nbsp;", out)
571
+
572
+ def test_whitespace_only_body_fires(self):
573
+ out, n = fix_empty_body("<body>\r</body>")
574
+ self.assertEqual(n, 1)
575
+ self.assertEqual(out, "<body>\r<p>&#160;</p></body>")
576
+
577
+ def test_body_attributes_and_leading_space_survive(self):
578
+ out, n = fix_empty_body('<body class="chapter">\n</body>')
579
+ self.assertEqual(n, 1)
580
+ self.assertEqual(out, '<body class="chapter">\n<p>&#160;</p></body>')
581
+
582
+ def test_case_insensitive_match(self):
583
+ out, n = fix_empty_body("<BODY></BODY>")
584
+ self.assertEqual(n, 1)
585
+ self.assertEqual(out, "<BODY><p>&#160;</p></BODY>")
586
+
587
+ def test_non_empty_body_untouched(self):
588
+ for body in ("<body><p>x</p></body>", '<body><img src="a.png"/></body>'):
589
+ with self.subTest(body=body):
590
+ out, n = fix_empty_body(body)
591
+ self.assertEqual((out, n), (body, 0))
592
+
593
+ def test_multiple_empty_bodies_count_individually(self):
594
+ # malformed (one body per document), but the count must stay honest
595
+ out, n = fix_empty_body("<body></body><body></body>")
596
+ self.assertEqual(n, 2)
597
+ self.assertEqual(out.count("<p>&#160;</p>"), 2)
598
+
599
+
553
600
  class TestFixNcxPlayorder(unittest.TestCase):
554
601
  def test_resequences_navpoint_attributes(self):
555
602
  ncx = (
@@ -8,7 +8,7 @@ resolution-markers = [
8
8
 
9
9
  [[package]]
10
10
  name = "bindery-cli"
11
- version = "0.60.0"
11
+ version = "0.61.1"
12
12
  source = { editable = "." }
13
13
  dependencies = [
14
14
  { name = "cquarry", marker = "python_full_version >= '3.14'" },
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes