shakacode
diff --git a/‎.agents/skills/address-review/SKILL.md‎
Lines changed: 878 additions & 0 deletions b/‎.agents/skills/address-review/SKILL.md‎
Lines changed: 878 additions & 0 deletions
diff --git a/‎.agents/skills/address-review/bin/fetch-pr-review-data‎
Lines changed: 360 additions & 0 deletions b/‎.agents/skills/address-review/bin/fetch-pr-review-data‎
Lines changed: 360 additions & 0 deletions
@@ -0,0 +1,360 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Fetch and normalize GitHub PR review data without writing to git or GitHub.
+#
+# Collapses the repeated `gh api ... | jq` review-fetch blocks (review summaries,
+# inline review comments, general issue comments, and the reviewThreads GraphQL
+# query) into one read-only call that emits a single normalized JSON document.
+# The reviewThreads thread_id/is_resolved metadata is joined onto each inline
+# comment by node_id so consumers do not have to redo that join.
+#
+# Requires: gh (GitHub CLI). Ruby stdlib only.
+
+require "json"
+require "open3"
+
+# Pure data shaping (no I/O) plus the gh-backed runner. The pure methods take the
+# raw `gh --paginate --slurp` output strings so they can be unit-tested directly.
+module FetchPrReviewData
+  SUMMARY_MARKER = "<!-- address-review-summary -->"
+
+  REVIEW_THREADS_QUERY = <<~GRAPHQL
+    query($owner:String!, $name:String!, $pr:Int!, $endCursor:String) {
+      repository(owner:$owner, name:$name) {
+        pullRequest(number:$pr) {
+          reviewThreads(first:100, after:$endCursor) {
+            nodes { id isResolved comments(first:100) { nodes { id databaseId } } }
+            pageInfo { hasNextPage endCursor }
+          }
+        }
+      }
+    }
+  GRAPHQL
+
+  class Error < StandardError; end
+
+  module_function
+
+  # gh --paginate --slurp wraps the pages of an array endpoint into an outer
+  # array (one element per page). Flatten one level to get the items.
+  def slurped_items(raw)
+    return [] if raw.nil? || raw.strip.empty?
+
+    pages = JSON.parse(raw)
+    return [] unless pages.is_a?(Array)
+
+    pages.flat_map { |page| page.is_a?(Array) ? page : [page] }
+  end
+
+  # GraphQL --paginate --slurp wraps pages into an array of response objects.
+  def thread_nodes(raw)
+    return [] if raw.nil? || raw.strip.empty?
+
+    pages = JSON.parse(raw)
+    pages = [pages] unless pages.is_a?(Array)
+    pages.flat_map do |page|
+      page.dig("data", "repository", "pullRequest", "reviewThreads", "nodes") || []
+    end
+  end
+
+  def build_review_threads(nodes)
+    nodes.map do |node|
+      {
+        "thread_id" => node["id"],
+        "is_resolved" => node["isResolved"] ? true : false,
+        "comments" => (node.dig("comments", "nodes") || []).map do |comment|
+          { "node_id" => comment["id"], "id" => comment["databaseId"] }
+        end
+      }
+    end
+  end
+
+  # Map each review comment node_id to its thread metadata.
+  def thread_index(review_threads)
+    index = {}
+    review_threads.each do |thread|
+      thread["comments"].each do |comment|
+        node_id = comment["node_id"]
+        next if node_id.nil?
+
+        index[node_id] = { "thread_id" => thread["thread_id"], "is_resolved" => thread["is_resolved"] }
+      end
+    end
+    index
+  end
+
+  def build_review_summaries(raw_reviews)
+    raw_reviews.filter_map do |review|
+      next if review["body"].to_s == ""
+
+      {
+        "id" => review["id"],
+        "type" => "review_summary",
+        "body" => review["body"],
+        "state" => review["state"],
+        "user" => review.dig("user", "login"),
+        "created_at" => review["submitted_at"],
+        "html_url" => review["html_url"]
+      }
+    end
+  end
+
+  def build_inline_comments(raw_inline, index)
+    raw_inline.map do |comment|
+      meta = index[comment["node_id"]]
+      {
+        "id" => comment["id"],
+        "node_id" => comment["node_id"],
+        "type" => "review",
+        "path" => comment["path"],
+        "body" => comment["body"],
+        "line" => comment["line"],
+        "start_line" => comment["start_line"],
+        "user" => comment.dig("user", "login"),
+        "in_reply_to_id" => comment["in_reply_to_id"],
+        "created_at" => comment["created_at"],
+        "html_url" => comment["html_url"],
+        "thread_id" => meta && meta["thread_id"],
+        "is_resolved" => meta ? meta["is_resolved"] : false
+      }
+    end
+  end
+
+  def build_issue_comments(raw_issue)
+    raw_issue.map do |comment|
+      {
+        "id" => comment["id"],
+        "node_id" => comment["node_id"],
+        "type" => "issue",
+        "body" => comment["body"],
+        "user" => comment.dig("user", "login"),
+        "created_at" => comment["created_at"],
+        "html_url" => comment["html_url"]
+      }
+    end
+  end
+
+  # Most recent issue comment whose body starts with the summary marker.
+  def compute_cutoff(raw_issue)
+    raw_issue
+      .select { |comment| comment["body"].to_s.start_with?(SUMMARY_MARKER) }
+      .filter_map { |comment| comment["created_at"] }
+      .reject(&:empty?)
+      .max
+      .to_s
+  end
+
+  # Build the normalized result hash from the four raw slurped strings.
+  def assemble(repo:, pr_number:, issue_raw:, reviews_raw:, inline_raw:, threads_raw:)
+    raw_issue = slurped_items(issue_raw)
+    review_threads = build_review_threads(thread_nodes(threads_raw))
+    index = thread_index(review_threads)
+
+    {
+      "repo" => repo,
+      "pr" => pr_number.to_i,
+      "review_cutoff_at" => compute_cutoff(raw_issue),
+      "review_summaries" => build_review_summaries(slurped_items(reviews_raw)),
+      "inline_comments" => build_inline_comments(slurped_items(inline_raw), index),
+      "issue_comments" => build_issue_comments(raw_issue),
+      "review_threads" => review_threads
+    }
+  end
+
+  def text_summary(result)
+    resolved_inline = result["inline_comments"].count { |comment| comment["is_resolved"] }
+    resolved_threads = result["review_threads"].count { |thread| thread["is_resolved"] }
+    cutoff = result["review_cutoff_at"].empty? ? "(none)" : result["review_cutoff_at"]
+    [
+      "PR review data for #{result['repo']}##{result['pr']}",
+      "review_cutoff_at: #{cutoff}",
+      "review_summaries: #{result['review_summaries'].length}",
+      "inline_comments: #{result['inline_comments'].length} (#{resolved_inline} in resolved threads)",
+      "issue_comments: #{result['issue_comments'].length}",
+      "review_threads: #{result['review_threads'].length} (#{resolved_threads} resolved)"
+    ].join("\n")
+  end
+
+  USAGE = <<~USAGE.freeze
+    Usage: fetch-pr-review-data <pr-number> [options]
+
+    Fetch normalized review data for a full-PR scan: review summary bodies, inline
+    review comments (with reviewThreads thread_id/is_resolved joined by node_id),
+    general issue comments, the raw review threads, and the latest address-review
+    summary-comment timestamp (review_cutoff_at).
+
+    Arguments:
+      <pr-number>        PR number to fetch (integer).
+
+    Options:
+          --repo REPO    GitHub repo in OWNER/REPO form. Defaults to gh repo view.
+          --json         Print JSON (default).
+          --text         Print a human-readable count summary instead of JSON.
+          --self-check   Run a parser check plus a read-only gh smoke check.
+      -h, --help         Show this help.
+
+    review_cutoff_at is the created_at of the most recent issue comment whose body
+    starts with "#{SUMMARY_MARKER}", or "" when none exists. Summary and status
+    marker comments are still included in issue_comments so consumers can filter
+    them; computing the cutoff here does not drop them.
+
+    Requires: gh (GitHub CLI)
+  USAGE
+
+  # gh-backed CLI: parses args, fetches the four endpoints, and prints the
+  # assembled result. All subprocess calls use array args (no shell).
+  class Runner
+    def run(argv)
+      opts = parse_args(argv)
+      if opts[:help]
+        puts USAGE
+        return 0
+      end
+      return self_check if opts[:self_check]
+
+      pr_number = validate_pr!(opts[:pr])
+      repo = resolve_repo!(opts[:repo])
+      print_result(fetch(repo, pr_number), opts[:format])
+      0
+    rescue Error => e
+      warn "Error: #{e.message}"
+      1
+    end
+
+    private
+
+    def parse_args(argv)
+      opts = { format: "json", help: false, self_check: false, pr: nil, repo: nil }
+      args = argv.dup
+      until args.empty?
+        arg = args.shift
+        case arg
+        when "--repo" then opts[:repo] = take_value!(args, "--repo")
+        when "--json" then opts[:format] = "json"
+        when "--text" then opts[:format] = "text"
+        when "--self-check" then opts[:self_check] = true
+        when "-h", "--help" then opts[:help] = true
+        when "--" then nil
+        else handle_positional(arg, opts)
+        end
+      end
+      opts
+    end
+
+    def handle_positional(arg, opts)
+      raise Error, "unknown option: #{arg}" if arg.start_with?("-")
+      raise Error, "unexpected extra argument: #{arg}" unless opts[:pr].nil?
+
+      opts[:pr] = arg
+    end
+
+    def take_value!(args, flag)
+      raise Error, "#{flag} requires a value" if args.empty?
+
+      args.shift
+    end
+
+    def validate_pr!(pr_number)
+      raise Error, "a positive integer PR number is required\n\n#{USAGE}" unless pr_number.to_s.match?(/\A[1-9]\d*\z/)
+
+      pr_number
+    end
+
+    # Strict OWNER/REPO: non-empty owner and name, exactly one slash, no spaces.
+    REPO_FORMAT = %r{\A[^/\s]+/[^/\s]+\z}
+
+    def resolve_repo!(repo)
+      repo ||= capture!("gh", "repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner").strip
+      raise Error, "--repo must be in OWNER/REPO form (got: '#{repo}')" unless repo.match?(REPO_FORMAT)
+
+      repo
+    end
+
+    def fetch(repo, pr_number)
+      owner, name = repo.split("/", 2)
+      FetchPrReviewData.assemble(
+        repo:,
+        pr_number:,
+        issue_raw: rest("repos/#{repo}/issues/#{pr_number}/comments"),
+        reviews_raw: rest("repos/#{repo}/pulls/#{pr_number}/reviews"),
+        inline_raw: rest("repos/#{repo}/pulls/#{pr_number}/comments"),
+        threads_raw: capture!(
+          "gh", "api", "graphql", "--paginate", "--slurp",
+          "-f", "owner=#{owner}", "-f", "name=#{name}", "-F", "pr=#{pr_number}",
+          "-f", "query=#{REVIEW_THREADS_QUERY}"
+        )
+      )
+    end
+
+    def rest(endpoint)
+      capture!("gh", "api", "--paginate", "--slurp", endpoint)
+    end
+
+    # Run a command with no shell (array args) and return UTF-8 stdout.
+    def capture!(*cmd)
+      out, status = Open3.capture2(*cmd)
+      raise Error, "command failed: #{cmd.first(3).join(' ')}" unless status.success?
+
+      out.force_encoding("UTF-8")
+    end
+
+    def print_result(result, format)
+      if format == "text"
+        puts FetchPrReviewData.text_summary(result)
+      else
+        puts JSON.pretty_generate(result)
+      end
+    end
+
+    def self_check
+      errors = self_check_errors(FetchPrReviewData.assemble(**self_check_fixtures))
+      unless errors.empty?
+        warn "self-check failed: #{errors.join('; ')}"
+        return 1
+      end
+      puts "assemble parser: ok"
+      puts gh_smoke
+      puts "self-check passed"
+      0
+    end
+
+    def self_check_fixtures
+      {
+        repo: "owner/repo",
+        pr_number: 1234,
+        issue_raw: '[[{"id":1,"body":"first","created_at":"2026-01-01T00:00:00Z"},' \
+                   '{"id":2,"body":"<!-- address-review-summary -->\nold","created_at":"2026-01-02T00:00:00Z"}],' \
+                   '[{"id":3,"body":"<!-- address-review-summary -->\nnew","created_at":"2026-01-03T00:00:00Z"}]]',
+        reviews_raw: '[[{"id":10,"body":"fix it","state":"COMMENTED","submitted_at":"2026-01-04T00:00:00Z"},' \
+                     '{"id":11,"body":"","state":"APPROVED"}]]',
+        inline_raw: '[[{"id":20,"node_id":"RC_20","path":"a.rb"},{"id":21,"node_id":"RC_21","path":"b.rb"}]]',
+        threads_raw: '[{"data":{"repository":{"pullRequest":{"reviewThreads":{"nodes":[' \
+                     '{"id":"T_A","isResolved":true,"comments":{"nodes":[{"id":"RC_20","databaseId":20}]}},' \
+                     '{"id":"T_B","isResolved":false,"comments":{"nodes":[{"id":"RC_21","databaseId":21}]}}]}}}}}]'
+      }
+    end
+
+    def self_check_errors(out)
+      by_id = out["inline_comments"].to_h { |comment| [comment["id"], comment] }
+      errors = []
+      errors << "review_cutoff_at=#{out['review_cutoff_at']}" unless out["review_cutoff_at"] == "2026-01-03T00:00:00Z"
+      errors << "review_summaries=#{out['review_summaries'].length}" unless out["review_summaries"].length == 1
+      errors << "issue_comments=#{out['issue_comments'].length}" unless out["issue_comments"].length == 3
+      errors << "RC_20 thread" unless by_id[20]["thread_id"] == "T_A" && by_id[20]["is_resolved"] == true
+      errors << "RC_21 resolved" unless by_id[21]["is_resolved"] == false
+      errors
+    end
+
+    def gh_smoke
+      return "gh smoke: skipped (gh not installed)" unless system("command -v gh > /dev/null 2>&1")
+
+      repo, status = Open3.capture2("gh", "repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner")
+      return "gh smoke: skipped (gh not authenticated)" unless status.success? && !repo.strip.empty?
+
+      "gh smoke: ok for #{repo.strip}"
+    end
+  end
+end
+
+exit(FetchPrReviewData::Runner.new.run(ARGV)) if $PROGRAM_NAME == __FILE__