bindery-cli 0.46.0__tar.gz → 0.46.1__tar.gz

{bindery_cli-0.46.0 → bindery_cli-0.46.1}/.github/workflows/ci.yml

@@ -44,9 +44,10 @@ jobs:
         # The install floor (decision 63): vir-tui/cquarry are marker-gated
         # to 3.14 there, so these legs install the core (tqdm only) and run
         # exactly the test modules that never touch the gated stack: the
-        # repair core, the plugin under calibre stubs, validate, and the
-        # version/grammar pins. audit/library/CLI-stack tests stay on the
-        # 3.14 leg above.
+        # repair core, the plugin under calibre stubs, validate, the
+        # version/grammar pins, the RSC-016 comment-hyphen fix, the
+        # RepairFlags wiring pins, and the flags-driven real-core run.
+        # audit/library/CLI-stack tests stay on the 3.14 leg above.
         python-version: ["3.12", "3.13"]
     steps:
       - uses: actions/checkout@v5
@@ -59,6 +60,8 @@ jobs:
           tests.test_transforms tests.test_epub tests.test_pagination
           tests.test_watermark tests.test_reserialize tests.test_version
           tests.test_plugin tests.test_validate
+          tests.test_comment_hyphens tests.test_flags_wiring
+          tests.test_flags_real_core
   plugin-compat:
     name: Parse-check the plugin zip under the interpreters Calibre embeds
     runs-on: ubuntu-latest

{bindery_cli-0.46.0 → bindery_cli-0.46.1}/CLAUDE.md

@@ -31,7 +31,7 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
   mimetype fix (added/normalized/first-stored, epub.py's archive rewrite); every core
   fix must render identically to the author's intent: never add, remove, or reorder
   visible content. The canonical opt-in inventory lives in spec.md: sixteen structural
-  repairs, three lossy strips, four safe opt-ins, plus `--reserialize`.
+  repairs, four lossy strips, four safe opt-ins, plus `--reserialize`.
   * **Structural repairs** (`--fix-empty-body`, `--fix-missing-title`, `--fix-id-colons`,
     `--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
     `--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`,
@@ -80,11 +80,13 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 - **The gate is the safety contract.** Never apply a repair epubcheck has not accepted.
   Respect the two-mode logic in `validate.gate` (fatal-fixing tolerates error unmasking;
   error-cleanup does not). The lossy strips (`--strip-pagination`, `--strip-broken-tags`,
-  `--strip-watermarks`) are accepted by `validate.no_worse` instead (their gain is
-  invisible to epubcheck, so it only forbids a regression, never demands a measured
-  improvement). The structural opt-ins go through the normal `gate`: their gain IS
-  visible (they clear errors), so a run with no measurable improvement is a noop and
-  nothing is applied. Changing either bar means re-running the library dry run.
+  `--strip-watermarks`, `--strip-stub-docs`) are accepted by `validate.no_worse` instead
+  (their gain is invisible to epubcheck, so it only forbids a regression, never demands
+  a measured improvement). The structural opt-ins go through the normal `gate` (their
+  gain IS visible, so a run with no measurable improvement is a noop and nothing is
+  applied) except the two whose gains sit on axes epubcheck does not measure:
+  `--fix-cover` and `--encode-url-spaces`, accepted under the same `no_worse` bar with
+  the partial rule intact. Changing either bar means re-running the library dry run.
 - **Library writes are sacred.** Replacement must stay atomic (temp in same dir, then
   `os.replace`), touch only the `.epub`, preserve mode, and be dry-run by default.
   Calibre format installation goes through cquarry's write module (`--install-to-calibre`;
@@ -93,7 +95,7 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 
 ## Layout
 
-- `src/bindery/transforms.py`: pure `str -> (str, int)` text transforms (including `strip_broken_tags`). Since v0.32.0: `strip_attrs_in_start_tags` anchors attribute edits on the quote-aware start-tag matcher, `_outside_protected` forwards arguments (context-carrying transforms can be decorated), `fix_id_colons` matches only the bare `id` attribute and only internal fragments (`fix_ncx_src_fragments` carries renames into the NCX), `fix_ncx_playorder` is anchored to `<navPoint>` start tags, and the css selector boundary covers namespaced and functional selector forms. HAZARD (the 0.41.0 spin): the quote-aware tag-prefix alternation (double-quoted | single-quoted | [^>]) OVERLAPS ([^>] matches quotes too), so a plain `*` re-partitions exponentially on failing candidates; every such greedy loop must carry the possessive `*+` (re 3.11+, the plugin's minimum Calibre). Since v0.42.0 the census is complete and pinned by tests/test_matcher_hardening.py: every greedy loop of this family is possessive (the three 0.41.1 rewrites plus _START_TAG_RE, _COVER_META_RE, _GUIDE_REF_RE, prune_dangling_edges' spine|item|itemref matcher, _ITEM_TAG_RE, _SPINE_ITEM_RE -- possessive is byte-identical on success because the loop is always followed by a literal `>` the [^>] branch cannot consume), and the five LAZY siblings (_VOID_RE, the transforms <img> matcher, and epub's link/a/img matchers) use the disjoint catch-all `[^>"']` instead: mutually exclusive branches cannot re-partition, and an unterminated quote inside a tag now fails to match rather than pairing across markup. NEW tag matchers: quote-aware possessive for greedy loops, the disjoint catch-all for lazy ones, and the tempered-quote idiom (["'])((?:(?!\1).)*)\1 for attribute values. Since v0.37.0: `fix_ncx_playorder` strips quotes before its already-correct comparison (regex groups carry quote characters; comparing quoted values against bare numbers counted phantom fixes on every sequential NCX and rewrote single-quoted correct attributes to double quotes).
+- `src/bindery/transforms.py`: pure `str -> (str, int)` text transforms (including `strip_broken_tags`). Since v0.32.0: `strip_attrs_in_start_tags` anchors attribute edits on the quote-aware start-tag matcher, `_outside_protected` forwards arguments (context-carrying transforms can be decorated), `fix_id_colons` matches only the bare `id` attribute and only internal fragments (`fix_ncx_src_fragments` carries renames into the NCX), `fix_ncx_playorder` is anchored to `<navPoint>` start tags, and the css selector boundary covers namespaced and functional selector forms. HAZARD (the 0.41.0 spin): the quote-aware tag-prefix alternation (double-quoted | single-quoted | [^>]) OVERLAPS ([^>] matches quotes too), so a plain `*` re-partitions exponentially on failing candidates; every such greedy loop must carry the possessive `*+` (re 3.11+, the plugin's minimum Calibre). Since v0.42.0 the census is complete and pinned by tests/test_matcher_hardening.py: every greedy loop of this family is possessive (the three 0.41.1 rewrites plus _START_TAG_RE, _COVER_META_RE, _GUIDE_REF_RE, prune_dangling_edges' spine|item|itemref matcher, _ITEM_TAG_RE, _SPINE_ITEM_RE; possessive is byte-identical on success because the loop is always followed by a literal `>` the [^>] branch cannot consume), and the five LAZY siblings (_VOID_RE, the transforms <img> matcher, and epub's link/a/img matchers) use the disjoint catch-all `[^>"']` instead: mutually exclusive branches cannot re-partition, and an unterminated quote inside a tag now fails to match rather than pairing across markup. NEW tag matchers: quote-aware possessive for greedy loops, the disjoint catch-all for lazy ones, and the tempered-quote idiom (["'])((?:(?!\1).)*)\1 for attribute values. Since v0.37.0: `fix_ncx_playorder` strips quotes before its already-correct comparison (regex groups carry quote characters; comparing quoted values against bare numbers counted phantom fixes on every sequential NCX and rewrote single-quoted correct attributes to double quotes).
 - `src/bindery/pagination.py`: the opt-in lossy page-number strip (runhead detection, page-layer decision, block-centric removal/merge, safety nets).
 - `src/bindery/watermark.py`: the opt-in lossy watermark strip (anchored and anchorless signature removal).
 - `src/bindery/reserialize.py`: structural repair via `html5lib`.
@@ -102,8 +104,8 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 - `src/bindery/validate.py`: epubcheck wrapper, the `gate` (improvement) and `no_worse` (no-regression, for the lossy strips) acceptance bars.
 - `src/bindery/library.py`: Calibre walk, atomic replace, backups, and native format installation. Since v0.19.0 `CalibreIdResolver` resolves the book id from `metadata.db` through cquarry (one lazy path→id map per run; since v0.20.0 the map comes from `CalibreDB.format_path_index()`, re-normalized with `resolve().lower()` for the resolver's symlinked-directory and case-insensitive matching); the `(id)` directory-name regex is only the no-catalog fallback. Since v0.24.0 `install_format()` places the repaired file atomically and updates the `data` row through `cquarry.write.WritableCalibreDB` (since v0.31.0 via `set_format`, cquarry 1.17's sanctioned remove+add in one transaction); the external `calibredb` CLI is gone. Since v0.32.0 a guessed id drives a row update only when metadata.db corroborates it (`_verify_guess`: books row exists, file in the book's own directory, catalogued `data.name` when a row exists); anything else saves in place and leaves the catalog untouched: never reintroduce directory-name guessing as the primary source: renamed/mismatched directories would replace the wrong book. Since 2026-09-15 `make_backup` takes the opt-in `--backup-keep N` ring: at most N backup files per book, the author original `.bak` never deleted, newest content at the highest name; default remains an unbounded rotation.
 - `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; `repair --json` emits the library per-book record vocabulary (2026-09-15; since v0.45.0 every per-book record, the phase1 payload included, also carries the structured fix breakdown: the `fixes` dict plus `ncx_uid_synced`/`watermark_refusals` off the `Outcome`, and `_phase1_decisions` reads that data instead of substring-matching the rendered `summary`, which stays for human eyes; CalibreQuarry's lossy-consent mirror is the waiting consumer, floor `bindery>=0.45.0`); since v0.29.0 also the `run` verbs: `phase1` (pre-import vetting over loose files: the audit battery composed with one gated repair sweep; read-only until `--apply-lossy`, which IS the lossy-strip consent) and `phase3` (the scoped post-import apply step: `library --id --sweep --only all --apply --all --install-to-calibre` plus a pre/post summary; mechanically refuses unscoped sweeps with exit 2; since 2026-09-15 the summary sums applied/equal states only and carries rejected projections as `rejected_projection`). Plus `bindery doctor` (2026-09-15): the environment self-check that imports none of the VirInvictus stack, never raises, and always exits 0. Both run verbs take `--non-interactive` and surface open questions as `decisions_needed` in their JSON, never prompts. They drive the shipped `run_library` through the real parser, so no flag can drift between the verb and the subcommand it wraps. Since v0.46.0 `cli._flags_from_args(args)` is the one place the argparse names map onto `RepairFlags` fields (each `or --all`), shared by `run_library` and `run_repair`; the old per-verb ~25-kwarg blocks are gone. `library --workers N` (v0.30.0) parallelizes only the sweep's candidate pass, in windows of N consumed in order so `--limit` stays lazy; the repair phase is never parallel (shared workdir, atomic-replacement contract). Since v0.40.0 `main()` guards the VirInvictus stack: a `ModuleNotFoundError` naming `vir_tui`/`cquarry` (marker-gated to 3.14+ on the 3.12 floor) becomes one stderr line and trouble exit 2 instead of a traceback; anything else missing still raises.
-- `plugin/__init__.py` + `scripts/build_plugin.py`: the Bindery Repair Calibre plugin (v0.37.0; identity `Bindery Repair` / `bindery_repair`, approved and built per the scoped spec in roadmap.md Phase 3). The builder vendors `transforms.py`, `epub.py`, `pagination.py`, `watermark.py`, `reserialize.py` byte-identically into the zip (the zip root is a package, so their relative imports resolve unchanged; the suite's drift test pins the equality) with the version tuple substituted from the single-source VERSION; `publish.yml` attaches `BinderyRepair-v<VERSION>.zip` to each release. The plugin runs ONLY the default pass (epubcheck cannot gate inside Calibre), never raises, is byte-idempotent (zero fixes returns the original path), testzip()-verifies its output, logs one line per book, and takes JSON config via `site_customization` (`log`, `log_path`, `max_size_mb` default 150, `epubcheck_path` experimental validation default OFF). Load it in tests through the `tests/test_plugin.py` stubs: the calibre namespace is installed in sys.modules and the package loads with a two-dir `__path__` (plugin dir first, then src/bindery) exactly like calibre's zipplugin loader shape. **Plugin/interpreter compatibility (v0.40.0):** v0.39.0 shipped PEP 758 unparenthesized except tuples, and the plugin died with a bare SyntaxError on every released Calibre (7.x and the whole 8.x series embed Python 3.11, 9.0+ embeds 3.14; from calibre's bypy sources.json, checked against the upstream clone). The core is now grammar-pinned: parenthesized except tuples everywhere, `ruff`'s `target-version = "py312"` pin (inference from requires-python would rewrite the parens back off), `tests/test_version.py`'s parse guard, and CI's `plugin-compat` job byte-compiling the built zip under 3.11/3.12/3.13/3.14. `minimum_calibre_version` is (7, 0, 0): the oldest series whose interpreter CI covers, replacing the hollow (2, 0, 0); `supported_platforms` stays `["linux"]` (developed and tested on Linux only). Any new syntax in the vendored modules must clear the guard before it ships.
-- `tests/`: transforms, end-to-end repair, atomic replace, pagination, watermarks, the audit analyzers (content/pagenumbers/emptytext/ocr/monolithic/completeness, archive integrity, spine classification), the library sweep and `CalibreIdResolver`, validate, reserialize, CLI wiring, the version pin and the syntax-floor grammar guard, and the Calibre plugin (build drift + run behavior under calibre stubs).
+- `plugin/__init__.py` + `scripts/build_plugin.py`: the Bindery Repair Calibre plugin (v0.37.0; identity `Bindery Repair` / `bindery_repair`, approved and built per the scoped spec in roadmap.md Phase 3). The builder vendors `transforms.py`, `epub.py`, `pagination.py`, `watermark.py`, `reserialize.py` byte-identically into the zip (the zip root is a package, so their relative imports resolve unchanged; the suite's drift test pins the equality) with the version tuple substituted from the single-source VERSION; `publish.yml` attaches `BinderyRepair-v<VERSION>.zip` to each release. The plugin runs ONLY the default pass (epubcheck cannot gate inside Calibre), never raises, is byte-idempotent (zero fixes returns the original path), testzip()-verifies its output, logs one line per book, and takes JSON config via `site_customization` (`log`, `log_path`, `max_size_mb` default 150, `max_log_mb` rotation cap default 2, `epubcheck_path` experimental validation default OFF). Load it in tests through the `tests/test_plugin.py` stubs: the calibre namespace is installed in sys.modules and the package loads with a two-dir `__path__` (plugin dir first, then src/bindery) exactly like calibre's zipplugin loader shape. **Plugin/interpreter compatibility (v0.40.0):** v0.39.0 shipped PEP 758 unparenthesized except tuples, and the plugin died with a bare SyntaxError on every released Calibre (7.x and the whole 8.x series embed Python 3.11, 9.0+ embeds 3.14; from calibre's bypy sources.json, checked against the upstream clone). The core is now grammar-pinned: parenthesized except tuples everywhere, `ruff`'s `target-version = "py312"` pin (inference from requires-python would rewrite the parens back off), `tests/test_version.py`'s parse guard, and CI's `plugin-compat` job byte-compiling the built zip under 3.11/3.12/3.13/3.14. `minimum_calibre_version` is (7, 0, 0): the oldest series whose interpreter CI covers, replacing the hollow (2, 0, 0); `supported_platforms` stays `["linux"]` (developed and tested on Linux only). Any new syntax in the vendored modules must clear the guard before it ships.
+- `tests/`: transforms, end-to-end repair, atomic replace, pagination, watermarks, the audit analyzers (content/pagenumbers/emptytext/ocr/monolithic/completeness, archive integrity, spine classification), the library sweep and `CalibreIdResolver`, validate, reserialize, CLI wiring, the version pin and the syntax-floor grammar guard, and the Calibre plugin (build drift + run behavior under calibre stubs). Since the v0.46.0 follow-ups: `tests/test_flags_wiring.py` reflectively pins the RepairFlags inventory to the argparse dests and `_flags_from_args` mapping (a flag added without a field, a field without a flag, or a remapped line fails there), the all-off defaults, and the version gate's caller-immutability contract (test_epub's `TestVersionGateKeepsFlagsIntact`); `tests/test_comment_hyphens.py` carries the RSC-016 fix; `tests/test_flags_real_core.py` drives every repair flag from argv through the unmocked core (--no-validate; the gate itself stays pinned by the mocked-oracle tests and runs for real wherever epubcheck exists). All three ride CI's core-compat 3.12/3.13 leg; the hand-listed module list there must gain an entry for every new stack-free test module.
 
 ## Conventions
 

{bindery_cli-0.46.0 → bindery_cli-0.46.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.46.0
+Version: 0.46.1
 Summary: Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library.
 Project-URL: Homepage, https://github.com/VirInvictus/bindery-cli
 Project-URL: Repository, https://github.com/VirInvictus/bindery-cli
@@ -67,7 +67,7 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--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.
 - **`--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.
 - **`--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:`).
-- **`--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.
+- **`--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.
 - **`--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.
 - **`--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.
 - **`--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.
@@ -94,7 +94,7 @@ Introducing a net-new fatal is always rejected. If epubcheck itself fails to run
 
 Under the hood, the oracle can run two ways: the usual `epubcheck --json -` subprocess, or a persistent daemon that writes `FastDaemon.java` into a temp directory at runtime, compiles it in memory with the running JVM's own compiler (Java's single-file source launcher: no javac, no javac/java version skew), and drives the warm JVM over a pipe. The daemon reports the counts it reads from the JSON document that epubcheck's own `CheckingReport` serializes, so it measures exactly what the subprocess measures, just ~15x faster. It is a pool bounded by `--workers` (serial runs use one), every roundtrip is bounded by the caller's timeout, and any failure tears it down and falls back to the subprocess for good.
 
-The lossy modes (`--strip-pagination`, `--strip-broken-tags`, and `--strip-watermarks`) are the exception to the "must improve" rule. Since they remove visible markup rather than correcting XML schema violations, epubcheck counts often remain unchanged. They are accepted when the result is **no worse** (no net-new fatals or errors), relying on strict programmatic safety nets instead.
+The lossy modes (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`, and `--strip-stub-docs`) are the exception to the "must improve" rule. Since they remove converter-injected content rather than correcting XML schema violations, epubcheck counts often remain unchanged. They are accepted when the result is **no worse** (no net-new fatals or errors), relying on strict programmatic safety nets instead.
 
 ## Install
 

{bindery_cli-0.46.0 → bindery_cli-0.46.1}/README.md

@@ -40,7 +40,7 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--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.
 - **`--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.
 - **`--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:`).
-- **`--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.
+- **`--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.
 - **`--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.
 - **`--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.
 - **`--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.
@@ -67,7 +67,7 @@ Introducing a net-new fatal is always rejected. If epubcheck itself fails to run
 
 Under the hood, the oracle can run two ways: the usual `epubcheck --json -` subprocess, or a persistent daemon that writes `FastDaemon.java` into a temp directory at runtime, compiles it in memory with the running JVM's own compiler (Java's single-file source launcher: no javac, no javac/java version skew), and drives the warm JVM over a pipe. The daemon reports the counts it reads from the JSON document that epubcheck's own `CheckingReport` serializes, so it measures exactly what the subprocess measures, just ~15x faster. It is a pool bounded by `--workers` (serial runs use one), every roundtrip is bounded by the caller's timeout, and any failure tears it down and falls back to the subprocess for good.
 
-The lossy modes (`--strip-pagination`, `--strip-broken-tags`, and `--strip-watermarks`) are the exception to the "must improve" rule. Since they remove visible markup rather than correcting XML schema violations, epubcheck counts often remain unchanged. They are accepted when the result is **no worse** (no net-new fatals or errors), relying on strict programmatic safety nets instead.
+The lossy modes (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`, and `--strip-stub-docs`) are the exception to the "must improve" rule. Since they remove converter-injected content rather than correcting XML schema violations, epubcheck counts often remain unchanged. They are accepted when the result is **no worse** (no net-new fatals or errors), relying on strict programmatic safety nets instead.
 
 ## Install
 

{bindery_cli-0.46.0 → bindery_cli-0.46.1}/patchnotes.md

@@ -1,4 +1,32 @@
 # bindery-cli Patch Notes
+## v0.46.1 (2026-10-02)
+
+### The closing sweep: documentation truth after the 0.46 line
+
+The 2026-10-02 verification of the four-lane run left four documentation
+findings against the v0.46.0 tree; all four land here as text plus one
+plugin string. No surface change beyond the plugin's help text.
+
+* The safety contract's lossy enumeration names all four modes: the
+  paragraph listed three and omitted `--strip-stub-docs` (shipped
+  v0.41.0), while the mode list twenty lines up, spec.md, and CLAUDE.md
+  all carry four. Its rationale sentence now says converter-injected
+  content rather than visible markup, true of the document-dropping stub
+  mode too.
+* CLAUDE.md's tests bullet loses its em-dash: the one straggler in the
+  v0.45.0..HEAD markdown delta, recast with a semicolon.
+* ci.yml's core-compat comment describes every module its list runs: the
+  v0.46.0 follow-ups added comment-hyphens, flags-wiring, and
+  flags-real-core to the module list without touching the enumeration
+  above it, so a reader reconciling comment against list found three
+  orphans.
+* The plugin's `customization_help` names `max_log_mb`: the rotation cap
+  is documented in the README and honored by the log writer, but the
+  in-Calibre customization dialog never mentioned the key. Rides the
+  release-attached plugin zip.
+* Suite: 544 -> 575 tests since v0.46.0 (the two follow-up wiring-test
+  commits, unpinned in that entry's count), all green on this text-only
+  sweep.
 ## v0.46.0 (2026-10-02)
 
 ### The last open repair class closes: RSC-016, plus the RepairFlags refactor
@@ -26,7 +54,7 @@
 
 * **`--encode-url-spaces` gained its rename half**, the biggest real-prevalence repair class left (PKG-010: 8,237 occurrences in 284 books at the 2026-09-17 refresh). Archive entries whose names carry raw spaces are renamed to their underscore spellings and every reference is rewritten (OPF, NCX, content `src`/`href`, stylesheet `url()`). The design was decided by experiment, not by the roadmap box's plan: epubcheck 5.3 DECODES references before entry lookup, so percent-encoded entries are unfindable by the encoded references pointing at them (all four raw/percent/underscore combinations built and checked); underscore on both sides resolves and clears PKG-010. Ambiguous renames are refused per entry (a target that already exists, two names converging, a duplicated archive name), a book with any non-UTF-8 document refuses all of its renames, a renamed OPF regenerates a stale container, and the acceptance rides `no_worse` because the gain sits on the warning axis the improvement gate does not measure (same bar as `--fix-cover`).
 * **The matcher fix that explains Theaetetus** (the 2026-09-16 hand-rescue): the encode pass's value class `[^"']` stopped at apostrophes inside double-quoted hrefs, so the 270 raw-space OPF hrefs never matched and the fatal survived. The matcher now takes the tempered-quote idiom (possessive, house style), and an apostrophe in a double-quoted filename is ordinary.
-* **`bindery audit cover`** (advisory, the EPUB3 half of the ruled hybrid): dangling EPUB2 `<meta name="cover">` (the `--fix-cover` class), the EPUB3 `properties~="cover-image"` declaration, and whether the named cover file exists. **`bindery audit tocdrift`**: the structural diff between the NCX navMap and the EPUB3 nav toc, keyed on the full target including fragments -- entries each side is missing plus label mismatches. Both never flag a book and never move the exit code; ToC synthesis stays out of the repair charter permanently. The loader exposes the parsed OPF, the NCX text, and the nav HTML on `Book`.
+* **`bindery audit cover`** (advisory, the EPUB3 half of the ruled hybrid): dangling EPUB2 `<meta name="cover">` (the `--fix-cover` class), the EPUB3 `properties~="cover-image"` declaration, and whether the named cover file exists. **`bindery audit tocdrift`**: the structural diff between the NCX navMap and the EPUB3 nav toc, keyed on the full target including fragments: entries each side is missing plus label mismatches. Both never flag a book and never move the exit code; ToC synthesis stays out of the repair charter permanently. The loader exposes the parsed OPF, the NCX text, and the nav HTML on `Book`.
 * **The audit-refresh deep-dive ran** (read-only FastSweep extract over the full 5,228-book library; raw report in the facility): RSC-005 164,302 -> 13,782 occurrences, RSC-007 3,219 -> 14,162 in 604 books (the classics-wave imports), RSC-020 9,953 in 337 books, PKG-010 8,237 in 284 books (population flat: the rename class was still live, hence this ship).
 * **The roman grammar is one copy again**: pagination.py is the canonical home (it vendors into the plugin; audit does not), audit.py imports `ROMAN_RE`/`ROMAN_MAX`/`roman_value`, and the two byte-identical copies cannot drift. The RepairFlags dataclass refactor stays boxed with its reason (pure churn on the signatures this release touched).
 * Suite: 497 -> 521 tests (tests/test_space_renames.py, tests/test_cover_tocdrift.py, and the updated `--encode-url-spaces` end-to-end pins).
@@ -35,13 +63,13 @@
 
 ### The stdlib XML hardening: untrusted metadata is bounded and entity-refused, no dependency
 
-* **`--audit` and every `load_book` caller no longer decompress blind.** Two protections, both stdlib-only (the defusedxml dependency stays declined): single entries whose declared size exceeds `_MAX_ENTRY_BYTES` (32 MB) are refused before decompression -- a bomb entry in a tiny zip cannot be downloaded into memory -- and the untrusted metadata files (container.xml, OPF, encryption.xml) parse through `_safe_xml_parse`, which refuses DOCTYPE/ENTITY declarations before xml.etree sees them. A refused or unparseable metadata file returns the shell book (the archive verdict is the book's whole story), never a hang or a traceback.
+* **`--audit` and every `load_book` caller no longer decompress blind.** Two protections, both stdlib-only (the defusedxml dependency stays declined): single entries whose declared size exceeds `_MAX_ENTRY_BYTES` (32 MB) are refused before decompression (a bomb entry in a tiny zip cannot be downloaded into memory), and the untrusted metadata files (container.xml, OPF, encryption.xml) parse through `_safe_xml_parse`, which refuses DOCTYPE/ENTITY declarations before xml.etree sees them. A refused or unparseable metadata file returns the shell book (the archive verdict is the book's whole story), never a hang or a traceback.
 * Pinned by `tests/test_xml_hardening.py` (entity-bomb container returns the shell book; clean XML parses; the entry cap is sane). The defusedxml dependency ask is closed as declined with the stdlib shape delivered.
 
 ## v0.42.0 (2026-09-16)
 
 ### The matcher audit executed: every quote-aware tag matcher hardened
-The follow-up box the 0.41.1 hotfix opened is closed with a full per-matcher census, and the audit found the box's own enumeration incomplete. Six GREEDY patterns of the exponential overlap class were unhardened -- `_START_TAG_RE` (the quote-aware start-tag matcher anchoring `--strip-epub3-attrs` and `--strip-bad-attrs`, running under `repair --all` on every content doc; not even named in the box), `_COVER_META_RE`, `_GUIDE_REF_RE`, `prune_dangling_edges`' spine|item|itemref matcher, `_ITEM_TAG_RE`, and `_SPINE_ITEM_RE`. All six are possessive-bounded now: byte-identical on every successful match (the loop is always followed by a literal `>` that the `[^>]` branch cannot consume, so backtracking only ever happened on failure) and linear on failure. Five LAZY patterns of the quadratic class (`_VOID_RE`, the transforms `<img>` matcher, and epub's link/anchor/img matchers) took the disjoint catch-all `[^>"']` instead of a blind possessive swap: mutually exclusive branches cannot re-partition, so any quantifier is linear, and an unterminated quote inside a tag now fails to match instead of pairing with a distant quote and matching across markup. Every well-formed shape is byte-identical. The epub `_IMG_TAG_RE` is renamed `_PRUNE_IMG_TAG_RE` (it collided with the transforms matcher of the same name). Everything else in the package audited safe by construction: tempered-quote value matchers, two-branch quote alternations, `[^>]*` single-class prefixes (linear, not quote-aware -- accepted, documented), lazy paired-delimiter spans, and the analyzer tokenizers.
+The follow-up box the 0.41.1 hotfix opened is closed with a full per-matcher census, and the audit found the box's own enumeration incomplete. Six GREEDY patterns of the exponential overlap class were unhardened: `_START_TAG_RE` (the quote-aware start-tag matcher anchoring `--strip-epub3-attrs` and `--strip-bad-attrs`, running under `repair --all` on every content doc; not even named in the box), `_COVER_META_RE`, `_GUIDE_REF_RE`, `prune_dangling_edges`' spine|item|itemref matcher, `_ITEM_TAG_RE`, and `_SPINE_ITEM_RE`. All six are possessive-bounded now: byte-identical on every successful match (the loop is always followed by a literal `>` that the `[^>]` branch cannot consume, so backtracking only ever happened on failure) and linear on failure. Five LAZY patterns of the quadratic class (`_VOID_RE`, the transforms `<img>` matcher, and epub's link/anchor/img matchers) took the disjoint catch-all `[^>"']` instead of a blind possessive swap: mutually exclusive branches cannot re-partition, so any quantifier is linear, and an unterminated quote inside a tag now fails to match instead of pairing with a distant quote and matching across markup. Every well-formed shape is byte-identical. The epub `_IMG_TAG_RE` is renamed `_PRUNE_IMG_TAG_RE` (it collided with the transforms matcher of the same name). Everything else in the package audited safe by construction: tempered-quote value matchers, two-branch quote alternations, `[^>]*` single-class prefixes (linear, not quote-aware; accepted, documented), lazy paired-delimiter spans, and the analyzer tokenizers.
 
 Pinned by `tests/test_matcher_hardening.py` (15 tests): alarm-guarded spin shapes per greedy site (OPF flavor, the truncated-OPF prune shape), unterminated-quote skips, and well-formed byte-identity. `CLAUDE.md`'s hazard note now carries the census and the rule for new matchers. The full suite is 491 tests.
 

{bindery_cli-0.46.0 → bindery_cli-0.46.1}/plugin/__init__.py

@@ -270,7 +270,9 @@ class BinderyRepair(FileTypePlugin):
     def customization_help(self, gui=False):
         return (
             'Enter a JSON object: {"log": true, "log_path": ..., '
-            '"max_size_mb": 150, "epubcheck_path": null}. '
-            "epubcheck_path enables the experimental post-repair validation "
-            "with the epubcheck binary (slow; off by default)."
+            '"max_size_mb": 150, "max_log_mb": 2, "epubcheck_path": null}. '
+            "max_log_mb is the log rotation cap in MB (default 2, one .old "
+            "generation kept, 0 disables). epubcheck_path enables the "
+            "experimental post-repair validation with the epubcheck binary "
+            "(slow; off by default)."
         )

{bindery_cli-0.46.0 → bindery_cli-0.46.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bindery-cli"
-version = "0.46.0"
+version = "0.46.1"
 description = "Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library."
 readme = "README.md"
 classifiers = [

{bindery_cli-0.46.0 → bindery_cli-0.46.1}/roadmap.md

@@ -89,6 +89,12 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
       docs/screenshots/library-sweep.png against a synthetic testing_facility
       library (invented titles, real dry-run output); the current PNG shows 16
       real rows. Asked 2026-09-15, unanswered.
+- [x] **The 2026-10-02 closing sweep** (the four-lane verification's doc
+      findings against the v0.46.0 tree): the safety contract's lossy
+      enumeration names all four modes, the core-compat em-dash is gone,
+      ci.yml's module comment covers all eleven stack-free modules, and the
+      plugin's `customization_help` names `max_log_mb`. *(SHIPPED v0.46.1:
+      text plus the one plugin string; no surface change.)*
 
 ## The repair domain in the ecosystem parity program (recorded 2026-09-29)
 
@@ -107,7 +113,7 @@ metadata.db registration and the Calibre plugin. Dispositions recorded under the
   embed/subset fonts, jacket, smarten punctuation, remove-unused-css, compress-images,
   upgrade-book, download-external-resources, the --opf rewrite, --cover. They are
   content-improving rather than repair, and dc: metadata editing is out of charter
-  (spec.md:583). Recorded here so the parity ledger's bindery row names them declined,
+  (spec.md:597). Recorded here so the parity ledger's bindery row names them declined,
   not missing.
 - **The `data`-row waiver note**: bindery has updated `data` rows through
   `WritableCalibreDB.set_format` since v0.24.0 (the sanctioned install path);
@@ -134,7 +140,7 @@ metadata.db registration and the Calibre plugin. Dispositions recorded under the
   also fires on `add_format`, so the plugin is byte-idempotent. The vendor slice
   (transforms/epub/pagination/watermark/reserialize + a plugin `__init__`) is
   generated at release from the tagged tree with a byte-equality drift test. Active
-  set = the gate-safe default pass only: every structural repair and the three
+  set = the gate-safe default pass only: every structural repair and the four
   lossy strips stay CLI-only, because epubcheck cannot gate inside Calibre (no jar/JVM
   and seconds-per-book latency). Config via `site_customization` JSON (`log`,
   `log_path`, `max_size_mb`, recorded default 150MB); `publish.yml` attaches

{bindery_cli-0.46.0 → bindery_cli-0.46.1}/spec.md

@@ -20,8 +20,9 @@ The deliberate exceptions to "semantics-preserving" come in opt-in groups. The s
 `--prune-missing-resources`, `--strip-broken-anchors`, `--encode-url-spaces`,
 `--fix-container`, `--fix-media-types`, `--fix-cover`,
 `--fix-comment-double-hyphen`) alter
-markup structure or fabricate minimal content; the three
-**lossy modes** (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`) remove
+markup structure or fabricate minimal content; the four
+**lossy modes** (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`,
+`--strip-stub-docs`) remove
 content a converter injected rather than content the author wrote. A fourth group of
 **safe opt-ins** (`--fix-ids`, `--add-img-alt`, `--strip-bad-attrs`,
 `--escape-unknown-entities`) repairs without altering visible markup, and
@@ -233,11 +234,13 @@ use, with the `partial` rule intact.
   different fatal class and is left alone. It applies to content documents, the NCX, and
   the OPF alike, and every replaced sequence is counted.
 
-Fifteen of the sixteen are evaluated by the normal `gate`: unlike the lossy strips,
+Fourteen of the sixteen are evaluated by the normal `gate`: unlike the lossy strips,
 their benefit is visible to epubcheck (they clear errors), so a run with no measurable
-improvement is a noop and nothing is applied. The exception is `--fix-cover`, whose
-gain is invisible to epubcheck: it is accepted under the same `no_worse` bar the
-lossy strips use, with the partial rule intact. CDATA sections are never rewritten
+improvement is a noop and nothing is applied. The two exceptions are `--fix-cover` and
+`--encode-url-spaces`, whose gains sit on axes epubcheck does not measure (cover
+wiring is not a schema finding; the rename half's PKG-010 gain sits on the warning
+axis): both are accepted under the same `no_worse` bar the lossy strips use, with
+the partial rule intact. CDATA sections are never rewritten
 anywhere; comment bodies only by the double-hyphen fix above, and nothing else inside
 them.
 
@@ -445,7 +448,7 @@ Two more advisory analyzers ship in v0.44.0. `cover` reads the package's own cov
 wiring (the EPUB3 half of the ruled hybrid): a dangling EPUB2 `<meta name="cover">`
 (the `--fix-cover` repair class), an EPUB3 `properties~="cover-image"` declaration,
 and whether the named cover file exists. `tocdrift` diffs the two tables of contents
-an EPUB 3 book may carry -- the NCX navMap against the nav document -- reporting
+an EPUB 3 book may carry (the NCX navMap against the nav document), reporting
 entries each side is missing and labels that disagree; it feeds decisions, never a
 rewrite (ToC synthesis is out of the repair charter permanently). Both never flag a
 book and never move the exit code.

{bindery_cli-0.46.0 → bindery_cli-0.46.1}/src/bindery/__init__.py

@@ -11,7 +11,7 @@ Calibre plugin built from this core.
 Single source of truth for the version. pyproject.toml must match VERSION below.
 """
 
-VERSION = "0.46.0"
+VERSION = "0.46.1"
 __version__ = VERSION
 
 from .epub import RepairReport, repair_epub  # noqa: E402

{bindery_cli-0.46.0 → bindery_cli-0.46.1}/src/bindery/cli.py

@@ -1488,7 +1488,7 @@ def _add_repair_flags(p: argparse.ArgumentParser) -> None:
         action="store_true",
         help="replace `--` inside XML comments with an en-dash (RSC-016: "
         "`--` is not permitted within comments); comment bodies only, "
-        "text and CDATA never touched",
+        "CDATA never touched",
     )
     p.add_argument(
         "--strip-pagination",

{bindery_cli-0.46.0 → bindery_cli-0.46.1}/src/bindery/transforms.py

@@ -721,8 +721,11 @@ def fix_comment_double_hyphen(s: str) -> tuple[str, int]:
     in character data is legal XML), CDATA sections are never touched, and
     each comment's `-->` terminator is left intact (the span ends there, so
     the body replacement cannot reach it). Every replaced sequence is
-    counted. An unclosed comment matches no span and is left for whatever
-    reports it; the fix claims only the double-hyphen class.
+    counted. An unclosed `<!--` runs the span to the first later `-->`, which is
+    exactly what an XML parser sees (once the opener never closes, that whole
+    region is comment content), so the fix rewrites wherever a parser reads a
+    comment; CDATA is protected either way, and the fix claims only the
+    double-hyphen class.
     """
     count = 0
 

{bindery_cli-0.46.0 → bindery_cli-0.46.1}/tests/test_epub.py

@@ -413,6 +413,63 @@ class TestPackageVersion(unittest.TestCase):
                 self.assertNotIn("epub3_attrs_stripped", report.fixes)
 
 
+class TestVersionGateKeepsFlagsIntact(unittest.TestCase):
+    """The package-version gate copies the flags (dataclasses.replace)
+    instead of mutating them: one EPUB3 book in a sweep must not switch
+    the EPUB2-targeted fixes off for every later book. The in-place
+    mutation regression class of 2026-09-08, pinned on the caller's
+    object because no report key can see it. Also pins both gated fields
+    decoupling: a regression that neutralizes only one of the pair must
+    still fail here (the downgrade half on an EPUB3 package)."""
+
+    EPUB3_OPF = (
+        '<?xml version="1.0"?>'
+        '<package xmlns="http://www.idpf.org/2007/opf" '
+        'version="3.0" unique-identifier="bookid">'
+        "<metadata/><spine/></package>"
+    )
+    EPUB3_CONTENT = (
+        '<?xml version="1.0"?>'
+        '<html xmlns="http://www.w3.org/1999/xhtml">'
+        '<body epub:type="chapter" aria-label="c">'
+        "<figure><figcaption>cap</figcaption></figure><p>x</p></body></html>"
+    )
+
+    def _repair(self, dst):
+        src = dst.with_name("in.epub")
+        with zipfile.ZipFile(src, "w") as z:
+            z.writestr("mimetype", "application/epub+zip")
+            z.writestr("OEBPS/content.opf", self.EPUB3_OPF)
+            z.writestr("OEBPS/c1.xhtml", self.EPUB3_CONTENT)
+        return src
+
+    def test_gate_does_not_mutate_the_callers_flags(self):
+        with tempfile.TemporaryDirectory() as td:
+            dst = Path(td) / "out.epub"
+            src = self._repair(dst)
+            flags = RepairFlags(strip_epub3_attrs=True, downgrade_epub3=True)
+            repair_epub(src, dst, flags)
+        self.assertTrue(flags.strip_epub3_attrs, "gate mutated the caller's flags")
+        self.assertTrue(flags.downgrade_epub3, "gate mutated the caller's flags")
+
+    def test_both_epub2_fixes_stay_inert_on_an_epub3_package(self):
+        # the replace() line neutralizes the pair together; a regression
+        # that decouples them (one field replaced, one mutated to respect
+        # the caller's True) re-enables the mutated half on EPUB3 books
+        with tempfile.TemporaryDirectory() as td:
+            dst = Path(td) / "out.epub"
+            src = self._repair(dst)
+            report = repair_epub(
+                src, dst, RepairFlags(strip_epub3_attrs=True, downgrade_epub3=True)
+            )
+            self.assertNotIn("epub3_attrs_stripped", report.fixes)
+            self.assertNotIn("epub3_tags_downgraded", report.fixes)
+            with zipfile.ZipFile(dst) as z:
+                c_out = z.read("OEBPS/c1.xhtml").decode()
+        self.assertIn('epub:type="chapter"', c_out)
+        self.assertIn("<figure>", c_out)
+
+
 class TestDowngradeEpub3Tags(unittest.TestCase):
     """The element half of the RSC-005 verdict: EPUB3 semantic elements
     downgrade to their EPUB2 equivalents, classes kept, CSS-protected names

bindery_cli-0.46.1/tests/test_flags_real_core.py

@@ -0,0 +1,487 @@
+"""Every repair flag, driven through the real command line and the real
+repair core (no mocks). The 2026-10-02 test-gap sweep named this gap:
+almost every CLI-level test mocks bindery.cli.repair_epub, so only a
+couple of flags were ever proven to work from argv. Each row here runs
+`bindery repair <fixture> <out> --<flag> --no-validate --json` through
+main() against a minimal book carrying exactly that flag's defect, and
+asserts the flag's own fix key fired in the JSON record.
+
+--no-validate is deliberate: the gate itself is pinned by the
+mocked-oracle tests and runs for real wherever epubcheck exists; CI has
+no epubcheck, and this file pins the argv-to-fix path, which is
+flag-independent of the oracle."""
+
+import io
+import json
+import tempfile
+import unittest
+import zipfile
+from contextlib import redirect_stdout
+from pathlib import Path
+
+from bindery.cli import main
+
+try:
+    import html5lib  # noqa: F401
+
+    HAVE_HTML5LIB = True
+except ImportError:
+    HAVE_HTML5LIB = False
+
+CONTAINER = (
+    '<?xml version="1.0"?><container version="1.0" '
+    'xmlns="urn:oasis:names:tc:opendocument:xmlns:container">'
+    '<rootfiles><rootfile full-path="OEBPS/content.opf" '
+    'media-type="application/oebps-package+xml"/></rootfiles></container>'
+)
+
+PNG_BYTES = b"\x89PNG\r\n\x1a\n"
+
+LONG = (
+    "the quick brown fox jumped over the lazy dog and then kept on running for many "
+    "miles across the wide green fields under a bright and cloudless summer sky"
+)
+
+STUB_DOC = (
+    '<?xml version="1.0"?><html xmlns="http://www.w3.org/1999/xhtml">'
+    "<body>This content is not available.</body></html>"
+)
+
+
+def _doc(body: str, *, title: str = "t") -> str:
+    return (
+        '<?xml version="1.0"?><html xmlns="http://www.w3.org/1999/xhtml">'
+        f"<head><title>{title}</title></head><body>{body}</body></html>"
+    )
+
+
+def _opf(items, refs, *, version: str = "2.0", meta: str = "", guide: str = "") -> str:
+    return (
+        '<?xml version="1.0"?>'
+        '<package xmlns="http://www.idpf.org/2007/opf" '
+        f'version="{version}" unique-identifier="id">'
+        f'<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">{meta}</metadata>'
+        f"<manifest>{''.join(items)}</manifest>"
+        f"<spine>{''.join(refs)}</spine>{guide}</package>"
+    )
+
+
+def _item(id_: str, href: str, mt: str = "application/xhtml+xml") -> str:
+    return f'<item id="{id_}" href="{href}" media-type="{mt}"/>'
+
+
+def _ref(id_: str) -> str:
+    return f'<itemref idref="{id_}"/>'
+
+
+def _fixtures() -> dict:
+    """flag option -> (entries, expected fix key). Each book is minimal and
+    carries exactly one flag's defect; the assertion is that the flag's own
+    fix key fires through the real core."""
+    c1 = _item("c1", "c1.xhtml")
+    r1 = _ref("c1")
+    plain = _doc("<p>word word word word</p>")
+    return {
+        "--fix-ids": (
+            {
+                "OEBPS/content.opf": _opf([_item("1bad", "c1.xhtml")], [_ref("1bad")]),
+                "OEBPS/c1.xhtml": plain,
+            },
+            "fix_manifest_ids",
+        ),
+        "--add-img-alt": (
+            {
+                "OEBPS/content.opf": _opf([c1, _item("i", "i.png", "image/png")], [r1]),
+                "OEBPS/c1.xhtml": _doc('<p>x</p><img src="i.png"/>'),
+                "OEBPS/i.png": PNG_BYTES,
+            },
+            "img_alt_added",
+        ),
+        "--reserialize": (
+            {
+                "OEBPS/content.opf": _opf([c1], [r1]),
+                "OEBPS/c1.xhtml": (
+                    '<html xmlns="http://www.w3.org/1999/xhtml"><body>'
+                    "<p>one<p>two</body></html>"
+                ),
+            },
+            "reserialized",
+        ),
+        "--strip-bad-attrs": (
+            {
+                "OEBPS/content.opf": _opf([c1], [r1]),
+                "OEBPS/c1.xhtml": _doc('<img v:shapes="x" src="i.png"/>'),
+            },
+            "stripped_invalid_attrs",
+        ),
+        "--escape-unknown-entities": (
+            {
+                "OEBPS/content.opf": _opf([c1], [r1]),
+                "OEBPS/c1.xhtml": _doc("<p>a &foo; b</p>"),
+            },
+            "escape_unknown_entities",
+        ),
+        "--fix-empty-body": (
+            {
+                "OEBPS/content.opf": _opf([c1], [r1]),
+                "OEBPS/c1.xhtml": (
+                    '<html xmlns="http://www.w3.org/1999/xhtml"><body></body></html>'
+                ),
+            },
+            "fix_empty_body",
+        ),
+        "--fix-missing-title": (
+            {
+                "OEBPS/content.opf": _opf([c1], [r1]),
+                "OEBPS/c1.xhtml": (
+                    '<html xmlns="http://www.w3.org/1999/xhtml">'
+                    "<head></head><body><p>x</p></body></html>"
+                ),
+            },
+            "fix_missing_title",
+        ),
+        "--fix-id-colons": (
+            {
+                "OEBPS/content.opf": _opf([c1], [r1]),
+                "OEBPS/c1.xhtml": _doc('<h2 id="s:1">t</h2><a href="#s:1">go</a>'),
+            },
+            "fix_id_colons",
+        ),
+        "--unwrap-block-in-inline": (
+            {
+                "OEBPS/content.opf": _opf([c1], [r1]),
+                "OEBPS/c1.xhtml": _doc('<span><div class="c">block</div></span>'),
+            },
+            "unwrap_block_in_inline",
+        ),
+        "--strip-invalid-value": (
+            {
+                "OEBPS/content.opf": _opf([c1], [r1]),
+                "OEBPS/c1.xhtml": _doc('<div value="1">x</div>'),
+            },
+            "strip_invalid_value",
+        ),
+        "--unwrap-illegal-tags": (
+            {
+                "OEBPS/content.opf": _opf([c1], [r1]),
+                "OEBPS/c1.xhtml": _doc("<w>hidden</w><p>x</p>"),
+            },
+            "unwrap_illegal_tags",
+        ),
+        "--fix-page-map": (
+            {
+                "OEBPS/content.opf": (
+                    '<?xml version="1.0"?>'
+                    '<package xmlns="http://www.idpf.org/2007/opf" '
+                    'version="2.0" unique-identifier="id"><metadata/>'
+                    f"<manifest>{c1}{_item('n', 'toc.ncx', 'application/x-dtbncx+xml')}"
+                    f'</manifest><spine page-map="pmap" toc="n">{r1}</spine></package>'
+                ),
+                "OEBPS/c1.xhtml": plain,
+                "OEBPS/toc.ncx": (
+                    '<?xml version="1.0"?>'
+                    '<ncx xmlns="http://www.daisy.org/z3986/2005/ncx/" version="2005-1">'
+                    "<head/><docTitle><text>t</text></docTitle><navMap>"
+                    '<pageList><navTarget id="pg1" playOrder="1">'
+                    "<navLabel><text>1</text></navLabel>"
+                    '<content src="c1.xhtml"/></navTarget></pageList>'
+                    "</navMap></ncx>"
+                ),
+            },
+            "page_map_stripped",
+        ),
+        "--strip-epub3-attrs": (
+            {
+                "OEBPS/content.opf": _opf([c1], [r1]),
+                "OEBPS/c1.xhtml": _doc('<p epub:type="chapter">x</p>'),
+            },
+            "epub3_attrs_stripped",
+        ),
+        "--downgrade-epub3-tags": (
+            {
+                "OEBPS/content.opf": _opf([c1], [r1]),
+                "OEBPS/c1.xhtml": _doc("<figure><figcaption>cap</figcaption></figure>"),
+            },
+            "epub3_tags_downgraded",
+        ),
+        "--prune-missing-resources": (
+            {
+                "OEBPS/content.opf": _opf([c1, _item("orphan", "absent2.xhtml")], [r1]),
+                "OEBPS/c1.xhtml": _doc(
+                    '<link href="gone.css" rel="stylesheet" type="text/css"/>'
+                    '<img src="absent.png"/>'
+                ),
+            },
+            "dead_links_pruned",
+        ),
+        "--strip-broken-anchors": (
+            {
+                "OEBPS/content.opf": _opf(
+                    [c1, _item("c2", "c2.xhtml")], [r1, _ref("c2")]
+                ),
+                "OEBPS/c1.xhtml": _doc('<a href="c2.xhtml#nope">text</a>'),
+                "OEBPS/c2.xhtml": _doc("<p>no ids here</p>"),
+            },
+            "broken_fragment_hrefs_stripped",
+        ),
+        "--encode-url-spaces": (
+            {
+                "OEBPS/content.opf": _opf(
+                    [c1, _item("i", "raw name.png", "image/png")], [r1]
+                ),
+                "OEBPS/c1.xhtml": _doc('<img src="raw name.png"/>'),
+                "OEBPS/raw name.png": PNG_BYTES,
+            },
+            "entries_renamed",
+        ),
+        "--fix-container": (
+            {
+                "META-INF/container.xml": (
+                    '<?xml version="1.0"?><container version="1.0" '
+                    'xmlns="urn:oasis:names:tc:opendocument:xmlns:container">'
+                    '<rootfiles><rootfile full-path="OEBPS/missing.opf" '
+                    'media-type="application/oebps-package+xml"/>'
+                    "</rootfiles></container>"
+                ),
+                "OEBPS/content.opf": _opf([c1], [r1]),
+                "OEBPS/c1.xhtml": plain,
+            },
+            "container_generated",
+        ),
+        "--fix-media-types": (
+            {
+                "OEBPS/content.opf": _opf(
+                    [c1, _item("i", "i.png", "image/jpeg")], [r1]
+                ),
+                "OEBPS/c1.xhtml": _doc("<p>x</p>"),
+                "OEBPS/i.png": PNG_BYTES,
+            },
+            "media_types_normalized",
+        ),
+        "--fix-cover": (
+            {
+                "OEBPS/content.opf": _opf(
+                    [c1, _item("cov", "cover.png", "image/jpeg")],
+                    [r1],
+                    meta='<meta name="cover" content="nope"/>',
+                    guide='<guide><reference type="cover" href="cover.png"/></guide>',
+                ),
+                "OEBPS/c1.xhtml": plain,
+                "OEBPS/cover.png": PNG_BYTES,
+            },
+            "cover_meta_repointed",
+        ),
+        "--fix-comment-double-hyphen": (
+            {
+                "OEBPS/content.opf": _opf([c1], [r1]),
+                "OEBPS/c1.xhtml": _doc("<!-- a -- b --><p>x</p>"),
+            },
+            "fix_comment_double_hyphen",
+        ),
+        "--strip-pagination": (
+            {
+                "OEBPS/content.opf": _opf([c1], [r1]),
+                "OEBPS/c1.xhtml": _doc(
+                    "".join(
+                        f"<p>{LONG} and</p><p>{n}</p><p>kept {LONG}.</p>"
+                        for n in range(1, 25)
+                    )
+                ),
+            },
+            "stripped_pagination",
+        ),
+        "--strip-broken-tags": (
+            {
+                "OEBPS/content.opf": _opf([c1], [r1]),
+                "OEBPS/c1.xhtml": _doc("<p>text /div&gt; more</p>"),
+            },
+            "stripped_broken_tags",
+        ),
+        "--strip-watermarks": (
+            {
+                "OEBPS/content.opf": _opf([c1], [r1]),
+                "OEBPS/c1.xhtml": plain,
+                "oceanofpdf.com": "",
+            },
+            "dropped_marker",
+        ),
+        "--strip-stub-docs": (
+            {
+                "OEBPS/content.opf": _opf(
+                    [_item(f"s{i}", f"s{i}.xhtml") for i in range(3)]
+                    + [_item(f"c{i}", f"c{i}.xhtml") for i in range(2)],
+                    [_ref(f"s{i}") for i in range(3)]
+                    + [_ref(f"c{i}") for i in range(2)],
+                ),
+                "OEBPS/s0.xhtml": STUB_DOC,
+                "OEBPS/s1.xhtml": STUB_DOC,
+                "OEBPS/s2.xhtml": STUB_DOC,
+                "OEBPS/c0.xhtml": _doc(
+                    "<p>Chapter one begins here with plenty of real prose so the "
+                    "book has honest chapters beside its placeholder pages.</p>"
+                ),
+                "OEBPS/c1.xhtml": _doc(
+                    "<p>Chapter two continues the real text with its own words, "
+                    "long enough that no analyzer would call it a placeholder.</p>"
+                ),
+            },
+            "stub_docs_dropped",
+        ),
+    }
+
+
+class FlagEndToEndTests(unittest.TestCase):
+    def _fixes_for(self, flag: str) -> dict:
+        entries, _ = _fixtures()[flag]
+        with tempfile.TemporaryDirectory() as td:
+            src = Path(td) / "in.epub"
+            dst = Path(td) / "out.epub"
+            out = Path(td) / "out.json"
+            with zipfile.ZipFile(src, "w") as z:
+                z.writestr("mimetype", "application/epub+zip", zipfile.ZIP_STORED)
+                if "META-INF/container.xml" not in entries:
+                    z.writestr("META-INF/container.xml", CONTAINER)
+                for entry, data in entries.items():
+                    z.writestr(entry, data)
+            buf = io.StringIO()
+            with redirect_stdout(buf):
+                rc = main(
+                    [
+                        "repair",
+                        str(src),
+                        str(dst),
+                        flag,
+                        "--no-validate",
+                        "--json",
+                        str(out),
+                    ]
+                )
+            self.assertEqual(rc, 0, f"{flag}: main() returned {rc}: {buf.getvalue()}")
+            self.assertTrue(dst.exists(), f"{flag}: nothing written")
+            record = json.loads(out.read_text())
+        self.assertEqual(record["status"], "unvalidated", flag)
+        return record["fixes"]
+
+    def test_fix_ids(self):
+        self.assertGreaterEqual(self._fixes_for("--fix-ids")["fix_manifest_ids"], 1)
+
+    def test_add_img_alt(self):
+        self.assertGreaterEqual(self._fixes_for("--add-img-alt")["img_alt_added"], 1)
+
+    @unittest.skipUnless(HAVE_HTML5LIB, "html5lib not installed")
+    def test_reserialize(self):
+        self.assertGreaterEqual(self._fixes_for("--reserialize")["reserialized"], 1)
+
+    def test_strip_bad_attrs(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--strip-bad-attrs")["stripped_invalid_attrs"], 1
+        )
+
+    def test_escape_unknown_entities(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--escape-unknown-entities")["escape_unknown_entities"], 1
+        )
+
+    def test_fix_empty_body(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--fix-empty-body")["fix_empty_body"], 1
+        )
+
+    def test_fix_missing_title(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--fix-missing-title")["fix_missing_title"], 1
+        )
+
+    def test_fix_id_colons(self):
+        self.assertGreaterEqual(self._fixes_for("--fix-id-colons")["fix_id_colons"], 1)
+
+    def test_unwrap_block_in_inline(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--unwrap-block-in-inline")["unwrap_block_in_inline"], 1
+        )
+
+    def test_strip_invalid_value(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--strip-invalid-value")["strip_invalid_value"], 1
+        )
+
+    def test_unwrap_illegal_tags(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--unwrap-illegal-tags")["unwrap_illegal_tags"], 1
+        )
+
+    def test_fix_page_map(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--fix-page-map")["page_map_stripped"], 1
+        )
+
+    def test_strip_epub3_attrs(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--strip-epub3-attrs")["epub3_attrs_stripped"], 1
+        )
+
+    def test_downgrade_epub3_tags(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--downgrade-epub3-tags")["epub3_tags_downgraded"], 1
+        )
+
+    def test_prune_missing_resources(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--prune-missing-resources")["dead_links_pruned"], 1
+        )
+
+    def test_strip_broken_anchors(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--strip-broken-anchors")["broken_fragment_hrefs_stripped"],
+            1,
+        )
+
+    def test_encode_url_spaces(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--encode-url-spaces")["entries_renamed"], 1
+        )
+
+    def test_fix_container(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--fix-container")["container_generated"], 1
+        )
+
+    def test_fix_media_types(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--fix-media-types")["media_types_normalized"], 1
+        )
+
+    def test_fix_cover(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--fix-cover")["cover_meta_repointed"], 1
+        )
+
+    def test_fix_comment_double_hyphen(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--fix-comment-double-hyphen")["fix_comment_double_hyphen"],
+            1,
+        )
+
+    def test_strip_pagination(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--strip-pagination")["stripped_pagination"], 20
+        )
+
+    def test_strip_broken_tags(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--strip-broken-tags")["stripped_broken_tags"], 1
+        )
+
+    def test_strip_watermarks(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--strip-watermarks")["dropped_marker"], 1
+        )
+
+    def test_strip_stub_docs(self):
+        self.assertGreaterEqual(
+            self._fixes_for("--strip-stub-docs")["stub_docs_dropped"], 3
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

bindery_cli-0.46.1/tests/test_flags_wiring.py

@@ -0,0 +1,113 @@
+"""The RepairFlags wiring invariants (added after the v0.46.0 refactor,
+from the 2026-10-02 test-gap sweep): the flag inventory lives in three
+places that must never drift apart silently -- the RepairFlags dataclass
+fields, the argparse dests in cli._add_repair_flags, and the
+dest-to-field mapping in cli._flags_from_args. Before this module, no
+test failed when a flag was added without a field, a field without a
+flag, or a mapping line was forgotten; a disconnected flag shipped
+silently. The dest-to-field pairs are spelled here on purpose: an
+intentional remap updates both copies, and an accidental one fails
+here."""
+
+import unittest
+from argparse import ArgumentParser, _StoreTrueAction
+from dataclasses import fields
+from pathlib import Path
+from unittest import mock
+
+from bindery import cli
+from bindery.epub import RepairFlags, RepairReport
+
+# argparse dest on the left, RepairFlags field on the right.
+DEST_TO_FIELD = {
+    "fix_ids": "fix_ids",
+    "add_img_alt": "img_alt",
+    "reserialize": "reserialize",
+    "strip_bad_attrs": "strip_attrs",
+    "escape_unknown_entities": "escape_entities",
+    "fix_empty_body": "empty_body",
+    "fix_missing_title": "missing_title",
+    "fix_id_colons": "id_colons",
+    "unwrap_block_in_inline": "block_in_inline",
+    "strip_invalid_value": "invalid_value",
+    "unwrap_illegal_tags": "illegal_tags",
+    "fix_page_map": "page_map",
+    "strip_epub3_attrs": "strip_epub3_attrs",
+    "downgrade_epub3_tags": "downgrade_epub3",
+    "prune_missing_resources": "prune_missing",
+    "strip_broken_anchors": "strip_anchors",
+    "encode_url_spaces": "url_spaces",
+    "fix_container": "fix_container",
+    "fix_media_types": "fix_media_types",
+    "fix_cover": "fix_cover",
+    "fix_comment_double_hyphen": "comment_double_hyphens",
+    "strip_pagination": "strip_pagination",
+    "strip_broken_tags": "strip_brokentags",
+    "strip_watermarks": "strip_watermarks",
+    "strip_stub_docs": "strip_stub_docs",
+}
+
+# The two store_true dests in _add_repair_flags that are not repair flags.
+NON_SELECTION_DESTS = {"all", "no_validate"}
+
+
+def _repair_flag_dests() -> set[str]:
+    """The dests cli._add_repair_flags defines: every flag it registers is
+    a store_true opt-in (the two non-selection dests are filtered by the
+    caller). Checked by action class, not the .action attribute: 3.14's
+    argparse actions do not carry it."""
+    dummy = ArgumentParser(add_help=False)
+    cli._add_repair_flags(dummy)
+    return {
+        a.dest
+        for a in dummy._actions
+        if isinstance(a, _StoreTrueAction) and a.dest != "help"
+    }
+
+
+class DefaultsTests(unittest.TestCase):
+    def test_every_field_defaults_false(self):
+        # The all-off instance IS the default pass, and the plugin's bare
+        # repair_epub(src, dst) call constructs exactly it: one field
+        # defaulting True would ship an ungated fix inside Calibre.
+        wrong = [
+            f.name
+            for f in fields(RepairFlags)
+            if getattr(RepairFlags(), f.name) is not False
+        ]
+        self.assertEqual(wrong, [])
+
+
+class WiringTests(unittest.TestCase):
+    def _flags_for_argv(self, *option_flags: str) -> RepairFlags:
+        """The RepairFlags object repair_epub receives for the given argv
+        (repair_epub mocked to a falsy report, so process_book stops
+        before the epubcheck leg)."""
+        args = cli.build_parser().parse_args(["repair", "x.epub", *option_flags])
+        with mock.patch(
+            "bindery.cli.repair_epub", return_value=RepairReport()
+        ) as repair:
+            cli.process_book(
+                Path("x.epub"),
+                Path("."),
+                validate=False,
+                flags=cli._flags_from_args(args),
+            )
+        return repair.call_args.kwargs["flags"]
+
+    def test_dest_inventory_matches_the_dataclass(self):
+        self.assertEqual(_repair_flag_dests() - NON_SELECTION_DESTS, set(DEST_TO_FIELD))
+
+    def test_each_dest_maps_to_its_pinned_field(self):
+        for dest, field in sorted(DEST_TO_FIELD.items()):
+            flags = self._flags_for_argv(f"--{dest.replace('_', '-')}")
+            truthy = [f.name for f in fields(RepairFlags) if getattr(flags, f.name)]
+            self.assertEqual(truthy, [field], f"--{dest.replace('_', '-')}")
+
+    def test_all_enables_every_field(self):
+        flags = self._flags_for_argv("--all")
+        self.assertTrue(all(getattr(flags, f.name) for f in fields(RepairFlags)))
+
+
+if __name__ == "__main__":
+    unittest.main()