ace-review 0.57.1 → 0.58.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 865eb269684936c32eb5d91b002f98419e71b1c89155715bc486382bfa4549f3
-  data.tar.gz: 0a4bbea96d948953da5fd157c10ae83c5d6b548888663975342ae11823784195
+  metadata.gz: fda3bb688af1e2d4c71e6f37dc20d25c4f756703c3a2910827629975fd0965e1
+  data.tar.gz: a479d205b501a785063680654466e0eda84e5d00397cc74831dbffc24d106552
 SHA512:
-  metadata.gz: 70a1f4d8f88fb5d9971e961fc0918b5c0477e87a52447b877814b429775b3196c648f2d99f24b216453d30e685ea29da97cb62b93809743a8f26f484402ec622
-  data.tar.gz: 39a724d6327716608165c95de3955ae77528fd19baaf107cf035e7cdef2e99697647cc247797f9e72c8639a6535e962791fa12f70fe878a582c181e87e746b43
+  metadata.gz: b5d61e56ef9b7c8cd02a8c44130e4c0d43266d3327290e963136f36b442a596d6070b9736d94f46427265be4696bc43c4d0e8c69142eaa4fd5019a0e6db31b9c
+  data.tar.gz: 0dde4d996c5f713b5f5babfe57f03814cfe658d217207071da16f8248e387e14bad4916184e8175c0f603842efac319636a73d5e1394b6b92a7c29dea072b208

data/.ace-defaults/review/config.yml

@@ -9,7 +9,7 @@
 # context         - Default context preset (default: "project")
 # max_concurrent_models - Max parallel LLM queries for multi-model execution (default: 3)
 # auto_execute    - Auto-execute LLM query without confirmation (default: false)
-# gh_timeout      - Timeout for GitHub CLI operations in seconds (default: 30)
+# provider_timeout - Timeout for forge operations in seconds (default: 30)
 # gh_simple_timeout - Timeout for simple gh commands like --version, auth status (default: 10)
 # llm_timeout     - Timeout for LLM queries in seconds (default: 900)
 #
@@ -37,7 +37,7 @@ defaults:
   bundle: "project"
   max_concurrent_models: 3  # Max parallel LLM queries for multi-model execution
   auto_execute: false  # Set to true to auto-execute LLM query without confirmation
-  gh_timeout: 30  # Timeout for GitHub CLI operations in seconds
+  provider_timeout: 30  # Timeout for forge operations in seconds
   gh_simple_timeout: 10  # Timeout for simple gh commands (--version, auth status)
   llm_timeout: 900  # Timeout for LLM queries in seconds (15 minutes)
 

data/CHANGELOG.md

@@ -7,11 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.57.1] - 2026-10-02
+## [0.58.0] - 2026-10-02
 
-### Fixed
+### Added
+- Provider-neutral PR reviews and comment handling for GitHub, default Forgejo, and named Forgejo servers with exact-head evidence.
 
-- A failed or incomplete provider entry no longer invalidates a campaign session's completed reviewer executions; one completed reviewer per needed scope still completes the round.
+### Changed
+- Replaced `--gh-timeout` with `--provider-timeout`; removed the GitHub-only review fetcher, poster, and resolver paths.
+- Preserve provider and repository identity across review sessions and comments; fail closed on moved heads and collection errors.
 
 
 ## [0.57.0] - 2026-10-01

data/docs/feedback-workflow.md

@@ -23,7 +23,7 @@ Key benefits:
 
 1. Run a review with feedback extraction:
    ```bash
-   ace-review --preset code-pr --pr 123 --auto-execute
+   ace-review --preset code-valid --pr 123 --auto-execute
    ```
 
 2. List feedback items:
@@ -245,7 +245,7 @@ feedback:
 ### Example Workflow Configuration
 
 ```yaml
-# .ace/review/presets/code-pr.yml
+# .ace/review/presets/code-valid.yml
 presets:
   - code
 
@@ -416,10 +416,10 @@ Each review execution creates a new session:
 
 ```bash
 # First review
-ace-review --pr 189 --preset code-pr
+ace-review --pr 189 --preset code-valid
 
 # Second review (different PR or updated code)
-ace-review --pr 190 --preset code-pr
+ace-review --pr 190 --preset code-valid
 
 # List all sessions
 ls -la .ace-local/review/sessions/

data/docs/getting-started.md

@@ -38,7 +38,7 @@ This runs a code-focused review against your current branch diff and writes sess
 Run:
 
 ```bash
-ace-review --pr 123 --preset code-pr --auto-execute
+ace-review --pr 123 --preset code-valid --auto-execute
 ```
 
 Use `--post-comment` when you want to publish the review back to GitHub.

data/docs/usage.md

@@ -29,7 +29,7 @@ ace-review [OPTIONS]
 
 | Option | Description |
 |--------|-------------|
-| `--preset` | Review preset: code, code-pr, security, performance, docs |
+| `--preset` | Review preset from the shipped catalog, such as code-valid, code-fit, integration, or docs |
 | `--pr` | Review GitHub PR (number, URL, or owner/repo#number) |
 | `--subject` | Subject config (repeatable): `diff:range`, `diff:range -- path`, `files:glob`, `preset:name` |
 | `--context` | Context config (preset name or YAML) |
@@ -43,7 +43,8 @@ ace-review [OPTIONS]
 |--------|-------------|
 | `--pr-comments` | Include PR comments as feedback source (default: true for --pr) |
 | `--post-comment` | Post review as PR comment (requires --pr) |
-| `--gh-timeout` | Timeout for gh CLI operations in seconds (default: 30) |
+| `--server` / `--default-server` | Select a configured forge server for a PR review |
+| `--provider-timeout` | Timeout for forge operations in seconds (default: 30) |
 
 ### Prompt Composition
 

data/lib/ace/review/atoms/pr_comment_formatter.rb

@@ -20,20 +20,37 @@ module Ace
 
         # Format comments data into markdown report
         #
-        # @param comments_data [Hash] Data from GhPrCommentFetcher
+        # @param comments_data [Hash] normalized provider comment data
         # @return [String] Formatted markdown report
         def self.format(comments_data)
           return nil unless comments_data && comments_data[:success]
 
           pr_number = comments_data[:pr_number]
           pr_title = comments_data[:pr_title]
-          comments = comments_data[:comments] || []
-          reviews = comments_data[:reviews] || []
+          # Full provider evidence is preserved upstream; prompt feedback
+          # excludes bot posts, blank bodies, and our own session comments
+          # (they are not unresolved human feedback).
+          comments = (comments_data[:comments] || []).reject do |comment|
+            author = comment[:author].to_s
+            body = comment[:body].to_s
+            author.match?(/\b(bot|github-actions|ace-review)\b/i) ||
+              body.empty? ||
+              own_session_post?(body)
+          end
+          reviews = (comments_data[:reviews] || []).reject do |review|
+            review[:author].to_s.match?(/\b(bot|github-actions|ace-review)\b/i)
+          end
           review_threads = comments_data[:review_threads] || []
 
           # Build report sections
           frontmatter = build_frontmatter(comments_data)
           summary = build_summary(comments, reviews, review_threads, pr_number, pr_title)
+          # Apply the same bot filter to thread comments; threads left
+          # without human comments are omitted from feedback.
+          review_threads = review_threads.map do |thread|
+            filtered = thread.merge(comments: Array(thread[:comments]).reject { |c| c[:author].to_s.match?(/\b(bot|github-actions|ace-review)\b/i) })
+            filtered.merge(comments: filtered[:comments])
+          end.reject { |thread| Array(thread[:comments]).empty? }
           inline_section = build_inline_comments_section(review_threads)
           unresolved_section = build_unresolved_section(comments, reviews)
           resolved_section = build_resolved_section(reviews)
@@ -76,6 +93,7 @@ module Ace
           inline_thread_count = review_threads.size
           reviewers = extract_reviewers(comments, reviews, review_threads)
           unresolved_count = count_unresolved(comments, reviews, review_threads)
+          unknown_resolution = review_threads.count { |t| t[:is_resolved].nil? }
 
           summary = "# Developer Feedback from PR ##{pr_number}\n\n"
           summary += "> #{pr_title}\n\n" if pr_title && !pr_title.empty?
@@ -83,6 +101,7 @@ module Ace
           summary += "- Total comments: #{total_comments}\n"
           summary += "- Inline code comments: #{inline_thread_count}\n" if inline_thread_count > 0
           summary += "- Unresolved items: #{unresolved_count}\n"
+          summary += "- Unknown-resolution threads: #{unknown_resolution}\n" if unknown_resolution > 0
           summary += "- Reviewers: #{reviewers.map { |r| "@#{r}" }.join(", ")}\n" if reviewers.any?
           summary
         end
@@ -144,7 +163,11 @@ module Ace
             line = thread[:line]
             thread_id = thread[:id]
             is_resolved = thread[:is_resolved]
-            status = is_resolved ? "Resolved" : "Unresolved"
+            status = case is_resolved
+            when true then "Resolved"
+            when false then "Unresolved"
+            else "Resolution unknown"
+            end
 
             # Header with file:line, thread ID, and status
             location = line ? "#{path}:#{line}" : path
@@ -186,6 +209,14 @@ module Ace
           section
         end
 
+        # An ACE post carries our review header AND a well-formed session
+        # marker as the trailing hidden line. A human reply quoting an
+        # earlier comment rarely matches both, so quotes stay visible.
+        def self.own_session_post?(body)
+          return false unless body.start_with?("## Code Review - ace-review")
+          body.match?(/<!--\s*ace-review-session:[a-zA-Z0-9._:-]+\s*-->\s*\z/)
+        end
+
         # Build comments table for quick reference
         #
         # @param comments [Array<Hash>] Issue comments
@@ -256,7 +287,7 @@ module Ace
         # @param review_threads [Array<Hash>] Inline review threads
         # @return [Integer] Count of unresolved items
         def self.count_unresolved(comments, reviews, review_threads = [])
-          unresolved_threads = review_threads.count { |t| !t[:is_resolved] }
+          unresolved_threads = review_threads.count { |t| t[:is_resolved] == false }
           actionable_comments = comments.count { |c| actionable_comment?(c[:body]) }
           actionable_comments + reviews.count { |r| r[:state] == "CHANGES_REQUESTED" } + unresolved_threads
         end

data/lib/ace/review/cli/commands/review.rb

@@ -16,10 +16,11 @@ module Ace
             Execute code review using presets or custom configuration
 
             Presets provide pre-configured review types with focused prompts:
-              code         → General code review
-              code-pr      → PR-focused code review
-              security     → Security-focused review
-              performance  → Performance-focused review
+              code-valid   → Code correctness review
+              code-fit     → Code design review
+              code-shine   → Code quality review
+              integration  → Integration review
+              spec         → Specification review
               docs         → Documentation review
 
             Configuration:
@@ -31,13 +32,13 @@ module Ace
           DESC
 
           example [
-            "--preset code-pr             # PR code review",
-            "--preset security --auto-execute  # Run and apply fixes",
+            "--preset code-valid --pr 123  # PR code review",
+            "--preset code-fit --auto-execute  # Run and apply fixes",
             "--pr 123                      # Review by PR number",
             "--pr 123 --delta             # Delta round since the most recent prior session's head",
             "--pr 123 --delta <head>      # Delta round since an explicit reviewed head",
-            "--preset code --subject diff:HEAD~3 --subject files:docs/**/*.md",
-            "--preset security --dry-run   # Preview without executing"
+            "--preset code-valid --subject diff:HEAD~3 --subject files:docs/**/*.md",
+            "--preset code-fit --dry-run   # Preview without executing"
           ]
 
           # Review configuration options
@@ -58,10 +59,12 @@ module Ace
           option :auto_execute, type: :boolean, default: nil, desc: "Execute LLM query automatically"
           option :save_session, type: :boolean, desc: "Save session files (default: true)"
           option :session_dir, type: :string, desc: "Custom session directory"
-          option :pr, type: :string, desc: "Review GitHub PR (number, URL, or owner/repo#number)"
+          option :pr, type: :string, desc: "Review PR (number, URL, or owner/repo#number)"
+          option :server, type: :string, desc: "Use the named configured forge server"
+          option :default_server, type: :boolean, desc: "Use the configured default forge server"
           option :pr_comments, type: :boolean, desc: "Include PR comments as feedback source (default: true for --pr)"
           option :post_comment, type: :boolean, desc: "Post review as PR comment (requires --pr)"
-          option :gh_timeout, type: :integer, desc: "Timeout for gh CLI operations in seconds (default: 30)"
+          option :provider_timeout, type: :integer, desc: "Timeout for forge operations in seconds (default: 30)"
           option :evidence_session, type: :array, desc: "Include selected prior review sessions as context"
           option :delta, type: :string, optional_value: true,
             desc: "Delta round for --pr: review only changes since a reference head (explicit head, or `auto` to auto-resolve from the most recent prior session for this PR); omit for a full round"
@@ -106,7 +109,9 @@ module Ace
             end
 
             # Type-convert numeric options (ace-support-cli returns strings, Thor converted to integers)
-            cli_options[:gh_timeout] = cli_options[:gh_timeout]&.to_i if cli_options[:gh_timeout]
+            if cli_options[:provider_timeout]
+              cli_options[:provider_timeout] = cli_options[:provider_timeout].to_i
+            end
 
             # Build and store options for testing compatibility
             @options = build_review_options(cli_options)

data/lib/ace/review/errors.rb

@@ -32,74 +32,6 @@ module Ace
         end
       end
 
-      # Raised when gh CLI is not installed
-      class GhCliNotInstalledError < Error
-        def initialize
-          message = "GitHub CLI (gh) is not installed.\n"
-          message += "Install with:\n"
-          message += "  macOS: brew install gh\n"
-          message += "  Linux: See https://cli.github.com/manual/installation\n"
-          message += "  Windows: See https://cli.github.com/manual/installation"
-
-          super(message)
-        end
-      end
-
-      # Raised when user is not authenticated with GitHub
-      class GhAuthenticationError < Error
-        def initialize
-          message = "GitHub authentication required.\n"
-          message += "Run 'gh auth login' to authenticate with GitHub.\n"
-          message += "Check status: gh auth status"
-
-          super(message)
-        end
-      end
-
-      # Raised when a PR is not found
-      class PrNotFoundError < Error
-        attr_reader :pr_identifier
-
-        def initialize(pr_identifier, details = nil)
-          @pr_identifier = pr_identifier
-          message = "Pull request '#{pr_identifier}' not found."
-          message += "\n#{details}" if details
-
-          super(message)
-        end
-      end
-
-      # Raised when PR diff exceeds GitHub's API size limit (300 files)
-      class DiffTooLargeError < Error
-        attr_reader :pr_identifier
-
-        def initialize(pr_identifier, details = nil)
-          @pr_identifier = pr_identifier
-          message = "Pull request '#{pr_identifier}' diff exceeds GitHub API size limit."
-          message += "\n#{details}" if details
-
-          super(message)
-        end
-      end
-
-      # Raised when attempting to post to a closed/merged PR
-      class PrStateError < Error
-        attr_reader :pr_number, :state
-
-        def initialize(pr_number, state)
-          @pr_number = pr_number
-          @state = state
-
-          message = "Cannot post comment to PR ##{pr_number}.\n"
-          message += "PR is in '#{state}' state. Comments can only be posted to open PRs."
-
-          super(message)
-        end
-      end
-
-      # Raised when gh CLI encounters a network error
-      class GhNetworkError < Error; end
-
       # Raised when ace-task cannot find task
       class TaskNotFoundError < Error
         attr_reader :task_ref

data/lib/ace/review/models/review_options.rb

@@ -9,7 +9,8 @@ module Ace
           :prompt_base, :prompt_format, :prompt_focus, :add_focus,
           :prompt_guidelines, :model, :models, :dry_run, :verbose,
           :auto_execute, :save_session, :session_dir,
-          :pr, :post_comment, :pr_metadata, :gh_timeout,
+          :pr, :post_comment, :pr_metadata, :provider_timeout,
+          :server, :default_server,
           :pr_comments, :pr_comment_data,
           :evidence_sessions, :campaign, :campaign_round, :campaign_scope,
           :delta,
@@ -54,7 +55,9 @@ module Ace
           @pr = hash[:pr]
           @post_comment = hash[:post_comment] || false
           @pr_metadata = hash[:pr_metadata]
-          @gh_timeout = hash[:gh_timeout]
+          @provider_timeout = hash[:provider_timeout]
+          @server = hash[:server]
+          @default_server = hash[:default_server] || false
 
           # PR comment options
           @pr_comments = hash[:pr_comments]  # nil = use default, true/false = explicit
@@ -195,7 +198,7 @@ module Ace
             end
           end
 
-          @gh_timeout ||= config["gh_timeout"]
+          @provider_timeout ||= config["provider_timeout"]
 
           self
         end

data/lib/ace/review/molecules/campaign_evidence.rb

@@ -18,16 +18,6 @@ module Ace
       class CampaignEvidence
         Contract = Atoms::CampaignContract
 
-        # One completion predicate for provider executions, shared with the
-        # extraction-inventory writer so session metadata and campaign
-        # evidence can never disagree about which reports were reviewed.
-        def self.completed_entry?(entry)
-          execution = entry["execution"] || {}
-          entry["status"] == "success" && execution["status"].to_s == "succeeded" &&
-            !execution["provider"].to_s.empty? && !execution["model"].to_s.empty? &&
-            !entry["completed_at"].to_s.empty?
-        end
-
         def initialize(repo_root:, check_evidence: nil, review_evidence: nil, approval_evidence: nil)
           @repo_root = File.realpath(repo_root)
           authority = CampaignExecutionEvidence.new(repo_root: @repo_root)
@@ -67,9 +57,9 @@ module Ace
           metadata = json_keys(YAML.safe_load_file(metadata_path, permitted_classes: [Time, Date, Symbol]))
           Contract.object!(metadata, "session metadata")
           expected = {"campaign_id" => record["id"], "contract_identity" => record["contract_identity"],
-                      "subject" => record["subject"], "round_id" => binding["round_id"], "scope" => scope,
-                      "head" => binding["head"], "base" => binding["base"],
-                      "scope_identity" => binding["scope_identity"][scope]}
+            "subject" => record["subject"], "round_id" => binding["round_id"], "scope" => scope,
+            "head" => binding["head"], "base" => binding["base"],
+            "scope_identity" => binding["scope_identity"][scope]}
           unless metadata["campaign_binding"] == expected && metadata["preset"] == expected["scope_identity"]["preset"]
             raise Contract::Invalid, "session campaign/contract/scope/head/base identity mismatch"
           end
@@ -93,7 +83,12 @@ module Ace
           reports = []
           entries.each do |entry|
             Contract.object!(entry, "model execution")
-            next unless self.class.completed_entry?(entry)
+            execution = entry["execution"] || {}
+            complete = entry["status"] == "success" && execution["status"] == "succeeded" &&
+              !execution["provider"].to_s.empty? && !execution["model"].to_s.empty? &&
+              !entry["completed_at"].to_s.empty?
+            completed &&= complete
+            next unless complete
             path = entry["output_file"].to_s
             raise Contract::Invalid, "completed execution has no report" if path.empty?
             path = File.expand_path(path, dir)
@@ -104,7 +99,7 @@ module Ace
             resolved, report_ref = artifact("path" => path, "sha256" => entry["report_sha256"])
             raise Contract::Invalid, "empty reviewer report" if File.read(resolved).strip.empty?
             refs << report_ref
-            reports << {"artifact" => report_ref, "execution" => entry["execution"] || {}}
+            reports << {"artifact" => report_ref, "execution" => execution}
             prompts = entry["prompt_sha256"]
             Contract.object!(prompts, "execution prompt checksums")
             %w[system user].each do |name|
@@ -122,10 +117,6 @@ module Ace
               raise Contract::Invalid, "feedback extraction inventory or reviewed reports changed"
             end
           end
-          # One completed reviewer per needed scope suffices: a failed or
-          # incomplete provider entry does not count as a reviewer, but it
-          # does not invalidate the model executions that did complete.
-          completed &&= reports.any?
           completed &&= extracted
           proof = completed ? @review_evidence.call(input.fetch("receipt"), head: binding["head"], artifacts: refs) : nil
           {"receipt" => input["receipt"], "execution_proof" => proof, "path" => dir.delete_prefix(@repo_root + File::SEPARATOR), "scope" => scope,

data/lib/ace/review/molecules/pr_provider.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "ace/git"
+require "ace/git/github"
+require "ace/git/forgejo"
+require "ace/git/organisms/pull_request_lifecycle"
+require "digest"
+
+module Ace
+  module Review
+    module Molecules
+      # Review-facing projection of the shared, exact-head provider contract.
+      # Provider commands and response parsing remain in ace-git packages.
+      class PrProvider
+        def self.format_comment(review_text, preset: nil, model: nil, timestamp: nil)
+          header = "## Code Review - ace-review\n\n"
+          header += "**Preset**: #{preset}\n" if preset
+          header += "**Model**: #{model}\n" if model
+          header += "**Generated**: #{timestamp}\n" if timestamp
+          header += "\n" if preset || model || timestamp
+          content = review_text.to_s
+          content += "\n```\n" if content.scan(/^```/).count.odd?
+          header + <<~MARKDOWN
+            <details>
+            <summary><b>Full Review</b> (click to expand)</summary>
+
+            #{content}
+
+            </details>
+          MARKDOWN
+        end
+
+        # The forge server URL resolved by the lifecycle at construction;
+        # posting compares it with the reviewed repository before mutating.
+        def resolved_server_url(pr_identifier)
+          @lifecycle.resolved_server_url(pr_identifier)
+        end
+
+        def initialize(server_name: nil, use_default: false, timeout: nil, runner: nil, lifecycle: nil)
+          @lifecycle = lifecycle || Ace::Git::Organisms::PullRequestLifecycle.new(
+            server_name: server_name, use_default: use_default,
+            timeout: timeout, runner: runner
+          )
+        end
+
+        def fetch(pr_identifier, include_comments: true)
+          snapshot = @lifecycle.review_snapshot(pr_identifier, include_comments: include_comments)
+          metadata = metadata_for(snapshot)
+          {
+            success: true,
+            diff: snapshot.diff,
+            metadata: metadata,
+            comments: comments_for(snapshot),
+            checks: snapshot.checks,
+            snapshot: snapshot
+          }
+        rescue Ace::Git::Error, ArgumentError => e
+          {success: false, error: "#{e.class.name.split('::').last}: #{e.message}"}
+        end
+
+        # Exact-head PR metadata only (no diff, comments, or checks); the
+        # delta resolver needs identity and base provenance, never the
+        # whole diff.
+        def fetch_metadata(pr_identifier)
+          snapshot = @lifecycle.review_metadata_snapshot(pr_identifier)
+          {success: true, metadata: metadata_for(snapshot)}
+        rescue Ace::Git::Error, ArgumentError => e
+          {success: false, error: "#{e.class.name.split('::').last}: #{e.message}"}
+        end
+
+        def post_comment(pr_identifier, expected_head:, content:, session_key:)
+          correlation = Digest::SHA256.hexdigest(session_key.to_s)
+          @lifecycle.post_review_comment(
+            pr_identifier, expected_head: expected_head,
+            body: content, correlation: correlation
+          )
+        end
+
+        def resolve_thread(pr_identifier, expected_head:, thread_id:)
+          @lifecycle.resolve_review_thread(
+            pr_identifier, expected_head: expected_head, thread_id: thread_id
+          )
+        end
+
+        def update_comment(pr_identifier, expected_head:, comment_id:, body:)
+          @lifecycle.update_review_comment(
+            pr_identifier, expected_head: expected_head,
+            comment_id: comment_id, body: body
+          )
+        end
+
+        def file_at_ref(pr_identifier, path:, ref:)
+          @lifecycle.file_at_ref(pr_identifier, path: path, ref: ref)
+        end
+
+        private
+
+        def metadata_for(snapshot)
+          pr = snapshot.pull_request
+          {
+            "server_name" => pr.server_name,
+            "provider" => snapshot.provider.to_s,
+            "repository_url" => pr.base_repository_url,
+            "number" => pr.number,
+            "title" => pr.title,
+            "body" => pr.body,
+            "author" => {"login" => pr.author},
+            "state" => pr.state.to_s.upcase,
+            "isDraft" => pr.draft,
+            "baseRefName" => pr.base_ref,
+            "baseRefOid" => snapshot.base_sha,
+            "headRefName" => pr.head_ref,
+            "headRefOid" => pr.head_sha,
+            "head_repository_url" => pr.head_repository_url,
+            "url" => pr.url,
+            "changedFiles" => snapshot.files.length,
+            "files" => snapshot.files.map { |path| {"path" => path} },
+            "checks" => snapshot.checks.map { |check| check.to_h.transform_keys(&:to_s) }
+          }
+        end
+
+        def comments_for(snapshot)
+          pr = snapshot.pull_request
+          comments = snapshot.review_evidence.comments
+          issue_comments = comments.reject(&:path).map do |comment|
+            {type: "issue_comment", id: comment.id, author: comment.author,
+             body: comment.body, url: comment.url}
+          end
+          inline = comments.select(&:path)
+          # Comments sharing a provider thread id belong to one thread; a
+          # nil thread id stays an honest per-comment entry.
+          threads = inline.select(&:thread_id).group_by(&:thread_id).map do |id, members|
+            first = members.first
+            {id: id, path: first.path, line: first.line, is_resolved: first.resolved,
+             comments: members.map { |comment|
+               {id: comment.id, author: comment.author, body: comment.body, url: comment.url}
+             }}
+          end
+          threads += inline.reject(&:thread_id).map do |comment|
+            {id: nil, path: comment.path, line: comment.line, is_resolved: comment.resolved,
+             comments: [{id: comment.id, author: comment.author, body: comment.body, url: comment.url}]}
+          end
+          reviews = snapshot.review_evidence.reviews.map do |review|
+            {id: review.id, author: review.author, body: review.body,
+             state: review.state.to_s.upcase, url: review.url}
+          end
+          {
+            success: true, comments: issue_comments, review_threads: threads,
+            reviews: reviews, pr_number: pr.number, pr_title: pr.title,
+            pr_author: pr.author, server_name: pr.server_name,
+            repository_url: pr.base_repository_url, head_sha: pr.head_sha
+          }
+        end
+      end
+    end
+  end
+end