[hallelx2]

Rewrites the README to show how pdfgrab works, end to end:

• content streams and operators, text state and font metrics, encodings and ToUnicode;
• chars to words to lines, and viewer space;
• the lines/text/explicit table strategies, the 0.008 pt clipped-paren bug and its fix, and the hybrid with MergeSplitTokens off;
• benchmarks (ICDAR 2013 per-document F1 0.442, the field comparison, the 0.935 grid-from-ground-truth ceiling labelled as a ceiling, and the negative results);
• agreement with pdfplumber, labelled as agreement rather than ground truth;
• limits, the API, the CLI, versions with the honest @main install line (HAL-2690), and layout.

There are 11 figures. Several originals contradicted the reports and were corrected before use: unmeasured drift rows, pooled metrics shown as per-document, and two claims that are no longer true.

Also:

• Lorx CI (.lorx/actions/ci.yml);
• 20 golangci-lint findings cleared (Close errors surfaced, CLI write errors returned, dead code removed);
• an empty encryption branch replaced by fixtures and TestEncryptedDocuments, measured with qpdf.

The concurrent-parse data race is noted in Limits and tracked in HAL-118.

Lorx: bit run --all green locally and cloud run #1 passed. Rendered on github.com with 17 images and none broken (GitHub Actions can't start jobs, HAL-1712).

Part of HAL-2755. No-Linear-Issue: HAL-2755 closes with the control plane README.

Summary by Sourcery

Document pdfgrab end to end, formalize containerized CI, and tighten error handling and encrypted-document coverage.

New Features:

• Rewrite the README as an end-to-end guide to pdfgrab’s PDF interpretation, text extraction, coordinate handling, table strategies, benchmarks, API, CLI, limitations, and usage.
• Add Lorx containerized CI covering formatting, vetting, builds, linting, and race-enabled tests.
• Add encrypted-PDF fixtures and regression coverage for owner-password and user-password behavior.

Bug Fixes:

• Preserve CLI output and document-close errors instead of silently discarding write or cleanup failures.
• Document and validate the table edge handling that preserves clipped outer-edge characters such as negative-number parentheses.
• Correct text filtering and remove obsolete helper and dead code identified by linting.

Enhancements:

• Improve the README’s benchmark and compatibility reporting with corrected metrics, caveats, comparisons, figures, and version guidance.
• Clarify PDF font, encoding, coordinate-space, text-grouping, and table-extraction behavior, including known limitations and concurrency constraints.

CI:

• Add Lorx CI as the merge gate because GitHub Actions cannot start jobs in this repository.

Documentation:

• Replace the README with a comprehensive user-facing showcase covering installation, examples, architecture, API, CLI, benchmarks, pdfplumber agreement, limitations, repository layout, and project status.

Tests:

• Add encrypted-document regression tests and qpdf fixture generation.
• Ensure tests report document-close failures rather than ignoring them.

Chores:

• Resolve golangci-lint findings across the codebase.

[sourcery-ai]

Sorry @hallelx2, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 1 day and 1 hour by commenting @sourcery-ai review. Upgrade to get a review now.

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 50e41cab-1dd9-4c5e-aac0-8554e60de0aa

---

📥 Commits

Reviewing files that changed from the base of the PR and between aaec2bb and 9a835a1.

---

⛔ Files ignored due to path filters (13)

• docs/media/advance-drift.png is excluded by !**/*.png
• docs/media/banner.png is excluded by !**/*.png
• docs/media/benchmarks.png is excluded by !**/*.png
• docs/media/citation-needs-coordinates.png is excluded by !**/*.png
• docs/media/clipped-paren.png is excluded by !**/*.png
• docs/media/encoding-chain.png is excluded by !**/*.png
• docs/media/go-ecosystem.png is excluded by !**/*.png
• docs/media/hybrid-architecture.png is excluded by !**/*.png
• docs/media/oracle-gap.png is excluded by !**/*.png
• docs/media/pdf-anatomy.png is excluded by !**/*.png
• docs/media/table-strategies.png is excluded by !**/*.png
• testdata/encrypted/owner-password-only.pdf is excluded by !**/*.pdf
• testdata/encrypted/user-password.pdf is excluded by !**/*.pdf

---

📒 Files selected for processing (24)

• .lorx/actions/ci.yml
• README.md
• clustering.go
• cmd/pdfgrab/main.go
• detect_textedge_test.go
• encrypted_test.go
• examples/extract_tables/main.go
• finder.go
• fonts_fixture_test.go
• golden_test.go
• internal/pdf/cmap.go
• internal/pdf/font.go
• internal/pdf/reader.go
• page.go
• page_test.go
• pdftable_test.go
• scripts/gen_encrypted_fixtures.sh
• spacing_regression_test.go
• table_test.go
• testhelpers_ext_test.go
• testhelpers_test.go
• text.go
• text_test.go
• viewport_test.go

---

 _________________________________________________________________________________________
< If you don't make mistakes, you're not working on hard enough problems. - Frank Wilczek >
 -----------------------------------------------------------------------------------------
  \
   \   \
        \ /\
        ( )
      .( o ).

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

---

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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.}

[sourcery-ai]

Reviewer's Guide

This PR substantially rewrites the README as a technically candid, figure-rich guide to pdfgrab’s implementation, API, table behavior, measurements, and limitations; it also adds Lorx container CI, fixes lint/resource/output error handling, and formalizes encrypted-PDF behavior with qpdf fixtures and tests.

Sequence diagram for CLI extraction with propagated output errors

sequenceDiagram
    participant User
    participant CLI
    participant Document
    participant Writer

    User->>CLI: run(args, stdout, stderr)
    CLI->>Document: OpenFile(path)
    Document-->>CLI: Document
    CLI->>Document: Page(n)
    CLI->>Document: ExtractTables(settings)
    CLI->>Writer: emit table or text output
    Writer-->>CLI: write error or success
    CLI->>Document: Close()
    Document-->>CLI: close error or success
    CLI-->>User: return first relevant error

Loading

State diagram for encrypted PDF handling

stateDiagram-v2
    [*] --> ReadContext
    ReadContext --> OwnerOnly: empty password succeeds
    ReadContext --> NeedsPassword: user password required
    OwnerOnly --> ParsePages
    ParsePages --> OpenDocument
    NeedsPassword --> ErrEncrypted
    OpenDocument --> [*]
    ErrEncrypted --> [*]

Loading

Flow diagram for pdfgrab table extraction strategies

flowchart TD
    Input[PDF page primitives and words] --> Strategy{Table strategy}
    Strategy --> Lines[lines or lines_strict: ruling edges]
    Strategy --> Text[ text: word alignment edges]
    Strategy --> Explicit[explicit: caller-supplied grid]
    Strategy --> Auto[auto: choose ruled or text axis]
    Lines --> Geometry[Edges intersections cells]
    Text --> Geometry
    Explicit --> Geometry
    Auto --> Geometry
    Geometry --> Extract[ExtractTables]
    Extract --> Output[Rows and CellsBBox]

Loading

File-Level Changes

Change	Details	Files
Reworked the README into an end-to-end technical and user-facing guide for pdfgrab.	Explains PDF interpretation, text state, font metrics, encodings, ToUnicode, text grouping, coordinate conversion, and table extraction. Documents table strategies, hybrid explicit-grid usage, the clipped-parenthesis fix, benchmarks, negative results, pdfplumber agreement, limitations, API, CLI, versions, and repository layout. Adds 11 documented figures and corrects metric caveats, pooled versus per-document results, ceiling claims, and agreement-versus-ground-truth wording.	README.md
Added containerized Lorx CI as the repository merge gate.	Runs formatting, vetting, build, lint, and race-enabled tests with staged dependencies and timeouts. Uses Go 1.25 and golangci-lint v2.14.0 containers with GOFLAGS=-buildvcs=false.	.lorx/actions/ci.yml
Resolved lint findings and made resource and output errors observable.	Propagates CLI help, version, output, and document-close errors, including deferred close failures. Reports close failures in examples and tests through shared helpers. Removes unused helpers and simplifies minor code flagged by lint.	cmd/pdfgrab/main.go examples/extract_tables/main.go clustering.go finder.go internal/pdf/cmap.go internal/pdf/font.go page.go text.go detect_textedge_test.go fonts_fixture_test.go golden_test.go page_test.go pdftable_test.go spacing_regression_test.go table_test.go text_test.go viewport_test.go testhelpers_ext_test.go testhelpers_test.go
Replaced the empty encryption handling branch with fixture-backed behavior tests.	Adds qpdf-generated owner-password-only and user-password-required AES-256 fixtures. Verifies owner-password-only documents open and user-password documents return ErrEncrypted. Documents that pdfcpu performs the empty-password decryption and the public layer surfaces failures.	internal/pdf/reader.go encrypted_test.go scripts/gen_encrypted_fixtures.sh testdata/encrypted/owner-password-only.pdf testdata/encrypted/user-password.pdf

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.