feat(docs comments): add locate subcommand to resolve a comment to a body range

[sebsnyk]

Motivation

A comment carries quotedFileContent.value (the literal text the comment was anchored to at creation time). To act surgically on a comment ("delete the text the reviewer flagged", "wrap it in a hyperlink"), the script needs (startIndex, endIndex) in the current doc body. Today every consumer has to roll this resolution themselves, including HTML-entity unescaping (Drive sometimes returns ", &, ', ·, >, <) and whitespace normalisation.

This is the load-bearing primitive for any "comments to automated edits" workflow.

Depends on

• feat(docs): add find-range primitive that maps text to Document index ranges #682 find-range primitive — comments locate is find-range applied to the comment's quotedFileContent.value with whitespace normalisation + HTML-entity unescaping turned on by default. Without feat(docs): add find-range primitive that maps text to Document index ranges #682, this command duplicates the same walk-and-index logic; with feat(docs): add find-range primitive that maps text to Document index ranges #682 it is a thin specialisation.

Consumed by

• feat(docs write): pre-flight orphan-comment check on --replace --markdown #691 docs write --check-orphans — the orphan pre-flight runs comments locate per open comment and treats orphaned: true as a "would orphan" hit. Sharing the locate path between the two commands keeps the normalisation rules consistent (a comment that survives --check-orphans is also resolvable by locate after the write).

Repro

# Today:
quote=$(gog drive comments list <DOC_ID> --include-quoted -j --all | jq -r '.comments[0].quotedFileContent.value')
# Then manually walk gog docs raw to find the index range. About 30 lines of jq/awk.

Proposed surface

gog docs comments locate <docId> <commentId> [--tab=...]

JSON output:

{
  "commentId": "AAAA...",
  "matches": [
    {"startIndex": 1234, "endIndex": 1267, "tabId": "kix.abc"}
  ],
  "orphaned": false,
  "quote": "the literal text the comment was anchored to"
}

Returns orphaned: true and an empty matches array when the quoted text no longer appears in the body.

Acceptance criteria

• Returns the correct range for the most recent edit-state of the doc.
• Reports orphaned comments cleanly (no error; flag in payload + exit code 4 in plain mode).
• Handles the entity-encoded quote cases (", &, ', · etc.) without manual decoding.
• Works in tabs via --tab resolution.

References

• comments.get response shape: https://developers.google.com/workspace/drive/api/reference/rest/v3/comments/get
• quotedFileContent field: same page

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 4, 2026, 8:36 AM ET / 12:36 UTC.

Summary
Keep open: current main has Docs comment CRUD and internal literal range matching, but it does not provide docs comments locate, and the linked shared find-range primitive remains open prerequisite work.

Reproducibility: yes. source inspection is enough for this feature gap: current main registers Docs comment CRUD but no locate subcommand, and existing range helpers are private to other commands.

Next step
Maintainers need to sequence this with the open shared find-range primitive and settle the command, JSON/plain output, tab, and exit-code contract before implementation.

Review details

Best possible solution:

Land or approve the shared docs find-range primitive first, then implement docs comments locate as a thin wrapper over that resolver using Drive comment quote retrieval.

Do we have a high-confidence way to reproduce the issue?

Yes, source inspection is enough for this feature gap: current main registers Docs comment CRUD but no locate subcommand, and existing range helpers are private to other commands.

Is this the best way to solve the issue?

Unclear: the requested surface is plausible, but the maintainable path is to settle and reuse the shared find-range primitive rather than creating a second resolver inside comment handling.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• Implementing comments locate before the shared find-range primitive would likely duplicate normalization and body-walk logic.
• The requested plain-mode exit-code contract and tab behavior need maintainer confirmation before a fix PR is safe.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 3d5c9cef65fa.

Label changes

Label changes:

• add issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.
• add clawsweeper:source-repro: Current issue advisory state selects this label.
• add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.
• remove issue-rating: 🌊 off-meta tidepool: Current issue advisory state no longer selects this label.

Label justifications:

• P2: This is a normal-priority Docs automation primitive with limited blast radius but real scripting value.
• impact:other: The issue affects agent/script ability to act on Docs review comments, which is meaningful but outside the specific owned impact categories.

Evidence reviewed

Acceptance criteria:

• go test ./internal/cmd -run 'Docs.*Comments|FindRange|FindReplace|Format|Tab'

What I checked:

• Docs comments command surface lacks locate: DocsCommentsCmd registers list/get/add/reply/resolve/reopen/delete only; there is no locate subcommand on current main. (internal/cmd/docs_comments.go:12, 3d5c9cef65fa)
• Generated docs lack locate: The generated gog docs comments page lists the same seven subcommands and no locate command page is present. (docs/commands/gog-docs-comments.md:17, 3d5c9cef65fa)
• Comment quote data is available but not resolved: The comment helper fetches quotedFileContent for Docs comments and comment details, but it only renders the quote rather than mapping it to body ranges. (internal/cmd/comment_ops.go:17, 3d5c9cef65fa)
• Adjacent text-range helper is narrower than requested: findTextMatches returns ranges for literal paragraph text and tab-filtered target documents, but it does not expose a command, HTML-entity decode quotes, or support whitespace-normalized matching. (internal/cmd/docs_mutation.go:360, 3d5c9cef65fa)
• History points to current Docs/comment area owner: git log -S and blame for Docs comments, quotedFileContent, and findTextMatches all point to commit 2c84d89 as the visible history for the current implementation. (internal/cmd/docs_comments.go:14, 2c84d8981dd5)
• Linked prerequisite remains open: The supplied GitHub context shows this issue depends on feat(docs): add find-range primitive that maps text to Document index ranges #682, which is still open and tracks the shared find-range primitive.

Likely related people:

• Peter Steinberger: Blame and git log -S for DocsCommentsCmd, quotedFileContent, and findTextMatches all point to the current squashed implementation commit for this area. (role: current Docs/comment implementation author; confidence: medium; commits: 2c84d8981dd5; files: internal/cmd/docs_comments.go, internal/cmd/comment_ops.go, internal/cmd/docs_mutation.go)
• sebsnyk: The supplied issue context shows this contributor authored this request and the linked find-range and orphan-check issues that define the intended workflow. (role: workflow proposer; confidence: medium)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.