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.
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/AGENTS.md +14 -1
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/PKG-INFO +3 -2
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/README.md +2 -1
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/patchnotes.md +47 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/pyproject.toml +1 -1
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/roadmap.md +1 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/spec.md +30 -12
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/__init__.py +1 -1
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/cli.py +36 -2
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/epub.py +98 -15
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_epub.py +190 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_flags_real_core.py +30 -2
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_flags_wiring.py +1 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/uv.lock +1 -1
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/.github/FUNDING.yml +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/.github/workflows/ci.yml +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/.github/workflows/publish.yml +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/.gitignore +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/LICENSE +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/OBSERVE-RESEARCH.md +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/docs/screenshots/library-sweep.png +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/logo.svg +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/plugin/__init__.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/project.done +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/run_tests.sh +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/scripts/FastSweep.java +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/scripts/build_plugin.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/scripts/fast_sweep.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/__main__.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/audit.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/library.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/observe.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/pagination.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/reserialize.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/transforms.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/validate.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/src/bindery/watermark.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_audit.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_cli.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_comment_hyphens.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_contamination.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_cover_tocdrift.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_help.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_library.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_matcher_hardening.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_observe.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_pagination.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_plugin.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_reserialize.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_space_renames.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_spine_guard.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_transforms.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_validate.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_version.py +0 -0
- {bindery_cli-0.55.0 → bindery_cli-0.56.0}/tests/test_watermark.py +0 -0
- {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-
|
|
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.
|
|
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.
|
|
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-
|
|
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
|
|
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-
|
|
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`**: ` ` 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
|
|
267
|
-
|
|
268
|
-
|
|
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-
|
|
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
|
|
361
|
-
`--
|
|
362
|
-
wiring is not a schema finding; the rename half's PKG-010 gain sits on the
|
|
363
|
-
axis
|
|
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.
|
|
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
|
|
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
|
|
528
|
-
#
|
|
529
|
-
#
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
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
|
|
548
|
-
|
|
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
|
-
|
|
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
|
-
[
|
|
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"],
|
|
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",
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|