feat: document hunk keyword expansion in output format

Author: umputun

.claude-plugin/skills/revdiff/references/usage.md

@@ -143,10 +143,15 @@ consider splitting this file into smaller modules
 ## handler.go:43 (+)
 use errors.Is() instead of direct comparison
 
+## handler.go:43-67 (+)
+refactor this hunk to reduce nesting
+
 ## store.go:18 (-)
 don't remove this validation
 ```
 
 Each annotation block: `## filename:line (type)` where type is `(+)` added, `(-)` removed, or `(file-level)`.
 
+When annotation text contains keywords "hunk" or "block" (case-insensitive, whole word), the output header automatically expands to include the full hunk line range (e.g., `handler.go:43-67 (+)` instead of `handler.go:43 (+)`). This gives AI consumers the range context without any extra steps.
+
 Use `--output` / `-o` flag to write annotations to a file instead of stdout.

CLAUDE.md

@@ -17,7 +17,7 @@ TUI for reviewing diffs, files, and documents with inline annotations, built wit
 - `highlight/` - chroma-based syntax highlighting, foreground-only ANSI output
 - `keymap/` - user-configurable keybindings (`Action` constants, `Keymap` type, parser, defaults, dump)
 - `theme/` - color theme system: Parse (with hex validation), Load, List, Dump, InitBundled, BundledNames, ColorKeys (bundled: dracula, nord, solarized-dark)
-- `annotation/` - in-memory annotation store, structured output formatting
+- `annotation/` - in-memory annotation store, structured output formatting; `Annotation.EndLine` enables hunk range headers when comment contains "hunk"/"block" keywords
 - `ui/mocks/` - moq-generated mocks (never edit manually)
 
 ## Key Interfaces (consumer-side, in `ui/`)

README.md

@@ -499,10 +499,15 @@ consider splitting this file into smaller modules
 ## handler.go:43 (+)
 use errors.Is() instead of direct comparison
 
+## handler.go:43-67 (+)
+refactor this hunk to reduce nesting
+
 ## store.go:18 (-)
 don't remove this validation
 ```
 
+When annotation text contains keywords "hunk" or "block" (case-insensitive, whole word), the output header automatically expands to include the full hunk line range (e.g., `handler.go:43-67 (+)` instead of `handler.go:43 (+)`). This gives AI consumers the range context without any extra steps.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

annotation/store.go

@@ -31,6 +31,7 @@ func (s *Store) Add(a Annotation) {
 	existing := s.annotations[a.File]
 	if i, ok := s.find(a.File, a.Line, a.Type); ok {
 		existing[i].Comment = a.Comment
+		existing[i].EndLine = a.EndLine
 		return
 	}
 	s.annotations[a.File] = append(existing, a)

annotation/store_test.go

@@ -27,6 +27,28 @@ func TestStore_AddReplacesExisting(t *testing.T) {
 	assert.Equal(t, "new comment", anns[0].Comment)
 }
 
+func TestStore_AddReplacesExistingPreservesEndLine(t *testing.T) {
+	s := NewStore()
+	s.Add(Annotation{File: "handler.go", Line: 43, Type: "+", Comment: "old comment", EndLine: 0})
+	s.Add(Annotation{File: "handler.go", Line: 43, Type: "+", Comment: "refactor this hunk", EndLine: 67})
+
+	anns := s.Get("handler.go")
+	require.Len(t, anns, 1)
+	assert.Equal(t, "refactor this hunk", anns[0].Comment)
+	assert.Equal(t, 67, anns[0].EndLine, "EndLine should be updated on replacement")
+}
+
+func TestStore_AddReplacesExistingClearsEndLine(t *testing.T) {
+	s := NewStore()
+	s.Add(Annotation{File: "handler.go", Line: 43, Type: "+", Comment: "refactor this hunk", EndLine: 67})
+	s.Add(Annotation{File: "handler.go", Line: 43, Type: "+", Comment: "just a note", EndLine: 0})
+
+	anns := s.Get("handler.go")
+	require.Len(t, anns, 1)
+	assert.Equal(t, "just a note", anns[0].Comment)
+	assert.Equal(t, 0, anns[0].EndLine, "EndLine should be cleared when replacement has no range")
+}
+
 func TestStore_AddMultipleLines(t *testing.T) {
 	s := NewStore()
 	s.Add(Annotation{File: "handler.go", Line: 43, Type: "+", Comment: "first"})

…plans/20260406-hunk-keyword-expansion.md …leted/20260406-hunk-keyword-expansion.mddocs/plans/20260406-hunk-keyword-expansion.md renamed to docs/plans/completed/20260406-hunk-keyword-expansion.md docs/plans/20260406-hunk-keyword-expansion.md renamed to docs/plans/completed/20260406-hunk-keyword-expansion.md

@@ -50,10 +50,10 @@ Add an `EndLine` field to `Annotation`. When creating an annotation, if the comm
 
 ### Task 3: Verify and document
 
-- [ ] run full test suite: `make test`
-- [ ] run linter: `make lint`
-- [ ] manual test: annotate a line with "fix this hunk", verify output shows range
-- [ ] update README.md output format section to mention range expansion
-- [ ] update site/docs.html output format section
-- [ ] update CLAUDE.md if needed
-- [ ] move this plan to `docs/plans/completed/`
+- [x] run full test suite: `make test`
+- [x] run linter: `make lint`
+- [x] manual test (skipped - not automatable)
+- [x] update README.md output format section to mention range expansion
+- [x] update site/docs.html output format section
+- [x] update CLAUDE.md if needed
+- [x] move this plan to `docs/plans/completed/`

site/docs.html

@@ -431,9 +431,13 @@ <h2 id="output-format">Output format</h2>
 <span class="code-comment">## handler.go:43 (+)</span>
 use errors.Is() instead of direct comparison
 
+<span class="code-comment">## handler.go:43-67 (+)</span>
+refactor this hunk to reduce nesting
+
 <span class="code-comment">## store.go:18 (-)</span>
 don't remove this validation</code></div>
         <p>Each annotation block: <code>## filename:line (type)</code> where type is <code>(+)</code> added, <code>(-)</code> removed, or <code>(file-level)</code>.</p>
+        <p>When annotation text contains keywords &ldquo;hunk&rdquo; or &ldquo;block&rdquo; (case-insensitive, whole word), the output header automatically expands to include the full hunk line range (e.g., <code>handler.go:43-67 (+)</code> instead of <code>handler.go:43 (+)</code>). This gives AI consumers the range context without any extra steps.</p>
 
         <h2 id="integration">Integration with other tools</h2>
         <p>The structured stdout output works with any tool that can read text:</p>

ui/annotate.go

@@ -232,7 +232,9 @@ func (m Model) diffLineNum(dl diff.DiffLine) int {
 }
 
 // hunkEndLine returns the display line number of the last line in the change hunk
-// containing diffLines[idx]. returns 0 if idx is not inside a change hunk.
+// containing diffLines[idx]. only walks forward through lines of the same change type
+// as the starting line, so both start and end use the same number space (old or new).
+// returns 0 if idx is not inside a change hunk.
 func (m Model) hunkEndLine(idx int) int {
 	if idx < 0 || idx >= len(m.diffLines) {
 		return 0
@@ -242,11 +244,11 @@ func (m Model) hunkEndLine(idx int) int {
 		return 0
 	}
 
-	// walk forward from idx to find the last contiguous change line
+	// walk forward from idx to find the last contiguous line of the same change type
+	startType := dl.ChangeType
 	last := idx
 	for i := idx + 1; i < len(m.diffLines); i++ {
-		ct := m.diffLines[i].ChangeType
-		if ct != diff.ChangeAdd && ct != diff.ChangeRemove {
+		if m.diffLines[i].ChangeType != startType {
 			break
 		}
 		last = i

ui/model_test.go

@@ -963,20 +963,20 @@ func TestModel_AnnotateHunkKeywordSetsEndLine(t *testing.T) {
 		assert.Equal(t, 3, anns[0].EndLine, "EndLine should be last add line's NewNum")
 	})
 
-	t.Run("block keyword populates EndLine", func(t *testing.T) {
+	t.Run("block keyword on single remove in mixed hunk", func(t *testing.T) {
 		m := testModel([]string{"a.go"}, nil)
 		m.tree = newFileTree([]string{"a.go"})
 		m.focus = paneDiff
 		m.currFile = "a.go"
 		m.diffLines = lines
-		m.diffCursor = 1 // on "old line" (remove, OldNum=2)
+		m.diffCursor = 1 // on "old line" (remove, OldNum=2) — only one remove in this hunk
 		m.startAnnotation()
 		m.annotateInput.SetValue("review this BLOCK carefully")
 		m.saveAnnotation()
 		anns := m.store.Get("a.go")
 		require.Len(t, anns, 1)
 		assert.Equal(t, 2, anns[0].Line)
-		assert.Equal(t, 3, anns[0].EndLine, "EndLine should be last add line's NewNum")
+		assert.Equal(t, 0, anns[0].EndLine, "single remove line, no multi-line range")
 	})
 
 	t.Run("no keyword does not set EndLine", func(t *testing.T) {
@@ -1021,11 +1021,11 @@ func TestModel_HunkEndLine(t *testing.T) {
 	m := testModel(nil, nil)
 	m.diffLines = lines
 
-	t.Run("returns last line of hunk from first change", func(t *testing.T) {
-		assert.Equal(t, 3, m.hunkEndLine(1), "hunk ending at add NewNum=3")
+	t.Run("remove line stops at same type boundary", func(t *testing.T) {
+		assert.Equal(t, 2, m.hunkEndLine(1), "single remove stays in old-file number space")
 	})
-	t.Run("returns last line from middle of hunk", func(t *testing.T) {
-		assert.Equal(t, 3, m.hunkEndLine(2))
+	t.Run("add line walks through consecutive adds", func(t *testing.T) {
+		assert.Equal(t, 3, m.hunkEndLine(2), "two adds, last NewNum=3")
 	})
 	t.Run("returns last line from last change line", func(t *testing.T) {
 		assert.Equal(t, 3, m.hunkEndLine(3))
@@ -1037,6 +1037,142 @@ func TestModel_HunkEndLine(t *testing.T) {
 		assert.Equal(t, 0, m.hunkEndLine(-1))
 		assert.Equal(t, 0, m.hunkEndLine(99))
 	})
+
+	t.Run("mixed hunk removes followed by adds", func(t *testing.T) {
+		// simulates a real diff where 3 lines are removed and 2 added
+		mixedLines := []diff.DiffLine{
+			{OldNum: 10, NewNum: 10, Content: "ctx", ChangeType: diff.ChangeContext},
+			{OldNum: 11, Content: "old line 1", ChangeType: diff.ChangeRemove},
+			{OldNum: 12, Content: "old line 2", ChangeType: diff.ChangeRemove},
+			{OldNum: 13, Content: "old line 3", ChangeType: diff.ChangeRemove},
+			{NewNum: 11, Content: "new line 1", ChangeType: diff.ChangeAdd},
+			{NewNum: 12, Content: "new line 2", ChangeType: diff.ChangeAdd},
+			{OldNum: 14, NewNum: 13, Content: "ctx", ChangeType: diff.ChangeContext},
+		}
+		m.diffLines = mixedLines
+
+		// cursor on first remove: end should be last remove (OldNum=13), not any add line
+		assert.Equal(t, 13, m.hunkEndLine(1), "remove hunk end stays in old-file space")
+		// cursor on middle remove
+		assert.Equal(t, 13, m.hunkEndLine(2), "middle remove walks to last remove")
+		// cursor on last remove
+		assert.Equal(t, 13, m.hunkEndLine(3), "last remove returns own OldNum")
+
+		// cursor on first add: end should be last add (NewNum=12), not a remove
+		assert.Equal(t, 12, m.hunkEndLine(4), "add hunk end stays in new-file space")
+		// cursor on last add
+		assert.Equal(t, 12, m.hunkEndLine(5), "last add returns own NewNum")
+	})
+}
+
+func TestModel_AnnotateReAnnotateKeywordChange(t *testing.T) {
+	lines := []diff.DiffLine{
+		{OldNum: 1, NewNum: 1, Content: "ctx before", ChangeType: diff.ChangeContext},
+		{NewNum: 2, Content: "new line", ChangeType: diff.ChangeAdd},
+		{NewNum: 3, Content: "added line", ChangeType: diff.ChangeAdd},
+		{OldNum: 2, NewNum: 4, Content: "ctx after", ChangeType: diff.ChangeContext},
+	}
+
+	t.Run("add keyword to existing annotation updates EndLine", func(t *testing.T) {
+		m := testModel([]string{"a.go"}, nil)
+		m.tree = newFileTree([]string{"a.go"})
+		m.focus = paneDiff
+		m.currFile = "a.go"
+		m.diffLines = lines
+		m.diffCursor = 1 // on "new line" (add, NewNum=2)
+		m.startAnnotation()
+		m.annotateInput.SetValue("this is fine")
+		m.saveAnnotation()
+		anns := m.store.Get("a.go")
+		require.Len(t, anns, 1)
+		assert.Equal(t, 0, anns[0].EndLine, "initially no EndLine")
+
+		// re-annotate same line with hunk keyword
+		m.startAnnotation()
+		m.annotateInput.SetValue("refactor this hunk")
+		m.saveAnnotation()
+		anns = m.store.Get("a.go")
+		require.Len(t, anns, 1)
+		assert.Equal(t, "refactor this hunk", anns[0].Comment)
+		assert.Equal(t, 3, anns[0].EndLine, "EndLine should be set after adding keyword")
+	})
+
+	t.Run("remove keyword from existing annotation clears EndLine", func(t *testing.T) {
+		m := testModel([]string{"a.go"}, nil)
+		m.tree = newFileTree([]string{"a.go"})
+		m.focus = paneDiff
+		m.currFile = "a.go"
+		m.diffLines = lines
+		m.diffCursor = 1
+		m.startAnnotation()
+		m.annotateInput.SetValue("refactor this hunk")
+		m.saveAnnotation()
+		anns := m.store.Get("a.go")
+		require.Len(t, anns, 1)
+		assert.Equal(t, 3, anns[0].EndLine, "initially has EndLine")
+
+		// re-annotate same line without keyword
+		m.startAnnotation()
+		m.annotateInput.SetValue("just a note")
+		m.saveAnnotation()
+		anns = m.store.Get("a.go")
+		require.Len(t, anns, 1)
+		assert.Equal(t, "just a note", anns[0].Comment)
+		assert.Equal(t, 0, anns[0].EndLine, "EndLine should be cleared after removing keyword")
+	})
+}
+
+func TestModel_AnnotateSingleLineHunkWithKeyword(t *testing.T) {
+	// single change line: hunkEndLine returns the same lineNum, so endLine > lineNum is false
+	lines := []diff.DiffLine{
+		{OldNum: 1, NewNum: 1, Content: "ctx before", ChangeType: diff.ChangeContext},
+		{NewNum: 2, Content: "single add", ChangeType: diff.ChangeAdd},
+		{OldNum: 2, NewNum: 3, Content: "ctx after", ChangeType: diff.ChangeContext},
+	}
+
+	m := testModel([]string{"a.go"}, nil)
+	m.tree = newFileTree([]string{"a.go"})
+	m.focus = paneDiff
+	m.currFile = "a.go"
+	m.diffLines = lines
+	m.diffCursor = 1 // on "single add" (add, NewNum=2)
+	m.startAnnotation()
+	m.annotateInput.SetValue("refactor this hunk")
+	m.saveAnnotation()
+
+	anns := m.store.Get("a.go")
+	require.Len(t, anns, 1)
+	assert.Equal(t, 2, anns[0].Line)
+	assert.Equal(t, 0, anns[0].EndLine, "single-line hunk should not set EndLine (avoids 2-2 range)")
+}
+
+func TestModel_AnnotateRemovedLineInMixedHunk(t *testing.T) {
+	// mixed hunk: 2 removes followed by 2 adds — annotating a remove line with hunk keyword
+	// should produce EndLine in the old-file number space, not crossing into the add lines
+	lines := []diff.DiffLine{
+		{OldNum: 10, NewNum: 10, Content: "ctx before", ChangeType: diff.ChangeContext},
+		{OldNum: 11, Content: "removed 1", ChangeType: diff.ChangeRemove},
+		{OldNum: 12, Content: "removed 2", ChangeType: diff.ChangeRemove},
+		{NewNum: 11, Content: "added 1", ChangeType: diff.ChangeAdd},
+		{NewNum: 12, Content: "added 2", ChangeType: diff.ChangeAdd},
+		{OldNum: 13, NewNum: 13, Content: "ctx after", ChangeType: diff.ChangeContext},
+	}
+
+	m := testModel([]string{"a.go"}, nil)
+	m.tree = newFileTree([]string{"a.go"})
+	m.focus = paneDiff
+	m.currFile = "a.go"
+	m.diffLines = lines
+	m.diffCursor = 1 // on first remove (OldNum=11)
+	m.startAnnotation()
+	m.annotateInput.SetValue("fix this hunk")
+	m.saveAnnotation()
+
+	anns := m.store.Get("a.go")
+	require.Len(t, anns, 1)
+	assert.Equal(t, 11, anns[0].Line, "start line is OldNum of first remove")
+	assert.Equal(t, 12, anns[0].EndLine, "end line is OldNum of last remove, not NewNum of an add")
+	assert.Equal(t, string(diff.ChangeRemove), anns[0].Type)
 }
 
 func TestModel_AnnotateEscCancels(t *testing.T) {