feat: scope page ranges to match and fields

[pjkersten]

Templates for envelope-style PDFs need to match identifying text on one page while extracting invoice fields and line items from other pages.

This adds an explicit match: selector with its own pages, keywords, and exclude_keywords, plus field-local pages support for modern fields: parsers, including fields.lines.

• match.pages scopes only template selection.
• fields.<name>.pages scopes only that field's input text.
• A field's area intersects its own page scope.
• Legacy top-level pages remains supported as a homogeneous-template compatibility shortcut.
• Mixing the explicit selector with legacy keywords, exclude_keywords, or pages is rejected to avoid ambiguous scope.

Documentation includes an envelope + invoice recipe. Regression coverage tests matching on page 1, scalar extraction from pages 1 and 2–3, and modern lines extraction from pages 2–3.

Tests: pytest — 1198 passed, 6 skipped.

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
src/invoice2data
api.py
src/invoice2data/extract
invoice_template.py
loader.py					226-230, 239-243, 249
tests
test_page_ranges.py
Project Total

This report was generated by python-coverage-comment-action