Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

fix(deepdoc): add orphan-row cleanup to Go table construction (parity with Python) (#18402)

Jack3a7e27515578
diff --git a/internal/deepdoc/parser/pdf/table/parity/orphan_row_extra_test.go b/internal/deepdoc/parser/pdf/table/parity/orphan_row_extra_test.go
new file mode 100644
index 0000000000..3a08ed101c
--- /dev/null
+++ b/internal/deepdoc/parser/pdf/table/parity/orphan_row_extra_test.go
@@ -0,0 +1,146 @@
+//go:build manual
+
+package parity
+
+// These tests drive CleanupOrphanRows directly (bypassing CleanupOrphanColumns)
+// so the row-merge DIRECTION logic can be asserted precisely. Going through
+// ConstructTable would let column cleanup remove the single-cell column first,
+// which makes the "both neighbors empty in the same column" case impossible to
+// isolate (that column would be an orphan column and get merged away).
+
+import (
+ "testing"
+
+ "ragflow/internal/deepdoc/parser/pdf/table"
+ pdf "ragflow/internal/deepdoc/parser/pdf/type"
+)
+
+// MergesUpWhenCloser: orphan row (col 2) with empty same-column cells above
+// and below; the vertical gap to the row above is smaller → merge UP.
+func TestCleanupOrphanRows_MergesUpWhenCloser(t *testing.T) {
+ grid := [][]pdf.TSRCell{
+ {
+ {Text: "A", X0: 0, X1: 100, Y0: 0, Y1: 30},
+ {Text: "B", X0: 101, X1: 200, Y0: 0, Y1: 30},
+ {Text: "", X0: 201, X1: 300, Y0: 0, Y1: 30},
+ {Text: "D", X0: 301, X1: 400, Y0: 0, Y1: 30},
+ },
+ {
+ {Text: "", X0: 0, X1: 100, Y0: 40, Y1: 70},
+ {Text: "", X0: 101, X1: 200, Y0: 40, Y1: 70},
+ {Text: "孤", X0: 201, X1: 300, Y0: 40, Y1: 70},
+ {Text: "", X0: 301, X1: 400, Y0: 40, Y1: 70},
+ },
+ {
+ {Text: "E", X0: 0, X1: 100, Y0: 200, Y1: 230},
+ {Text: "F", X0: 101, X1: 200, Y0: 200, Y1: 230},
+ {Text: "", X0: 201, X1: 300, Y0: 200, Y1: 230},
+ {Text: "H", X0: 301, X1: 400, Y0: 200, Y1: 230},
+ },
+ }
+ // up = 40-30 = 10; down = 200-70 = 130 → up < down → merge UP into row 0.
+ out := table.CleanupOrphanRows(grid)
+ if len(out) != 2 {
+ t.Fatalf("expected 2 rows after up-merge, got %d", len(out))
+ }
+ if out[0][2].Text != "孤" {
+ t.Errorf("orphan should merge UP into row 0 col 2, got %q at [0][2]", out[0][2].Text)
+ }
+}
+
+// MergesDownWhenCloser: same shape, but the row below is closer → merge DOWN.
+func TestCleanupOrphanRows_MergesDownWhenCloser(t *testing.T) {
+ grid := [][]pdf.TSRCell{
+ {
+ {Text: "A", X0: 0, X1: 100, Y0: 0, Y1: 30},
+ {Text: "B", X0: 101, X1: 200, Y0: 0, Y1: 30},
+ {Text: "", X0: 201, X1: 300, Y0: 0, Y1: 30},
+ {Text: "D", X0: 301, X1: 400, Y0: 0, Y1: 30},
+ },
+ {
+ {Text: "", X0: 0, X1: 100, Y0: 100, Y1: 130},
+ {Text: "", X0: 101, X1: 200, Y0: 100, Y1: 130},
+ {Text: "孤", X0: 201, X1: 300, Y0: 100, Y1: 130},
+ {Text: "", X0: 301, X1: 400, Y0: 100, Y1: 130},
+ },
+ {
+ {Text: "E", X0: 0, X1: 100, Y0: 140, Y1: 170},
+ {Text: "F", X0: 101, X1: 200, Y0: 140, Y1: 170},
+ {Text: "", X0: 201, X1: 300, Y0: 140, Y1: 170},
+ {Text: "H", X0: 301, X1: 400, Y0: 140, Y1: 170},
+ },
+ }
+ // up = 100-30 = 70; down = 140-130 = 10 → down < up → merge DOWN into row 2.
+ out := table.CleanupOrphanRows(grid)
+ if len(out) != 2 {
+ t.Fatalf("expected 2 rows after down-merge, got %d", len(out))
+ }
+ if out[1][2].Text != "孤" {
+ t.Errorf("orphan should merge DOWN into row 1 col 2, got %q at [1][2]", out[1][2].Text)
+ }
+}
+
+// BottomMergesUp: orphan at the LAST row (col 0), row above same column empty.
+// i+1 >= nRows → hasBelow true → merge UP (up is finite).
+func TestCleanupOrphanRows_BottomMergesUp(t *testing.T) {
+ grid := [][]pdf.TSRCell{
+ {
+ {Text: "X", X0: 0, X1: 100, Y0: 0, Y1: 30},
+ {Text: "B", X0: 101, X1: 200, Y0: 0, Y1: 30},
+ {Text: "C", X0: 201, X1: 300, Y0: 0, Y1: 30},
+ {Text: "D", X0: 301, X1: 400, Y0: 0, Y1: 30},
+ },
+ {
+ {Text: "", X0: 0, X1: 100, Y0: 35, Y1: 65},
+ {Text: "E", X0: 101, X1: 200, Y0: 35, Y1: 65},
+ {Text: "F", X0: 201, X1: 300, Y0: 35, Y1: 65},
+ {Text: "G", X0: 301, X1: 400, Y0: 35, Y1: 65},
+ },
+ {
+ {Text: "孤", X0: 0, X1: 100, Y0: 100, Y1: 130},
+ {Text: "", X0: 101, X1: 200, Y0: 100, Y1: 130},
+ {Text: "", X0: 201, X1: 300, Y0: 100, Y1: 130},
+ {Text: "", X0: 301, X1: 400, Y0: 100, Y1: 130},
+ },
+ }
+ out := table.CleanupOrphanRows(grid)
+ if len(out) != 2 {
+ t.Fatalf("expected 2 rows after bottom up-merge, got %d", len(out))
+ }
+ if out[1][0].Text != "孤" {
+ t.Errorf("bottom orphan should merge UP into row 1 col 0, got %q at [1][0]", out[1][0].Text)
+ }
+}
+
+// NoNeighborsKept: orphan row sandwiched between TWO entirely empty rows.
+// Both up and down distances are +inf → the guard keeps the row in place
+// (Python would assert/crash here). This preserves data instead of relocating.
+func TestCleanupOrphanRows_NoNeighborsKept(t *testing.T) {
+ grid := [][]pdf.TSRCell{
+ {
+ {Text: "", X0: 0, X1: 100, Y0: 0, Y1: 30},
+ {Text: "", X0: 101, X1: 200, Y0: 0, Y1: 30},
+ {Text: "", X0: 201, X1: 300, Y0: 0, Y1: 30},
+ {Text: "", X0: 301, X1: 400, Y0: 0, Y1: 30},
+ },
+ {
+ {Text: "", X0: 0, X1: 100, Y0: 40, Y1: 70},
+ {Text: "", X0: 101, X1: 200, Y0: 40, Y1: 70},
+ {Text: "孤", X0: 201, X1: 300, Y0: 40, Y1: 70},
+ {Text: "", X0: 301, X1: 400, Y0: 40, Y1: 70},
+ },
+ {
+ {Text: "", X0: 0, X1: 100, Y0: 80, Y1: 110},
+ {Text: "", X0: 101, X1: 200, Y0: 80, Y1: 110},
+ {Text: "", X0: 201, X1: 300, Y0: 80, Y1: 110},
+ {Text: "", X0: 301, X1: 400, Y0: 80, Y1: 110},
+ },
+ }
+ out := table.CleanupOrphanRows(grid)
+ if len(out) != 3 {
+ t.Fatalf("expected 3 rows kept (no mergeable neighbor), got %d", len(out))
+ }
+ if out[1][2].Text != "孤" {
+ t.Errorf("orphan should stay in its own row when both neighbors are empty, got %q at [1][2]", out[1][2].Text)
+ }
+}
diff --git a/internal/deepdoc/parser/pdf/table/parity/orphan_row_test.go b/internal/deepdoc/parser/pdf/table/parity/orphan_row_test.go
new file mode 100644
index 0000000000..b1bc8373fa
--- /dev/null
+++ b/internal/deepdoc/parser/pdf/table/parity/orphan_row_test.go
@@ -0,0 +1,273 @@
+//go:build manual
+
+// Package parity isolates the orphan-row / orphan-column cleanup parity tests
+// from the rest of the `table` package's test files. The package's other
+// manual-tier test file (table_parity_issues_test.go) does not currently
+// compile on main (references removed/renamed symbols), which would otherwise
+// break the whole package's manual test binary. These tests only depend on the
+// EXPORTED surface (ConstructTable, CleanupOrphanColumns) plus the exported
+// pdf.TSRCell / pdf.TableItem types, so they build independently.
+//
+// Run:
+//
+// bash build.sh --test-manual ./internal/deepdoc/parser/pdf/table/parity/
+package parity
+
+import (
+ "strings"
+ "testing"
+
+ "ragflow/internal/deepdoc/parser/pdf/table"
+ pdf "ragflow/internal/deepdoc/parser/pdf/type"
+)
+
+// =============================================================================
+// Parity finding #2 (orphan-row cleanup): Go lacks a row counterpart to
+// CleanupOrphanColumns.
+//
+// Python's construct_table (deepdoc/vision/table_structure_recognizer.py:279-333)
+// merges a row that holds EXACTLY ONE non-empty cell into its nearest vertical
+// neighbor when len(cols) >= 4. The merge direction is chosen by the minimum
+// vertical gap (up vs down); a row "sandwiched" between two populated cells in
+// the same column is kept. Go's ConstructTable (table_construct.go:39) only
+// calls CleanupOrphanColumns and has no orphan-row pass.
+//
+// Item state after cleanup: ConstructTable sets item.Grid and item.Rows from
+// the cleaned grid (Python-aligned). Both must be derived AFTER the cleanup
+// passes, since cleanup may drop rows/columns.
+//
+// The tests below assert the Python-aligned behavior. They are RED on main
+// because the row-cleanup pass does not exist.
+// =============================================================================
+
+// buildGrid builds a rectangular [][]pdf.TSRCell from a text matrix using
+// deterministic coordinates: column ci occupies [ci*100, ci*100+100],
+// row ri occupies [ri*40, ri*40+30]. Empty strings become empty cells.
+// Coordinates matter for the merge-distance logic but not for row/col counting.
+func buildGrid(text [][]string) [][]pdf.TSRCell {
+ rows := make([][]pdf.TSRCell, len(text))
+ for ri := range text {
+ rows[ri] = make([]pdf.TSRCell, len(text[ri]))
+ for ci := range text[ri] {
+ rows[ri][ci] = pdf.TSRCell{
+ X0: float64(ci) * 100,
+ X1: float64(ci)*100 + 100,
+ Y0: float64(ri) * 40,
+ Y1: float64(ri)*40 + 30,
+ Text: text[ri][ci],
+ }
+ }
+ }
+ return rows
+}
+
+func trCount(html string) int { return strings.Count(html, "<tr>") }
+
+func colCount(rows [][]pdf.TSRCell) int {
+ if len(rows) == 0 {
+ return 0
+ }
+ return len(rows[0])
+}
+
+// =============================================================================
+// A) Orphan MIDDLE row merges UP.
+// Row 2 has a single cell ("孤儿") at col 0. Row 1 col 0 is EMPTY (not
+// sandwiched above) and row 3 col 0 is populated (ff=true). Python merges the
+// orphan UP into row 1 (up gap finite, down gap +inf) and pops row 2 → 3 rows.
+// =============================================================================
+
+func TestConstructTable_OrphanRow_MergesUp(t *testing.T) {
+ grid := buildGrid([][]string{
+ {"H0", "H1", "H2", "H3"},
+ {"", "A1", "A2", "A3"},
+ {"孤儿", "", "", ""},
+ {"D0", "D1", "D2", "D3"},
+ })
+
+ html := table.ConstructTable(nil, nil, "", &pdf.TableItem{Grid: grid})
+
+ // FIXED: 4 rows → 3 after merging the single-cell row up.
+ if got := trCount(html); got != 3 {
+ t.Errorf("ORPHAN-ROW BUG: expected 3 <tr> after merging the single-cell row up, got %d. Python merges row 2 into row 1 (table_structure_recognizer.py:279-333).", got)
+ }
+
+ // '孤儿' must land in the row containing 'A1' (merged UP), not its own row.
+ mergedUp := false
+ for _, tr := range strings.Split(html, "<tr>") {
+ if strings.Contains(tr, "孤儿") && strings.Contains(tr, "A1") {
+ mergedUp = true
+ }
+ }
+ if !mergedUp {
+ t.Errorf("ORPHAN-ROW BUG: '孤儿' should merge UP into the row containing 'A1'. HTML:\n%s", html)
+ }
+ t.Logf("HTML:\n%s", html)
+}
+
+// =============================================================================
+// B) Orphan TOP row merges DOWN.
+// Row 0 (top) is an orphan at col 0. i==0 → f=true; row 1 col 0 EMPTY → ff=false
+// → merge DOWN into row 1. Row 0 popped → 3 rows.
+// =============================================================================
+
+func TestConstructTable_OrphanRow_TopMergesDown(t *testing.T) {
+ grid := buildGrid([][]string{
+ {"顶孤", "", "", ""},
+ {"", "B1", "B2", "B3"},
+ {"C0", "C1", "C2", "C3"},
+ {"D0", "D1", "D2", "D3"},
+ })
+
+ html := table.ConstructTable(nil, nil, "", &pdf.TableItem{Grid: grid})
+
+ if got := trCount(html); got != 3 {
+ t.Errorf("ORPHAN-ROW BUG: expected 3 <tr> after merging the top orphan row down, got %d. Python merges row 0 into row 1 (table_structure_recognizer.py:279-333).", got)
+ }
+
+ // '顶孤' must land in the row containing 'B1' (merged DOWN).
+ mergedDown := false
+ for _, tr := range strings.Split(html, "<tr>") {
+ if strings.Contains(tr, "顶孤") && strings.Contains(tr, "B1") {
+ mergedDown = true
+ }
+ }
+ if !mergedDown {
+ t.Errorf("ORPHAN-ROW BUG: top orphan '顶孤' should merge DOWN into the row containing 'B1'. HTML:\n%s", html)
+ }
+ t.Logf("HTML:\n%s", html)
+}
+
+// =============================================================================
+// C) Sandwiched orphan KEPT (regression guard). GREEN on main and after fix.
+// Row 2 is an orphan at col 0, but BOTH vertical neighbors (row 1 col 0 and
+// row 3 col 0) are populated → 'sandwiched'. Python skips the merge
+// (table_structure_recognizer.py:293-297). Must stay 4 rows.
+// =============================================================================
+
+func TestConstructTable_OrphanRow_SandwichedKept(t *testing.T) {
+ grid := buildGrid([][]string{
+ {"H0", "H1", "H2", "H3"},
+ {"X0", "A1", "A2", "A3"},
+ {"夹孤", "", "", ""},
+ {"Z0", "D1", "D2", "D3"},
+ })
+
+ html := table.ConstructTable(nil, nil, "", &pdf.TableItem{Grid: grid})
+
+ if got := trCount(html); got != 4 {
+ t.Errorf("REGRESSION GUARD: sandwiched orphan must be KEPT (4 rows), got %d. Python skips merge when both vertical neighbors are populated.", got)
+ }
+
+ // '夹孤' must NOT be merged into a neighbor row.
+ for _, tr := range strings.Split(html, "<tr>") {
+ if strings.Contains(tr, "夹孤") && (strings.Contains(tr, "X0") || strings.Contains(tr, "Z0")) {
+ t.Errorf("REGRESSION GUARD: sandwiched orphan '夹孤' must stay in its own row, not merge with 'X0'/'Z0'. HTML:\n%s", html)
+ }
+ }
+ t.Logf("HTML:\n%s", html)
+}
+
+// =============================================================================
+// F) Gate is on COLUMN count (>=4). Regression guard. GREEN on main and after fix.
+// A 3-column table with an orphan middle row must be KEPT, because Python gates
+// row cleanup on len(cols) >= 4 (columns), not rows. Guards the fix against
+// using the wrong axis (as the column cleanup currently does).
+// =============================================================================
+
+func TestConstructTable_OrphanRow_GateNeeds4Columns(t *testing.T) {
+ grid := buildGrid([][]string{
+ {"H0", "H1", "H2"},
+ {"", "A1", "A2"},
+ {"三孤", "", ""},
+ {"D0", "D1", "D2"},
+ })
+
+ html := table.ConstructTable(nil, nil, "", &pdf.TableItem{Grid: grid})
+
+ if got := trCount(html); got != 4 {
+ t.Errorf("REGRESSION GUARD: with only 3 columns, orphan row must be KEPT (4 rows). Python gates row cleanup on len(cols)>=4 (columns), not rows. Got %d.", got)
+ }
+ t.Logf("HTML:\n%s", html)
+}
+
+// =============================================================================
+// D) Column cleanup gate is on the ROW count (>=4). Regression guard.
+// Python gates column cleanup on `len(rows) >= 4` (construct_table:221), NOT
+// unconditionally. So for a 2-row table Python does NOT run column cleanup and
+// keeps the single-cell orphan column. The Go gate (len(rows) < 4) must be
+// preserved to match; this guards against removing it (which would make Go
+// drop orphan columns Python keeps).
+// =============================================================================
+
+func TestCleanupOrphanColumns_SmallTableKeepsOrphanColumn(t *testing.T) {
+ grid := buildGrid([][]string{
+ {"", "孤列", "A2"}, // col 1 is the orphan; left neighbor empty → mergeable
+ {"B0", "", "B2"},
+ })
+
+ out := table.CleanupOrphanColumns(grid)
+
+ if colCount(out) != 3 {
+ t.Errorf("REGRESSION GUARD: a 2-row table must KEEP its orphan column (3 cols). Python gates column cleanup on len(rows)>=4 (construct_table:221), so it does not run here. Got %d columns.", colCount(out))
+ }
+ t.Logf("columns after cleanup: %d", colCount(out))
+}
+
+// D2) Column cleanup DOES run for >=4 rows and removes a single-cell orphan
+// column. Positive counterpart to D: confirms the gate is row-count based, not
+// removed entirely. col 1 has text only in row 0 (e==1 orphan); col 0/col 2
+// have text in other rows → mergeable → column removed (3 → 2 cols).
+func TestCleanupOrphanColumns_LargeTableRemovesOrphanColumn(t *testing.T) {
+ grid := buildGrid([][]string{
+ {"", "孤列", "A2"},
+ {"B0", "", "B2"},
+ {"C0", "", "C2"},
+ {"D0", "", "D2"},
+ })
+
+ out := table.CleanupOrphanColumns(grid)
+
+ if colCount(out) != 2 {
+ t.Errorf("expected 2 columns after removing the single-cell orphan column for a >=4-row table (Python runs column cleanup when len(rows)>=4). Got %d columns.", colCount(out))
+ }
+ t.Logf("columns after cleanup: %d", colCount(out))
+}
+
+// =============================================================================
+// E) item.Rows is stale after cleanup (related bug in the same function).
+// 5-row, 3-column table with a single-cell orphan column (left neighbor empty
+// in the populated row) → CleanupOrphanColumns removes it (3 → 2 cols).
+// ConstructTable sets item.Rows (line 57) BEFORE CleanupOrphanColumns (line 59),
+// so item.Rows keeps 3 cols while the HTML has 2. RED on main.
+// =============================================================================
+
+func TestConstructTable_RowsFieldReflectsCleanup(t *testing.T) {
+ grid := buildGrid([][]string{
+ {"", "孤列", "H2"},
+ {"R1_0", "", "R1_2"},
+ {"R2_0", "", "R2_2"},
+ {"R3_0", "", "R3_2"},
+ {"R4_0", "", "R4_2"},
+ })
+
+ item := &pdf.TableItem{Grid: grid}
+ html := table.ConstructTable(nil, nil, "", item)
+
+ htmlCols := 0
+ if trCount(html) > 0 {
+ firstRow := strings.Split(html, "<tr>")[1]
+ htmlCols = strings.Count(firstRow, "<td ") + strings.Count(firstRow, "<th ")
+ }
+
+ if len(item.Rows) > 0 && len(item.Rows[0]) != htmlCols {
+ t.Errorf("STALE item.Rows BUG: item.Rows[0] has %d cols but HTML row has %d cols. ConstructTable must derive item.Rows AFTER CleanupOrphanColumns.", len(item.Rows[0]), htmlCols)
+ }
+ // item.Grid must also reflect the cleaned grid: CleanupOrphanRows re-slices
+ // the rows header, so a stale item.Grid would feed downstream consumers
+ // (e.g. cross-page merge) the un-cleaned grid.
+ if len(item.Grid) > 0 && len(item.Grid[0]) != htmlCols {
+ t.Errorf("STALE item.Grid BUG: item.Grid[0] has %d cols but HTML row has %d cols. ConstructTable must re-assign item.Grid from the cleaned rows.", len(item.Grid[0]), htmlCols)
+ }
+ t.Logf("item.Grid cols=%d item.Rows cols=%d html cols=%d", len(item.Grid[0]), len(item.Rows[0]), htmlCols)
+}
diff --git a/internal/deepdoc/parser/pdf/table/table_construct.go b/internal/deepdoc/parser/pdf/table/table_construct.go
index ca785b30ce..6709f36845 100644
--- a/internal/deepdoc/parser/pdf/table/table_construct.go
+++ b/internal/deepdoc/parser/pdf/table/table_construct.go
@@ -52,11 +52,19 @@ func ConstructTable(cells []pdf.TSRCell, boxes []pdf.TextBox, caption string, it
rows = GroupTSRCellsToRows(cells)
}
if len(rows) > 0 && HasText(rows) {
+ // Clean up orphan columns then orphan rows (Python order: columns at
+ // construct_table:224-277, then rows at :279-333). Both passes mutate
+ // the same grid and may drop rows/columns, so item.Grid and item.Rows
+ // must be re-derived AFTER them (the old code set item.Rows before
+ // column cleanup, leaving it stale; item.Grid also went stale because
+ // CleanupOrphanRows returns a re-sliced header).
+ rows = CleanupOrphanColumns(rows)
+ rows = CleanupOrphanRows(rows)
hdrs := HeaderSetWithBlockType(rows)
if item != nil {
+ item.Grid = rows
item.Rows = RowsToStrings(rows)
}
- rows = CleanupOrphanColumns(rows)
spanInfo, covered := CalSpans(rows)
return RowsToHTML(rows, caption, hdrs, spanInfo, covered)
}
@@ -207,12 +215,15 @@ func minRectangleDistance(left1, right1, top1, bottom1, left2, right2, top2, bot
return math.Sqrt(dx*dx + dy*dy)
}
-// Orphan column/row cleanup (Python: construct_table lines 256-368)
+// Orphan column/row cleanup (Python: construct_table:221-277 columns, :279-333 rows)
-// CleanupOrphanColumns removes columns that have only a single non-empty cell
-// when there are ≥4 rows. Matches Python's construct_table column cleanup.
+// CleanupOrphanColumns removes columns that have only a single non-empty cell.
+// Matches Python's construct_table column cleanup (table_structure_recognizer.py:224-277),
+// which is gated on the ROW count: `if len(rows) >= 4` (construct_table:221).
+// The original Go gate (len(rows) < 4) matched Python and is preserved here —
+// removing it would make Go drop orphan columns that Python keeps for <4-row tables.
func CleanupOrphanColumns(rows [][]pdf.TSRCell) [][]pdf.TSRCell {
- if len(rows) < 4 || len(rows) == 0 {
+ if len(rows) < 4 {
return rows
}
nCols := len(rows[0])
@@ -236,6 +247,17 @@ func CleanupOrphanColumns(rows [][]pdf.TSRCell) [][]pdf.TSRCell {
// Step 3: Calculate merge distance
leftDist, rightDist := calculateMergeDistance(rows, j, ii, nCols, hasLeftText, hasRightText)
+ // Python asserts at least one side is mergeable (left < 100000 or
+ // right < 100000). If both neighbors are empty there is nothing to
+ // merge the orphan into, so skip the column rather than dropping its
+ // only cell (Python would assert/crash here). This guards the >=4-row
+ // degenerate case where a column has a single cell but no mergeable
+ // neighbor column.
+ if leftDist >= 1e9 && rightDist >= 1e9 {
+ j++
+ continue
+ }
+
// Step 4: Merge the column
if leftDist < rightDist && j > 0 {
mergeColumnIntoLeft(rows, j)
@@ -251,6 +273,114 @@ func CleanupOrphanColumns(rows [][]pdf.TSRCell) [][]pdf.TSRCell {
return rows
}
+// CleanupOrphanRows removes rows that hold exactly one non-empty cell when the
+// table has >=4 columns, merging that lone cell into its nearest vertical
+// neighbor. Mirrors Python's construct_table row cleanup
+// (table_structure_recognizer.py:279-333).
+//
+// A "sandwiched" orphan row — both the row above and the row below have text in
+// the same column as the lone cell — is kept, because merging would destroy a
+// real data row. Otherwise the orphan cell is merged UP if the vertical gap to
+// the row above is smaller than to the row below, else DOWN. The neighbor cell
+// keeps its own coordinates and only its text is extended (Python extends the
+// box list); CalSpans recomputes spans from geometry, so no row-number
+// bookkeeping (Python's "rn") is needed here.
+//
+// The >=4 threshold is the COLUMN count (Python's len(cols) >= 4), evaluated
+// after column cleanup, not the row count.
+func CleanupOrphanRows(rows [][]pdf.TSRCell) [][]pdf.TSRCell {
+ if len(rows) == 0 || len(rows[0]) < 4 {
+ return rows
+ }
+ nRows := len(rows)
+ i := 0
+ for i < nRows {
+ // Count non-empty cells; remember the lone populated column.
+ e, jj := 0, 0
+ for j := range rows[i] {
+ if strings.TrimSpace(rows[i][j].Text) != "" {
+ e++
+ jj = j
+ if e > 1 {
+ break
+ }
+ }
+ }
+ if e != 1 {
+ // 0 cells (empty row) or >1 (not an orphan): nothing to merge.
+ i++
+ continue
+ }
+
+ // Are the directly-adjacent cells in the same column populated?
+ hasAbove := (i > 0 && strings.TrimSpace(rows[i-1][jj].Text) != "") || i == 0
+ hasBelow := (i+1 < nRows && strings.TrimSpace(rows[i+1][jj].Text) != "") || i+1 >= nRows
+ if hasAbove && hasBelow {
+ // Sandwiched between two populated cells → keep.
+ i++
+ continue
+ }
+
+ // Minimum vertical gap to the nearest mergeable neighbor.
+ const inf = 1e9
+ up, down := inf, inf
+ if i > 0 && !hasAbove {
+ for j := range rows[i-1] {
+ if strings.TrimSpace(rows[i-1][j].Text) != "" {
+ if d := rows[i][jj].Y0 - rows[i-1][j].Y1; d < up {
+ up = d
+ }
+ }
+ }
+ }
+ if i+1 < nRows && !hasBelow {
+ for j := range rows[i+1] {
+ if strings.TrimSpace(rows[i+1][j].Text) != "" {
+ if d := rows[i+1][j].Y0 - rows[i][jj].Y1; d < down {
+ down = d
+ }
+ }
+ }
+ }
+ // Python asserts up < 100000 or down < 100000 (at least one side is
+ // mergeable) because hasAbove/hasBelow are not both true. If BOTH
+ // adjacent rows are entirely empty there is nowhere to merge into —
+ // keep the orphan rather than relocating it (Python would assert/crash
+ // here). Mirrors the orphan-column guard in CleanupOrphanColumns.
+ if up >= inf && down >= inf {
+ i++
+ continue
+ }
+
+ if up < down {
+ mergeOrphanCell(rows, i, i-1, jj)
+ } else {
+ mergeOrphanCell(rows, i, i+1, jj)
+ }
+ // Drop the orphan row; the next row shifts into position i.
+ rows = append(rows[:i], rows[i+1:]...)
+ nRows--
+ }
+ return rows
+}
+
+// mergeOrphanCell appends the lone cell at (from, col) into the target cell at
+// (to, col). Matches Python's tbl[to][col].extend(tbl[from][col]): when the
+// target already has text, the orphan text is appended after it. The target
+// keeps its own coordinates; only the text is merged.
+func mergeOrphanCell(rows [][]pdf.TSRCell, from, to, col int) {
+ target := &rows[to][col]
+ orphan := strings.TrimSpace(rows[from][col].Text)
+ if orphan == "" {
+ return
+ }
+ if strings.TrimSpace(target.Text) == "" {
+ target.Text = orphan
+ } else {
+ target.Text = target.Text + " " + orphan
+ }
+}
+
// countNonEmptyCells counts non-empty cells in a column and returns the count
// and the index of the last non-empty row.
func countNonEmptyCells(rows [][]pdf.TSRCell, col int) (count int, lastRow int) {
diff --git a/internal/deepdoc/parser/pdf/table/table_construct_test.go b/internal/deepdoc/parser/pdf/table/table_construct_test.go
index 7fde522aa8..2a269a420a 100644
--- a/internal/deepdoc/parser/pdf/table/table_construct_test.go
+++ b/internal/deepdoc/parser/pdf/table/table_construct_test.go
@@ -698,7 +698,8 @@ func TestMergeCaptions_NeedsCaptionLayoutType(t *testing.T) {
}
func TestCleanupOrphanColumns(t *testing.T) {
- // Test 1: Less than 4 rows - no cleanup
+ // Test 1: column cleanup is gated on >=4 rows, so a 3-row table is
+ // skipped; even if it ran, this single-column grid has no orphan column.
t.Run("less than 4 rows", func(t *testing.T) {
rows := [][]pdf.TSRCell{
{{Text: "a"}},