fix: guard None offset and empty page-range in TOC processing

[voidborne-d]

Summary

Two related bugs in the TOC-with-page-numbers processing pipeline that cause silent failures or hard crashes when indexing certain PDFs.

---

Bug 1 — TypeError crash when page-offset is None

Function: add_page_offset_to_toc_json
Triggered by: calculate_page_offset() returning None (no title/page pairs matched)

calculate_page_offset() explicitly returns None when it cannot find any matching (title, page-number, physical-index) pairs — which happens when:

• The TOC page numbers do not correspond to any of the first toc_check_page_num pages, or
• The document has an unconventional layout where TOC page numbers and physical positions are mismatched.

add_page_offset_to_toc_json() then tried:

data[i]['physical_index'] = data[i]['page'] + offset  # offset is None → TypeError

Fix: Add an early-return guard — when offset is None, return data unchanged and let process_none_page_numbers handle the unresolved items:

def add_page_offset_to_toc_json(data, offset):
    if offset is None:
        return data
    ...

---

Bug 2 — Empty LLM context for last (and first) TOC item

Function: process_none_page_numbers
Triggered by: The last TOC entry lacking a physical_index

The function computes a page search window range(prev_physical_index, next_physical_index + 1):

• next_physical_index defaulted to -1 ("no next item"), so range(prev, 0) is always empty for any prev > 0.
• prev_physical_index defaulted to 0, producing list_index = 0 - start_index = -1, which the bounds check silently skips (page 1 excluded).

With an empty window, page_contents = [] → the LLM receives an empty string → it cannot locate the section → the last TOC entry is permanently unresolved.

Fix:

• next_physical_index default → end_index = len(page_list) + start_index - 1 (last page of document)
• prev_physical_index default → start_index (first valid page index, not 0)

---

Tests added (17, all passing)

TestAddPageOffsetToTocJson (11 tests)

• None offset returns data unchanged, no crash
• Integer / zero / negative offsets work correctly
• Items without page key are untouched
• Pipeline simulation: empty pairs → None offset → no crash

TestProcessNonePageNumbers (6 tests)

• Last item gets non-empty [prev..end_index] range
• First item list_index default no longer negative
• Single-page document handled correctly
• Middle items still use actual neighbor indices
• Regression documents old vs new default behaviour
• No-op when all items already have physical_index

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.