Handle GitHub comment node encoding fragility

[leynos]

Summary

• document and fall back when GitHub comment node encoding changes
• describe node ID assumptions and REST fallback in docs

Testing

• make fmt
• make lint
• make test
• make markdownlint
• make nixie

---

https://chatgpt.com/codex/tasks/task_e_68c06493d49c83228169762681f7aaa2

Summary by Sourcery

Improve robustness of pull request review thread resolution by falling back to GitHub’s REST API when GraphQL node encoding changes

Enhancements:

• Extract thread ID parsing into a helper function
• Add fetch_comment_node_id to retrieve the node_id via REST and integrate it as a fallback in resolve_comment
• Adjust resolve_comment to retry the GraphQL lookup using the REST-obtained node_id on failure

Documentation:

• Document the base64 node ID assumptions and the REST fallback behavior in the design guide

[sourcery-ai]

Reviewer's Guide

Adds a robust fallback for resolving GitHub review comment threads by first attempting the existing GraphQL lookup and then falling back to the REST API if the base64 node encoding changes, accompanied by helper functions and updated documentation.

Sequence diagram for robust GitHub comment thread resolution

sequenceDiagram
    participant Client
    participant GraphQL API
    participant REST API
    Client->>GraphQL API: Query thread using base64 node id
    alt GraphQL lookup succeeds
        GraphQL API-->>Client: Return thread id
    else GraphQL lookup fails
        Client->>REST API: Fetch comment node_id
        REST API-->>Client: Return node_id
        Client->>GraphQL API: Query thread using REST node_id
        GraphQL API-->>Client: Return thread id
    end

Loading

Class diagram for new and updated comment resolution helpers

classDiagram
    class GraphQLClient {
        +run_query(query: &str, variables: Value) : Result<Value, Error>
    }
    class RepoInfo {
        +owner: String
        +name: String
    }
    class VkError {
        +RequestContext
        +BadResponse
    }
    class CommentRef {
        +comment_id: u64
        +thread_id: Option<String>
    }
    class resolve_comment {
        +resolve_comment(token: &str, reference: &CommentRef, reply: Option<&str>) : Result<(), VkError>
    }
    class thread_id_from_lookup {
        +thread_id_from_lookup(lookup: &Value) : Option<&str>
    }
    class fetch_comment_node_id {
        +fetch_comment_node_id(token: &str, repo: &RepoInfo, comment_id: u64) : Result<String, VkError>
    }
    resolve_comment --> GraphQLClient
    resolve_comment --> thread_id_from_lookup
    resolve_comment --> fetch_comment_node_id
    fetch_comment_node_id --> RepoInfo
    fetch_comment_node_id --> VkError
    thread_id_from_lookup --> VkError

Loading

File-Level Changes

Change	Details	Files
Extract thread ID via a new helper for cleaner JSON parsing.	Added thread_id_from_lookup to parse nested JSON fields Included doc comments and examples for the helper	src/resolve.rs
Implement REST API fallback to fetch the comment node ID.	Created async fetch_comment_node_id using reqwest Handled request/parse errors with VkError variants Documented usage and error behavior	src/resolve.rs
Enhance resolve_comment to attempt GraphQL then REST fallback.	Base64-encode the comment node and run the GraphQL query Match on lookup failure to invoke REST fallback and retry Removed cfg qualifiers around github_client and imports Added comments explaining the fallback logic	src/resolve.rs
Update design docs to describe the new fallback mechanism.	Expanded vk-design.md to explain base64 assumptions and REST retry Clarified token requirements and command behavior	docs/vk-design.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Summary by CodeRabbit

• New Features

  • More reliable “Resolve thread” behaviour with a fallback path that uses REST if GraphQL lookup fails (behind the unstable-rest-resolve feature).
  • Optional ability to post a reply before resolving a thread when using unstable-rest-resolve.

• Documentation

  • Updated guidance on resolving threads, including fallback behaviour, token requirements, and reply-before-resolve notes.

• Tests

  • Added integration test validating the GraphQL-to-REST fallback flow during thread resolution.

Walkthrough

Summarise the resolve flow change: query GraphQL for a thread using a synthesised comment node ID; if that lookup fails and the feature flag unstable-rest-resolve is enabled, fetch the comment's node_id via REST, re-query GraphQL for the thread, then run the resolveThread mutation. Add helper to extract thread IDs and conditionally accept an optional reply message.

Changes

Cohort / File(s)	Summary
Docs: Resolve threads docs/vk-design.md	Update description to use a synthesised base64 comment node ID for GraphQL lookup, document REST fallback when unstable-rest-resolve is enabled, note unchanged GITHUB_TOKEN requirement and reply-before-resolve behaviour.
Core: Resolve logic & feature-gated fallback src/resolve.rs	Add thread_id_from_lookup helper. Change GraphQL lookup to use PullRequestReviewComment:<id> base64 id. Under unstable-rest-resolve, add REST path fetch_comment_node_id to obtain comment.node_id and retry GraphQL; gate imports/logging with cfg. Add feature-gated message: Option<String> parameter to resolve_comment. Retain final RESOLVE_THREAD_MUTATION.
Tests: REST fallback integration test tests/resolve.rs	Add async, feature-gated test resolve_falls_back_to_rest using a MITM server to mock mixed GraphQL/REST responses and assert request order: POST /graphql → GET /repos/.../pulls/comments/1 → POST /graphql → POST /graphql.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant U as User CLI
  participant R as resolve_comment
  participant GQL as GitHub GraphQL
  participant REST as GitHub REST

  U->>R: Resolve PR review comment
  R->>GQL: Query thread by node id (base64 "PullRequestReviewComment:<id>")
  alt Thread id returned
    GQL-->>R: threadId
  else Not found / GraphQL lookup empty/error
    note right of R #FFDDAA: Feature gated fallback\n`unstable-rest-resolve` only
    R->>REST: GET /repos/{owner}/{repo}/pulls/comments/{id}
    REST-->>R: comment.node_id
    R->>GQL: Re-query thread by comment.node_id
    GQL-->>R: threadId
  end
  R->>GQL: Mutation RESOLVE_THREAD_MUTATION(threadId, optional message)
  GQL-->>R: resolve response
  R-->>U: Completed

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Pre-merge checks (3 passed)

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	Accept the title as it succinctly and accurately describes the primary change — handling GitHub comment node encoding fragility — and is concise, specific, and relevant to the changeset. Ensure it maps to the code and documentation updates that add a REST fallback and document node-id assumptions. Keep the title as-is.
Description Check	✅ Passed	Accept the PR description because it directly relates to the changeset by documenting purpose, code changes (REST fallback and helper), documentation updates, and testing commands. Ensure the description's testing steps and task link remain accurate and reproducible for reviewers. Keep the description as-is for this check and expand later if reviewers request more implementation details.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

Poem

Threads once hidden, now recalled,
GraphQL first, then REST when stalled.
Base64 nudges, node_ids align,
One more query, then resolve in time.
Tests clap four calls — succeed, refined.

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between bc22ae4 and 638801d.

📒 Files selected for processing (3)

• docs/vk-design.md (1 hunks)
• src/resolve.rs (4 hunks)
• tests/resolve.rs (1 hunks)

🧰 Additional context used

📓 Path-based instructions (3)

**/*.rs

📄 CodeRabbit inference engine (AGENTS.md)

**/*.rs: Every module must begin with a module level (//!) comment explaining the module's purpose and utility.
Document public APIs using Rustdoc comments (///) so documentation can be generated with cargo doc.
Place function attributes after doc comments.
Do not use return in single-line functions.
Use predicate functions for conditional criteria with more than two branches.
Prefer immutable data and avoid unnecessary mut bindings.
Handle errors with the Result type instead of panicking where feasible.
Prefer semantic error enums: Derive std::error::Error (via the thiserror crate) for any condition the caller might inspect, retry, or map to an HTTP status.
Use an opaque error only at the app boundary: Use eyre::Report for human-readable logs; these should not be exposed in public APIs.
Never export the opaque type from a library: Convert to domain enums at API boundaries, and to eyre only in the main main() entrypoint or top-level async task.
Clippy warnings MUST be disallowed.
Fix any warnings emitted during tests in the code itself rather than silencing them.
Where a function is too long, extract meaningfully named helper functions adhering to separation of concerns and CQRS.
Where a function has too many parameters, group related parameters in meaningfully named structs.
Where a function is returning a large error consider using Arc to reduce the amount of data returned.
Write unit and behavioural tests for new functionality. Run both before and after making any change.
Avoid unsafe code unless absolutely necessary and document any usage clearly.
Lints must not be silenced except as a last resort.
Lint rule suppressions must be tightly scoped and include a clear reason.
Prefer expect over allow.
Prefer .expect() over .unwrap().
Use concat!() to combine long string literals rather than escaping newlines with a backslash.

Files:

• tests/resolve.rs
• src/resolve.rs

---

⚙️ CodeRabbit configuration file

**/*.rs: * Seek to keep the cyclomatic complexity of functions no more than 12.

• Adhere to single responsibility and CQRS

• Place function attributes after doc comments.

• Do not use return in single-line functions.

• Move conditionals with >2 branches into a predicate function.

• Avoid unsafe unless absolutely necessary.

• Every module must begin with a //! doc comment that explains the module's purpose and utility.

• Comments and docs must follow en-GB-oxendict (-ize / -our) spelling and grammar

• Lints must not be silenced except as a last resort.

  • #[allow] is forbidden.
  • Only narrowly scoped #[expect(lint, reason = "...")] is allowed.
  • No lint groups, no blanket or file-wide suppression.
  • Include FIXME: with link if a fix is expected.

• Where code is only used by specific features, it must be conditionally compiled or a conditional expectation for unused_code applied.

• Use rstest fixtures for shared setup and to avoid repetition between tests.

• Replace duplicated tests with #[rstest(...)] parameterised cases.

• Prefer mockall for mocks/stubs.

• Prefer .expect() over .unwrap()

• Ensure that any API or behavioural changes are reflected in the documentation in docs/

• Ensure that any completed roadmap steps are recorded in the appropriate roadmap in docs/

• Files must not exceed 400 lines in length

  • Large modules must be decomposed
  • Long match statements or dispatch tables should be decomposed by domain and collocated with targets
  • Large blocks of inline data (e.g., test fixtures, constants or templates) must be moved to external files and inlined at compile-time or loaded at run-time.

• Environment access (env::set_var and env::remove_var) are always unsafe in Rust 2024 and MUST be marked as such

  • For testing of functionality depending upon environment variables, dependency injection and the mockable crate are the preferred option.
  • If mockable cannot be used, env mutations in tests ...

Files:

• tests/resolve.rs
• src/resolve.rs

docs/**/*.md

📄 CodeRabbit inference engine (AGENTS.md)

docs/**/*.md: Use the markdown files within the docs/ directory as a knowledge base and source of truth for project requirements, dependency choices, and architectural decisions.
Proactively update the relevant file(s) in the docs/ directory to reflect the latest state when new decisions are made, requirements change, libraries are added/removed, or architectural patterns evolve.

Files:

• docs/vk-design.md

**/*.md

📄 CodeRabbit inference engine (AGENTS.md)

**/*.md: Documentation must use en-GB-oxendict spelling and grammar, except for the naming of the "LICENSE" file.
Validate Markdown files using make markdownlint.
Run make fmt after any documentation changes to format all Markdown files and fix table markup.
Validate Mermaid diagrams in Markdown files by running make nixie.
Markdown paragraphs and bullet points must be wrapped at 80 columns.
Code blocks in Markdown must be wrapped at 120 columns.
Tables and headings in Markdown must not be wrapped.
Use dashes (-) for list bullets in Markdown.
Use GitHub-flavoured Markdown footnotes ([^1]) for references and footnotes.

Files:

• docs/vk-design.md

---

⚙️ CodeRabbit configuration file

**/*.md: * Avoid 2nd person or 1st person pronouns ("I", "you", "we")

• Use en-GB-oxendict (-ize / -our) spelling and grammar
• Headings must not be wrapped.
• Documents must start with a level 1 heading
• Headings must correctly increase or decrease by no more than one level at a time
• Use GitHub-flavoured Markdown style for footnotes and endnotes.
• Numbered footnotes must be numbered by order of appearance in the document.

Files:

• docs/vk-design.md

🧬 Code graph analysis (2)

tests/resolve.rs (1)

tests/utils/mod.rs (3)

• shutdown (30-33)
• start_mitm (49-98)
• vk_cmd (109-117)

src/resolve.rs (1)

src/review_threads/tests.rs (1)

• repo (16-21)

🔇 Additional comments (6)

src/resolve.rs (5)

11-12: Feature-gated logging — LGTM

Warn logging is correctly gated to avoid unused imports without the feature.

---

36-51: Helper is precise and documented — LGTM

The extractor is tight, null-safe, and documented with a runnable example.

---

232-258: REST fallback with warnings — LGTM

Fallback is correctly gated; warnings make the behaviour observable without being noisy.

---

259-266: Non‑REST path — LGTM

The non‑feature path cleanly errors on missing thread id.

---

187-196: Stabilise public signature: always accept message: Option

Normalise the API by taking message: Option unconditionally and discarding it when the feature is disabled. Verify there are no callers before changing the signature.

Run these in the repo root to find callers and feature usage:

rg -nP -uu 'resolve_comment\s*\(' || true
rg -nP -uu '(?:\b(?:crate|self|super|[A-Za-z_]\w*)::)+resolve_comment\s*\(' || true
rg -n 'unstable-rest-resolve' || true
rg -n 'pub async fn resolve_comment' || true

If no callers rely on the cfg-dependent signature, apply this diff:

-pub async fn resolve_comment(
-    token: &str,
-    reference: CommentRef<'_>,
-    #[cfg(feature = "unstable-rest-resolve")] message: Option<String>,
-) -> Result<(), VkError> {
+pub async fn resolve_comment(
+    token: &str,
+    reference: CommentRef<'_>,
+    message: Option<String>,
+) -> Result<(), VkError> {
@@
-    #[cfg(feature = "unstable-rest-resolve")]
-    let (repo, pull_number) = (reference.repo, reference.pull_number);
+    #[cfg(not(feature = "unstable-rest-resolve"))]
+    let _ = &message;
+    #[cfg(feature = "unstable-rest-resolve")]
+    let (repo, pull_number) = (reference.repo, reference.pull_number);

tests/resolve.rs (1)

101-149: Fallback-to-REST path — LGTM

The sequence asserts the expected GraphQL→REST→GraphQL flow.

✨ Finishing touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch codex/document-github-id-format-dependency

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[leynos]

@coderabbitai Have the following now been resolved?

• Guard github_client and fetch_comment_node_id behind the unstable-rest-resolve feature so you don’t pull in reqwest and REST fallback logic when the feature is disabled.
• In fetch_comment_node_id, explicitly check for non-2xx HTTP status codes before calling .json() so you can return a more descriptive error on 404s or rate limits.
• Add a warning or debug log when you fall back to the REST API after a GraphQL lookup failure so users know when the encoding assumption has changed.

[leynos]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/resolve.rs (1)

168-171: Stabilise the public function signature across features.

Avoid feature-dependent parameter lists on resolve_comment; it complicates downstream usage and breaks API compatibility when the feature is toggled.

Apply this diff:

-pub async fn resolve_comment(
-    token: &str,
-    reference: CommentRef<'_>,
-    #[cfg(feature = "unstable-rest-resolve")] message: Option<String>,
-) -> Result<(), VkError> {
+pub async fn resolve_comment(
+    token: &str,
+    reference: CommentRef<'_>,
+    message: Option<String>,
+) -> Result<(), VkError> {

And add a no-op binding when the feature is disabled:

@@
     let comment_id = reference.comment_id;
-    #[cfg(feature = "unstable-rest-resolve")]
+    #[cfg(feature = "unstable-rest-resolve")]
     let (repo, pull_number) = (reference.repo, reference.pull_number);
+    #[cfg(not(feature = "unstable-rest-resolve"))]
+    let _ = message;

♻️ Duplicate comments (1)

docs/vk-design.md (1)

42-44: Spelling now conforms to en-GB-oxendict (-ize).

‘synthesizing’ with -ize is correct. No further action.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 53ba608 and bc22ae4.

📒 Files selected for processing (3)

• docs/vk-design.md (1 hunks)
• src/resolve.rs (4 hunks)
• tests/resolve.rs (1 hunks)

🧰 Additional context used

📓 Path-based instructions (2)

**/*.md

⚙️ CodeRabbit configuration file

**/*.md: * Avoid 2nd person or 1st person pronouns ("I", "you", "we")

• Use en-GB-oxendict (-ize / -our) spelling and grammar
• Headings must not be wrapped.
• Documents must start with a level 1 heading
• Headings must correctly increase or decrease by no more than one level at a time
• Use GitHub-flavoured Markdown style for footnotes and endnotes.
• Numbered footnotes must be numbered by order of appearance in the document.

Files:

• docs/vk-design.md

**/*.rs

⚙️ CodeRabbit configuration file

**/*.rs: * Seek to keep the cyclomatic complexity of functions no more than 12.

• Adhere to single responsibility and CQRS

• Place function attributes after doc comments.

• Do not use return in single-line functions.

• Move conditionals with >2 branches into a predicate function.

• Avoid unsafe unless absolutely necessary.

• Every module must begin with a //! doc comment that explains the module's purpose and utility.

• Comments and docs must follow en-GB-oxendict (-ize / -our) spelling and grammar

• Lints must not be silenced except as a last resort.

  • #[allow] is forbidden.
  • Only narrowly scoped #[expect(lint, reason = "...")] is allowed.
  • No lint groups, no blanket or file-wide suppression.
  • Include FIXME: with link if a fix is expected.

• Where code is only used by specific features, it must be conditionally compiled or a conditional expectation for unused_code applied.

• Use rstest fixtures for shared setup and to avoid repetition between tests.

• Replace duplicated tests with #[rstest(...)] parameterised cases.

• Prefer mockall for mocks/stubs.

• Prefer .expect() over .unwrap()

• Ensure that any API or behavioural changes are reflected in the documentation in docs/

• Ensure that any completed roadmap steps are recorded in the appropriate roadmap in docs/

• Files must not exceed 400 lines in length

  • Large modules must be decomposed
  • Long match statements or dispatch tables should be decomposed by domain and collocated with targets
  • Large blocks of inline data (e.g., test fixtures, constants or templates) must be moved to external files and inlined at compile-time or loaded at run-time.

• Environment access (env::set_var and env::remove_var) are always unsafe in Rust 2024 and MUST be marked as such

  • For testing of functionality depending upon environment variables, dependency injection and the mockable crate are the preferred option.
  • If mockable cannot be used, env mutations in tests ...

Files:

• src/resolve.rs
• tests/resolve.rs

🔍 Remote MCP Ref

Concise additional context for reviewing PR #121

• docs/vk-design.md — Documents the new thread-id lookup approach: build/query the comment node (base64 "PullRequestReviewComment:"), and if that fails fall back to fetching the comment's node_id via REST (when feature enabled). Notes the REST path posts a reply before resolving and that GITHUB_TOKEN / abort-on-no-token behavior is unchanged.

• src/resolve.rs — Key code changes:

  • Adds thread_id_from_lookup helper and a fetch_comment_node_id REST function (GET /repos/{owner}/{repo}/pulls/comments/{id}) guarded by #[cfg(feature = "unstable-rest-resolve")]. The REST fetch checks resp.status().is_success() and returns explicit VkError on non-2xx.
  • resolve_comment first attempts the GraphQL lookup; on missing/failing thread id it logs warn! and, if the feature is enabled, falls back to REST to obtain node_id then retries GraphQL.
  • Conditional imports (log::warn, reqwest, etc.) are feature-gated.
  • Public signature impact: resolve_comment gains an extra parameter message: Option behind the unstable-rest-resolve feature — i.e., the function's exported signature differs depending on the feature flag.

• tests/resolve.rs — Adds async test resolve_falls_back_to_rest (gated by unstable-rest-resolve) that runs a MITM server and asserts the request sequence and behavior: POST /graphql (empty), GET /repos/o/r/pulls/comments/1 (REST node_id), POST /graphql (thread id), POST /graphql (resolve).

• Cargo.toml — Defines the feature unstable-rest-resolve (empty feature).

Suggested review focus

• API compatibility: confirm the conditional change to resolve_comment's public signature is acceptable (crate consumers / semver implications).
• Feature gating: verify reqwest/log and the REST code are fully behind #[cfg(feature = "...")] and that building without the feature does not pull in reqwest.
• Tests & CI: ensure the new test is exercised in CI (or runs under the feature) and that docs match implemented behavior.

🔇 Additional comments (5)

tests/resolve.rs (1)

140-148: Validate expected fallback sequence.

The asserted call order correctly demonstrates GraphQL → REST → GraphQL → GraphQL. Good coverage.

src/resolve.rs (4)

11-12: Gate logging import correctly.

Feature-gate log::warn to avoid pulling the dependency when the feature is disabled. Good.

---

203-210: Document node-id synthesis inline and keep it minimal.

Lookup construction and initial query are correct and succinct. Good.

---

211-237: Log REST fallback entry points.

Warnings on both error and “missing thread id” paths meet the observability requirement. Good.

---

238-245: Return structured error when REST is disabled.

Non-feature path properly errors on missing thread id. Good.