djvu-rs 0.28.0__tar.gz

djvu_rs-0.28.0/.codex/config.toml

@@ -0,0 +1,8 @@
+[shell_environment_policy]
+inherit = "core"
+
+[shell_environment_policy.set]
+CLAUDE_CODE_DISABLE_1M_CONTEXT = "1"
+CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING = "1"
+CLAUDE_CODE_DISABLE_AUTO_MEMORY = "1"
+CLAUDE_CODE_SUBAGENT_MODEL = "sonnet"

djvu_rs-0.28.0/.config/nextest.toml

@@ -0,0 +1,16 @@
+# cargo-nextest configuration
+# https://nexte.st/docs/configuration
+
+[profile.default]
+# Mark tests that run longer than 60 s as "slow" (informational only)
+slow-timeout = "60s"
+
+[profile.ci]
+slow-timeout = "60s"
+# Retry flaky tests once before failing
+retries = 1
+
+# PDF export and large IW44 decode tests are legitimately slow — allow up to 5 min
+[[profile.ci.overrides]]
+filter = 'binary(pdf_conversion) or test(iw44_new_decode_big)'
+slow-timeout = "120s"

djvu_rs-0.28.0/.githooks/pre-commit

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Pre-commit checks — mirrors the CI lint/build steps.
+# Install once: git config core.hooksPath .githooks
+set -euo pipefail
+
+echo "→ cargo fmt --check"
+cargo fmt --check
+
+echo "→ cargo clippy"
+cargo clippy --quiet -- -D warnings
+
+echo "→ no_std build"
+cargo build --no-default-features --quiet
+
+echo "✓ pre-commit passed"

djvu_rs-0.28.0/.githooks/pre-push

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Mirror of the deterministic CI gates; blocks a push that would red the CI.
+# Enable once: make hooks   (sets core.hooksPath=.githooks)
+# Bypass once: git push --no-verify
+exec "$(git rev-parse --show-toplevel)/scripts/check.sh"

djvu_rs-0.28.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug report
+about: Something panics, returns wrong output, or fails to compile
+labels: bug
+---
+
+## Environment
+
+- djvu-rs version:
+- Rust version (`rustc --version`):
+- OS:
+
+## What happened
+
+<!-- Describe what went wrong. -->
+
+## Reproducer
+
+<!-- Paste a minimal failing test, or attach the DjVu file if it can be shared publicly. -->
+
+```rust
+#[test]
+fn repro() {
+    // ...
+}
+```
+
+## Expected behavior
+
+## Actual behavior / error output
+
+```
+// paste panic message, error, or wrong output here
+```

djvu_rs-0.28.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,29 @@
+---
+name: Feature request
+about: Propose a new codec, API, or CLI subcommand
+labels: enhancement
+---
+
+## Summary
+
+<!-- One sentence: what do you want added? -->
+
+## Motivation
+
+<!-- What problem does this solve? Who needs it? -->
+
+## Proposed API / CLI
+
+<!-- Show a code snippet or CLI invocation of how it would look. -->
+
+```rust
+// example
+```
+
+## Alternatives considered
+
+<!-- Any other approaches you thought about? -->
+
+## Spec reference
+
+<!-- If this is a codec feature, link to the relevant DjVu v3 spec section. -->

djvu_rs-0.28.0/.github/pull_request_template.md

@@ -0,0 +1,21 @@
+## Summary
+
+<!-- What does this PR do? One paragraph is enough. -->
+
+## Checklist
+
+- [ ] `cargo fmt --check` passes
+- [ ] `cargo clippy -- -D warnings` passes
+- [ ] `cargo test` passes (unit + integration + doctests)
+- [ ] `cargo build --no-default-features` passes (no_std check)
+- [ ] New public items have `///` doc comments
+- [ ] Tests added for new behavior
+- [ ] No `unwrap()` / `expect()` / `panic!` in library code
+
+## Performance impact
+
+<!-- If the change touches a codec or render path, paste before/after `cargo bench` numbers. -->
+
+## Related issue
+
+<!-- Closes #N -->

djvu_rs-0.28.0/.github/workflows/api-stability.yml

@@ -0,0 +1,170 @@
+name: API stability
+
+# Enforces the compatibility contract in docs/api-compatibility.md (#695):
+#   - unintended breakage of the stable public API surface (cargo-semver-checks)
+#   - the documented feature combinations and targets all build
+#   - the Send/Sync + panic-free contracts hold under the async feature
+#
+# These are kept in a dedicated workflow (not ci.yml) so the API-policy gates
+# evolve independently of the core fmt/clippy/test pipeline.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: 1
+
+jobs:
+  # ── Public API breakage detection (AC2) ──────────────────────────────────────
+  # Compares the PR against the latest version published on crates.io. For a
+  # 0.x crate, cargo-semver-checks treats a MINOR bump as the breaking axis, so
+  # this fails only on an *unintended* break of the stable surface that was not
+  # accompanied by the required version bump.
+  semver:
+    name: Public API breakage (cargo-semver-checks)
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    # TODO(#695): non-blocking until the next crates.io release resets the
+    # baseline. cargo-semver-checks compares against the last published release
+    # (currently v0.27.0); the error enums DocError / DjvmError / SmmrError
+    # gained variants (and SmmrError's implicit discriminants shifted) in the
+    # already-merged #696 work, so the gate reports pre-existing, intended
+    # breakage that no change on this PR can clear. Flip this back to a hard
+    # failure (delete continue-on-error) once a release has shipped and/or the
+    # error enums are marked #[non_exhaustive] per docs/api-compatibility.md §1
+    # ("Error stability rule").
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+        with:
+          key: semver-checks
+
+      - name: cargo-semver-checks (stable public API)
+        uses: obi1kenobi/cargo-semver-checks-action@v2
+        with:
+          # Default features = the decode-only `std` stable surface. Writer /
+          # async / experimental surfaces are checked as they stabilize.
+          feature-group: default-features
+          package: djvu-rs
+
+  # ── Documented feature combinations & targets (AC3) ──────────────────────────
+  # The human-readable companion is docs/feature-matrix.md; keep the two in sync.
+  feature-matrix:
+    name: Feature matrix (${{ matrix.name }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: "no_std (host)"
+            flags: "--no-default-features"
+          - name: "default (std, decode-only)"
+            flags: ""
+          - name: "jpeg"
+            flags: "--features std,jpeg"
+          - name: "pdf"
+            flags: "--features pdf"
+          - name: "epub"
+            flags: "--features epub"
+          - name: "cbz"
+            flags: "--features cbz"
+          - name: "tiff"
+            flags: "--features tiff"
+          - name: "cli"
+            flags: "--features cli"
+          - name: "async"
+            flags: "--features async"
+          - name: "parallel"
+            flags: "--features parallel"
+          - name: "mmap"
+            flags: "--features mmap"
+          - name: "serde"
+            flags: "--features serde"
+          - name: "image"
+            flags: "--features image"
+          - name: "kitchen-sink"
+            flags: "--features cli,tiff,async,serde,image,epub,mmap,parallel"
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+        with:
+          key: feature-matrix
+
+      - name: cargo check ${{ matrix.flags }}
+        run: cargo check ${{ matrix.flags }}
+
+  # ── wasm32 documented feature set (AC3) ──────────────────────────────────────
+  feature-matrix-wasm:
+    name: Feature matrix (wasm32 ${{ matrix.name }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: "no_std"
+            flags: "--no-default-features"
+          - name: "wasm"
+            flags: "--features wasm"
+          - name: "wasm-lazy"
+            flags: "--features wasm-lazy"
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install Rust stable + wasm32 target
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-unknown-unknown
+
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+        with:
+          key: feature-matrix-wasm
+
+      - name: cargo check --target wasm32-unknown-unknown ${{ matrix.flags }}
+        run: cargo check --target wasm32-unknown-unknown ${{ matrix.flags }}
+
+  # ── Contract tests under the async feature (AC7 + AC8) ───────────────────────
+  # The default Test (stable) job runs without `async`, so the Send/Sync
+  # assertions for LazyDocument and the async panic-free surface are only
+  # exercised here.
+  contract-tests:
+    name: Send/Sync + panic-free contracts (async)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+        with:
+          key: contract-tests
+
+      - name: Send/Sync contract
+        run: cargo test --test send_sync_contract --features async
+
+      - name: Panic-free corpus + adversarial inputs
+        run: cargo test --test panic_free_corpus --features cli

djvu_rs-0.28.0/.github/workflows/bench-dashboard.yml

@@ -0,0 +1,110 @@
+name: Benchmark dashboard
+
+# Publishes Criterion benchmark history to a public dashboard on the gh-pages
+# branch via benchmark-action/github-action-benchmark. Runs only on main-branch
+# pushes that touch source/benches and on release tags, so PR runs in
+# bench.yml stay fast and the public timeline only records merged commits.
+#
+# Output: https://matyushkin.github.io/djvu-rs/dev/bench/
+#
+# See #197 for design rationale.
+
+on:
+  push:
+    branches: [main]
+    tags:
+      - 'v*'
+    paths:
+      - 'src/**'
+      - 'benches/**'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
+  workflow_dispatch:
+
+permissions:
+  contents: write          # push to gh-pages
+  deployments: write       # github-action-benchmark stores deployment markers
+
+concurrency:
+  group: bench-dashboard
+  cancel-in-progress: false  # don't drop history points
+
+env:
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: 1
+
+jobs:
+  publish:
+    name: Publish dashboard
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+        with:
+          key: bench-dashboard-ubuntu
+
+      # ── Run all Criterion benchmarks in bencher format ───────────────────
+      # github-action-benchmark consumes the `bencher` (libtest) format.
+      - name: Bench codecs
+        run: cargo bench --bench codecs -- --output-format bencher 2>&1 | tee bench_output.txt
+
+      - name: Bench render
+        run: cargo bench --bench render --features pdf -- --output-format bencher 2>&1 | tee -a bench_output.txt
+
+      - name: Bench document
+        run: cargo bench --bench document -- --output-format bencher 2>&1 | tee -a bench_output.txt
+
+      # ── DjVuLibre baseline (overlay on the same dashboard) ───────────────
+      # Compiles libdjvulibre's render benchmark and emits one bencher line
+      # per DPI so github-action-benchmark plots a parallel timeline next to
+      # djvu-rs's render_page series. This satisfies the "DjVuLibre ratio
+      # overlay" item of #197's DoD. The asset (colorbook.djvu) is checked
+      # into references/djvujs/ so no fetch step is needed.
+      - name: Run DjVuLibre render benchmark
+        id: djvulibre
+        continue-on-error: true
+        run: |
+          mkdir -p target/djvulibre-bench
+          bash scripts/bench_djvulibre.sh target/djvulibre-bench
+          # Parse render_only lines from djvulibre_bench.txt → one bencher line
+          # per case.  Extract the target DPI from the preceding "size" line so
+          # each case gets a unique name (djvulibre_render_dpi_72 etc.) that
+          # aligns with the Criterion render_page/dpi/* series.
+          python3 - <<'PYEOF' >> bench_output.txt
+          import re, pathlib
+          txt = pathlib.Path("target/djvulibre-bench/djvulibre_bench.txt").read_text()
+          current_dpi = None
+          for line in txt.splitlines():
+              m_size = re.search(r"->(\d+)dpi", line)
+              if m_size:
+                  current_dpi = int(m_size.group(1))
+                  continue
+              m_render = re.match(r"render_only\s*:\s*([\d.]+)\s*ms", line)
+              if m_render and current_dpi is not None:
+                  ns = int(float(m_render.group(1)) * 1_000_000)
+                  print(f"test djvulibre_render_dpi_{current_dpi} ... bench: {ns} ns/iter (+/- 0)")
+          PYEOF
+
+      # ── Publish history + dashboard to gh-pages ─────────────────────────
+      - name: Push to gh-pages dashboard
+        uses: benchmark-action/github-action-benchmark@v1
+        with:
+          name: djvu-rs benchmarks
+          tool: 'cargo'
+          output-file-path: bench_output.txt
+          # Persist on the gh-pages branch under dev/bench/ → published page.
+          gh-pages-branch: gh-pages
+          benchmark-data-dir-path: dev/bench
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          auto-push: true
+          # 10 % regression alert on any benchmark; comment on the commit that
+          # introduced it (see #197 DoD).
+          alert-threshold: '110%'
+          fail-on-alert: false
+          comment-on-alert: true
+          alert-comment-cc-users: '@matyushkin'