bindery-cli 0.55.0__tar.gz → 0.56.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.
Files changed (56) hide show
  1. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/AGENTS.md +14 -1
  2. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/PKG-INFO +3 -2
  3. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/README.md +2 -1
  4. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/patchnotes.md +47 -0
  5. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/pyproject.toml +1 -1
  6. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/roadmap.md +1 -0
  7. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/spec.md +30 -12
  8. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/__init__.py +1 -1
  9. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/cli.py +36 -2
  10. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/epub.py +98 -15
  11. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_epub.py +190 -0
  12. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_flags_real_core.py +30 -2
  13. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_flags_wiring.py +1 -0
  14. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/uv.lock +1 -1
  15. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/.github/FUNDING.yml +0 -0
  16. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/.github/workflows/ci.yml +0 -0
  17. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/.github/workflows/publish.yml +0 -0
  18. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/.gitignore +0 -0
  19. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/LICENSE +0 -0
  20. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/OBSERVE-RESEARCH.md +0 -0
  21. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/docs/screenshots/library-sweep.png +0 -0
  22. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/logo.svg +0 -0
  23. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/plugin/__init__.py +0 -0
  24. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/project.done +0 -0
  25. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/run_tests.sh +0 -0
  26. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/scripts/FastSweep.java +0 -0
  27. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/scripts/build_plugin.py +0 -0
  28. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/scripts/fast_sweep.py +0 -0
  29. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/__main__.py +0 -0
  30. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/audit.py +0 -0
  31. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/library.py +0 -0
  32. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/observe.py +0 -0
  33. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/pagination.py +0 -0
  34. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/reserialize.py +0 -0
  35. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/transforms.py +0 -0
  36. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/validate.py +0 -0
  37. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/watermark.py +0 -0
  38. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_audit.py +0 -0
  39. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_cli.py +0 -0
  40. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_comment_hyphens.py +0 -0
  41. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_contamination.py +0 -0
  42. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_cover_tocdrift.py +0 -0
  43. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_help.py +0 -0
  44. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_library.py +0 -0
  45. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_matcher_hardening.py +0 -0
  46. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_observe.py +0 -0
  47. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_pagination.py +0 -0
  48. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_plugin.py +0 -0
  49. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_reserialize.py +0 -0
  50. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_space_renames.py +0 -0
  51. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_spine_guard.py +0 -0
  52. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_transforms.py +0 -0
  53. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_validate.py +0 -0
  54. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_version.py +0 -0
  55. {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_watermark.py +0 -0
  56. {bindery_cli-0.55.0 → bindery_cli-0.56.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: twenty-four structural
33
+ visible content. The canonical opt-in inventory lives in spec.md: twenty-five structural
34
34
  repairs, four lossy strips, four safe opt-ins, plus `--reserialize`.
35
35
  * **Structural repairs** (`--fix-empty-body`, `--fix-missing-title`, `--fix-id-colons`,
36
36
  `--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
@@ -87,6 +87,19 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
87
87
  different spelling (the spine guard correctly refuses; the mass carrier
88
88
  is `--encode-url-spaces` territory), so the prune's coverage boundary is
89
89
  documented, not widened.
90
+ The v0.56.0 one (the boxed OPF-030 recipe, built same-day on Brandon's
91
+ call): `--fix-unique-identifier` wires the package's dangling
92
+ unique-identifier id onto the first `dc:identifier` start tag
93
+ (`unique_identifier_wired`), with the masked-NCX coordination: the uid
94
+ sync predicts the post-wiring uid before the loop (the same pure
95
+ function on the same input region, never a snapshot of a different
96
+ layout), so one run both wires the OPF and aligns the NCX dtb:uid the
97
+ broken wiring was masking. Refusals: absent/empty attribute, non-NCName
98
+ id, already-wired, no dc:identifier, first-identifier-has-id; normal
99
+ `gate`. The CSS-007 font half shipped the same release inside
100
+ `--fix-media-types` (font/* blessed on both package versions, magic
101
+ confirmed, `.eot` never touched) with the flag accepted under `no_worse`
102
+ (its gain sits on the INFO axis).
90
103
  They alter markup structure or fabricate minimal content. v0.14–v0.16 ran these unconditionally, which broke this rule;
91
104
  v0.17.0 restored it. `--unwrap-illegal-tags` additionally protects any illegal-tag
92
105
  name that an EPUB stylesheet styles as an element selector (`css_protected_tags`,
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: bindery-cli
3
- Version: 0.55.0
3
+ Version: 0.56.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
@@ -66,11 +66,12 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
66
66
  - **`--downgrade-epub3-tags`**: downgrades EPUB3/HTML5 semantic elements to their EPUB2 equivalents (`figure`/`section` to `div`, `figcaption` to `p`), keeping existing classes and appending the semantic name (`class="figure"`) as the styling hook. Tag names a stylesheet styles as an element selector are protected book-wide, so styled formatting is never destroyed. Both EPUB2-targeted fixes are gated on the package version declared in the OPF: on an EPUB 3 book they do nothing, because their target defects only exist below EPUB 3.
67
67
  - **`--unwrap-illegal-tags`**: strips completely invalid or deprecated HTML tags that break EPUB3 validation (`<st>`, `<sentence>`, `<o>`, `<w>`, `<pagebreak>`) while retaining their inner text. Any of those names styled as an *element selector* by an EPUB stylesheet (`.css` entries and inline `<style>` blocks alike; class/id selectors like `.st`/`#w` don't count) is protected for the whole book, guaranteeing format preservation.
68
68
  - **`--declare-missing-items`**: the RSC-008 inverse of the prune: adds the manifest `<item>` declarations the OPF never wrote for files the archive carries and the book references (content `<img src>`/`<link href>` targets, CSS `url()` resources, OPF guide references). Deterministic ids, media types from a blessed extension map only, and no `<itemref>` is ever written: the spine is untouched.
69
+ - **`--fix-unique-identifier`**: wires the dangling OPF unique-identifier (OPF-030): adds the id the package names to the first `dc:identifier` when no element carries it, and aligns the NCX `dtb:uid` the broken wiring was masking in the same run. The `dc:` values are never touched; ambiguous shapes refuse.
69
70
  - **`--prune-missing-resources`**: removes references to files the archive does not contain (RSC-007/PKG-010): dead `<link>` elements, anchors' `href` to absent files (anchor text preserved), absent `<img>` sources (replaced by their alt text when they carry one), and orphaned non-spine OPF manifest items (with every package edge that pointed at them rewritten: `spine@toc`, `item@media-overlay`, `item@fallback`, and the EPUB2 cover meta). Spine documents are never pruned: a missing spine document is reported as a damaged fragment, not silently dropped.
70
71
  - **`--strip-broken-anchors`**: strips href attributes that cannot resolve, keeping the anchor text byte-for-byte: a `#fragment` the target document does not define (RSC-020/RSC-012; NCX navTargets fall back to the document target, so chapter navigation survives) and unresolvable URI schemes (`kindle:`, `file:`).
71
72
  - **`--encode-url-spaces`**: percent-encodes raw spaces in `src`/`href` attribute values across the package (OPF manifest, NCX, content documents). A URL with a literal space is not a valid URL (RSC-020) and unresolvable on strict readers; the encoded form denotes the same file. Since v0.44.0 the flag also renames archive entries whose names carry raw spaces to their underscore spellings and rewrites every reference to them (OPF, NCX, content, CSS `url()`), clearing the PKG-010 space-in-filename advisories: underscore, never percent-encoding, because epubcheck decodes references before entry lookup.
72
73
  - **`--fix-container`**: generates `META-INF/container.xml` at the located OPF when the container is missing or names a file the archive does not contain. This is the gateway defect: epubcheck stays fatal while the OPF is unfindable, so no repair can be gate-accepted on such a book until the container exists.
73
- - **`--fix-media-types`**: normalizes wrong manifest media-type declarations (OPF-029, e.g. a jpg stamped `image/png` by an aggregator). Attribute-only and quote-preserving; it fires only when the file's magic bytes confirm the extension, so a misnamed-but-consistent file (a PNG renamed .jpg) is never made worse.
74
+ - **`--fix-media-types`**: normalizes wrong manifest media-type declarations (OPF-029, e.g. a jpg stamped `image/png` by an aggregator). Attribute-only and quote-preserving; it fires only when the file's magic bytes confirm the extension, so a misnamed-but-consistent file (a PNG renamed .jpg) is never made worse. Since v0.56.0 it also covers the CSS-007 font slice (a `ttf`/`otf`/`woff`/`woff2` declared outside epubcheck's blessed font set is rewritten to its `font/*` spelling when the magic bytes confirm; `.eot` is never touched), and the flag is accepted under the no-worse bar because that half's gain sits on the INFO axis.
74
75
  - **`--fix-cover`**: repairs dangling EPUB2 cover wiring. A `<meta name="cover">` whose content names no manifest item is re-pointed when the OPF guide's own cover reference names an existing item, and removed when nothing identifies it; EPUB3 `properties="cover-image"` is deliberately audit-only (guessing which image is the cover is not deterministic). Cover wiring is invisible to epubcheck, so cover-only repairs are accepted under the same no-worse bar the lossy strips use.
75
76
  - **`--fix-comment-double-hyphen`**: replaces `--` sequences inside XML comments with en-dashes. `--` is illegal inside an XML comment (epubcheck fatal RSC-016: the book opens in lenient readers but never passes epubcheck). The edit stays inside the comment bodies: text nodes and CDATA sections are never touched, and each comment's terminator is left intact.
76
77
  - **`--fix-svg-dup-ids`**: renames duplicate `id` values inside standalone `.svg` entries (old calibre SVG page renders repeat glyph ids within one document; the intake wave that found this carried 445 to 1,339 'Duplicate "glNNNN"' errors per book). The first occurrence keeps its name, later ones gain `_2`/`_3`, and internal references are deliberately untouched: they already resolve to the first definition under every reader's first-match lookup.
@@ -39,11 +39,12 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
39
39
  - **`--downgrade-epub3-tags`**: downgrades EPUB3/HTML5 semantic elements to their EPUB2 equivalents (`figure`/`section` to `div`, `figcaption` to `p`), keeping existing classes and appending the semantic name (`class="figure"`) as the styling hook. Tag names a stylesheet styles as an element selector are protected book-wide, so styled formatting is never destroyed. Both EPUB2-targeted fixes are gated on the package version declared in the OPF: on an EPUB 3 book they do nothing, because their target defects only exist below EPUB 3.
40
40
  - **`--unwrap-illegal-tags`**: strips completely invalid or deprecated HTML tags that break EPUB3 validation (`<st>`, `<sentence>`, `<o>`, `<w>`, `<pagebreak>`) while retaining their inner text. Any of those names styled as an *element selector* by an EPUB stylesheet (`.css` entries and inline `<style>` blocks alike; class/id selectors like `.st`/`#w` don't count) is protected for the whole book, guaranteeing format preservation.
41
41
  - **`--declare-missing-items`**: the RSC-008 inverse of the prune: adds the manifest `<item>` declarations the OPF never wrote for files the archive carries and the book references (content `<img src>`/`<link href>` targets, CSS `url()` resources, OPF guide references). Deterministic ids, media types from a blessed extension map only, and no `<itemref>` is ever written: the spine is untouched.
42
+ - **`--fix-unique-identifier`**: wires the dangling OPF unique-identifier (OPF-030): adds the id the package names to the first `dc:identifier` when no element carries it, and aligns the NCX `dtb:uid` the broken wiring was masking in the same run. The `dc:` values are never touched; ambiguous shapes refuse.
42
43
  - **`--prune-missing-resources`**: removes references to files the archive does not contain (RSC-007/PKG-010): dead `<link>` elements, anchors' `href` to absent files (anchor text preserved), absent `<img>` sources (replaced by their alt text when they carry one), and orphaned non-spine OPF manifest items (with every package edge that pointed at them rewritten: `spine@toc`, `item@media-overlay`, `item@fallback`, and the EPUB2 cover meta). Spine documents are never pruned: a missing spine document is reported as a damaged fragment, not silently dropped.
43
44
  - **`--strip-broken-anchors`**: strips href attributes that cannot resolve, keeping the anchor text byte-for-byte: a `#fragment` the target document does not define (RSC-020/RSC-012; NCX navTargets fall back to the document target, so chapter navigation survives) and unresolvable URI schemes (`kindle:`, `file:`).
44
45
  - **`--encode-url-spaces`**: percent-encodes raw spaces in `src`/`href` attribute values across the package (OPF manifest, NCX, content documents). A URL with a literal space is not a valid URL (RSC-020) and unresolvable on strict readers; the encoded form denotes the same file. Since v0.44.0 the flag also renames archive entries whose names carry raw spaces to their underscore spellings and rewrites every reference to them (OPF, NCX, content, CSS `url()`), clearing the PKG-010 space-in-filename advisories: underscore, never percent-encoding, because epubcheck decodes references before entry lookup.
45
46
  - **`--fix-container`**: generates `META-INF/container.xml` at the located OPF when the container is missing or names a file the archive does not contain. This is the gateway defect: epubcheck stays fatal while the OPF is unfindable, so no repair can be gate-accepted on such a book until the container exists.
46
- - **`--fix-media-types`**: normalizes wrong manifest media-type declarations (OPF-029, e.g. a jpg stamped `image/png` by an aggregator). Attribute-only and quote-preserving; it fires only when the file's magic bytes confirm the extension, so a misnamed-but-consistent file (a PNG renamed .jpg) is never made worse.
47
+ - **`--fix-media-types`**: normalizes wrong manifest media-type declarations (OPF-029, e.g. a jpg stamped `image/png` by an aggregator). Attribute-only and quote-preserving; it fires only when the file's magic bytes confirm the extension, so a misnamed-but-consistent file (a PNG renamed .jpg) is never made worse. Since v0.56.0 it also covers the CSS-007 font slice (a `ttf`/`otf`/`woff`/`woff2` declared outside epubcheck's blessed font set is rewritten to its `font/*` spelling when the magic bytes confirm; `.eot` is never touched), and the flag is accepted under the no-worse bar because that half's gain sits on the INFO axis.
47
48
  - **`--fix-cover`**: repairs dangling EPUB2 cover wiring. A `<meta name="cover">` whose content names no manifest item is re-pointed when the OPF guide's own cover reference names an existing item, and removed when nothing identifies it; EPUB3 `properties="cover-image"` is deliberately audit-only (guessing which image is the cover is not deterministic). Cover wiring is invisible to epubcheck, so cover-only repairs are accepted under the same no-worse bar the lossy strips use.
48
49
  - **`--fix-comment-double-hyphen`**: replaces `--` sequences inside XML comments with en-dashes. `--` is illegal inside an XML comment (epubcheck fatal RSC-016: the book opens in lenient readers but never passes epubcheck). The edit stays inside the comment bodies: text nodes and CDATA sections are never touched, and each comment's terminator is left intact.
49
50
  - **`--fix-svg-dup-ids`**: renames duplicate `id` values inside standalone `.svg` entries (old calibre SVG page renders repeat glyph ids within one document; the intake wave that found this carried 445 to 1,339 'Duplicate "glNNNN"' errors per book). The first occurrence keeps its name, later ones gain `_2`/`_3`, and internal references are deliberately untouched: they already resolve to the first definition under every reader's first-match lookup.
@@ -1,5 +1,52 @@
1
1
  # bindery-cli Patch Notes
2
2
 
3
+ ## v0.56.0 (2026-10-25)
4
+
5
+ ### The two boxed recipes, built: the OPF-030 wiring and the CSS-007 font half
6
+
7
+ The v0.55.0 census lanes left two deterministic-but-marginal candidates
8
+ recorded as recipes; both shipped the same day on the follow-up call.
9
+
10
+ **`--fix-unique-identifier` (the OPF-030 recipe).** The dominant family:
11
+ the package names an id (`bookid`, `uuid_id`, ISBN shapes) but no
12
+ `dc:identifier` carries any id attribute at all. The repair writes the id
13
+ the package itself names onto the first `dc:identifier` start tag; the
14
+ dc: values are never touched. It refuses to guess every ambiguous shape:
15
+ an absent or empty `unique-identifier` attribute, a non-NCName id, an
16
+ already-wired OPF, no `dc:identifier` element, or a first identifier that
17
+ already carries an id. The live gate on the census specimen (The Eagle Has
18
+ Landed) surfaced a masking twist: the broken wiring was hiding a real
19
+ NCX-001 (epubcheck cannot compare `dtb:uid` to an unresolvable
20
+ identifier), and the default pass's uid sync skipped because the source
21
+ had no resolvable uid. The repair now predicts the post-wiring uid (the
22
+ same pure transformation the OPF branch applies; never a snapshot of a
23
+ different layout, the issue #10 lesson) so one run wires the OPF AND
24
+ aligns the NCX: the specimen went from 2 errors (OPF-030 + a masked
25
+ latent) to 1 (a pre-existing out-of-scope OPF-032), accept, with
26
+ `unique_identifier_wired:1` and the NCX sync fired. The multi-OPF merge
27
+ leftovers whose failing OPF is a stale non-rootfile are unreachable by
28
+ construction (only the located rootfile is repaired).
29
+
30
+ **The CSS-007 font half of `--fix-media-types`.** The census found the
31
+ INFO-severity family: `@font-face` srcs whose OPF declaration sits
32
+ outside epubcheck's version-specific blessed font set (`text/plain`
33
+ fonts, `application/xfont+otf`, `octet-stream` woff2). The map gains
34
+ `ttf`/`otf`/`woff`/`woff2` with their magic bytes; the `font/*`
35
+ spellings are blessed on BOTH package versions (EPUB2 blesses the prefix,
36
+ EPUB3's exact list carries them), so no version gate is needed, and the
37
+ existing magic-byte confirmation rule is unchanged (a font is rewritten
38
+ only when its bytes name the format the extension does; `.eot` is never
39
+ touched -- epubcheck rejects EOT as a font src however it is declared, so
40
+ correcting it can only churn). Because CSS-007 is INFO, the error counts
41
+ do not see the gain, so the flag is now accepted under the `no_worse` bar
42
+ (the cover-wiring ruling's shape): the OPF-029 error slice still measures
43
+ its real decrease through the normal gate, and a font-only repair no
44
+ longer reads as gainless. Live gate on Brave New World (8 `text/plain`
45
+ fonts): `media_types_normalized:8`, accept, CSS-007 fully cleared.
46
+
47
+ Twenty-five structural repairs. Suite: 768 tests.
48
+
49
+
3
50
  ## v0.55.0 (2026-10-25)
4
51
 
5
52
  ### The issue batch: the 2026-10-24 surgery's follow-ups, #11 through #16
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "bindery-cli"
7
- version = "0.55.0"
7
+ version = "0.56.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 = [
@@ -49,6 +49,7 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
49
49
  | 0.53 | `bindery observe` (the observatory): the whole-library census in one warm-JVM pass (counts and error codes together, sentinel-backed so no book is dropped), tabulation (severity histogram, code profile, worst offenders), the gated repair preview composed in-process, the versioned `.observe` artifact with `--against` trend diffing and the keep-root-clean output guard; the library and audit walks skip `.caltrash` | v0.53.0-v0.53.1 |
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
+ | 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 |
52
53
 
53
54
  ## Open work
54
55
 
@@ -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 twenty-four
16
+ The deliberate exceptions to "semantics-preserving" come in opt-in groups. The twenty-five
17
17
  **structural repairs** (`--fix-empty-body`, `--fix-missing-title`, `--fix-id-colons`,
18
18
  `--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
19
19
  `--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`,
@@ -22,7 +22,8 @@ The deliberate exceptions to "semantics-preserving" come in opt-in groups. The t
22
22
  `--fix-container`, `--fix-media-types`, `--fix-cover`, `--fix-comment-double-hyphen`,
23
23
  `--fix-svg-dup-ids`, `--fix-duplicate-ids`, `--fix-cdata-terminator`,
24
24
  `--fix-misnested-inline`,
25
- `--fix-stray-close`, `--fix-unterminated-attr`, `--fix-unbound-prefix`) alter
25
+ `--fix-stray-close`, `--fix-unterminated-attr`, `--fix-unbound-prefix`,
26
+ `--fix-unique-identifier`) alter
26
27
  markup structure or fabricate minimal content; the four
27
28
  **lossy modes** (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`,
28
29
  `--strip-stub-docs`) remove
@@ -141,7 +142,7 @@ byte-for-byte. The normal gate applies.
141
142
 
142
143
  ### Opt-in: structural repairs
143
144
 
144
- Twenty-four repairs go past well-formedness and therefore require their own flag; none is ever
145
+ Twenty-five repairs go past well-formedness and therefore require their own flag; none is ever
145
146
  part of the default pipeline:
146
147
 
147
148
  - **`--fix-empty-body`**: `&nbsp;` inside a strictly empty `<body></body>` ("body
@@ -263,9 +264,15 @@ touched.
263
264
  - **`--fix-media-types`**: normalize wrong manifest `media-type` declarations (OPF-029: a
264
265
  file's bytes do not match the declared type). The expected type comes from the extension, and
265
266
  the rewrite fires only when the file's magic bytes at offset 0 confirm the extension (jpg,
266
- jpeg, png, gif): a PNG renamed `.jpg` keeps its wrong-but-consistent declaration rather than
267
- gaining a worse one. Attribute-only, quote-style preserved; files absent from the archive
268
- belong to `--prune-missing-resources`.
267
+ jpeg, png, gif; since v0.56.0 also the CSS-007 font slice: `ttf`/`otf`/`woff`/`woff2`
268
+ declared outside epubcheck's blessed font set are rewritten to their `font/*` spellings
269
+ when the magic bytes confirm the extension -- `font/*` is blessed on both package
270
+ versions, so no version gate is needed; `.eot` is never touched, epubcheck rejects EOT
271
+ as a font src however it is declared): a PNG renamed `.jpg` keeps its
272
+ wrong-but-consistent declaration rather than gaining a worse one. Attribute-only,
273
+ quote-style preserved; files absent from the archive belong to
274
+ `--prune-missing-resources`. The font half's gain sits on the INFO axis the counts do
275
+ not measure, so the flag is accepted under the `no_worse` bar (v0.56.0).
269
276
 
270
277
  - **`--fix-cover`**: repair dangling EPUB2 cover wiring (the cover-wiring ruling's
271
278
  deterministic half). A `<meta name="cover" content="X">` whose `X` names no manifest id is
@@ -276,6 +283,17 @@ file is absent: that class belongs to `--prune-missing-resources` and its edge c
276
283
  The EPUB3 `properties="cover-image"` slice is audit-only by ruling. Cover wiring is invisible
277
284
  to epubcheck, so cover-only repairs are accepted under the `no_worse` bar the lossy strips
278
285
  use, with the `partial` rule intact.
286
+ - **`--fix-unique-identifier`**: wire the OPF-030 dangling unique-identifier (v0.56.0, the
287
+ census lane's recipe): when `<package unique-identifier="X">` names an id no element
288
+ carries (the dominant family: identifiers that lost their id attributes wholesale), the id
289
+ X is written onto the first `dc:identifier` start tag. The dc: values are never touched,
290
+ and the repair predicts the post-wiring uid for the always-on NCX sync (the broken wiring
291
+ was masking the dtb:uid comparison; one run wires the OPF and aligns the NCX instead of
292
+ surfacing NCX-001 for a second run -- the issue #9 masking pattern, unmasked direction).
293
+ Refuses to guess: an absent or empty attribute, a non-NCName id, an already-wired OPF, no
294
+ `dc:identifier` element, or a first identifier that already carries an id. The multi-OPF
295
+ leftovers whose failing OPF is a stale non-rootfile are unreachable by construction
296
+ (only the located rootfile is repaired).
279
297
  - **`--fix-comment-double-hyphen`**: replace `--` inside XML comments with an en-dash
280
298
  (RSC-016: "The string `--` is not permitted within comments", a fatal: the book parses in
281
299
  lenient readers and never passes epubcheck). The edit is confined to comment bodies:
@@ -355,13 +373,13 @@ use, with the `partial` rule intact.
355
373
  byte-identical. Runs on the OPF only: content documents have the
356
374
  invalid-attribute drop (`--strip-bad-attrs`) for the same defect class.
357
375
 
358
- Twenty-two of the twenty-four are evaluated by the normal `gate`: unlike the lossy strips,
376
+ Twenty-three of the twenty-five are evaluated by the normal `gate`: unlike the lossy strips,
359
377
  their benefit is visible to epubcheck (they clear errors), so a run with no measurable
360
- improvement is a noop and nothing is applied. The two exceptions are `--fix-cover` and
361
- `--encode-url-spaces`, whose gains sit on axes epubcheck does not measure (cover
362
- wiring is not a schema finding; the rename half's PKG-010 gain sits on the warning
363
- axis): both are accepted under the same `no_worse` bar the lossy strips use, with
364
- the partial rule intact. CDATA sections are never rewritten
378
+ improvement is a noop and nothing is applied. The three exceptions are `--fix-cover`, `--encode-url-spaces`, and
379
+ `--fix-media-types` (whose gains sit on axes epubcheck's counts do not measure:
380
+ cover wiring is not a schema finding; the rename half's PKG-010 gain sits on the
381
+ warning axis; the font half's CSS-007 gain sits on the INFO axis): all are accepted
382
+ under the same `no_worse` bar the lossy strips use, with the partial rule intact. CDATA sections are never rewritten
365
383
  anywhere; comment bodies only by the double-hyphen fix above, and nothing else inside
366
384
  them.
367
385
 
@@ -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.55.0"
14
+ VERSION = "0.56.0"
15
15
  __version__ = VERSION
16
16
 
17
17
  from .epub import RepairReport, repair_epub # noqa: E402
@@ -107,6 +107,7 @@ def _flags_from_args(args: argparse.Namespace) -> RepairFlags:
107
107
  stray_close=args.fix_stray_close or all_,
108
108
  unterminated_attr=args.fix_unterminated_attr or all_,
109
109
  unbound_prefix=args.fix_unbound_prefix or all_,
110
+ unique_identifier=args.fix_unique_identifier or all_,
110
111
  )
111
112
 
112
113
 
@@ -217,6 +218,21 @@ def process_book(
217
218
  verdict = "partial"
218
219
  else:
219
220
  verdict = "accept"
221
+ if report.fixes.get("media_types_normalized"):
222
+ # v0.56.0: the font half of --fix-media-types clears CSS-007, an INFO
223
+ # finding the error/warning counts do not measure, so a font-only
224
+ # repair answers 'equal' from the improvement gate. The
225
+ # magic-byte-confirmed normalization is worth having regardless (the
226
+ # cover-wiring ruling's shape): same no_worse bar, partial rule
227
+ # intact. The OPF-029 error slice still measures a real decrease and
228
+ # accepts through the normal gate; this promotion only stops an
229
+ # INFO-only or mixed-equal repair from reading as gainless.
230
+ if not no_worse(before, after):
231
+ verdict = "reject"
232
+ elif after.fatals > 0:
233
+ verdict = "partial"
234
+ else:
235
+ verdict = "accept"
220
236
  if report.fixes.get("entries_renamed"):
221
237
  # The rename half's gain sits on epubcheck's WARNING axis
222
238
  # (PKG-010 space-in-filename advisories), which the improvement
@@ -1826,10 +1842,16 @@ _REPAIR_FLAG_TABLE: dict[str, list[tuple[str, str, str]]] = {
1826
1842
  "fix_media_types",
1827
1843
  "normalize wrong manifest media-types (magic-byte confirmed)",
1828
1844
  "normalize wrong manifest media-type declarations (OPF-029, e.g. a "
1829
- "jpg stamped image/png by an aggregator). Attribute-only and "
1845
+ "jpg stamped image/png by an aggregator; since v0.56.0 also the "
1846
+ "CSS-007 font slice: a ttf/otf/woff/woff2 declared outside "
1847
+ "epubcheck's blessed font set, rewritten to its font/* spelling "
1848
+ "when the magic bytes confirm the extension). Attribute-only and "
1830
1849
  "quote-preserving; it fires only when the file's magic bytes "
1831
1850
  "confirm the extension, so a misnamed-but-consistent file is never "
1832
- "made worse.",
1851
+ "made worse (.eot is never touched: epubcheck rejects EOT as a "
1852
+ "font src however it is declared). Accepted under the no-worse "
1853
+ "bar: the font half's gain sits on the INFO axis the counts do "
1854
+ "not measure.",
1833
1855
  ),
1834
1856
  (
1835
1857
  "declare_missing_items",
@@ -1843,6 +1865,18 @@ _REPAIR_FLAG_TABLE: dict[str, list[tuple[str, str, str]]] = {
1843
1865
  "An itemref with no manifest item is deliberately not repaired: "
1844
1866
  "which file it meant is underdetermined.",
1845
1867
  ),
1868
+ (
1869
+ "fix_unique_identifier",
1870
+ "wire the dangling OPF unique-identifier onto the first dc:identifier (OPF-030)",
1871
+ "add the id the package's unique-identifier attribute names to the "
1872
+ "first dc:identifier start tag when no element carries it (OPF-030 "
1873
+ "'The unique-identifier X was not found'; the census's dominant "
1874
+ "family is identifiers that lost their id attributes wholesale). "
1875
+ "Writes only the id the package itself names; the dc: values are "
1876
+ "never touched. Refuses to guess: an absent or empty attribute, a "
1877
+ "non-NCName id, an already-wired OPF, no dc:identifier element, or "
1878
+ "a first identifier that already carries an id.",
1879
+ ),
1846
1880
  (
1847
1881
  "fix_cover",
1848
1882
  "re-point or remove a dangling EPUB2 cover meta (no-worse bar)",
@@ -290,6 +290,7 @@ class RepairFlags:
290
290
  stray_close: bool = False
291
291
  unterminated_attr: bool = False
292
292
  unbound_prefix: bool = False
293
+ unique_identifier: bool = False
293
294
 
294
295
 
295
296
  @dataclass
@@ -524,14 +525,25 @@ def prune_dangling_edges(opf_text: str, pruned_ids: set[str]) -> tuple[str, int]
524
525
  return out, count
525
526
 
526
527
 
527
- # The media-type map is deliberately narrow: image types with an unambiguous
528
- # magic at offset 0, which is exactly the aggregator prevalence class (a jpg
529
- # stamped image/png). Extend only with a named epubcheck finding.
530
- _MEDIA_TYPES: dict[str, tuple[str, bytes]] = {
531
- ".jpg": ("image/jpeg", b"\xff\xd8\xff"),
532
- ".jpeg": ("image/jpeg", b"\xff\xd8\xff"),
533
- ".png": ("image/png", b"\x89PNG"),
534
- ".gif": ("image/gif", b"GIF8"),
528
+ # The media-type map: image types with an unambiguous magic at offset 0
529
+ # (the aggregator prevalence class: a jpg stamped image/png), plus the v0.56.0
530
+ # font half (issue #17's CSS-007 lane: @font-face srcs whose OPF declaration
531
+ # sits outside epubcheck's blessed font set -- text/plain fonts,
532
+ # application/xfont+otf, octet-stream woff2). The font/* spellings are blessed
533
+ # on BOTH package versions (EPUB2 blesses the font/ prefix; EPUB3's exact list
534
+ # carries them), so the map needs no version gate. Deliberately absent:
535
+ # application/vnd.ms-fontobject (.eot) -- epubcheck rejects EOT as a font src
536
+ # whatever it is declared, so "correcting" it can only churn; .ttc/.dat fonts
537
+ # (no blessed single spelling); extend only with a named epubcheck finding.
538
+ _MEDIA_TYPES: dict[str, tuple[str, tuple[bytes, ...]]] = {
539
+ ".jpg": ("image/jpeg", (b"\xff\xd8\xff",)),
540
+ ".jpeg": ("image/jpeg", (b"\xff\xd8\xff",)),
541
+ ".png": ("image/png", (b"\x89PNG",)),
542
+ ".gif": ("image/gif", (b"GIF8",)),
543
+ ".ttf": ("font/ttf", (b"\x00\x01\x00\x00", b"true", b"OTTO")),
544
+ ".otf": ("font/otf", (b"OTTO", b"\x00\x01\x00\x00")),
545
+ ".woff": ("font/woff", (b"wOFF",)),
546
+ ".woff2": ("font/woff2", (b"wOF2",)),
535
547
  }
536
548
  _MEDIA_TYPE_ATTR_RE = re.compile(
537
549
  r"""((?:^|\s)media-type\s*=\s*)(["'])((?:(?!\2).)*)(\2)""", re.IGNORECASE
@@ -539,14 +551,19 @@ _MEDIA_TYPE_ATTR_RE = re.compile(
539
551
 
540
552
 
541
553
  def fix_manifest_media_types(opf_text: str, opf_dir: str, peek) -> tuple[str, int]:
542
- """Normalize wrong manifest ``media-type`` declarations (OPF-029).
554
+ """Normalize wrong manifest ``media-type`` declarations (OPF-029, and
555
+ since v0.56.0 the CSS-007 font slice).
543
556
 
544
557
  An item's expected type comes from its extension; the rewrite only fires
545
558
  when the actual bytes at offset 0 confirm the extension (a PNG renamed
546
559
  .jpg keeps its - wrong but honest - declaration rather than gaining a
547
- worse one). Files absent from the archive are the prune's business, not
548
- this pass. Quote styles are preserved. Returns (text, count).
549
- """
560
+ worse one; a font is rewritten only when its magic names the same format
561
+ the extension does). Files absent from the archive are the prune's
562
+ business, not this pass. Quote styles are preserved. Returns (text,
563
+ count). The font half's gain sits on epubcheck's INFO axis (CSS-007),
564
+ which the error counts do not measure, so process_book accepts this
565
+ flag's repairs under the no_worse bar (the cover-wiring ruling's
566
+ shape)."""
550
567
  changed = 0
551
568
 
552
569
  def repl(m: re.Match) -> str:
@@ -563,7 +580,7 @@ def fix_manifest_media_types(opf_text: str, opf_dir: str, peek) -> tuple[str, in
563
580
  if expected is None or mm.group(3) == expected[0]:
564
581
  return tag
565
582
  head = peek(resolved)
566
- if head is None or not head.startswith(expected[1]):
583
+ if head is None or not any(head.startswith(magic) for magic in expected[1]):
567
584
  return tag
568
585
  changed += 1
569
586
  start, end = mm.span(3)
@@ -1527,6 +1544,47 @@ def opf_unique_id(opf_text: str) -> str | None:
1527
1544
  return m.group(1).strip() if m else None
1528
1545
 
1529
1546
 
1547
+ # The OPF-030 wiring repair (v0.56.0; the census lane's recorded recipe). The
1548
+ # dominant family: the package names an id but NO dc:identifier carries any id
1549
+ # attribute at all (a converter dropped the ids wholesale).
1550
+ _DC_IDENTIFIER_TAG_RE = re.compile(
1551
+ r"""<dc:identifier\b(?:"[^"]*"|'[^']*'|[^>])*+>""", re.IGNORECASE
1552
+ )
1553
+
1554
+
1555
+ def fix_unique_identifier_wiring(opf_text: str) -> tuple[str, int]:
1556
+ """Add the package's ``unique-identifier`` id to the first ``dc:identifier``.
1557
+
1558
+ epubcheck's OPF-030 fires when the ``<package unique-identifier="X">``
1559
+ attribute names an id no element carries; the census's dominant family is
1560
+ identifiers that carry no id attribute at all. The wiring writes only the
1561
+ id the package itself names onto the first identifier start tag: the dc:
1562
+ values are never touched, and reading/rendering cannot change. Refusals,
1563
+ each a shape this repair refuses to guess at: an absent or empty
1564
+ ``unique-identifier`` (nothing to wire; fabricating both halves of the
1565
+ contract is metadata surgery), a named id that is not a valid XML NCName
1566
+ (the wiring would create a new invalid id), an id="X" anywhere in the OPF
1567
+ (already wired -- the rare multi-OPF leftovers whose failing OPF is a
1568
+ stale non-rootfile are unreachable here anyway, since only the located
1569
+ rootfile is repaired), no ``dc:identifier`` element, or a first identifier
1570
+ that already carries an id (wiring X onto a different identifier than the
1571
+ first is a choice, not a determination). Returns (text, count).
1572
+ """
1573
+ attr = _UID_ATTR_RE.search(opf_text)
1574
+ if attr is None:
1575
+ return opf_text, 0
1576
+ uid = attr.group(2)
1577
+ if _is_invalid_ncname(uid):
1578
+ return opf_text, 0
1579
+ if re.search(rf"""id\s*=\s*(["']){re.escape(uid)}\1""", opf_text):
1580
+ return opf_text, 0
1581
+ m = _DC_IDENTIFIER_TAG_RE.search(opf_text)
1582
+ if m is None or re.search(r"""\bid\s*=""", m.group(0)):
1583
+ return opf_text, 0
1584
+ wired = m.group(0).replace("<dc:identifier", f'<dc:identifier id="{uid}"', 1)
1585
+ return opf_text[: m.start()] + wired + opf_text[m.end() :], 1
1586
+
1587
+
1530
1588
  def sync_ncx_uid(ncx_text: str, uid: str) -> tuple[str, bool]:
1531
1589
  """Set the NCX dtb:uid meta to `uid`. Returns (text, changed)."""
1532
1590
  cur = _DTB_UID_RE.search(ncx_text) or _DTB_UID_RE_REV.search(ncx_text)
@@ -1717,6 +1775,11 @@ def repair_epub(
1717
1775
  under an OPF-namespaced package; anything else refuses the whole
1718
1776
  document. Content documents are not touched (their unbound prefixes have
1719
1777
  the --strip-bad-attrs drop).
1778
+ With `unique_identifier`, wire the OPF-030 dangling unique-identifier: add
1779
+ the id the package names to the first dc:identifier start tag when no
1780
+ element carries it. Refuses to guess (absent/empty attribute, non-NCName
1781
+ id, already-wired, no dc:identifier, a first identifier that has an id);
1782
+ dc: values are never touched.
1720
1783
  With `strip_stub_docs` (lossy, the no_worse bar), drop spine documents whose
1721
1784
  entire visible text is one identical short placeholder repeated across the
1722
1785
  spine (the Bookmate/DRM-sample export whose chapters are all the same
@@ -1757,6 +1820,19 @@ def repair_epub(
1757
1820
  pkg_major = package_version(opf_text)
1758
1821
  if pkg_major is None or pkg_major >= 3:
1759
1822
  flags = replace(flags, strip_epub3_attrs=False, downgrade_epub3=False)
1823
+ # The wiring repair creates the id->identifier link the NCX uid sync
1824
+ # needs: on a dangling-uid book the source has no resolvable uid, so
1825
+ # `uid` above is None and the default-pass sync would skip, leaving
1826
+ # the NCX-001 that the broken wiring was masking to a second run.
1827
+ # Predict the post-wiring uid by running the SAME pure transformation
1828
+ # the OPF branch applies below -- nothing between here and there
1829
+ # touches the package attribute or the dc:identifier tags, so the
1830
+ # prediction is the branch's result, not a snapshot guess. Skipped
1831
+ # when uid is "" (the non-strict-UTF-8 OPF case: never drive a
1832
+ # mojibake uid into the NCX).
1833
+ wired_uid = None
1834
+ if flags.unique_identifier and uid is None and opf_text is not None:
1835
+ wired_uid = opf_unique_id(fix_unique_identifier_wiring(opf_text)[0])
1760
1836
  # Running-header detection and the page-layer decision need the whole book, so
1761
1837
  # collect content text once up front. Only when the lossy strip is requested.
1762
1838
  runheads: set[str] = set()
@@ -2067,8 +2143,9 @@ def repair_epub(
2067
2143
  if n:
2068
2144
  counts["ncx_fragments_stripped"] = n
2069
2145
  synced = False
2070
- if uid:
2071
- text, synced = sync_ncx_uid(text, uid)
2146
+ sync_uid = uid if uid else wired_uid
2147
+ if sync_uid:
2148
+ text, synced = sync_ncx_uid(text, sync_uid)
2072
2149
  if synced:
2073
2150
  report.ncx_uid_synced = True
2074
2151
  if counts or synced or ncx_changed:
@@ -2087,6 +2164,7 @@ def repair_epub(
2087
2164
  or flags.comment_double_hyphens
2088
2165
  or flags.strip_stub_docs
2089
2166
  or flags.unbound_prefix
2167
+ or flags.unique_identifier
2090
2168
  ):
2091
2169
  opf_changed = False
2092
2170
  if flags.unbound_prefix:
@@ -2102,6 +2180,11 @@ def repair_epub(
2102
2180
  if n:
2103
2181
  report.add({"fix_manifest_ids": n})
2104
2182
  opf_changed = True
2183
+ if flags.unique_identifier:
2184
+ text, n = fix_unique_identifier_wiring(text)
2185
+ if n:
2186
+ report.add({"unique_identifier_wired": n})
2187
+ opf_changed = True
2105
2188
  if flags.page_map:
2106
2189
  text, n = strip_page_map(text)
2107
2190
  if n:
@@ -17,6 +17,7 @@ from bindery.epub import (
17
17
  fix_manifest_ids,
18
18
  fix_ncx_ids,
19
19
  fix_pagelist_class,
20
+ fix_unique_identifier_wiring,
20
21
  generate_container,
21
22
  ncx_uid_mismatch,
22
23
  opf_unique_id,
@@ -1303,6 +1304,127 @@ class TestEncodeUrlSpacesEpub(unittest.TestCase):
1303
1304
  self.assertNotIn("url_spaces_encoded", report.fixes)
1304
1305
 
1305
1306
 
1307
+ class TestFixUniqueIdentifier(unittest.TestCase):
1308
+ """The OPF-030 wiring repair (v0.56.0): add the id the package names to
1309
+ the first dc:identifier when no element carries it; every ambiguous
1310
+ shape refuses."""
1311
+
1312
+ OPF_HEAD = (
1313
+ '<?xml version="1.0"?>'
1314
+ '<package xmlns="http://www.idpf.org/2007/opf" version="2.0" '
1315
+ 'unique-identifier="{uid}">'
1316
+ '<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">'
1317
+ )
1318
+
1319
+ def _opf(self, uid: str, idents: str) -> str:
1320
+ return self.OPF_HEAD.format(uid=uid) + idents + "</metadata></package>"
1321
+
1322
+ def test_wires_the_first_identifier(self):
1323
+ opf = self._opf(
1324
+ "bookid",
1325
+ "<dc:identifier>urn:uuid:X</dc:identifier>"
1326
+ "<dc:identifier>urn:uuid:Y</dc:identifier>",
1327
+ )
1328
+ out, n = fix_unique_identifier_wiring(opf)
1329
+ self.assertEqual(n, 1)
1330
+ self.assertIn('<dc:identifier id="bookid">', out)
1331
+ self.assertIn("<dc:identifier>urn:uuid:Y</dc:identifier>", out)
1332
+ ET.fromstring(out)
1333
+
1334
+ def test_existing_attributes_are_kept(self):
1335
+ opf = self._opf(
1336
+ "bookid", '<dc:identifier opf:scheme="ISBN">978</dc:identifier>'
1337
+ )
1338
+ out, n = fix_unique_identifier_wiring(opf)
1339
+ self.assertEqual(n, 1)
1340
+ self.assertIn('<dc:identifier id="bookid" opf:scheme="ISBN">', out)
1341
+
1342
+ def test_empty_attribute_refuses(self):
1343
+ opf = self._opf("", "<dc:identifier>urn:uuid:X</dc:identifier>").replace(
1344
+ 'unique-identifier=""', ""
1345
+ )
1346
+ out, n = fix_unique_identifier_wiring(opf)
1347
+ self.assertEqual((out, n), (opf, 0))
1348
+
1349
+ def test_invalid_ncname_refuses(self):
1350
+ opf = self._opf("1bad", "<dc:identifier>urn:uuid:X</dc:identifier>")
1351
+ out, n = fix_unique_identifier_wiring(opf)
1352
+ self.assertEqual((out, n), (opf, 0))
1353
+
1354
+ def test_already_wired_refuses(self):
1355
+ opf = self._opf(
1356
+ "bookid", '<dc:identifier id="other">urn:uuid:X</dc:identifier>'
1357
+ )
1358
+ # uid names "bookid", the first identifier carries a DIFFERENT id:
1359
+ # wiring onto a later element is a choice, refused
1360
+ out, n = fix_unique_identifier_wiring(opf)
1361
+ self.assertEqual((out, n), (opf, 0))
1362
+
1363
+ def test_uid_carried_anywhere_refuses(self):
1364
+ opf = self._opf(
1365
+ "bookid",
1366
+ "<dc:identifier>urn:uuid:X</dc:identifier>"
1367
+ '<dc:identifier id="bookid">urn:uuid:Y</dc:identifier>',
1368
+ )
1369
+ out, n = fix_unique_identifier_wiring(opf)
1370
+ self.assertEqual((out, n), (opf, 0))
1371
+
1372
+ def test_no_identifier_refuses(self):
1373
+ opf = self._opf("bookid", "<dc:title>t</dc:title>")
1374
+ out, n = fix_unique_identifier_wiring(opf)
1375
+ self.assertEqual((out, n), (opf, 0))
1376
+
1377
+ def test_repair_end_to_end(self):
1378
+ with tempfile.TemporaryDirectory() as td:
1379
+ src, dst = Path(td) / "in.epub", Path(td) / "out.epub"
1380
+ with zipfile.ZipFile(src, "w") as z:
1381
+ z.writestr("mimetype", "application/epub+zip")
1382
+ z.writestr(
1383
+ "OEBPS/content.opf",
1384
+ self._opf("bookid", "<dc:identifier>urn:uuid:X</dc:identifier>"),
1385
+ )
1386
+ z.writestr(
1387
+ "OEBPS/c1.xhtml",
1388
+ '<?xml version="1.0"?><html '
1389
+ 'xmlns="http://www.w3.org/1999/xhtml"><head><title>t</title>'
1390
+ "</head><body><p>x</p></body></html>",
1391
+ )
1392
+ report = repair_epub(src, dst, flags=RepairFlags(unique_identifier=True))
1393
+ self.assertEqual(report.fixes.get("unique_identifier_wired"), 1)
1394
+ with zipfile.ZipFile(dst) as z:
1395
+ self.assertIn(
1396
+ '<dc:identifier id="bookid">',
1397
+ z.read("OEBPS/content.opf").decode("utf-8"),
1398
+ )
1399
+
1400
+ def test_repair_also_syncs_the_masked_ncx(self):
1401
+ # The eagle shape: the dangling uid wiring MASKS the NCX-001 check
1402
+ # (epubcheck cannot compare dtb:uid to an unresolvable identifier).
1403
+ # One run must wire the OPF AND align the NCX to the now-resolvable
1404
+ # uid, or the fix trades OPF-030 for a surfaced NCX-001.
1405
+ with tempfile.TemporaryDirectory() as td:
1406
+ src, dst = Path(td) / "in.epub", Path(td) / "out.epub"
1407
+ with zipfile.ZipFile(src, "w") as z:
1408
+ z.writestr("mimetype", "application/epub+zip")
1409
+ z.writestr(
1410
+ "OEBPS/content.opf",
1411
+ self._opf("bookid", "<dc:identifier>urn:uuid:X</dc:identifier>"),
1412
+ )
1413
+ z.writestr("OEBPS/toc.ncx", NCX_BAD)
1414
+ z.writestr(
1415
+ "OEBPS/c1.xhtml",
1416
+ '<?xml version="1.0"?><html '
1417
+ 'xmlns="http://www.w3.org/1999/xhtml"><head><title>t</title>'
1418
+ "</head><body><p>x</p></body></html>",
1419
+ )
1420
+ report = repair_epub(src, dst, flags=RepairFlags(unique_identifier=True))
1421
+ self.assertEqual(report.fixes.get("unique_identifier_wired"), 1)
1422
+ self.assertTrue(report.ncx_uid_synced)
1423
+ with zipfile.ZipFile(dst) as z:
1424
+ ncx = z.read("OEBPS/toc.ncx").decode("utf-8")
1425
+ self.assertIn('content="urn:uuid:X"', ncx)
1426
+
1427
+
1306
1428
  class TestDeclareMissingItems(unittest.TestCase):
1307
1429
  """The RSC-008 repair (issue #16): declare present-but-undeclared
1308
1430
  resources the book references; never touch the spine."""
@@ -1800,6 +1922,74 @@ class TestFixMediaTypes(unittest.TestCase):
1800
1922
  self.assertNotIn("media_types_normalized", report.fixes)
1801
1923
 
1802
1924
 
1925
+ class TestFontMediaTypes(unittest.TestCase):
1926
+ """v0.56.0: the CSS-007 font half of --fix-media-types. The font/*
1927
+ spellings are blessed on both package versions; the magic must confirm
1928
+ the extension; .eot is never touched (epubcheck rejects EOT as a font
1929
+ src however it is declared)."""
1930
+
1931
+ @staticmethod
1932
+ def _build(path: Path, href: str, media_type: str, data: bytes) -> None:
1933
+ opf = (
1934
+ '<?xml version="1.0"?>'
1935
+ '<package xmlns="http://www.idpf.org/2007/opf" unique-identifier="bookid">'
1936
+ '<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">'
1937
+ '<dc:identifier id="bookid">urn:uuid:X</dc:identifier>'
1938
+ "</metadata>"
1939
+ "<manifest>"
1940
+ f'<item id="f" href="{href}" media-type="{media_type}"/>'
1941
+ "</manifest>"
1942
+ "<spine/></package>"
1943
+ )
1944
+ with zipfile.ZipFile(path, "w", zipfile.ZIP_DEFLATED) as z:
1945
+ z.writestr("mimetype", "application/epub+zip")
1946
+ z.writestr("META-INF/container.xml", TestFixContainer.CONTAINER)
1947
+ z.writestr("OEBPS/content.opf", opf)
1948
+ z.writestr("OEBPS/" + href, data)
1949
+
1950
+ def test_font_declared_text_plain_is_normalized(self):
1951
+ with tempfile.TemporaryDirectory() as td:
1952
+ src, dst = Path(td) / "in.epub", Path(td) / "out.epub"
1953
+ self._build(src, "f.ttf", "text/plain", b"\x00\x01\x00\x00\x00")
1954
+ report = repair_epub(src, dst, RepairFlags(fix_media_types=True))
1955
+ self.assertEqual(report.fixes.get("media_types_normalized"), 1)
1956
+ with zipfile.ZipFile(dst) as z:
1957
+ self.assertIn(
1958
+ 'media-type="font/ttf"',
1959
+ z.read("OEBPS/content.opf").decode("utf-8"),
1960
+ )
1961
+
1962
+ def test_font_with_wrong_magic_is_left(self):
1963
+ # text/plain declared over a file whose bytes are no font magic:
1964
+ # the declaration is wrong but the extension cannot be trusted either
1965
+ with tempfile.TemporaryDirectory() as td:
1966
+ src, dst = Path(td) / "in.epub", Path(td) / "out.epub"
1967
+ self._build(src, "f.ttf", "text/plain", b"not a font at all")
1968
+ report = repair_epub(src, dst, RepairFlags(fix_media_types=True))
1969
+ self.assertNotIn("media_types_normalized", report.fixes)
1970
+
1971
+ def test_woff2_octet_stream_normalized(self):
1972
+ with tempfile.TemporaryDirectory() as td:
1973
+ src, dst = Path(td) / "in.epub", Path(td) / "out.epub"
1974
+ self._build(src, "f.woff2", "application/octet-stream", b"wOF2\x00\x01")
1975
+ report = repair_epub(src, dst, RepairFlags(fix_media_types=True))
1976
+ self.assertEqual(report.fixes.get("media_types_normalized"), 1)
1977
+ with zipfile.ZipFile(dst) as z:
1978
+ self.assertIn(
1979
+ 'media-type="font/woff2"',
1980
+ z.read("OEBPS/content.opf").decode("utf-8"),
1981
+ )
1982
+
1983
+ def test_eot_is_never_touched(self):
1984
+ with tempfile.TemporaryDirectory() as td:
1985
+ src, dst = Path(td) / "in.epub", Path(td) / "out.epub"
1986
+ self._build(
1987
+ src, "f.eot", "application/vnd.ms-fontobject", b"\x00\x00\x00lol"
1988
+ )
1989
+ report = repair_epub(src, dst, RepairFlags(fix_media_types=True))
1990
+ self.assertNotIn("media_types_normalized", report.fixes)
1991
+
1992
+
1803
1993
  class TestFixCover(unittest.TestCase):
1804
1994
  """Phase 16 C, the cover-wiring ruling (2026-09-12: hybrid). The
1805
1995
  deterministic half is the EPUB2 cover meta: a dangling content id is
@@ -272,10 +272,16 @@ def _fixtures() -> dict:
272
272
  "--fix-media-types": (
273
273
  {
274
274
  "OEBPS/content.opf": _opf(
275
- [c1, _item("i", "i.png", "image/jpeg")], [r1]
275
+ [
276
+ c1,
277
+ _item("i", "i.png", "image/jpeg"),
278
+ _item("f", "f.ttf", "text/plain"),
279
+ ],
280
+ [r1],
276
281
  ),
277
282
  "OEBPS/c1.xhtml": _doc("<p>x</p>"),
278
283
  "OEBPS/i.png": PNG_BYTES,
284
+ "OEBPS/f.ttf": b"\x00\x01\x00\x00\x00",
279
285
  },
280
286
  "media_types_normalized",
281
287
  ),
@@ -399,6 +405,22 @@ def _fixtures() -> dict:
399
405
  },
400
406
  "fix_unterminated_attr",
401
407
  ),
408
+ "--fix-unique-identifier": (
409
+ {
410
+ "OEBPS/content.opf": (
411
+ '<?xml version="1.0"?>'
412
+ '<package xmlns="http://www.idpf.org/2007/opf" '
413
+ 'version="2.0" unique-identifier="bookid">'
414
+ '<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">'
415
+ "<dc:title>t</dc:title>"
416
+ "<dc:identifier>urn:uuid:dangling</dc:identifier>"
417
+ "</metadata>"
418
+ f"<manifest>{c1}</manifest><spine>{r1}</spine></package>"
419
+ ),
420
+ "OEBPS/c1.xhtml": plain,
421
+ },
422
+ "unique_identifier_wired",
423
+ ),
402
424
  "--fix-unbound-prefix": (
403
425
  {
404
426
  "OEBPS/content.opf": _opf(
@@ -546,8 +568,14 @@ class FlagEndToEndTests(unittest.TestCase):
546
568
  )
547
569
 
548
570
  def test_fix_media_types(self):
571
+ # v0.56.0: the fixture carries an image AND a font misdeclaration
549
572
  self.assertGreaterEqual(
550
- self._fixes_for("--fix-media-types")["media_types_normalized"], 1
573
+ self._fixes_for("--fix-media-types")["media_types_normalized"], 2
574
+ )
575
+
576
+ def test_fix_unique_identifier(self):
577
+ self.assertEqual(
578
+ self._fixes_for("--fix-unique-identifier")["unique_identifier_wired"], 1
551
579
  )
552
580
 
553
581
  def test_fix_cover(self):
@@ -49,6 +49,7 @@ DEST_TO_FIELD = {
49
49
  "fix_stray_close": "stray_close",
50
50
  "fix_unterminated_attr": "unterminated_attr",
51
51
  "fix_unbound_prefix": "unbound_prefix",
52
+ "fix_unique_identifier": "unique_identifier",
52
53
  "strip_pagination": "strip_pagination",
53
54
  "strip_broken_tags": "strip_brokentags",
54
55
  "strip_watermarks": "strip_watermarks",
@@ -8,7 +8,7 @@ resolution-markers = [
8
8
 
9
9
  [[package]]
10
10
  name = "bindery-cli"
11
- version = "0.55.0"
11
+ version = "0.56.0"
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