fix(docs): widen native-table search window in markdown append (#592)

[sebsnyk]

Summary

Fixes #592 — gog docs write --markdown --append silently dropped any markdown table in the appended content, failing with insert native table: table not found near index N. Body text appended fine; only the native-table insert step blew up.

Root cause

After issuing InsertTableRequest, TableInserter.getTableCellIndices walks Documents.Get to bind cell indices to the freshly-inserted Table element. It matched the table by requiring element.StartIndex in [tableStartIndex-2, tableStartIndex+2], but the Docs API's actual reported StartIndex drifts further than 2 code units in practice — the auto-newline behaviour documented for InsertTableRequest combines with our pre-inserted placeholder paragraph to push the table several positions past the requested Location.Index. Outside the window, the matcher returned no hit and surfaced the table not found error, so the table was silently dropped while the surrounding text appended successfully.

The docs create --file --markdown path is unaffected because Drive's native markdown importer converts tables end-to-end without ever calling InsertNativeTable — the bug is specific to the markdown append/replace path.

Fix

Replace the tight ±2 window with a new pickTableNear helper that scans the body content and picks the Table element whose StartIndex is closest to tableStartIndex while staying within a small backward tolerance. The closest-match policy uniquely identifies the freshly-inserted table even if the doc already contains other tables, and the backward tolerance absorbs minor index quirks. InsertTable can only shift existing content forward, so requiring near-or-after positioning is correct by construction.

Test plan

• go test ./internal/cmd -run 'TestInsertDocsMarkdownAt|TestPickTableNear|TestNextTableInsertOffset|TestBuildTableCellRequests|TestParseMarkdown|TestMarkdownToDocsRequests' -count=1
• go test ./... — green
• go vet ./... — clean
• gofmt -l on touched files — no diff
• New internal/cmd/docs_append_table_test.go reproduces the issue against an httptest-backed Docs mock (configurable drift between Location.Index and the table's reported StartIndex); a drift of 5 reliably triggers table not found near index 9 pre-fix and passes post-fix
• TestPickTableNear_PrefersClosestForwardMatch documents the matcher's semantics for exact match, +1/+5/+25 drift, earlier-in-doc tables outside the backward tolerance, and the no-tables case
• Existing docs write --append --markdown: 3rd+ table in single call reorders trailing punctuation of preceding paragraph #607/docs write --append --markdown: inline markdown inside table cells (bold/italic/code) renders literally #608/docs write --append --markdown: empty-header tables leak last row as literal pipe text after the table #609 regression tests still pass
• Live Google Docs smoke test (not feasible from this sandbox; recommend a maintainer rerun on a disposable doc before landing — the issue includes a self-contained repro)

🤖 Generated with Claude Code