chore: add DOCUMENT::PDF module with PDF handling

[ziflex]

This pull request introduces a new read-only PDF document module for Ferret, registering it under the DOCUMENT::PDF namespace. The module allows Ferret scripts to open PDF files, access page collections, extract text, and retrieve positioned text fragments, all via a stable API that abstracts the underlying PDF parsing library. The implementation includes documentation, integration in the project workspace, core logic, and comprehensive capability tests.

The most important changes are:

Module Addition and Integration

• Added the document/pdf module to the project, including its registration in go.work and documentation in the main README.md. This makes PDF document handling available in Ferret scripts via DOCUMENT::PDF. [1] [2]

Documentation

• Created modules/document/pdf/README.md with installation, usage, API reference, examples, and notes on capabilities and limitations of the PDF module.

Core Implementation

• Implemented the core PDF document logic in modules/document/pdf/core/document.go, providing types and methods for opening PDFs, retrieving page and document properties, extracting text, and handling resource management with concurrency safety.
• Added a package doc comment in modules/document/pdf/core/doc.go to clarify the purpose and encapsulation of the core implementation.

Testing

• Added comprehensive capability tests in modules/document/pdf/core/capability_test.go to verify document and page property access, lazy iteration, error handling after document closure, and correct FQL runtime integration.

[Copilot]

Pull request overview

This PR adds a new optional Ferret contrib module, document/pdf, registering a read-only DOCUMENT::PDF namespace for opening PDFs via Ferret’s filesystem abstraction and extracting page/text information.

Changes:

• Introduces modules/document/pdf with a core implementation (document/page handles, buffering fallback, extraction) and a thin lib layer for Ferret function bindings.
• Adds module documentation and examples for DOCUMENT::PDF usage.
• Wires the new module into the workspace (go.work) and the runtime test harness registration list.

Reviewed changes

Copilot reviewed 30 out of 31 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/runtime/main.go	Registers the new document/pdf module in the runtime test harness.
README.md	Lists the new document/pdf module in the repo module table.
go.work	Adds ./modules/document/pdf to the workspace.
modules/document/pdf/README.md	Module documentation, API reference, and examples for DOCUMENT::PDF.
modules/document/pdf/options.go	Module registration options (buffer size policy).
modules/document/pdf/module.go	Module wiring and namespace registration.
modules/document/pdf/module_test.go	End-to-end FQL tests for the module API and error paths.
modules/document/pdf/doc.go	Package doc comment for the module.
modules/document/pdf/go.mod	New module dependencies and Go version.
modules/document/pdf/go.sum	Checksums for new module dependencies.
modules/document/pdf/test_helpers_test.go	Test helper to generate PDF fixtures for module-level tests.
modules/document/pdf/lib/doc.go	Package doc comment for Ferret binding layer.
modules/document/pdf/lib/lib.go	Registers DOCUMENT::PDF functions into the runtime namespace.
modules/document/pdf/lib/lib_test.go	Verifies the expected function names are registered (and no aliases).
modules/document/pdf/lib/open.go	Ferret binding for OPEN using configured open options.
modules/document/pdf/lib/page.go	Ferret bindings for PAGE_INFO and BLOCKS.
modules/document/pdf/lib/document.go	Ferret bindings for PAGE_COUNT, PAGES, PAGE, TEXT, CLOSE.
modules/document/pdf/lib/require.go	Shared runtime argument validation helpers for bindings.
modules/document/pdf/core/doc.go	Package doc comment describing the core implementation boundary.
modules/document/pdf/core/document.go	Document handle implementation, open/close, page access, text extraction.
modules/document/pdf/core/document_test.go	Core behavior tests (open, buffering fallback, cancellation, isolation, etc.).
modules/document/pdf/core/errors.go	Standardized operation-scoped error wrapping/helpers.
modules/document/pdf/core/extractor.go	Protected page content extraction with panic recovery.
modules/document/pdf/core/options.go	OpenOptions and normalization for buffering limits.
modules/document/pdf/core/page.go	Page handle implementation: text, info, positioned blocks.
modules/document/pdf/core/page_info.go	Page box/rotation extraction and normalization logic.
modules/document/pdf/core/resource.go	Resource ID generator wiring for runtime identity/hashing.
modules/document/pdf/core/source.go	Opens PDF sources via Ferret FS, using random-access or buffering fallback.
modules/document/pdf/core/source_buffer.go	Implements in-memory buffering with limit enforcement.
modules/document/pdf/core/test_helpers_test.go	Core test helpers including in-memory FS stubs and PDF fixture generation.
modules/document/pdf/core/types.go	Public core types for page info and positioned text fragments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 33 out of 34 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 33 out of 34 changed files in this pull request and generated no new comments.