bindery-cli 0.52.0__tar.gz → 0.53.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/.github/workflows/ci.yml +1 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/PKG-INFO +34 -3
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/README.md +33 -2
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/patchnotes.md +60 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/pyproject.toml +1 -1
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/roadmap.md +1 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/spec.md +41 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/src/bindery/__init__.py +3 -3
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/src/bindery/audit.py +5 -2
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/src/bindery/cli.py +60 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/src/bindery/library.py +7 -2
- bindery_cli-0.53.1/src/bindery/observe.py +539 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/tests/test_help.py +1 -1
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/tests/test_library.py +13 -0
- bindery_cli-0.53.1/tests/test_observe.py +365 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/uv.lock +1 -1
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/.github/FUNDING.yml +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/.github/workflows/publish.yml +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/.gitignore +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/AGENTS.md +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/LICENSE +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/docs/screenshots/library-sweep.png +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/logo.svg +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/plugin/__init__.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/project.done +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/run_tests.sh +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/scripts/FastSweep.java +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/scripts/build_plugin.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/scripts/fast_sweep.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/src/bindery/__main__.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/src/bindery/epub.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/src/bindery/pagination.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/src/bindery/reserialize.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/src/bindery/transforms.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/src/bindery/validate.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/src/bindery/watermark.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/tests/test_audit.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/tests/test_cli.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/tests/test_comment_hyphens.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/tests/test_contamination.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/tests/test_cover_tocdrift.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/tests/test_epub.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/tests/test_flags_real_core.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/tests/test_flags_wiring.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/tests/test_matcher_hardening.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/tests/test_pagination.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/tests/test_plugin.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/tests/test_reserialize.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/tests/test_space_renames.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/tests/test_spine_guard.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/tests/test_transforms.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/tests/test_validate.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/tests/test_version.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/tests/test_watermark.py +0 -0
- {bindery_cli-0.52.0 → bindery_cli-0.53.1}/tests/test_xml_hardening.py +0 -0
|
@@ -62,6 +62,7 @@ jobs:
|
|
|
62
62
|
tests.test_plugin tests.test_validate
|
|
63
63
|
tests.test_comment_hyphens tests.test_flags_wiring
|
|
64
64
|
tests.test_flags_real_core tests.test_spine_guard
|
|
65
|
+
tests.test_observe
|
|
65
66
|
plugin-compat:
|
|
66
67
|
name: Parse-check the plugin zip under the interpreters Calibre embeds
|
|
67
68
|
runs-on: ubuntu-latest
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: bindery-cli
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.53.1
|
|
4
4
|
Summary: Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library.
|
|
5
5
|
Project-URL: Homepage, https://github.com/VirInvictus/bindery-cli
|
|
6
6
|
Project-URL: Repository, https://github.com/VirInvictus/bindery-cli
|
|
@@ -95,7 +95,7 @@ Every repair is gated by [epubcheck](https://github.com/w3c/epubcheck). The acce
|
|
|
95
95
|
- If a book **had fatals**, success means **fewer fatals**. The error count may rise as previously-hidden schema warnings become visible once the file parses; that is the book going from "won't open" to "opens with nits," not a regression.
|
|
96
96
|
- If a book had **no fatals**, an error increase is a real regression, so a strict error decrease is required.
|
|
97
97
|
|
|
98
|
-
Introducing a net-new fatal is always rejected. If epubcheck itself fails to run (crash, timeout, unparsable output), the book is reported as an error and never applied; only an explicit `--no-validate` skips the gate. Originals are never modified except by an explicit, atomic in-place replace (see below), and even then only after the gate accepts the result.
|
|
98
|
+
Introducing a net-new fatal is always rejected. One structural veto rides above the counts: the repairer probes source and candidate with a spine-resolution check (itemref to manifest item to archive entry), and any candidate whose spine dangles more than the original's is rejected no matter what the counts say, because a repair that orphans live reading-order references can otherwise measure as an improvement. If epubcheck itself fails to run (crash, timeout, unparsable output), the book is reported as an error and never applied; only an explicit `--no-validate` skips the gate. Originals are never modified except by an explicit, atomic in-place replace (see below), and even then only after the gate accepts the result.
|
|
99
99
|
|
|
100
100
|
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.
|
|
101
101
|
|
|
@@ -195,9 +195,12 @@ without a gate, and the mode costs two epubcheck runs per imported book.
|
|
|
195
195
|
|
|
196
196
|
## Usage
|
|
197
197
|
|
|
198
|
-
|
|
198
|
+
Six verbs: `bindery repair` fixes a single EPUB epubcheck-gated, `bindery audit`
|
|
199
199
|
reports content flaws without touching anything, `bindery library` sweeps a Calibre
|
|
200
200
|
library tree (dry run by default; `--apply` replaces accepted books atomically in place),
|
|
201
|
+
`bindery observe` validates every EPUB under a tree in one warm-JVM pass and writes one
|
|
202
|
+
versioned `.observe` census artifact (counts and error codes together, tabulated, with
|
|
203
|
+
the gated repair preview and `--against` trend diffing),
|
|
201
204
|
`bindery run` composes the acquisition pathway's EPUB slices (phase-1 pre-import
|
|
202
205
|
vetting, phase-3 scoped post-import repair) for a calling agent, and `bindery doctor`
|
|
203
206
|
checks the installation (see Install).
|
|
@@ -353,6 +356,34 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
|
|
|
353
356
|
- A `partial` book (improved but still unable to open) is reported for manual follow-up and fails the run with exit 2, in `library`, `run phase1`, and `run phase3` alike: a book that still needs a human is trouble.
|
|
354
357
|
- `repair` refuses to overwrite an existing output file unless `--force` is given.
|
|
355
358
|
|
|
359
|
+
## Observing a library
|
|
360
|
+
|
|
361
|
+
`bindery observe` is the whole-library census: one warm-JVM pass validates
|
|
362
|
+
every EPUB (counts and error codes together, clean books included), the
|
|
363
|
+
result is tabulated (severity histogram, dominant error-code classes, worst
|
|
364
|
+
offenders), and one self-describing `.observe` artifact carries the per-book
|
|
365
|
+
records so any later question can be answered without re-validating:
|
|
366
|
+
|
|
367
|
+
```sh
|
|
368
|
+
bindery observe ~/docs/Calibre\ Library --output ~/observe/base.observe
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
- Strictly read-only: the only file written is the artifact, and the writer
|
|
372
|
+
refuses to land it inside the scanned root (the default output is
|
|
373
|
+
`observe-<timestamp>.observe` in the current directory).
|
|
374
|
+
- The optional repair preview (default on, `--no-preview` skips) composes the
|
|
375
|
+
shipped library runner in-process as a dry-run over the default flag set:
|
|
376
|
+
it measures what `--apply` would write, per candidate, and never writes.
|
|
377
|
+
- `--against base.observe` carries a trend block in the new artifact: library
|
|
378
|
+
deltas, error-mass delta, and per-code changes with `new_codes` and
|
|
379
|
+
`resolved_codes`. Artifacts are versioned (`bindery-observe-v1`); a
|
|
380
|
+
schema mismatch is a usage error, never a silently incomparable trend.
|
|
381
|
+
- A book the JVM cannot read arrives as a sentinel record instead of being
|
|
382
|
+
dropped, and a run that comes back short of the input count refuses to
|
|
383
|
+
write a partial census. The library and audit walks skip `.caltrash`.
|
|
384
|
+
- Exit codes: 0 artifact written, 1 invocation problem, 2 the census harness
|
|
385
|
+
failed mid-run.
|
|
386
|
+
|
|
356
387
|
## Run slices
|
|
357
388
|
|
|
358
389
|
`bindery run` wraps the acquisition pathway's EPUB steps as verbs. They add no
|
|
@@ -68,7 +68,7 @@ Every repair is gated by [epubcheck](https://github.com/w3c/epubcheck). The acce
|
|
|
68
68
|
- If a book **had fatals**, success means **fewer fatals**. The error count may rise as previously-hidden schema warnings become visible once the file parses; that is the book going from "won't open" to "opens with nits," not a regression.
|
|
69
69
|
- If a book had **no fatals**, an error increase is a real regression, so a strict error decrease is required.
|
|
70
70
|
|
|
71
|
-
Introducing a net-new fatal is always rejected. If epubcheck itself fails to run (crash, timeout, unparsable output), the book is reported as an error and never applied; only an explicit `--no-validate` skips the gate. Originals are never modified except by an explicit, atomic in-place replace (see below), and even then only after the gate accepts the result.
|
|
71
|
+
Introducing a net-new fatal is always rejected. One structural veto rides above the counts: the repairer probes source and candidate with a spine-resolution check (itemref to manifest item to archive entry), and any candidate whose spine dangles more than the original's is rejected no matter what the counts say, because a repair that orphans live reading-order references can otherwise measure as an improvement. If epubcheck itself fails to run (crash, timeout, unparsable output), the book is reported as an error and never applied; only an explicit `--no-validate` skips the gate. Originals are never modified except by an explicit, atomic in-place replace (see below), and even then only after the gate accepts the result.
|
|
72
72
|
|
|
73
73
|
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.
|
|
74
74
|
|
|
@@ -168,9 +168,12 @@ without a gate, and the mode costs two epubcheck runs per imported book.
|
|
|
168
168
|
|
|
169
169
|
## Usage
|
|
170
170
|
|
|
171
|
-
|
|
171
|
+
Six verbs: `bindery repair` fixes a single EPUB epubcheck-gated, `bindery audit`
|
|
172
172
|
reports content flaws without touching anything, `bindery library` sweeps a Calibre
|
|
173
173
|
library tree (dry run by default; `--apply` replaces accepted books atomically in place),
|
|
174
|
+
`bindery observe` validates every EPUB under a tree in one warm-JVM pass and writes one
|
|
175
|
+
versioned `.observe` census artifact (counts and error codes together, tabulated, with
|
|
176
|
+
the gated repair preview and `--against` trend diffing),
|
|
174
177
|
`bindery run` composes the acquisition pathway's EPUB slices (phase-1 pre-import
|
|
175
178
|
vetting, phase-3 scoped post-import repair) for a calling agent, and `bindery doctor`
|
|
176
179
|
checks the installation (see Install).
|
|
@@ -326,6 +329,34 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
|
|
|
326
329
|
- A `partial` book (improved but still unable to open) is reported for manual follow-up and fails the run with exit 2, in `library`, `run phase1`, and `run phase3` alike: a book that still needs a human is trouble.
|
|
327
330
|
- `repair` refuses to overwrite an existing output file unless `--force` is given.
|
|
328
331
|
|
|
332
|
+
## Observing a library
|
|
333
|
+
|
|
334
|
+
`bindery observe` is the whole-library census: one warm-JVM pass validates
|
|
335
|
+
every EPUB (counts and error codes together, clean books included), the
|
|
336
|
+
result is tabulated (severity histogram, dominant error-code classes, worst
|
|
337
|
+
offenders), and one self-describing `.observe` artifact carries the per-book
|
|
338
|
+
records so any later question can be answered without re-validating:
|
|
339
|
+
|
|
340
|
+
```sh
|
|
341
|
+
bindery observe ~/docs/Calibre\ Library --output ~/observe/base.observe
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
- Strictly read-only: the only file written is the artifact, and the writer
|
|
345
|
+
refuses to land it inside the scanned root (the default output is
|
|
346
|
+
`observe-<timestamp>.observe` in the current directory).
|
|
347
|
+
- The optional repair preview (default on, `--no-preview` skips) composes the
|
|
348
|
+
shipped library runner in-process as a dry-run over the default flag set:
|
|
349
|
+
it measures what `--apply` would write, per candidate, and never writes.
|
|
350
|
+
- `--against base.observe` carries a trend block in the new artifact: library
|
|
351
|
+
deltas, error-mass delta, and per-code changes with `new_codes` and
|
|
352
|
+
`resolved_codes`. Artifacts are versioned (`bindery-observe-v1`); a
|
|
353
|
+
schema mismatch is a usage error, never a silently incomparable trend.
|
|
354
|
+
- A book the JVM cannot read arrives as a sentinel record instead of being
|
|
355
|
+
dropped, and a run that comes back short of the input count refuses to
|
|
356
|
+
write a partial census. The library and audit walks skip `.caltrash`.
|
|
357
|
+
- Exit codes: 0 artifact written, 1 invocation problem, 2 the census harness
|
|
358
|
+
failed mid-run.
|
|
359
|
+
|
|
329
360
|
## Run slices
|
|
330
361
|
|
|
331
362
|
`bindery run` wraps the acquisition pathway's EPUB steps as verbs. They add no
|
|
@@ -1,5 +1,65 @@
|
|
|
1
1
|
# bindery-cli Patch Notes
|
|
2
2
|
|
|
3
|
+
## v0.53.1 (2026-10-24)
|
|
4
|
+
|
|
5
|
+
### The .observe artifact now carries its per-book census rows
|
|
6
|
+
|
|
7
|
+
v0.53.0's spec, README, and patchnotes promised per-book census rows in the
|
|
8
|
+
artifact ("any later question can be answered without re-validating"), and
|
|
9
|
+
the first real run proved the promise hollow: the writer composed every
|
|
10
|
+
aggregate but never the `books` array. The rows are written now, one record
|
|
11
|
+
per book, clean ones included: path relative to the root, counts, the
|
|
12
|
+
error-code list, and the unreadable flag. The schema is unchanged
|
|
13
|
+
(`bindery-observe-v1`: the field set grew; no existing consumer reads the
|
|
14
|
+
array), and the test pins the rows.
|
|
15
|
+
|
|
16
|
+
## v0.53.0 (2026-10-24)
|
|
17
|
+
|
|
18
|
+
### `bindery observe`: the whole-library census, one artifact per run
|
|
19
|
+
|
|
20
|
+
The 2026-10-24 whole-library autopsy answered "where are we at" the hard way:
|
|
21
|
+
a dry-run sweep plus hand tabulation in the main thread. That session is now
|
|
22
|
+
a verb. `bindery observe PATH` validates every EPUB under a tree in one
|
|
23
|
+
warm-JVM pass, paying JVM startup once and running the parallel stream across
|
|
24
|
+
all cores, and writes one self-describing `.observe` artifact: the library
|
|
25
|
+
totals, a severity histogram (fatal books, error-count buckets, warnings-only,
|
|
26
|
+
unreadable, error mass), the error-code profile as occurrences and distinct
|
|
27
|
+
books, the worst offenders, and the per-book census rows so any later question
|
|
28
|
+
can be answered from the artifact without re-validating.
|
|
29
|
+
|
|
30
|
+
The harness embeds its Java like the FastDaemon does (JEP 330 single-file
|
|
31
|
+
launcher, no javac, in-memory compile), so the verb ships in the wheel and
|
|
32
|
+
the scripts/ benchmarking facility stays unshipped and untouched. Counting
|
|
33
|
+
matches the subprocess oracle by construction: the harness scans the JSON
|
|
34
|
+
document `generate()` serializes, the same document epubcheck --json emits
|
|
35
|
+
and the gate is calibrated on. The census answers for every input path: a
|
|
36
|
+
book the JVM cannot read arrives as the `-1,-1,-1` sentinel record instead of
|
|
37
|
+
being dropped (the scripts/ audit mode's silence is exactly why a missing-
|
|
38
|
+
rows warning was needed there), and a run that comes back short of the input
|
|
39
|
+
count refuses to write a partial census (exit 2).
|
|
40
|
+
|
|
41
|
+
The optional repair preview (default on; `--no-preview` skips) composes the
|
|
42
|
+
shipped library runner in-process, the `run phase1` pattern: a dry-run sweep
|
|
43
|
+
over the default flag set recording per-candidate status, before/after
|
|
44
|
+
counts, and the fix breakdown. It measures what `--apply` would write and
|
|
45
|
+
never writes. Artifacts are versioned (`bindery-observe-v1`); `--against
|
|
46
|
+
FILE` composes a trend block against a previous artifact of the same schema
|
|
47
|
+
(library deltas, error-mass delta, per-code book-count changes with
|
|
48
|
+
`new_codes`/`resolved_codes`), and a schema mismatch is a usage error rather
|
|
49
|
+
than a silently incomparable trend. The verb is strictly read-only: the only
|
|
50
|
+
file written is the artifact, and the writer refuses to land it inside the
|
|
51
|
+
scanned root (default output `observe-<timestamp>.observe` in the current
|
|
52
|
+
directory). Exit contract: 0 artifact written, 1 invocation problem, 2 census
|
|
53
|
+
harness failure.
|
|
54
|
+
|
|
55
|
+
### `.caltrash` is not library content
|
|
56
|
+
|
|
57
|
+
The same session's census found two trashed books walking the tree as repair
|
|
58
|
+
candidates. `iter_epubs` (the library sweep's walk) and the audit directory
|
|
59
|
+
walk now skip anything under `.caltrash`: a deletion pending Calibre's own
|
|
60
|
+
cleanup is never a repair candidate, and an `--apply` could in principle have
|
|
61
|
+
written into the trash.
|
|
62
|
+
|
|
3
63
|
## v0.52.0 (2026-10-21)
|
|
4
64
|
|
|
5
65
|
### The repairer's own prune could destroy the book it was repairing (issue #10)
|
|
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "bindery-cli"
|
|
7
|
-
version = "0.
|
|
7
|
+
version = "0.53.1"
|
|
8
8
|
description = "Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
classifiers = [
|
|
@@ -46,6 +46,7 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
|
|
|
46
46
|
| 0.50 | The contamination analyzer (issue #8): foreign-title template stamps, fan-bundle ad signatures, review-paste front matter; advisory by contract, archive-wide corpus (`Book.extra_docs`, capped), and the `_dir_dispatch` map that fixes the v0.44.0 cover/tocdrift ocr misroute in directory/single mode | v0.50.0 |
|
|
47
47
|
| 0.51 | The unbound-prefix repair (issue #9): `--fix-unbound-prefix` binds the Calibre embed scar's undeclared attribute prefix inline (evidence-based URI, scope-tracked, refuse over guess), plus the masked-ncx-gain rule that stops a real dtb:uid sync reading as no measurable gain under a fatal package | v0.51.0 |
|
|
48
48
|
| 0.52 | The spine guard (issue #10): the manifest prune reads the layout its hrefs are written in and derives its spine protection from the text it prunes (the raw-space wave's spine collapse), and `process_book` vetoes any candidate whose spine (itemref -> item -> archive) dangles more than the source's, above the counts and every promotion | v0.52.0 |
|
|
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 |
|
|
49
50
|
|
|
50
51
|
## Open work
|
|
51
52
|
|
|
@@ -572,6 +572,47 @@ the audit's trouble, so it takes the trouble slot), 2 for its own usage errors (
|
|
|
572
572
|
path that is not a directory, a directory with no EPUBs, an unknown book id) and
|
|
573
573
|
for tagging-setup failure.
|
|
574
574
|
|
|
575
|
+
## Observe subcommand (read-only census)
|
|
576
|
+
|
|
577
|
+
`bindery observe PATH [--output FILE] [--against FILE] [--workers N] [--limit N]
|
|
578
|
+
[--no-preview]` validates every EPUB under a tree in one warm-JVM pass and
|
|
579
|
+
writes one self-describing `.observe` artifact. It is the whole-library
|
|
580
|
+
answering of "where are we at": the census measures every book (clean ones
|
|
581
|
+
included) for epubcheck counts AND error codes together, tabulates the result
|
|
582
|
+
(library totals, a severity histogram with error-mass and per-count buckets,
|
|
583
|
+
the error-code profile as occurrences and distinct books, the worst offenders),
|
|
584
|
+
and records per-book census rows so any later question can be answered from
|
|
585
|
+
the artifact without re-validating.
|
|
586
|
+
|
|
587
|
+
The census harness embeds its Java like the FastDaemon does (JEP 330, no
|
|
588
|
+
javac, in-memory compile) and always answers for every input path: a book the
|
|
589
|
+
JVM cannot read arrives as the `-1,-1,-1` sentinel record rather than being
|
|
590
|
+
dropped, and a run that comes back short of the input count refuses to write
|
|
591
|
+
a partial census (exit 2). Counting matches the subprocess oracle by
|
|
592
|
+
construction: the harness scans the JSON document `generate()` serializes,
|
|
593
|
+
the same document the gate is calibrated on.
|
|
594
|
+
|
|
595
|
+
The optional repair preview (default on; `--no-preview` skips) composes the
|
|
596
|
+
shipped library runner in-process (`run phase1`'s pattern): a dry-run sweep
|
|
597
|
+
over the default flag set, recording per-candidate status, before/after
|
|
598
|
+
counts, and the fix breakdown. The preview measures what `--apply` would
|
|
599
|
+
write; it never writes. `--workers N` governs the preview's sweep pass; the
|
|
600
|
+
census is parallel inside its own JVM.
|
|
601
|
+
|
|
602
|
+
The artifact is versioned (`schema: bindery-observe-v1`) and strictly
|
|
603
|
+
read-only: the only file the verb writes is the artifact itself, and the
|
|
604
|
+
writer refuses to land it inside the scanned root (the keep-root-clean
|
|
605
|
+
rule; the default output is `observe-<timestamp>.observe` in the current
|
|
606
|
+
directory). `--against FILE` loads a previous artifact of the same schema and
|
|
607
|
+
carries a `trend` block: library-total deltas, error-mass delta, and per-code
|
|
608
|
+
book-count changes with `new_codes`/`resolved_codes`. A schema mismatch is a
|
|
609
|
+
usage error, never a silently incomparable trend. Exit codes: 0 artifact
|
|
610
|
+
written, 1 invocation problem (no EPUBs, toolchain missing, output inside
|
|
611
|
+
the scanned root, `--against` schema mismatch), 2 the census harness failed
|
|
612
|
+
mid-run. The library and audit walks skip `.caltrash` (trash is not library
|
|
613
|
+
content; the 2026-10-24 census found two trashed books walking the tree
|
|
614
|
+
before the guard).
|
|
615
|
+
|
|
575
616
|
## Run verbs (acquisition slices)
|
|
576
617
|
|
|
577
618
|
`bindery run phase1 DIR [--json FILE] [--apply-lossy] [--backup DIR] [--non-interactive]`
|
|
@@ -3,15 +3,15 @@
|
|
|
3
3
|
The repair side: an always-on core of five well-formedness fixes plus the NCX
|
|
4
4
|
pipeline and the mimetype fix, with the structural repairs, the four lossy
|
|
5
5
|
strips (page numbers, broken tags, watermarks, stub documents), and the safe opt-ins behind
|
|
6
|
-
explicit flags. Around it: the read-only `audit` verb (
|
|
7
|
-
structural analyzers), the `library` sweep with atomic in-place replacement in a Calibre
|
|
6
|
+
explicit flags. Around it: the read-only `audit` verb (nine body-text and
|
|
7
|
+
structural analyzers), the read-only `observe` census (one warm-JVM whole-library pass writing a versioned `.observe` artifact), the `library` sweep with atomic in-place replacement in a Calibre
|
|
8
8
|
library, the `run phase1`/`phase3` acquisition slices, and the Bindery Repair
|
|
9
9
|
Calibre plugin built from this core.
|
|
10
10
|
|
|
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.53.1"
|
|
15
15
|
__version__ = VERSION
|
|
16
16
|
|
|
17
17
|
from .epub import RepairReport, repair_epub # noqa: E402
|
|
@@ -3243,9 +3243,12 @@ def run_directory(
|
|
|
3243
3243
|
print(f"ERROR: {directory} is not a directory.")
|
|
3244
3244
|
return 2
|
|
3245
3245
|
# the is_file filter matches iter_epubs: a directory named *.epub is a
|
|
3246
|
-
# spurious scan error, not a book
|
|
3246
|
+
# spurious scan error, not a book; .caltrash is excluded for the same
|
|
3247
|
+
# reason it is excluded there (trash is not library content)
|
|
3247
3248
|
epubs = sorted(
|
|
3248
|
-
p
|
|
3249
|
+
p
|
|
3250
|
+
for p in directory.rglob("*.epub", case_sensitive=False)
|
|
3251
|
+
if p.is_file() and ".caltrash" not in p.parts
|
|
3249
3252
|
)
|
|
3250
3253
|
if not epubs:
|
|
3251
3254
|
print(f"No .epub files found under {directory}")
|
|
@@ -39,6 +39,7 @@ from .library import (
|
|
|
39
39
|
iter_epubs,
|
|
40
40
|
make_backup,
|
|
41
41
|
)
|
|
42
|
+
from .observe import run_observe
|
|
42
43
|
from .validate import (
|
|
43
44
|
CheckResult,
|
|
44
45
|
epubcheck_available,
|
|
@@ -2388,6 +2389,65 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
2388
2389
|
_add_repair_flags(lib)
|
|
2389
2390
|
lib.set_defaults(func=run_library)
|
|
2390
2391
|
|
|
2392
|
+
obs = sub.add_parser(
|
|
2393
|
+
"observe",
|
|
2394
|
+
help="read-only whole-library census: one versioned .observe artifact",
|
|
2395
|
+
usage="bindery observe [options] path",
|
|
2396
|
+
description="Validate every EPUB under a tree in one warm-JVM pass "
|
|
2397
|
+
"(epubcheck counts and error codes together), tabulate the census "
|
|
2398
|
+
"(severity histogram, dominant error-code classes, worst offenders), "
|
|
2399
|
+
"optionally compose the gated repair preview (what `bindery library "
|
|
2400
|
+
"--apply` would write: a dry-run over the default flag set), and "
|
|
2401
|
+
"write one self-describing .observe artifact for trend diffing with "
|
|
2402
|
+
"--against. Strictly read-only: the only file written is the "
|
|
2403
|
+
"artifact, and the writer refuses to land it inside the scanned "
|
|
2404
|
+
"root. Exit codes: 0 artifact written, 1 invocation problem (no "
|
|
2405
|
+
"EPUBs, toolchain missing, output inside the scanned root, --against "
|
|
2406
|
+
"schema mismatch), 2 the census harness failed mid-run.",
|
|
2407
|
+
epilog="examples:\n"
|
|
2408
|
+
" bindery observe ~/docs/Calibre\\ Library --output ~/observe/base.observe\n"
|
|
2409
|
+
" bindery observe ~/docs/Calibre\\ Library --output next.observe "
|
|
2410
|
+
"--against base.observe\n",
|
|
2411
|
+
formatter_class=argparse.RawDescriptionHelpFormatter,
|
|
2412
|
+
)
|
|
2413
|
+
obs.add_argument("path")
|
|
2414
|
+
og = obs.add_argument_group("output")
|
|
2415
|
+
og.add_argument(
|
|
2416
|
+
"--output",
|
|
2417
|
+
"-o",
|
|
2418
|
+
metavar="FILE",
|
|
2419
|
+
help="the .observe artifact path (default: observe-<timestamp>.observe "
|
|
2420
|
+
"in the current directory; refused inside the scanned root)",
|
|
2421
|
+
)
|
|
2422
|
+
og.add_argument(
|
|
2423
|
+
"--against",
|
|
2424
|
+
metavar="FILE",
|
|
2425
|
+
help="a previous .observe artifact: the new artifact carries a trend "
|
|
2426
|
+
"delta block (library totals, error mass, per-code changes)",
|
|
2427
|
+
)
|
|
2428
|
+
oc = obs.add_argument_group("run control")
|
|
2429
|
+
oc.add_argument(
|
|
2430
|
+
"--workers",
|
|
2431
|
+
type=int,
|
|
2432
|
+
default=1,
|
|
2433
|
+
metavar="N",
|
|
2434
|
+
help="concurrent epubcheck workers for the preview's sweep pass "
|
|
2435
|
+
"(default 1); the census pass is parallel inside its own JVM",
|
|
2436
|
+
)
|
|
2437
|
+
oc.add_argument(
|
|
2438
|
+
"--limit",
|
|
2439
|
+
type=int,
|
|
2440
|
+
metavar="N",
|
|
2441
|
+
help="validate at most N books (sampling)",
|
|
2442
|
+
)
|
|
2443
|
+
oc.add_argument(
|
|
2444
|
+
"--no-preview",
|
|
2445
|
+
action="store_true",
|
|
2446
|
+
help="skip the repair preview: census and tabulation only, a single "
|
|
2447
|
+
"validation pass",
|
|
2448
|
+
)
|
|
2449
|
+
obs.set_defaults(func=run_observe)
|
|
2450
|
+
|
|
2391
2451
|
run = sub.add_parser(
|
|
2392
2452
|
"run",
|
|
2393
2453
|
help="the acquisition run slices: phase-1 pre-import vetting, phase-3 "
|
|
@@ -20,9 +20,14 @@ from pathlib import Path
|
|
|
20
20
|
|
|
21
21
|
def iter_epubs(root: Path):
|
|
22
22
|
"""Yield every .epub under a Calibre library tree, sorted. Case-insensitive on the
|
|
23
|
-
suffix: Calibre emits lowercase, but a hand-added Book.EPUB should not be invisible.
|
|
23
|
+
suffix: Calibre emits lowercase, but a hand-added Book.EPUB should not be invisible.
|
|
24
|
+
Books inside .caltrash are deletions pending Calibre's own cleanup, never repair
|
|
25
|
+
candidates: the 2026-10-24 whole-library census found two of them walking the tree,
|
|
26
|
+
and an --apply could in principle have written into the trash."""
|
|
24
27
|
yield from sorted(
|
|
25
|
-
p
|
|
28
|
+
p
|
|
29
|
+
for p in root.rglob("*.epub", case_sensitive=False)
|
|
30
|
+
if p.is_file() and ".caltrash" not in p.parts
|
|
26
31
|
)
|
|
27
32
|
|
|
28
33
|
|