From da7b76555a9b098ee5e6c7972c3fce90601f295f Mon Sep 17 00:00:00 2001
From: Barrett Ruth <br.barrettruth@gmail.com>
Date: Wed, 4 Feb 2026 13:16:22 -0500
Subject: [PATCH] docs: add incomplete syntax context as known limitation

Treesitter parses diff hunks in isolation without surrounding code
context, which can cause incorrect highlighting when hunks show partial
blocks (e.g., adding lines inside `return { ... }` without seeing the
`return`). Document this as a known limitation in README and vimdoc.
---
 README.md          |  7 +++++++
 doc/diffs.nvim.txt | 11 +++++++++++
 2 files changed, 18 insertions(+)

diff --git a/README.md b/README.md
index 3c5b2db..c38528d 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,13 @@ luarocks install diffs.nvim
 
 ## Known Limitations
 
+- **Incomplete syntax context**: Treesitter parses each diff hunk in isolation
+  without surrounding code context. When a hunk shows lines added to an existing
+  block (e.g., adding a plugin inside `return { ... }`), the parser doesn't see
+  the `return` statement and may produce incorrect highlighting. This is
+  inherent to parsing code fragments—no diff tooling solves this without
+  significant complexity.
+
 - **Syntax flashing**: `diffs.nvim` hooks into the `FileType fugitive` event
   triggered by `vim-fugitive`, at which point the buffer is preliminarily
   painted. The buffer is then re-painted after `debounce_ms` milliseconds,
diff --git a/doc/diffs.nvim.txt b/doc/diffs.nvim.txt
index d75a552..6b66ee1 100644
--- a/doc/diffs.nvim.txt
+++ b/doc/diffs.nvim.txt
@@ -185,6 +185,17 @@ Diff mode views: ~
 ==============================================================================
 KNOWN LIMITATIONS                                       *diffs-limitations*
 
+Incomplete Syntax Context ~
+                                                      *diffs-syntax-context*
+Treesitter parses each diff hunk in isolation without surrounding code
+context. When a hunk shows lines added to an existing block (e.g., adding a
+plugin inside `return { ... }`), the parser doesn't see the `return`
+statement and may produce incorrect or unusual highlighting.
+
+This is inherent to parsing code fragments. No diff tooling solves this
+problem without significant complexity—the parser simply doesn't have enough
+information to understand the full syntactic structure.
+
 Syntax Highlighting Flash ~
                                                              *diffs-flash*
 When opening a fugitive buffer, there is an unavoidable visual "flash" where