Harden parser boundaries and Python packaging

[Lulzx]

What changed

• make CLI argument and page-range handling strict, memory-safe, and automation-friendly
• add explicit C/Python extraction error reporting and consistent invalid-page behavior
• clean up failed document construction paths
• cap decompression while streaming, validate predictor parameters, and free LZW dictionary allocations
• build platform-correct Python wheels from the current Zig library and prevent stale-library test loading
• expand CI and regression coverage for Zig modes, Python versions, malformed PDFs, JSON output, and packaging

Why

The robustness audit found an invalid-free in mixed page ranges, successful exit codes on failures, ambiguous FFI errors, incomplete constructor cleanup, stale native-library loading, and decompression paths that could exceed intended memory limits.

Validation

• Zig tests in Debug and ReleaseSafe
• native, WASM, and ReleaseFast builds
• 211 Python tests passed; 1 optional memory test skipped by the commit hook
• memory guard passed separately
• all 88 malformed corpus PDFs completed without crashes or invalid JSON
• platform wheel built, installed in isolation, and extracted the generated fixture successfully

Summary by CodeRabbit

• New Features

  • Added platform-specific Python wheel building with bundled native libraries.
  • Added explicit native error reporting and improved Python exception handling.
  • Added stricter CLI validation and page-range support.
  • Added decompression size limits and predictor validation.

• Bug Fixes

  • Improved cleanup for failed document loading and decompression operations.
  • Prevented invalid page and extraction requests from failing silently.

• Documentation

  • Added wheel installation and native library configuration guidance.

• Tests

  • Expanded CI coverage across Zig and Python versions, CLI behavior, native errors, and wheel installation.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: d76665c2-f54b-4802-b84d-82d94c9b06e8

📥 Commits

Reviewing files that changed from the base of the PR and between 6a11bba and c677f1c.

📒 Files selected for processing (21)

• .github/workflows/ci.yml
• .gitignore
• README.md
• build.zig
• gen_test.zig
• python/README.md
• python/pyproject.toml
• python/setup.py
• python/tests/test_cli_robustness.py
• python/tests/test_memory_regression.py
• python/tests/test_zpdf.py
• python/zpdf/__init__.py
• python/zpdf/_cdef.h
• python/zpdf/_ffi.py
• src/capi.zig
• src/cff.zig
• src/cff_std_strings.zig
• src/decompress.zig
• src/main.zig
• src/markdown.zig
• src/root.zig

---

📝 Walkthrough

Walkthrough

The PR adds native error propagation, stricter CLI and decompression validation, document cleanup on constructor failures, Python wheel packaging, CI coverage, and Zig source formatting updates.

Changes

ZPDF validation and distribution

Layer / File(s)	Summary
Native error reporting and Python exception mapping src/capi.zig, python/zpdf/__init__.py, python/zpdf/_cdef.h, python/tests/test_zpdf.py	Native extraction APIs report thread-local errors. Python bindings map errors to exceptions and validate page arguments.
CLI validation and error propagation src/main.zig, build.zig, gen_test.zig, python/tests/test_cli_robustness.py, python/tests/test_memory_regression.py	CLI commands reject invalid arguments and propagate document, extraction, output, and page-range failures.
Bounded decompression and predictor validation src/decompress.zig	Flate, LZW, and RunLength decoding enforce output limits and release temporary allocations. Predictor validation uses checked arithmetic and supported dimensions and bit depths.
Document constructor cleanup src/root.zig	Constructors release owned memory and close initialized documents when allocation or parsing fails.
Python wheels and CI verification python/setup.py, python/pyproject.toml, python/zpdf/_ffi.py, python/README.md, README.md, .github/workflows/ci.yml, .gitignore	The build creates platform-specific wheels with the native library. CI builds and installs wheels across Python versions.
Zig source formatting normalization src/cff.zig, src/cff_std_strings.zig, src/markdown.zig	Parser, standard-string, and Markdown code formatting changed without reported behavior changes.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant PythonZpdf
  participant NativeExtraction
  participant zpdf_last_error
  Caller->>PythonZpdf: Call extraction or page helper
  PythonZpdf->>NativeExtraction: Invoke native API
  NativeExtraction->>zpdf_last_error: Set thread-local status
  zpdf_last_error-->>PythonZpdf: Return error code
  PythonZpdf-->>Caller: Return value or mapped exception

Loading

sequenceDiagram
  participant PythonBuild
  participant Zig
  participant Wheel
  participant IsolatedVenv
  PythonBuild->>Zig: Locate or build zpdf shared library
  Zig-->>PythonBuild: Return native library
  PythonBuild->>Wheel: Copy library into zpdf package
  Wheel-->>IsolatedVenv: Install platform wheel
  IsolatedVenv->>Wheel: Import packaged zpdf library

Loading

Possibly related PRs

• Lulzx/zpdf#5: Shares extraction and error-handling areas in src/root.zig and python/tests/test_zpdf.py.
• Lulzx/zpdf#6: Shares core parsing and Markdown extraction areas.
• Lulzx/zpdf#8: Relates to compat.MainWithArgs and Zig 0.16.0 compatibility.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/robustness-hardening

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}