feat(autoindex): name XLSX columns from a two-row grouped header (stacked on #1132)

[thomas-villani]

Stacked on #1132. This branch builds on #1132's merge scan, so until #1132 merges, this diff also shows its commit (dc719492). The new change is the single commit ab19f6c3. Please review and merge #1132 first.

What this changes, and why

pandas writes a DataFrame with MultiIndex columns as a header two rows deep, with each outer label merged across its inner columns:

row 1:        Q1 (B1:C1)    Q2 (D1:E1)
row 2:        Jan   Feb     Jan   Feb
row 4: East   1     2       3     4

Header detection passes over row 1, because a narrower candidate above a wider one is treated as a title line. The fields therefore came out as Jan, Feb, Jan_2, Feb_2: the quarter was lost, and two columns were named only by a dedup suffix. Hand-built reports with Actual | Budget bands over the same month columns have the same shape.

Now the row directly above the header names the columns under it: Q1_Jan, Q1_Feb, Q2_Jan, Q2_Feb.

When the upper row counts as group labels (group_prefixes). All of these must hold:

• It sits directly above the header.
• It holds only text.
• At least one of its cells is merged across two or more header columns.
• No merge spans every header column. A title merged over the whole table labels the table, not a group.

When the row qualifies:

• Each of its cells prefixes the header columns it spans.
• An unmerged cell prefixes only its own column, because pandas does not merge a group that is one column wide.
• A cell whose merge runs down into the header row (Region in A1:A2) belongs to the header, so it gives no prefix. feat(autoindex): fill vertically merged XLSX cells down the rows they cover #1132's fill-down already puts it into the header row.

Sample/full consistency. The sampling run skips the merge scan on any sheet over 64 MB decompressed (#1132). The sample types the fields the full run indexes, so a column's name must not depend on which run read the sheet. Header merges are therefore used only on sheets that both runs scan. Above that size, a two-row header keeps only its lower row, as it does today; this is listed in the module's known limits.

scan_merges now returns every multi-cell range as a Merge; before, it kept only ranges more than one row tall. FillDown takes the vertical ones, so fill-down behavior is unchanged.

Evidence

cargo test -p xerj-autoindex --lib     1200 passed; 0 failed; 2 ignored   (1195 before)
cargo clippy -p xerj-autoindex --all-targets -- -D warnings   clean
cargo build --release -j 32 -p xerj-autoindex                 ok

Mutation checks. Each mutation was applied, the xlsx tests were run, and the mutation was reverted:

mutation	failing tests
prefixing disabled	4: all of the new positive tests
full-width-title rule removed	3. The shared test fixture has always carried an A1:D1 title merge, so the older header tests also guard this rule.
vertical-label skip removed	1

Real file: a pandas 2.x df.to_excel with MultiIndex columns, extracted with a temporary probe test that was removed before commit:

Quarters!r4 {"col_A":"East","Q1_Jan":1,"Q1_Feb":2,"Q2_Jan":3,"Q2_Feb":4}
Quarters!r5 {"col_A":"West","Q1_Jan":5,"Q1_Feb":6,"Q2_Jan":7,"Q2_Feb":8}

The output is identical with a 500-row sample and with no limit. These still extract exactly as they do on #1132:

• an openpyxl report with a title merged over its width;
• the MultiIndex-rows export;
• the 14k-row groupby export.

Checks

• cargo fmt --all (--check clean)
• Scoped release build: cargo build --release -j 32 -p xerj-autoindex
• cargo test -p xerj-autoindex --lib passes
• ES-YAML conformance suite: not run. The change is confined to the autoindex XLSX extractor, a client-side crate.
• New ES-compatible YAML case: N/A
• Docs: the module doc describes the behavior and its limits. The public "merged cells" wording follow-up from feat(autoindex): fill vertically merged XLSX cells down the rows they cover #1132 still applies.
• CONTRIBUTION_REVIEW audit: not run in full. Failure behavior: with no merge list (no <mergeCells>, scan failure, or a large sheet), names are exactly what they were before.

Not run: no throughput benchmark. The change adds one pass over the merge list per sheet, run when the header is found, plus a filter when FillDown is built. The per-row path is unchanged.

Provenance

• Written by: AI agent (Claude Code, Claude Opus 5.5), run by @thomas-villani, who reviewed it.
• Verified: every command and number above.
• Assumed:
  • Excel-authored workbooks with banded headers use the same merged-label layout. Only pandas and hand-built fixtures were tested.
  • Headers three or more rows deep keep only their two lowest rows, and no file of that shape was tested.

🤖 Generated with Claude Code