bindery-cli 0.56.0__tar.gz → 0.57.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.56.0 → bindery_cli-0.57.1}/AGENTS.md +25 -11
  2. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/PKG-INFO +1 -1
  3. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/patchnotes.md +82 -0
  4. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/pyproject.toml +1 -1
  5. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/roadmap.md +1 -0
  6. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/spec.md +31 -11
  7. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/src/bindery/__init__.py +1 -1
  8. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/src/bindery/cli.py +27 -17
  9. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/src/bindery/epub.py +16 -9
  10. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/src/bindery/transforms.py +62 -24
  11. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_cli.py +64 -7
  12. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_epub.py +122 -0
  13. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_flags_real_core.py +16 -10
  14. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_transforms.py +165 -0
  15. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/uv.lock +1 -1
  16. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/.github/FUNDING.yml +0 -0
  17. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/.github/workflows/ci.yml +0 -0
  18. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/.github/workflows/publish.yml +0 -0
  19. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/.gitignore +0 -0
  20. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/LICENSE +0 -0
  21. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/OBSERVE-RESEARCH.md +0 -0
  22. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/README.md +0 -0
  23. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/docs/screenshots/library-sweep.png +0 -0
  24. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/logo.svg +0 -0
  25. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/plugin/__init__.py +0 -0
  26. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/project.done +0 -0
  27. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/run_tests.sh +0 -0
  28. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/scripts/FastSweep.java +0 -0
  29. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/scripts/build_plugin.py +0 -0
  30. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/scripts/fast_sweep.py +0 -0
  31. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/src/bindery/__main__.py +0 -0
  32. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/src/bindery/audit.py +0 -0
  33. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/src/bindery/library.py +0 -0
  34. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/src/bindery/observe.py +0 -0
  35. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/src/bindery/pagination.py +0 -0
  36. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/src/bindery/reserialize.py +0 -0
  37. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/src/bindery/validate.py +0 -0
  38. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/src/bindery/watermark.py +0 -0
  39. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_audit.py +0 -0
  40. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_comment_hyphens.py +0 -0
  41. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_contamination.py +0 -0
  42. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_cover_tocdrift.py +0 -0
  43. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_flags_wiring.py +0 -0
  44. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_help.py +0 -0
  45. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_library.py +0 -0
  46. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_matcher_hardening.py +0 -0
  47. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_observe.py +0 -0
  48. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_pagination.py +0 -0
  49. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_plugin.py +0 -0
  50. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_reserialize.py +0 -0
  51. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_space_renames.py +0 -0
  52. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_spine_guard.py +0 -0
  53. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_validate.py +0 -0
  54. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_version.py +0 -0
  55. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_watermark.py +0 -0
  56. {bindery_cli-0.56.0 → bindery_cli-0.57.1}/tests/test_xml_hardening.py +0 -0
@@ -64,12 +64,20 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
64
64
  verified against 5.3), ambiguous renames refused per entry (`space_rename_map`),
65
65
  accepted under `no_worse` because PKG-010 sits on the warning axis the gate
66
66
  does not measure. `--fix-unbound-prefix` (v0.51.0, issue #9, the Calibre
67
- embed scar) binds an attribute prefix the OPF never declares inline on the
68
- element that uses it (`<dc:identifier id="ID1" ns0:scheme="calibre">`
67
+ embed scar; element half v0.57.0, issue #22) binds a prefix the OPF
68
+ never declares in scope inline on the element that uses it: the
69
+ attribute half (`<dc:identifier id="ID1" ns0:scheme="calibre">`
69
70
  whose `xmlns:ns0` sits on a sibling, out of XML scope; two RSC-016 fatals
70
- plus OPF-030): URI evidence is the same prefix declared elsewhere in the
71
- document (all declarations must agree) or the OPF namespace for a DC
72
- element under an OPF-namespaced package, anything else refuses the whole
71
+ plus OPF-030) and, since v0.57.0, the element half (the Calibre 9.7.0
72
+ writer self-declares `xmlns:dc` on every dc: element but one, so that
73
+ element's own name dies with `FATAL(RSC-016): The prefix "dc" for
74
+ element "dc:date" is not bound`; the scope walk now checks each start
75
+ tag's own name and binds it on the element): URI evidence is the same
76
+ prefix declared elsewhere in the
77
+ document (all declarations must agree) or the use site's own namespace
78
+ for a Dublin Core site under an OPF-namespaced package (the OPF
79
+ namespace for a DC element's attributes, the DC namespace for a literal
80
+ `dc:` element name), anything else refuses the whole
73
81
  document; scope-tracked over a comment/CDATA-aware tokenizer, OPF only
74
82
  (content docs have the `--strip-bad-attrs` drop); normal `gate`.
75
83
  The v0.55.0 two (the 2026-10-25 issue batch): `--declare-missing-items`
@@ -145,12 +153,18 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
145
153
  gain IS visible, so a run with no measurable improvement is a noop and nothing is
146
154
  applied) except the two whose gains sit on axes epubcheck does not measure:
147
155
  `--fix-cover` and `--encode-url-spaces`, accepted under the same `no_worse` bar with
148
- the partial rule intact. One masked-axis rule (v0.51.0, issue #9): when the gate
149
- answers noop but `report.ncx_uid_synced` fired on a book that started with fatals,
150
- `process_book` reclassifies the verdict to `partial` (a fatal package halts the
151
- metadata checks, so the dtb:uid comparison never ran in either measurement and the
152
- real sync measures as no gain); application behavior is unchanged, since still-fatal
153
- books are never applied. One structural veto rides above the counts (v0.52.0,
156
+ the partial rule intact. One masked-axis rule (v0.51.0, issue #9, for the
157
+ NCX sync; generalized v0.57.0, issue #22, to every fired fix): when the gate
158
+ answers noop on a book that started AND stayed fatal, `process_book`
159
+ reclassifies the verdict to `partial` (a still-fatal package keeps
160
+ epubcheck's per-file halt, so whatever the fix cleared below the halt --
161
+ the dtb:uid comparison, an error axis, a second latent fatal unmasked by the
162
+ fix that cleared the first: `unbound_prefixes_bound:1`, 1f/1e -> 1f/0e,
163
+ fatals read 1 -> 1 -- measures as no gain, and a silent `equal` buries a
164
+ book that still will not open instead of landing it on the manual list);
165
+ application behavior is unchanged, since still-fatal
166
+ books are never applied, and clean books are untouched (no fatals on both
167
+ sides, no reclassification). One structural veto rides above the counts (v0.52.0,
154
168
  issue #10): `process_book` probes source and candidate with `epub.spine_dangles`
155
169
  (itemref -> manifest item -> archive entry, resolved through the same helper the
156
170
  repair's existence checks use) and rejects any candidate whose dangle count rises
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: bindery-cli
3
- Version: 0.56.0
3
+ Version: 0.57.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
@@ -1,5 +1,87 @@
1
1
  # bindery-cli Patch Notes
2
2
 
3
+ ## v0.57.1 (2026-10-25)
4
+
5
+ ### The prefixed dtb:uid sync: the issue #22 specimen's last finding
6
+
7
+ Same night as v0.57.0, on the follow-up call: the Hackers specimen
8
+ repaired to `0f/1e` because its residual error was NCX-001, not embed
9
+ damage. That book's 2010-era NCX spells every element with the `ncx:`
10
+ prefix (`<ncx:meta name="dtb:uid" .../>`), and the always-on sync's
11
+ matchers anchored on a literal `<meta`, so a prefixed dtb:uid carrier
12
+ was invisible: the sync skipped, and the drift survived an otherwise
13
+ clean repair. Both matchers (`_DTB_UID_RE` and the reversed
14
+ content-before-name form) now accept an optional namespace prefix on the
15
+ meta element; the group layout is unchanged (the prefix lives inside the
16
+ reconstruct group), so the quote-agnostic replacement logic is
17
+ untouched, and a prefixed element whose local name merely starts with
18
+ "meta" (the `<p:metadata>` shape) still matches nothing. The `--only
19
+ ncx` sweep selector reads the same matchers, so prefixed-NCX books with
20
+ drifted uids are now candidates too. Live gate on the specimen chain:
21
+ the scarred Hackers book now goes `1f/1e/0w -> 0f/0e/0w` in one run
22
+ (`unbound_prefixes_bound:2, ncx_uid_synced`), the exact end state the
23
+ hand repair had reached.
24
+
25
+ Suite: 793 tests.
26
+
27
+
28
+ ## v0.57.0 (2026-10-25)
29
+
30
+ ### Issue #22: the embed scar's element half, and the end of the silent equal
31
+
32
+ The reconcile-embed fallout's last scar shape, plus the reporting gap its
33
+ investigation exposed.
34
+
35
+ **`--fix-unbound-prefix` binds element prefixes (shape 1).** Calibre
36
+ 9.7.0's `embed_metadata` self-declares `xmlns:dc` on every dc: element it
37
+ writes but one, leaving that element's own ELEMENT prefix unbound:
38
+ `FATAL(RSC-016): The prefix "dc" for element "dc:date" is not bound`. The
39
+ v0.51.0 repair covered attribute prefixes only (`ns0:scheme`); the element
40
+ name is a different use site and nothing in the inventory touched it, so
41
+ the specimen chain sat one fatal apart from clean with no repair left to
42
+ run. The same scope-tracking walk now checks each start tag's own name:
43
+ an unbound element prefix is bound inline on the element, the exact shape
44
+ the file's healthy siblings already use. The evidence rules carry over
45
+ with one addition: rule 1 is unchanged (the prefix declared elsewhere in
46
+ the document, every declaration agreeing), and rule 2 for a literal `dc:`
47
+ element under an OPF-namespaced package resolves to the DC namespace
48
+ itself (the attribute half's rule 2 names the OPF namespace because
49
+ `opf:scheme` rides on DC elements; a `dc:` element IS the Dublin Core
50
+ element). Ambiguous or unevidenced prefixes still refuse the whole
51
+ document, clean documents stay byte-identical, and the each-use-site
52
+ counting contract holds (nested unbound elements each get their own
53
+ declaration, mirroring the attribute half). One start tag never carries
54
+ two declarations for one prefix (XML forbids the duplicate attribute;
55
+ the code-review pass caught the collision between an unbound element
56
+ prefix and an unbound same-prefix attribute on one tag, and fixed the
57
+ attribute-vs-attribute variant the attribute half had always carried).
58
+ Live gate on the specimen
59
+ (Hackers, the issue's own chain): the scarred original went
60
+ `1f/1e -> 0f/1e` with `unbound_prefixes_bound:2` (attribute + element in
61
+ one run), and the half-repaired intermediate that v0.56.0 refused as
62
+ `equal` now repairs (`1f/0e -> 0f/1e`, the element bind alone). The
63
+ residual error on the specimen is NCX-001, not embed damage: its 2010-era
64
+ NCX spells every element with the `ncx:` prefix, which the always-on
65
+ dtb:uid sync's `<meta\b` matcher does not read; that sync gap is recorded
66
+ on the issue and left unrepaired here.
67
+
68
+ **Still-fatal noops reclassify as partial (shape 2).** The same
69
+ investigation caught the gate answering `equal (no measurable gain)` on a
70
+ book whose fix had cleared one fatal and unmasked a latent second:
71
+ `unbound_prefixes_bound:1` fired, `1f/1e -> 1f/0e`, fatals read 1 -> 1,
72
+ and the silent skip buried a book that still will not open. The v0.51.0
73
+ masked-ncx-gain rule already reclassified exactly this shape for the uid
74
+ sync; it is now general (the gate's noop on any book that started and
75
+ stayed fatal means the fix's real axis lives below epubcheck's per-file
76
+ halt, whatever the fix was): the verdict is `partial`, the book lands on
77
+ the manual list (`still_fatal`), and the still-fatal rule is untouched
78
+ (partial candidates were never auto-applied). Clean books are unaffected:
79
+ the rule cannot fire without fatals on both sides, and the gate's own
80
+ partial and reject answers never enter it.
81
+
82
+ Twenty-five structural repairs. Suite: 789 tests.
83
+
84
+
3
85
  ## v0.56.0 (2026-10-25)
4
86
 
5
87
  ### The two boxed recipes, built: the OPF-030 wiring and the CSS-007 font half
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "bindery-cli"
7
- version = "0.56.0"
7
+ version = "0.57.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 = [
@@ -50,6 +50,7 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
50
50
  | 0.54 | The surgery fixes: `fix_ncx_playorder` is contract-gated (epubcheck's playOrder contract: same-target sharing, distinct-target distinctness, contiguous 1..K across navTarget/pageTarget; the old unconditional 1..N renumbering rewrote valid TOCs into violations, 211 of 579 firings gate-rejected vs 17 real fixes) and `_PROTECTED_RE` protects the Calibre `/*<![CDATA[*/ ... /*]]>*/` wrapper as one unit (the bare CDATA span exposed the trailing `*/` to strip_prolog_junk's amputation, 111 phantom-fix rejections); verified by the 2026-10-24 error-code surgery (OBSERVE-RESEARCH.md) | v0.54.0 |
51
51
  | 0.55 | The issue-batch release (issues #11-#16, the 2026-10-24 surgery's follow-ups): `--strip-epub3-attrs` extended with `role` + `aria-hidden` (the census killed the DOCTYPE-gate concern: epubcheck is profile-driven; #11), `--fix-duplicate-ids` for content docs (#14), `--declare-missing-items` for RSC-008 (#16, with the prune's RSC-001 boundary documented), the size-scaled epubcheck timeout with one retry and the distinct `OracleTimeout` (#15), observe schema v2 (`codes.messages` rename, true `codes.occurrences`, the `counting` block, v1 `--against` accepted; #13), the #12 content-model ruling (measured, not repaired: the wrap changes layout), and the #17 census lanes (RSC-012/OPF-029 dispositions on existing flags; OPF-030/CSS-007/RSC-004 recorded leave-measured with recipes) | v0.55.0 |
52
52
  | 0.56 | The boxed recipes, built same-day on the follow-up call: `--fix-unique-identifier` (the OPF-030 recipe: wire the package's named id onto the first dc:identifier, refuses every ambiguous shape, and predicts the post-wiring uid so the NCX sync the broken wiring was masking fires in the same run -- eagle 2e -> 1e accept) and the CSS-007 font half inside `--fix-media-types` (font/* blessed on both package versions, magic confirmed, .eot never touched; accepted under no_worse because the gain sits on the INFO axis -- Brave New World 8 fonts normalized, CSS-007 cleared) | v0.56.0 |
53
+ | 0.57 | The embed scar's element half and the end of the silent equal (issue #22): `--fix-unbound-prefix` now binds an unbound ELEMENT prefix inline (the 9.7.0 writer self-declares xmlns:dc on every dc: element but one; rule 2 for a literal dc: element resolves to the DC namespace itself; Hackers 1f/1e -> 0f/1e with both binds in one run, and the half-repaired intermediate that read equal now repairs), and the masked-axis reclassification generalizes from the v0.51.0 NCX sync to every fired fix: a gate noop on a book that started and stayed fatal reads partial (the manual list) instead of a silent equal; the specimen's residual ncx:-prefixed dtb:uid gap shipped as the v0.57.1 patch (both matchers read a prefixed `<ncx:meta>` carrier; Hackers fully clean 0f/0e/0w) | v0.57.0-v0.57.1 |
53
54
 
54
55
  ## Open work
55
56
 
@@ -70,7 +70,12 @@ Applied to content documents (`.xhtml`, `.html`, `.htm`, `.xml`), in order:
70
70
 
71
71
  Applied to the NCX sidecar (`.ncx`): strip_prolog_junk, escape_bare_amp,
72
72
  fix_named_entities, plus **dtb:uid sync** (rewriting the NCX's `dtb:uid`
73
- meta to match the OPF's unique identifier when they drift, NCX-001) and
73
+ meta to match the OPF's unique identifier when they drift, NCX-001; the
74
+ matcher reads the meta under a namespace prefix too since v0.57.1 --
75
+ 2010-era producers spell every element `<ncx:meta>`, and a prefixed
76
+ `dtb:uid` carrier used to survive an otherwise-clean repair as the
77
+ book's last finding -- and the `--only ncx` selector reads the same
78
+ matchers) and
74
79
  **fix_ncx_playorder** (resequencing `playOrder` values so the NCX
75
80
  satisfies epubcheck's playOrder contract: elements whose `<content src>`
76
81
  point at the same target share one value, distinct targets carry distinct
@@ -358,16 +363,20 @@ leftovers whose failing OPF is a stale non-rootfile are unreachable by construct
358
363
  quote before the next `<` (a real multi-line value closes quote-first), and only
359
364
  double-quoted values are judged. It runs before the other tag-shape readers, which an
360
365
  open value otherwise lies to.
361
- - **`--fix-unbound-prefix`**: bind an attribute prefix the OPF never declares inline on
362
- the element that uses it (the Calibre embed scar, issue #9: one dc: element carries
363
- `ns0:scheme` while the `xmlns:ns0` declaration sits on a sibling, out of XML scope;
364
- the RSC-016 "prefix is not bound" fatals make the whole package unparseable, which
365
- also costs OPF-030 on the unique-identifier and masks the NCX-001 comparison). The
366
- declaration is inserted on the user, the shape the file's own healthy siblings
367
- already use. The URI is evidence-based, never guessed: the same prefix declared
368
- elsewhere in the document with every declaration agreeing, or the OPF namespace for
369
- a Dublin Core element under an OPF-namespaced package (the canonical EPUB 2
370
- `opf:scheme` shape); anything else refuses the document untouched. Scope is tracked
366
+ - **`--fix-unbound-prefix`**: bind a prefix the OPF never declares in scope inline on
367
+ the element that uses it (the Calibre embed scar: issue #9's attribute half, one dc:
368
+ element carrying `ns0:scheme` while the `xmlns:ns0` declaration sits on a sibling, out
369
+ of XML scope; and issue #22's element half, a later writer build self-declaring
370
+ `xmlns:dc` on every dc: element but one, so that element's own name dies with the
371
+ RSC-016 "prefix is not bound" fatal). Either scar makes the whole package
372
+ unparseable, which also costs OPF-030 on the unique-identifier and masks the NCX-001
373
+ comparison. The declaration is inserted on the user (element name or attribute
374
+ alike), the shape the file's own healthy siblings already use. The URI is
375
+ evidence-based, never guessed: the same prefix declared elsewhere in the document
376
+ with every declaration agreeing, or the use site's own namespace under an
377
+ OPF-namespaced package (the OPF namespace for a Dublin Core element's attributes,
378
+ the canonical EPUB 2 `opf:scheme` shape; the DC namespace for a literal `dc:` element
379
+ name); anything else refuses the document untouched. Scope is tracked
371
380
  with a lenient element stack over a comment/CDATA-aware tokenizer, so declarations
372
381
  that genuinely cover a use satisfy it without an edit and clean documents are
373
382
  byte-identical. Runs on the OPF only: content documents have the
@@ -456,6 +465,17 @@ be run or its output cannot be parsed during a validated run, the book is an `er
456
465
  the gate has not accepted anything, so nothing is applied or written. With
457
466
  `--no-validate`, the gate is skipped and repairs are trusted on the RepairReport alone.
458
467
 
468
+ One reporting rule rides on the noop verdict: the masked-axis reclassification. A
469
+ `noop` on a book that started fatal means the fix fired and the count did not move,
470
+ and with fatals still standing epubcheck's per-file halt hides whatever the fix
471
+ actually cleared below the halt: the dtb:uid comparison (issue #9, where the rule
472
+ was first scoped to the NCX sync), a cleared error axis, or a second latent fatal
473
+ unmasked by the fix that cleared the first (issue #22's embed scar:
474
+ `unbound_prefixes_bound` fired, `1f/1e -> 1f/0e`, fatals read 1 -> 1). Real,
475
+ unmeasurable work on a book that still will not open is `partial`, never a silent
476
+ `equal`: partial lands the book on the manual list. Application behavior is
477
+ unchanged (still-fatal candidates are never auto-applied).
478
+
459
479
  One structural veto rides above the count gate: the spine-resolution check. The
460
480
  message count is not spine-aware, so a repair that orphans live itemrefs (manifest
461
481
  items pruned whose files the archive still carries, idrefs rewritten to forms that
@@ -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.56.0"
14
+ VERSION = "0.57.1"
15
15
  __version__ = VERSION
16
16
 
17
17
  from .epub import RepairReport, repair_epub # noqa: E402
@@ -177,15 +177,21 @@ def process_book(
177
177
  watermark_refusals=report.watermark_refusals,
178
178
  )
179
179
  verdict = gate(before, after)
180
- if verdict == "noop" and report.ncx_uid_synced and before.fatals > 0:
181
- # The NCX-001 axis was masked in both measurements (issue #9): a fatal
182
- # in the package halts the metadata checks, so epubcheck never compared
183
- # dtb:uid to the unique-identifier, and the sync that really fixed it
184
- # measures as no gain. The sync is semantics-preserving by construction
185
- # (it writes only a differing dtb:uid content value), so the verdict
186
- # stops calling real work gainless: partial, with the still-fatal rule
187
- # intact (the library sweep still refuses to apply it; the single-file
188
- # verb still writes it under the PARTIAL label when given a DST).
180
+ if verdict == "noop" and before.fatals > 0:
181
+ # The masked-axis rule. v0.51.0 (issue #9) named it for the NCX uid
182
+ # sync; v0.57.0 (issue #22) generalizes it to every fired fix. A
183
+ # still-fatal package keeps epubcheck's per-file halt, so any gain
184
+ # living below the halt — the dtb:uid comparison, a cleared error
185
+ # axis, a second latent fatal unmasked by the fix that cleared the
186
+ # first (the Hackers dc:date scar: unbound_prefixes_bound fired,
187
+ # 1f/1e -> 1f/0e, fatals read 1 -> 1) — measures as no gain. The
188
+ # honest verdict for real, unmeasurable work on a book that still
189
+ # will not open is partial, never equal: partial lands the book on
190
+ # the manual list (the sweep's still_fatal set) instead of vanishing
191
+ # into a silent skip. Application behavior is unchanged: still-fatal
192
+ # books are never auto-applied, and the gate's own partial/reject
193
+ # answers (fatals reduced, or a regression) never enter this branch
194
+ # (gate noop with fatals before implies fatals after).
189
195
  verdict = "partial"
190
196
  if (
191
197
  report.fixes.get("stripped_pagination")
@@ -1900,18 +1906,22 @@ _REPAIR_FLAG_TABLE: dict[str, list[tuple[str, str, str]]] = {
1900
1906
  ),
1901
1907
  (
1902
1908
  "fix_unbound_prefix",
1903
- "bind an undeclared attribute prefix inline (Calibre embed scar)",
1904
- "bind an attribute prefix the OPF never declares inline on the "
1909
+ "bind an undeclared namespace prefix inline (Calibre embed scar)",
1910
+ "bind a prefix the OPF never declares in scope inline on the "
1905
1911
  "element that uses it (RSC-016 'prefix is not bound'): calibre's "
1906
1912
  "embed_metadata writer can leave one dc: element carrying "
1907
1913
  "ns0:scheme while the xmlns declaration sits on a sibling, out of "
1908
- "XML scope, which fatals the whole package (plus OPF-030 on the "
1914
+ "XML scope, and a later writer build leaves one dc: element's own "
1915
+ "name unbound the same way (every dc: element self-declares "
1916
+ "xmlns:dc except one, so <dc:date> dies with RSC-016); either "
1917
+ "scar fatals the whole package (plus OPF-030 on the "
1909
1918
  "unique-identifier). The URI is evidence-based, never guessed: "
1910
- "the same prefix declared elsewhere in the document, or the OPF "
1911
- "namespace for a Dublin Core element under an OPF-namespaced "
1912
- "package; anything else refuses the document untouched. Content "
1913
- "documents are not touched (their unbound prefixes have the "
1914
- "--strip-bad-attrs drop).",
1919
+ "the same prefix declared elsewhere in the document, or the use "
1920
+ "site's own namespace under an OPF-namespaced package (the OPF "
1921
+ "namespace for a Dublin Core element's attributes, the DC "
1922
+ "namespace for a dc: element name); anything else refuses the "
1923
+ "document untouched. Content documents are not touched (their "
1924
+ "unbound prefixes have the --strip-bad-attrs drop).",
1915
1925
  ),
1916
1926
  ],
1917
1927
  "lossy strips (these delete converter-injected content; accepted on a no-worse bar)": [
@@ -233,12 +233,16 @@ def fix_ncx_ids(ncx_text: str) -> tuple[str, int]:
233
233
 
234
234
  # Both accept single or double quotes; group 3 is the uid value and group(1)+group(4)
235
235
  # reconstruct everything around it, so the replacement logic is quote-agnostic too.
236
+ # The element may carry a namespace prefix: the 2010-era O'Reilly NCX spellings
237
+ # every element as <ncx:meta> (v0.57.1, the issue #22 specimen's residual
238
+ # NCX-001). The prefix group needs its trailing colon, so it cannot swallow
239
+ # into the [^>]* runs, and a failing split re-parts only within the tag name.
236
240
  _DTB_UID_RE = re.compile(
237
- r"(<meta\b[^>]*\bname=[\"']dtb:uid[\"'][^>]*\bcontent=([\"']))((?:(?!\2).)*)(\2)",
241
+ r"(<(?:[A-Za-z_][\w.:-]*:)?meta\b[^>]*\bname=[\"']dtb:uid[\"'][^>]*\bcontent=([\"']))((?:(?!\2).)*)(\2)",
238
242
  re.IGNORECASE,
239
243
  )
240
244
  _DTB_UID_RE_REV = re.compile(
241
- r"(<meta\b[^>]*\bcontent=([\"']))((?:(?!\2).)*)"
245
+ r"(<(?:[A-Za-z_][\w.:-]*:)?meta\b[^>]*\bcontent=([\"']))((?:(?!\2).)*)"
242
246
  r"(\2[^>]*\bname=[\"']dtb:uid[\"'][^>]*>)",
243
247
  re.IGNORECASE,
244
248
  )
@@ -1766,15 +1770,18 @@ def repair_epub(
1766
1770
  own `>` (`<p class="footnote>` -> `<p class="footnote">`; the RSC-016
1767
1771
  'must not contain the < character' fatal). It runs before the tag-shape
1768
1772
  readers, which an open value otherwise lies to.
1769
- With `unbound_prefix`, bind an attribute prefix the OPF never declares
1773
+ With `unbound_prefix`, bind a prefix the OPF never declares in scope
1770
1774
  inline on the element that uses it (the Calibre embed scar: one dc:
1771
1775
  element carries `ns0:scheme` while the xmlns declaration sits on a
1772
- sibling, out of scope; two RSC-016 fatals plus OPF-030 on the
1773
- unique-identifier). The URI is evidence-based: the same prefix declared
1774
- elsewhere in the document, or the OPF namespace for a Dublin Core element
1775
- under an OPF-namespaced package; anything else refuses the whole
1776
- document. Content documents are not touched (their unbound prefixes have
1777
- the --strip-bad-attrs drop).
1776
+ sibling, out of scope; and, issue #22, the writer's own element half —
1777
+ every dc: element self-declares `xmlns:dc` but one, and that
1778
+ `<dc:date>`'s ELEMENT prefix is unbound; two RSC-016 fatals plus OPF-030
1779
+ on the unique-identifier between them). The URI is evidence-based: the
1780
+ same prefix declared elsewhere in the document, or the use site's own
1781
+ namespace under an OPF-namespaced package (the OPF namespace for a
1782
+ Dublin Core element's attributes, the DC namespace for a `dc:` element
1783
+ name); anything else refuses the whole document. Content documents are
1784
+ not touched (their unbound prefixes have the --strip-bad-attrs drop).
1778
1785
  With `unique_identifier`, wire the OPF-030 dangling unique-identifier: add
1779
1786
  the id the package names to the first dc:identifier start tag when no
1780
1787
  element carries it. Refuses to guess (absent/empty attribute, non-NCName
@@ -1153,18 +1153,23 @@ def fix_unbound_prefixes(opf: str) -> tuple[str, int]:
1153
1153
  Calibre's embed_metadata writer has been observed to leave one dc: element
1154
1154
  carrying an attribute prefix (``ns0:scheme``) whose xmlns declaration never
1155
1155
  made it into the document: the declaration sits on a sibling, and XML scope
1156
- ends at the sibling's end tag. The unparseable package costs every
1157
- downstream check (two RSC-016 fatals plus OPF-030 on the
1158
- unique-identifier). The repair is the shape the file's own healthy
1159
- siblings already use: declare the prefix on the element that uses it.
1156
+ ends at the sibling's end tag. A later writer build (Calibre 9.7.0, issue
1157
+ #22) leaves one dc: element's own ELEMENT prefix unbound the same way: it
1158
+ self-declares ``xmlns:dc`` on every dc: element but one, and that one
1159
+ (``<dc:date>``) dies with RSC-016. Both scars are the same defect — a
1160
+ prefix used where XML scope has no binding for it — and the repair is the
1161
+ shape the file's own healthy siblings already use: declare the prefix on
1162
+ the element that uses it, on its name or its attribute alike.
1160
1163
 
1161
1164
  The URI is evidence-based, never guessed: (1) the same prefix declared
1162
1165
  elsewhere in the document, every declaration agreeing on one URI; (2) the
1163
- prefix declared nowhere, but the carrying element is Dublin Core (its
1164
- element prefix resolves to the DC namespace, or the literal ``dc:``
1165
- spelling when that is itself unbound) and the package element declares the
1166
- OPF namespace, the canonical EPUB 2 ``opf:scheme``/``opf:role`` shape
1167
- calibre's writer emits; (3) anything else refuses the whole document (an
1166
+ prefix declared nowhere, but the use site is Dublin Core under a package
1167
+ element that declares the OPF namespace — for an attribute, the carrying
1168
+ element is DC (its element prefix resolves to the DC namespace, or the
1169
+ literal ``dc:`` spelling when that is itself unbound) and the canonical
1170
+ EPUB 2 ``opf:scheme``/``opf:role`` shape names the OPF namespace; for an
1171
+ element, the literal ``dc:`` spelling IS the Dublin Core element, and its
1172
+ namespace is the DC one; (3) anything else refuses the whole document (an
1168
1173
  invented URI would be a guess, and a half-bound package is still fatal, so
1169
1174
  a partial fix would buy nothing). Declarations scoped to an ancestor (or
1170
1175
  to the element itself) satisfy the check without an edit, so clean
@@ -1234,34 +1239,67 @@ def fix_unbound_prefixes(opf: str) -> tuple[str, int]:
1234
1239
  for u in (default_uri, *decls.values())
1235
1240
  if u
1236
1241
  )
1237
- # Push before the attribute check: the element's own declarations
1238
- # apply to its own attributes.
1242
+ # Push before the checks: the element's own declarations apply to its
1243
+ # own name and its own attributes alike.
1239
1244
  scope.append((name, decls))
1240
- binds: list[str] = []
1245
+ # (prefix, fallback) pairs awaiting a URI: every use site whose prefix
1246
+ # is unbound in scope. The fallback is the URI rule 2 names for that
1247
+ # use site, or "" when rule 2 has nothing to say (it needs a Dublin
1248
+ # Core use site under an OPF-namespaced package; anything else would
1249
+ # be a guess and refuses instead).
1250
+ elem_prefix, esep, _ = name.partition(":")
1251
+ elem_ns = None
1252
+ for _, d in reversed(scope):
1253
+ if elem_prefix in d:
1254
+ elem_ns = d[elem_prefix]
1255
+ break
1256
+ wanted: list[tuple[str, str]] = []
1257
+ # One declaration per prefix per start tag (XML forbids a duplicate
1258
+ # attribute): the element's own binding names the prefix for the
1259
+ # whole tag, so an attribute on the same tag never queues it again.
1260
+ pending: set[str] = set()
1261
+ if (
1262
+ esep
1263
+ and elem_prefix not in _PREBOUND_PREFIXES
1264
+ and not any(elem_prefix in d for _, d in scope)
1265
+ ):
1266
+ # The element's own name can carry the scar (issue #22): the
1267
+ # embed writer self-declares xmlns:dc on every dc: element but
1268
+ # one, and that element's own prefix is then unbound. A
1269
+ # dc:-prefixed element under an OPF-namespaced package is Dublin
1270
+ # Core by the spec, so its fallback URI is the DC namespace.
1271
+ fallback = _DC_NS if pkg_ns and elem_prefix == "dc" else ""
1272
+ wanted.append((elem_prefix, fallback))
1273
+ pending.add(elem_prefix)
1241
1274
  for aname in attr_names:
1242
1275
  prefix, sep, _ = aname.partition(":")
1243
1276
  if not sep or prefix in _PREBOUND_PREFIXES:
1244
1277
  continue
1245
1278
  if any(prefix in d for _, d in scope):
1246
1279
  continue
1280
+ if prefix in pending:
1281
+ continue
1282
+ # The canonical EPUB 2 attribute shape: opf:scheme/opf:role ride
1283
+ # on Dublin Core elements with the OPF namespace.
1284
+ fallback = (
1285
+ _OPF_NS
1286
+ if pkg_ns
1287
+ and (elem_ns == _DC_NS or (elem_ns is None and elem_prefix == "dc"))
1288
+ else ""
1289
+ )
1290
+ wanted.append((prefix, fallback))
1291
+ pending.add(prefix)
1292
+ binds: list[str] = []
1293
+ for prefix, fallback in wanted:
1247
1294
  uris = decl_uris.get(prefix)
1248
1295
  if uris is not None:
1249
1296
  if len(uris) != 1:
1250
1297
  return opf, 0 # one prefix, two URIs: intent unreadable
1251
1298
  uri = next(iter(uris))
1299
+ elif fallback:
1300
+ uri = fallback
1252
1301
  else:
1253
- elem_prefix, _, _ = name.partition(":")
1254
- elem_ns = None
1255
- for _, d in reversed(scope):
1256
- if elem_prefix in d:
1257
- elem_ns = d[elem_prefix]
1258
- break
1259
- if pkg_ns and (
1260
- elem_ns == _DC_NS or (elem_ns is None and elem_prefix == "dc")
1261
- ):
1262
- uri = _OPF_NS
1263
- else:
1264
- return opf, 0 # no evidence: refuse the whole document
1302
+ return opf, 0 # no evidence: refuse the whole document
1265
1303
  binds.append(f' xmlns:{prefix}="{uri}"')
1266
1304
  if binds:
1267
1305
  # Insert directly after the element name, the position the
@@ -316,6 +316,30 @@ class TestRepairJson(unittest.TestCase):
316
316
  self.assertEqual(data["before"]["fatals"], 1)
317
317
  self.assertEqual(data["after"]["fatals"], 0)
318
318
 
319
+ def test_masked_partial_writes_with_dst(self):
320
+ # Issue #22's reclassification at the verb level: a still-fatal
321
+ # gate-noop book reads partial (not equal), and an explicit DST is
322
+ # still written, labeled PARTIAL (rc 0: the file is a real change
323
+ # worth keeping, the label says it is not fixed).
324
+ with tempfile.TemporaryDirectory() as td:
325
+ src = Path(td) / "in.epub"
326
+ dst = Path(td) / "out.epub"
327
+ build(src)
328
+ jout = Path(td) / "repair.json"
329
+ results = [CheckResult(1, 1, 0), CheckResult(1, 1, 0)]
330
+ out = io.StringIO()
331
+ with (
332
+ mock.patch("bindery.cli.run_epubcheck", side_effect=results),
333
+ redirect_stdout(out),
334
+ ):
335
+ rc = main(["repair", str(src), str(dst), "--json", str(jout)])
336
+ data = json.loads(jout.read_text())
337
+ self.assertTrue(dst.exists())
338
+ self.assertEqual(rc, 0)
339
+ self.assertEqual(data["status"], "partial")
340
+ self.assertTrue(data["applied"])
341
+ self.assertIn("PARTIAL", out.getvalue())
342
+
319
343
  def test_nochange_and_reject_records_are_written(self):
320
344
  with tempfile.TemporaryDirectory() as td:
321
345
  src2 = Path(td) / "in2.epub"
@@ -1700,7 +1724,11 @@ class TestSweepWorkers(unittest.TestCase):
1700
1724
 
1701
1725
  def oracle(path):
1702
1726
  checked.append(path.name)
1703
- return CheckResult(1, 0, 0)
1727
+ # Error-flat, never fatal: a fatal-flat book with a fired core
1728
+ # fix reads partial since the masked-axis rule (issue #22), and
1729
+ # partial books are trouble (exit 2) rather than the rc-0 path
1730
+ # this limit/window mechanic tests.
1731
+ return CheckResult(0, 1, 0)
1704
1732
 
1705
1733
  with tempfile.TemporaryDirectory() as td:
1706
1734
  for name in ("a", "b", "c", "d", "e"):
@@ -1737,7 +1765,8 @@ class TestSweepWorkers(unittest.TestCase):
1737
1765
 
1738
1766
  def oracle(path):
1739
1767
  checked.append(path.name)
1740
- return CheckResult(1, 0, 0)
1768
+ # Error-flat, never fatal: see test_limit_stays_lazy_within_one_window.
1769
+ return CheckResult(0, 1, 0)
1741
1770
 
1742
1771
  with tempfile.TemporaryDirectory() as td:
1743
1772
  for name in ("a", "b", "c", "d", "e"):
@@ -1882,11 +1911,13 @@ class TestStripStubDocsGate(unittest.TestCase):
1882
1911
  self.assertEqual(o.status, "reject")
1883
1912
 
1884
1913
 
1885
- class TestMaskedNcxUidGain(unittest.TestCase):
1886
- """Issue #9, the gate's masked axis: a fatal package halts the metadata
1887
- checks, so epubcheck never compares dtb:uid to the unique-identifier and
1888
- a real NCX uid sync measures as no gain. A noop verdict that carries a
1889
- sync on a book that started with fatals is reclassified partial: real
1914
+ class TestMaskedFatalGain(unittest.TestCase):
1915
+ """The gate's masked axis. Issue #9 named it for the NCX uid sync; issue
1916
+ #22 generalized it to every fired fix: a still-fatal package keeps
1917
+ epubcheck's per-file halt, so real work below the halt — a sync, a
1918
+ cleared error axis, a second latent fatal unmasked by the fix that
1919
+ cleared the first — measures as no gain, and the verdict must not call
1920
+ it gainless. Noop + fatals on both sides reclassifies to partial: real
1890
1921
  work the oracle could not see, still-fatal rules intact."""
1891
1922
 
1892
1923
  def _verdict(self, before, after, report):
@@ -1923,6 +1954,32 @@ class TestMaskedNcxUidGain(unittest.TestCase):
1923
1954
  o = self._verdict(CheckResult(1, 0, 0), CheckResult(2, 0, 0), report)
1924
1955
  self.assertEqual(o.status, "reject")
1925
1956
 
1957
+ def test_fired_fix_still_fatal_is_partial_not_equal(self):
1958
+ # Issue #22's exact shape (the Hackers dc:date scar): the fix fired,
1959
+ # cleared one fatal, and unmasked a latent second (1f/1e -> 1f/0e):
1960
+ # fatals read 1 -> 1, the gate says noop, and equal would hide a
1961
+ # book that still will not open.
1962
+ report = RepairReport(fixes={"unbound_prefixes_bound": 1})
1963
+ o = self._verdict(CheckResult(1, 1, 0), CheckResult(1, 0, 0), report)
1964
+ self.assertEqual(o.status, "partial")
1965
+ self.assertNotIn("no measurable gain", o.summary)
1966
+ self.assertIn("unbound_prefixes_bound", o.summary)
1967
+
1968
+ def test_unrelated_fix_on_still_fatal_book_is_partial(self):
1969
+ # Any fired fix under a still-fatal package sits on a masked axis:
1970
+ # the per-file halt hides whatever the fix cleared below it.
1971
+ report = RepairReport(fixes={"fix_manifest_ids": 1})
1972
+ o = self._verdict(CheckResult(2, 0, 0), CheckResult(2, 0, 0), report)
1973
+ self.assertEqual(o.status, "partial")
1974
+
1975
+ def test_clean_book_noop_stays_equal(self):
1976
+ # No fatals, no unmasking: a noop is a noop, and a clean book must
1977
+ # not land on the manual list.
1978
+ report = RepairReport(fixes={"fix_manifest_ids": 1})
1979
+ o = self._verdict(CheckResult(0, 1, 0), CheckResult(0, 1, 0), report)
1980
+ self.assertEqual(o.status, "equal")
1981
+ self.assertIn("no measurable gain", o.summary)
1982
+
1926
1983
 
1927
1984
  class TestHelpLayout(unittest.TestCase):
1928
1985
  """The two-level help contract (the 2026-10-06 restructure): the compact
@@ -41,6 +41,15 @@ NCX_BAD = (
41
41
  '<meta name="dtb:uid" content="urn:uuid:THE-WRONG-ID"/>'
42
42
  "</head></ncx>"
43
43
  )
44
+ # The Hackers spelling (issue #22's residual NCX-001): every element
45
+ # carries the ncx: prefix, including the dtb:uid meta.
46
+ NCX_BAD_PREFIXED = (
47
+ '<?xml version="1.0"?>'
48
+ '<ncx:ncx xmlns:ncx="http://www.daisy.org/z3986/2005/ncx/" version="2005-1">'
49
+ "<ncx:head>"
50
+ '<ncx:meta name="dtb:uid" content="urn:uuid:THE-WRONG-ID"/>'
51
+ "</ncx:head></ncx:ncx>"
52
+ )
44
53
  CONTENT = (
45
54
  '<?xml version="1.0"?>'
46
55
  '<html xmlns="http://www.w3.org/1999/xhtml"><head>'
@@ -78,6 +87,58 @@ class TestParts(unittest.TestCase):
78
87
  self.assertTrue(changed)
79
88
  self.assertIn(f'content="{uid}"', out)
80
89
 
90
+ def test_sync_ncx_uid_prefixed_meta(self):
91
+ # v0.57.1 (issue #22 follow-up): the 2010-era NCX spellings every
92
+ # element as <ncx:meta>; the sync reads and rewrites the dtb:uid
93
+ # there exactly as on the unprefixed shape.
94
+ out, changed = sync_ncx_uid(NCX_BAD_PREFIXED, "urn:uuid:THE-RIGHT-ID")
95
+ self.assertTrue(changed)
96
+ self.assertIn('content="urn:uuid:THE-RIGHT-ID"', out)
97
+ _, changed2 = sync_ncx_uid(out, "urn:uuid:THE-RIGHT-ID")
98
+ self.assertFalse(changed2)
99
+
100
+ def test_prefixed_meta_rev_order(self):
101
+ # content before name, under the prefix: the reversed-order matcher
102
+ # carries the same prefix extension.
103
+ ncx = (
104
+ '<ncx:ncx xmlns:ncx="http://www.daisy.org/z3986/2005/ncx/"><ncx:head>'
105
+ '<ncx:meta content="urn:uuid:THE-WRONG-ID" name="dtb:uid"/>'
106
+ "</ncx:head></ncx:ncx>"
107
+ )
108
+ out, changed = sync_ncx_uid(ncx, "urn:uuid:THE-RIGHT-ID")
109
+ self.assertTrue(changed)
110
+ self.assertIn('content="urn:uuid:THE-RIGHT-ID"', out)
111
+ ET.fromstring(out)
112
+
113
+ def test_prefixed_meta_no_false_positives(self):
114
+ # A prefixed element whose local name merely starts with "meta"
115
+ # (metadata) is not a dtb:uid carrier, prefix or not.
116
+ ncx = (
117
+ '<p:package xmlns:p="urn:x"><p:head>'
118
+ '<p:metadata name="dtb:uid" content="urn:uuid:THE-WRONG-ID"/>'
119
+ "</p:head></p:package>"
120
+ )
121
+ self.assertEqual(sync_ncx_uid(ncx, "urn:uuid:OTHER"), (ncx, False))
122
+
123
+ def test_ncx_uid_mismatch_prefixed(self):
124
+ # The --only ncx selector reads the same matchers: a prefixed-NCX
125
+ # book with a drifted uid is a candidate, an in-sync one is not.
126
+ with tempfile.TemporaryDirectory() as td:
127
+ src = Path(td) / "in.epub"
128
+ with zipfile.ZipFile(src, "w") as z:
129
+ z.writestr("OEBPS/c1.xhtml", CONTENT)
130
+ z.writestr("OEBPS/toc.ncx", NCX_BAD_PREFIXED)
131
+ z.writestr("OEBPS/content.opf", OPF)
132
+ self.assertTrue(ncx_uid_mismatch(src))
133
+ out, changed = sync_ncx_uid(NCX_BAD_PREFIXED, "urn:uuid:THE-RIGHT-ID")
134
+ self.assertTrue(changed)
135
+ src2 = Path(td) / "synced.epub"
136
+ with zipfile.ZipFile(src2, "w") as z:
137
+ z.writestr("OEBPS/c1.xhtml", CONTENT)
138
+ z.writestr("OEBPS/toc.ncx", out)
139
+ z.writestr("OEBPS/content.opf", OPF)
140
+ self.assertFalse(ncx_uid_mismatch(src2))
141
+
81
142
 
82
143
  class TestManifestIds(unittest.TestCase):
83
144
  def test_digit_led_ids_renamed_with_refs(self):
@@ -2322,6 +2383,28 @@ SCARRED_OPF = (
2322
2383
  '<spine toc="ncx"><itemref idref="c1"/></spine></package>'
2323
2384
  )
2324
2385
 
2386
+ # The Hackers shape (issue #22): no xmlns:dc on <metadata>; every dc:
2387
+ # element self-declares inline except <dc:date>, whose ELEMENT prefix is
2388
+ # then unbound, and the identifier's ns0:scheme is out of scope too.
2389
+ EMBED_SCARRED_OPF = (
2390
+ '<?xml version="1.0" encoding="UTF-8"?>'
2391
+ '<package xmlns="http://www.idpf.org/2007/opf" unique-identifier="ID1" '
2392
+ 'version="2.0">'
2393
+ "<metadata>"
2394
+ '<dc:title xmlns:dc="http://purl.org/dc/elements/1.1/">Hackers</dc:title>'
2395
+ '<dc:creator xmlns:dc="http://purl.org/dc/elements/1.1/" '
2396
+ 'xmlns:ns0="http://www.idpf.org/2007/opf" ns0:role="aut" '
2397
+ 'ns0:file-as="Levy, Steven">Steven Levy</dc:creator>'
2398
+ '<dc:identifier xmlns:dc="http://purl.org/dc/elements/1.1/" id="ID1" '
2399
+ 'ns0:scheme="calibre">fccddb12-6dd3-4896-ab23-c676558ca98b</dc:identifier>'
2400
+ "<dc:date>2001-01-02</dc:date>"
2401
+ "</metadata>"
2402
+ '<manifest><item id="c1" href="c1.xhtml" '
2403
+ 'media-type="application/xhtml+xml"/><item id="ncx" href="toc.ncx" '
2404
+ 'media-type="application/x-dtbncx+xml"/></manifest>'
2405
+ '<spine toc="ncx"><itemref idref="c1"/></spine></package>'
2406
+ )
2407
+
2325
2408
 
2326
2409
  class TestUnboundPrefix(unittest.TestCase):
2327
2410
  """Issue #9: the Calibre embed scar. One dc: element carries an
@@ -2366,3 +2449,42 @@ class TestUnboundPrefix(unittest.TestCase):
2366
2449
  # the bound package parses and its unique-identifier resolves
2367
2450
  ET.fromstring(opf)
2368
2451
  self.assertFalse(ncx_uid_mismatch(dst))
2452
+
2453
+ def _build_embed_scar(self, td: str) -> tuple[Path, Path]:
2454
+ src, dst = Path(td) / "in.epub", Path(td) / "out.epub"
2455
+ with zipfile.ZipFile(src, "w") as z:
2456
+ z.writestr("mimetype", "application/epub+zip")
2457
+ z.writestr("OEBPS/c1.xhtml", CONTENT)
2458
+ # the real specimen's NCX is prefixed throughout (v0.57.1)
2459
+ z.writestr("OEBPS/toc.ncx", NCX_BAD_PREFIXED)
2460
+ z.writestr("OEBPS/content.opf", EMBED_SCARRED_OPF)
2461
+ return src, dst
2462
+
2463
+ def test_embed_scar_element_and_attribute_bound(self):
2464
+ # Issue #22: one run binds both halves of the 9.7.0 scar. On the
2465
+ # specimen each fix alone left the other masked behind a still-fatal
2466
+ # package (1f/1e -> 1f/0e); together they parse it clean. The NCX
2467
+ # sync fires on the specimen's prefixed meta spelling (v0.57.1).
2468
+ with tempfile.TemporaryDirectory() as td:
2469
+ src, dst = self._build_embed_scar(td)
2470
+ report = repair_epub(src, dst, RepairFlags(unbound_prefix=True))
2471
+ self.assertEqual(report.fixes.get("unbound_prefixes_bound"), 2)
2472
+ self.assertTrue(report.ncx_uid_synced)
2473
+ with zipfile.ZipFile(dst) as z:
2474
+ opf = z.read("OEBPS/content.opf").decode()
2475
+ self.assertIn(
2476
+ '<dc:date xmlns:dc="http://purl.org/dc/elements/1.1/">2001-01-02</dc:date>',
2477
+ opf,
2478
+ )
2479
+ self.assertIn(
2480
+ '<dc:identifier xmlns:ns0="http://www.idpf.org/2007/opf" '
2481
+ 'xmlns:dc="http://purl.org/dc/elements/1.1/" id="ID1"',
2482
+ opf,
2483
+ )
2484
+ ET.fromstring(opf)
2485
+
2486
+ def test_off_by_default_embed_scar(self):
2487
+ with tempfile.TemporaryDirectory() as td:
2488
+ src, dst = self._build_embed_scar(td)
2489
+ report = repair_epub(src, dst)
2490
+ self.assertNotIn("unbound_prefixes_bound", report.fixes)
@@ -423,16 +423,22 @@ def _fixtures() -> dict:
423
423
  ),
424
424
  "--fix-unbound-prefix": (
425
425
  {
426
- "OEBPS/content.opf": _opf(
427
- [c1],
428
- [r1],
429
- # The Calibre embed scar: ns0 declared on the sibling
430
- # creator only, so the identifier's ns0:scheme is unbound.
431
- meta=(
432
- '<dc:creator xmlns:ns0="http://www.idpf.org/2007/opf" '
433
- 'ns0:role="aut">A</dc:creator>'
434
- '<dc:identifier id="id" ns0:scheme="calibre">uuid-x</dc:identifier>'
435
- ),
426
+ "OEBPS/content.opf": (
427
+ '<?xml version="1.0"?>'
428
+ '<package xmlns="http://www.idpf.org/2007/opf" '
429
+ 'version="2.0" unique-identifier="id">'
430
+ # The 9.7.0 embed scar (issue #22): no xmlns:dc on
431
+ # <metadata>; the creator self-declares it, the
432
+ # identifier's ns0:scheme is out of scope, and dc:date's
433
+ # own element prefix is unbound.
434
+ "<metadata>"
435
+ '<dc:creator xmlns:dc="http://purl.org/dc/elements/1.1/" '
436
+ 'xmlns:ns0="http://www.idpf.org/2007/opf" '
437
+ 'ns0:role="aut">A</dc:creator>'
438
+ '<dc:identifier id="id" ns0:scheme="calibre">uuid-x</dc:identifier>'
439
+ "<dc:date>2001-01-02</dc:date>"
440
+ "</metadata>"
441
+ f"<manifest>{c1}</manifest><spine>{r1}</spine></package>"
436
442
  ),
437
443
  "OEBPS/c1.xhtml": plain,
438
444
  },
@@ -958,6 +958,22 @@ def _scarred_opf(scar: str, healthy: str = "") -> str:
958
958
  )
959
959
 
960
960
 
961
+ def _embed_scarred_opf(scar: str, healthy: str = "") -> str:
962
+ """The Hackers shape (issue #22): the metadata element carries no
963
+ xmlns:dc; every healthy dc: element self-declares one inline, exactly the
964
+ embed writer's habit, and the scarred element misses its declaration."""
965
+ return (
966
+ '<?xml version="1.0" encoding="UTF-8"?>\n'
967
+ '<package xmlns="http://www.idpf.org/2007/opf" unique-identifier="ID1" '
968
+ 'version="2.0">\n'
969
+ " <metadata>\n"
970
+ f" {healthy}\n"
971
+ f" {scar}\n"
972
+ " </metadata>\n"
973
+ "</package>"
974
+ )
975
+
976
+
961
977
  class TestFixUnboundPrefixes(unittest.TestCase):
962
978
  SCAR = '<dc:identifier id="ID1" ns0:scheme="calibre">uuid-x</dc:identifier>'
963
979
  HEALTHY = (
@@ -1125,6 +1141,155 @@ class TestFixUnboundPrefixes(unittest.TestCase):
1125
1141
  self.assertEqual((twice, n2), (once, 0))
1126
1142
 
1127
1143
 
1144
+ _DC_DECL = 'xmlns:dc="http://purl.org/dc/elements/1.1/"'
1145
+
1146
+
1147
+ class TestFixUnboundElementPrefixes(unittest.TestCase):
1148
+ """Issue #22, the element half of the embed scar: the writer
1149
+ self-declares xmlns:dc on every dc: element but one, so that element's
1150
+ own ELEMENT prefix is unbound (RSC-016 'The prefix "dc" for element
1151
+ "dc:date" is not bound'). Same evidence rules as the attribute half;
1152
+ the dc: element's rule-2 fallback is the DC namespace itself."""
1153
+
1154
+ def test_unbound_element_prefix_bound_inline(self):
1155
+ # The Hackers specimen shape: healthy siblings self-declare, the
1156
+ # scarred element's declaration never made it in.
1157
+ doc = _embed_scarred_opf(
1158
+ "<dc:date>2001-01-02</dc:date>",
1159
+ f"<dc:title {_DC_DECL}>Hackers</dc:title>",
1160
+ )
1161
+ out, n = fix_unbound_prefixes(doc)
1162
+ self.assertEqual(n, 1)
1163
+ self.assertIn(
1164
+ f"<dc:date {_DC_DECL}>2001-01-02</dc:date>",
1165
+ out,
1166
+ )
1167
+ ET.fromstring(out)
1168
+
1169
+ def test_element_and_attribute_scars_together(self):
1170
+ # The full scar: ns0:scheme unbound on the identifier AND dc:date's
1171
+ # element prefix unbound; one run binds both (2f -> 0f on the
1172
+ # specimen, where either alone masked the other).
1173
+ doc = _embed_scarred_opf(
1174
+ f'<dc:identifier {_DC_DECL} id="ID1" ns0:scheme="calibre">u</dc:identifier>'
1175
+ "<dc:date>2001-01-02</dc:date>",
1176
+ '<dc:creator xmlns:ns0="http://www.idpf.org/2007/opf" '
1177
+ f'{_DC_DECL} ns0:role="aut">A</dc:creator>',
1178
+ )
1179
+ out, n = fix_unbound_prefixes(doc)
1180
+ self.assertEqual(n, 2)
1181
+ self.assertIn('xmlns:ns0="http://www.idpf.org/2007/opf"', out)
1182
+ self.assertIn(f"<dc:date {_DC_DECL}>", out)
1183
+ ET.fromstring(out)
1184
+
1185
+ def test_self_closing_element_prefix_bound(self):
1186
+ doc = _embed_scarred_opf("<dc:date/>", f"<dc:title {_DC_DECL}>H</dc:title>")
1187
+ out, n = fix_unbound_prefixes(doc)
1188
+ self.assertEqual(n, 1)
1189
+ self.assertIn(f"<dc:date {_DC_DECL}/>", out)
1190
+ ET.fromstring(out)
1191
+
1192
+ def test_never_declared_dc_element_gets_dc_ns(self):
1193
+ # Rule 2 for elements: no declaration anywhere; a dc:-prefixed
1194
+ # element under an OPF-namespaced package is Dublin Core by the
1195
+ # spec, so the DC namespace itself is the deterministic URI.
1196
+ doc = _embed_scarred_opf("<dc:date>2001-01-02</dc:date>")
1197
+ out, n = fix_unbound_prefixes(doc)
1198
+ self.assertEqual(n, 1)
1199
+ self.assertIn(f"<dc:date {_DC_DECL}>", out)
1200
+ ET.fromstring(out)
1201
+
1202
+ def test_element_prefix_uses_document_evidence(self):
1203
+ # Rule 1 outranks the dc-means-DC-NS intuition: the document's own
1204
+ # declarations say what its prefix means, and the fix matches them.
1205
+ doc = _embed_scarred_opf(
1206
+ "<dc:date>2001-01-02</dc:date>",
1207
+ '<dc:title xmlns:dc="http://foreign.example/not-dc">H</dc:title>',
1208
+ )
1209
+ out, n = fix_unbound_prefixes(doc)
1210
+ self.assertEqual(n, 1)
1211
+ self.assertIn('<dc:date xmlns:dc="http://foreign.example/not-dc">', out)
1212
+ ET.fromstring(out)
1213
+
1214
+ def test_ambiguous_element_evidence_refuses(self):
1215
+ doc = _embed_scarred_opf(
1216
+ "<dc:date>2001-01-02</dc:date>",
1217
+ '<dc:title xmlns:dc="http://www.idpf.org/2007/opf">H</dc:title>'
1218
+ '<dc:publisher xmlns:dc="http://other.example/ns">P</dc:publisher>',
1219
+ )
1220
+ self.assertEqual(fix_unbound_prefixes(doc), (doc, 0))
1221
+
1222
+ def test_no_evidence_not_dc_refuses(self):
1223
+ doc = _embed_scarred_opf("<ns9:date>2001-01-02</ns9:date>")
1224
+ self.assertEqual(fix_unbound_prefixes(doc), (doc, 0))
1225
+
1226
+ def test_dc_element_without_opf_package_refuses(self):
1227
+ # Rule 2 needs the package itself to carry the OPF namespace; a
1228
+ # bare dc: spelling outside one means nothing deterministic.
1229
+ doc = _embed_scarred_opf("<dc:date>2001-01-02</dc:date>").replace(
1230
+ 'xmlns="http://www.idpf.org/2007/opf" ', ""
1231
+ )
1232
+ self.assertEqual(fix_unbound_prefixes(doc), (doc, 0))
1233
+
1234
+ def test_ancestor_declaration_satisfies(self):
1235
+ # The Century Rain fixture's shape: xmlns:dc on <metadata> covers
1236
+ # every dc: element name below it; nothing to do.
1237
+ doc = _scarred_opf("<dc:date>2001-01-02</dc:date>")
1238
+ self.assertEqual(fix_unbound_prefixes(doc), (doc, 0))
1239
+
1240
+ def test_own_declaration_satisfies(self):
1241
+ doc = _embed_scarred_opf(f"<dc:date {_DC_DECL}>2001-01-02</dc:date>")
1242
+ self.assertEqual(fix_unbound_prefixes(doc), (doc, 0))
1243
+
1244
+ def test_nested_element_prefixes_each_bound(self):
1245
+ # The each-use-site contract the attribute half established: an
1246
+ # inner element's unbound prefix gets its own inline declaration
1247
+ # even though the outer's edit will scope over it.
1248
+ doc = _embed_scarred_opf("<dc:meta><dc:date>2001-01-02</dc:date></dc:meta>")
1249
+ out, n = fix_unbound_prefixes(doc)
1250
+ self.assertEqual(n, 2)
1251
+ ET.fromstring(out)
1252
+
1253
+ def test_element_and_attribute_same_prefix_bound_once(self):
1254
+ # One declaration per prefix per start tag: an attribute sharing the
1255
+ # element's own unbound prefix never queues a second xmlns (the
1256
+ # code-review collision), and the element's Dublin Core identity
1257
+ # decides the URI for both.
1258
+ doc = _embed_scarred_opf('<dc:date dc:event="x">2001-01-02</dc:date>')
1259
+ out, n = fix_unbound_prefixes(doc)
1260
+ self.assertEqual(n, 1)
1261
+ self.assertEqual(out.count("xmlns:dc="), 1)
1262
+ ET.fromstring(out)
1263
+
1264
+ def test_two_attributes_same_prefix_bound_once(self):
1265
+ # The attribute half's own variant of the same collision (it
1266
+ # emitted a duplicate xmlns attribute before the dedupe). The
1267
+ # Century Rain fixture declares xmlns:dc on <metadata>, so only
1268
+ # the two same-prefix attributes are unbound here.
1269
+ doc = _scarred_opf(
1270
+ '<dc:identifier id="ID1" ns0:x="1" ns0:y="2">u</dc:identifier>',
1271
+ '<dc:creator xmlns:ns0="http://www.idpf.org/2007/opf">A</dc:creator>',
1272
+ )
1273
+ out, n = fix_unbound_prefixes(doc)
1274
+ self.assertEqual(n, 1)
1275
+ # the sibling's own declaration plus the one bind (never two binds)
1276
+ self.assertEqual(out.count("xmlns:ns0="), 2)
1277
+ ET.fromstring(out)
1278
+
1279
+ def test_xml_prefix_never_flagged(self):
1280
+ doc = _embed_scarred_opf('<xml:stylesheet href="x"/>')
1281
+ self.assertEqual(fix_unbound_prefixes(doc), (doc, 0))
1282
+
1283
+ def test_idempotent(self):
1284
+ doc = _embed_scarred_opf(
1285
+ "<dc:date>2001-01-02</dc:date>",
1286
+ f"<dc:title {_DC_DECL}>Hackers</dc:title>",
1287
+ )
1288
+ once, _ = fix_unbound_prefixes(doc)
1289
+ twice, n2 = fix_unbound_prefixes(once)
1290
+ self.assertEqual((twice, n2), (once, 0))
1291
+
1292
+
1128
1293
  class TestCssProtectedTags(unittest.TestCase):
1129
1294
  def test_element_selector_protects(self):
1130
1295
  self.assertIn("st", css_protected_tags("st { color: red }"))
@@ -8,7 +8,7 @@ resolution-markers = [
8
8
 
9
9
  [[package]]
10
10
  name = "bindery-cli"
11
- version = "0.56.0"
11
+ version = "0.57.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