Skip to content

extradoc: word-atomic in-paragraph diff for readable redlines - #78

Open
cassus wants to merge 1 commit into
think41:mainfrom
cassus:fix/word-atomic-diff
Open

extradoc: word-atomic in-paragraph diff for readable redlines#78
cassus wants to merge 1 commit into
think41:mainfrom
cassus:fix/word-atomic-diff

Conversation

@cassus

@cassus cassus commented Jul 22, 2026

Copy link
Copy Markdown

Context & disclosure. This is a readability enhancement (not a bug fix)
that I've used and verified on real documents in SUGGEST mode. The change, the
tests, and this write-up are largely AI-generated (Claude Opus); the prose and
code are largely AI-authored, so please weight the detail accordingly.

It's motivated by SUGGEST mode, which isn't generally available yet and
whose main PR hasn't landed — so it's completely fine if you'd rather not merge
this now. I'm opening it mainly to share the approach upstream. Note it also
changes the diff granularity for direct edits, which I haven't specifically
exercised — see the trade-off below.

This project has been really useful to me and I'd like to give back: if you want
more human attention, deeper testing, or changes to make this mergeable, I'm
happy to engage personally and put in the work — just say the word.

What

Diff paragraph bodies at word-token granularity instead of character level,
so multi-word edits stay single readable chunks in the Docs Suggestions UI
rather than fragmenting into char-level "insert/delete soup". A char-level
fallback kicks in for whitespace-only edits (e.g. "PARTI" -> "PART I") so a
single inserted/removed space stays a minimal edit rather than replacing the
whole token.

Trade-off / scope

This changes the opcodes produced by _diff_paragraph_runs, which affects any
consumer of paragraph-level diffs, not just SUGGEST-mode redlines. The intent
is purely cosmetic (fewer, more meaningful suggestion chunks); it does not
change which characters end up in the final document. Happy to gate it behind a
flag if you'd prefer to keep char-level diffing as the default.

Changes

  • reconcile_v3/lower.py_word_diff_opcodes / _tokenize_words; wire
    _diff_paragraph_runs to use them.
  • tests/reconcile_v3/test_lower.pyTestWordAtomicDiff: a one-word change
    stays one atomic replace opcode (plain char-level difflib fragments
    "brown"->"red" on a spurious shared 'r'); a whitespace-only change
    falls back to a minimal char-level insert.

Verification

  • Full unit suite green (703 passed locally).

Diff paragraph bodies at word-token granularity so multi-word edits stay
single readable chunks in the Docs Suggestions UI instead of char-level
fragment-soup, with a char-level fallback for whitespace-only edits (e.g.
"PARTI" -> "PART I") so single-space changes stay minimal.

Adds regression tests: a one-word change stays one atomic replace opcode
(char-level difflib would fragment "brown"->"red" on a spurious shared 'r');
a whitespace-only change falls back to a minimal char-level insert.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant