fix(doc-api): retarget comment-anchor guidance to query.match wire shape#3433
Merged
caio-pizzol merged 2 commits intoMay 21, 2026
Merged
Conversation
… anchoring
highlightRange is snippet-relative (offset by up to SNIPPET_PADDING=30
chars from the start of the block). Telling LLMs to build target.range
from it produces silently mis-anchored comments or TARGET_NOT_FOUND
errors.
The correct field is context.textRanges[0], which is a complete
block-relative TextAddress ({kind:"text", blockId, range:{start,end}})
and can be passed straight through as the comment target.
Update the superdoc_comment tool description accordingly.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
(cherry picked from commit 16fca2d)
@bjohas correctly identified that highlightRange is snippet-relative and unsafe for comment ranges. The original patch pointed at items[0].context.textRanges[0], which is doc.find output shape. superdoc_search dispatches to doc.query.match, whose items expose {target, snippet, highlightRange, blocks} with no `context` field. Retarget the description prose and the prompt template to build the comment target from items[0].blocks: - single block: {kind: "text", blockId: blocks[0].blockId, range: blocks[0].range} - cross block: {kind: "text", segments: blocks.map(b => ({blockId: b.blockId, range: b.range}))} Both shapes are accepted by comments.create (TextAddress | TextTarget). items[0].target is a SelectionTarget and is not accepted. Regenerate the shipped MCP catalog and prompt artifacts, and add a regression test that pins the wire shape so the broken path can't be reintroduced. A related bug at packages/superdoc/AGENTS.md (same misuse of items[0].target) is a follow-up; separate PR. (cherry picked from commit cc0ebe16bc3aff2c31c8aec3fe3008fa017faf15)
Contributor
3 tasks
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
caio-pizzol
deleted the
caio-pizzol/comment-anchor-retarget-supersedes-3224
branch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Retargets @bjohas's #3224 to the actual API shape
superdoc_searchemits.@bjohas correctly spotted that
highlightRangeis snippet-relative and unsafe as a comment range. The original patch then pointed agents atresult.items[0].context.textRanges[0], which is thedoc.findoutput shape;superdoc_searchactually dispatches todoc.query.match, whose items carrytarget(a SelectionTarget),snippet,highlightRange, andblocks, with nocontextfield. The wire shape is verified at four layers: schema (schemas.ts:4960-4971), adapter source (query-match-adapter.ts:567-602), the existing test suite, and a runtime pinning test.The description and prompt template now build the target from
items[0].blocks: single-block matches use{kind:"text", blockId: blocks[0].blockId, range: blocks[0].range}; cross-block matches use aTextTargetwithsegments. Both are accepted bycomments.createperschemas.ts:4874-4878. The shipped MCP catalog and prompt artifacts are regenerated. A regression test inquery-match-adapter.test.tspins the wire shape so the broken path can't drift back.Supersedes #3224 only because GitHub blocks maintainer pushes to org-owned forks (the
OpenDevEdfork is an organization, not a user account). @bjohas's original commit is preserved here viacherry-pick -x, linking back to the source SHA.A related bug at
packages/superdoc/AGENTS.md:235(same misuse ofitems[0].targetagainstcomments.create) is out of scope here; will track separately.