chore: add DOCUMENT::XLSX

[ziflex]

This pull request introduces a new Excel-compatible .xlsx module for Ferret, providing workbook and worksheet helpers under the DOCUMENT::XLSX namespace. It includes documentation, integration into the project, and core implementation files for workbook lifecycle, worksheet operations, querying, range handling, and error management.

Project integration and documentation:

• Added the new document/xlsx module to go.work and documented it in the main README.md, including a comprehensive module-specific README.md with usage instructions, function reference, and examples. [1] [2] [3]

Core implementation for .xlsx support:

• Implemented core logic for workbook/worksheet management, including file I/O with Ferret's filesystem, range parsing, matrix validation, query options, error handling, and resource ID generation. [1] [2] [3] [4] [5] [6] [7] [8]

Testing:

• Added tests for worksheet querying, including header normalization, row trimming, and validation of query options.

[Copilot]

Pull request overview

This pull request adds a new Ferret contrib module at modules/document/xlsx that exposes Excel-compatible .xlsx workbook and worksheet helpers under the DOCUMENT::XLSX namespace, including Ferret runtime integration plus module and usage documentation.

Changes:

• Introduces the new document/xlsx module with core workbook/worksheet implementation and a thin lib Ferret-function bridge.
• Adds documentation and examples for the new namespace, and wires the module into the workspace (go.work) and module index (README.md).
• Adds Go tests and FQL workflows covering workbook lifecycle, querying behavior, and error handling.

Reviewed changes

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

Show a summary per file

File	Description
tests/runtime/main.go	Registers the new module in the runtime test binary.
tests/modules/document/xlsx/workflow.fql	Adds a happy-path FQL workflow test for range IO + querying.
tests/modules/document/xlsx/errors.fql	Adds FQL coverage for deleted-sheet and closed-workbook errors.
README.md	Lists the new document/xlsx module in the repo module index.
go.work	Adds ./modules/document/xlsx to the Go workspace.
modules/document/xlsx/README.md	Adds module-level documentation, API reference, and examples.
modules/document/xlsx/module.go	Implements module registration under DOCUMENT::XLSX.
modules/document/xlsx/module_test.go	Adds module-level smoke and integration tests via ferret.New(...).
modules/document/xlsx/doc.go	Adds package documentation for the module.
modules/document/xlsx/examples/filter_active_sales.fql	Adds an end-to-end example workflow for querying/filtering.
modules/document/xlsx/go.mod	Defines the new module and its dependencies (notably excelize).
modules/document/xlsx/go.sum	Locks the dependency graph for the new module.
modules/document/xlsx/lib/doc.go	Documents the purpose of the Ferret bridge package.
modules/document/xlsx/lib/lib.go	Registers DOCUMENT::XLSX::* functions in the namespace.
modules/document/xlsx/lib/lib_test.go	Verifies the namespace function registry.
modules/document/xlsx/lib/require.go	Adds runtime argument/type guards for workbook/worksheet handles.
modules/document/xlsx/lib/workbook.go	Implements Ferret-facing workbook operations (open/save/sheet ops).
modules/document/xlsx/lib/worksheet.go	Implements Ferret-facing worksheet operations (get/set/range/write/append).
modules/document/xlsx/core/doc.go	Documents the core implementation package.
modules/document/xlsx/core/errors.go	Defines core error values and operation error wrapping.
modules/document/xlsx/core/filesystem.go	Implements Ferret filesystem-backed open/save helpers.
modules/document/xlsx/core/matrix.go	Implements matrix decoding/validation for range writes and appends.
modules/document/xlsx/core/query_options.go	Implements query WITH decoding and header normalization.
modules/document/xlsx/core/query_test.go	Adds tests for worksheet querying, headers, trimming, and validation.
modules/document/xlsx/core/range.go	Implements A1 cell/range parsing and validation helpers.
modules/document/xlsx/core/resource.go	Adds resource ID generation for workbook/worksheet handles.
modules/document/xlsx/core/sheet_validation.go	Adds worksheet name validation.
modules/document/xlsx/core/test_helpers_test.go	Adds shared test helpers (value assertions, FS context setup).
modules/document/xlsx/core/values.go	Implements scalar value conversion to/from Excel cells.
modules/document/xlsx/core/workbook.go	Implements workbook lifecycle, sheet management, and persistence.
modules/document/xlsx/core/workbook_test.go	Adds workbook lifecycle, persistence, and FS policy tests.
modules/document/xlsx/core/worksheet.go	Implements worksheet cell/range IO, append, and queryable behavior.
modules/document/xlsx/core/worksheet_test.go	Adds worksheet IO, conversion, validation, and append tests.

---

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