carson 1.0.0

data/lib/carson/runtime/review/data_access.rb

@@ -0,0 +1,253 @@
+module Carson
+	class Runtime
+		module Review
+			module DataAccess
+			private
+
+				def pull_request_details( owner:, repo:, pr_number: )
+					node = pull_request_details_node( owner: owner, repo: repo, pr_number: pr_number )
+					paginate_pull_request_connections!( owner: owner, repo: repo, pr_number: pr_number, node: node )
+					normalise_pull_request_details( node: node )
+				end
+
+				# Base PR payload with first page of each connection; remaining pages are fetched separately.
+				def pull_request_details_node( owner:, repo:, pr_number: )
+					stdout_text, stderr_text, success, = gh_run(
+						"api", "graphql",
+						"-f", "query=#{pull_request_details_query}",
+						"-F", "owner=#{owner}",
+						"-F", "repo=#{repo}",
+						"-F", "number=#{pr_number}"
+					)
+					unless success
+						error_text = gh_error_text( stdout_text: stdout_text, stderr_text: stderr_text, fallback: "unable to read pull request ##{pr_number}" )
+						raise error_text
+					end
+					payload = JSON.parse( stdout_text )
+					node = payload.dig( "data", "repository", "pullRequest" )
+					raise "pull request ##{pr_number} not found" unless node.is_a?( Hash )
+					node
+				end
+
+				# Paginates every relevant PR connection so gate/sweep decisions are based on complete data.
+				def paginate_pull_request_connections!( owner:, repo:, pr_number:, node: )
+					paginate_pull_request_connection!( owner: owner, repo: repo, pr_number: pr_number, node: node, connection_name: "reviewThreads" )
+					paginate_pull_request_connection!( owner: owner, repo: repo, pr_number: pr_number, node: node, connection_name: "comments" )
+					paginate_pull_request_connection!( owner: owner, repo: repo, pr_number: pr_number, node: node, connection_name: "reviews" )
+				end
+
+				# Fetches remaining connection pages using pageInfo; missing pageInfo defaults to one-page behaviour.
+				def paginate_pull_request_connection!( owner:, repo:, pr_number:, node:, connection_name: )
+					connection = node[ connection_name ]
+					return unless connection.is_a?( Hash )
+					nodes = Array( connection[ "nodes" ] )
+					page_info = connection[ "pageInfo" ].is_a?( Hash ) ? connection[ "pageInfo" ] : {}
+					while page_info[ "hasNextPage" ] == true
+						cursor = page_info[ "endCursor" ].to_s
+						break if cursor.empty?
+						page_connection = pull_request_connection_page(
+							owner: owner,
+							repo: repo,
+							pr_number: pr_number,
+							connection_name: connection_name,
+							after_cursor: cursor
+						)
+						nodes.concat( Array( page_connection[ "nodes" ] ) )
+						page_info = page_connection[ "pageInfo" ].is_a?( Hash ) ? page_connection[ "pageInfo" ] : {}
+					end
+					connection[ "nodes" ] = nodes
+					connection[ "pageInfo" ] = page_info
+				end
+
+				# Requests one additional page for the chosen PR connection.
+				def pull_request_connection_page( owner:, repo:, pr_number:, connection_name:, after_cursor: )
+					query = pull_request_connection_page_query( connection_name: connection_name )
+					stdout_text, stderr_text, success, = gh_run(
+						"api", "graphql",
+						"-f", "query=#{query}",
+						"-F", "owner=#{owner}",
+						"-F", "repo=#{repo}",
+						"-F", "number=#{pr_number}",
+						"-F", "after=#{after_cursor}"
+					)
+					unless success
+						error_text = gh_error_text(
+							stdout_text: stdout_text,
+							stderr_text: stderr_text,
+							fallback: "unable to paginate pull request ##{pr_number} #{connection_name}"
+						)
+						raise error_text
+					end
+					payload = JSON.parse( stdout_text )
+					node = payload.dig( "data", "repository", "pullRequest" )
+					raise "pull request ##{pr_number} not found during #{connection_name} pagination" unless node.is_a?( Hash )
+					connection = node[ connection_name ]
+					raise "missing #{connection_name} payload during pagination" unless connection.is_a?( Hash )
+					connection
+				end
+
+				def normalise_pull_request_details( node: )
+					{
+						number: node.fetch( "number" ),
+						title: node.fetch( "title" ).to_s,
+						url: node.fetch( "url" ).to_s,
+						state: node.fetch( "state" ).to_s.upcase,
+						updated_at: node.fetch( "updatedAt" ).to_s,
+						merged_at: node[ "mergedAt" ].to_s,
+						closed_at: node[ "closedAt" ].to_s,
+						author: { login: node.dig( "author", "login" ).to_s },
+						comments: normalise_issue_comments( nodes: node.dig( "comments", "nodes" ) ),
+						reviews: normalise_reviews( nodes: node.dig( "reviews", "nodes" ) ),
+						review_threads: normalise_review_threads( nodes: node.dig( "reviewThreads", "nodes" ) )
+					}
+				end
+
+				# Converts GraphQL issue comment nodes into a stable internal format.
+				def normalise_issue_comments( nodes: )
+					Array( nodes ).map do |entry|
+						{
+							author: entry.dig( "author", "login" ).to_s,
+							body: entry[ "body" ].to_s,
+							url: entry[ "url" ].to_s,
+							created_at: entry[ "createdAt" ].to_s
+						}
+					end
+				end
+
+				# Converts GraphQL review nodes into a stable internal format.
+				def normalise_reviews( nodes: )
+					Array( nodes ).map do |entry|
+						{
+							author: entry.dig( "author", "login" ).to_s,
+							state: entry[ "state" ].to_s.upcase,
+							body: entry[ "body" ].to_s,
+							url: entry[ "url" ].to_s,
+							created_at: entry[ "submittedAt" ].to_s
+						}
+					end
+				end
+
+				# Converts GraphQL review-thread nodes into a stable internal format.
+				def normalise_review_threads( nodes: )
+					Array( nodes ).map do |entry|
+						{
+							is_resolved: entry[ "isResolved" ] == true,
+							is_outdated: entry[ "isOutdated" ] == true,
+							comments: Array( entry.dig( "comments", "nodes" ) ).map do |comment|
+								{
+									author: comment.dig( "author", "login" ).to_s,
+									body: comment[ "body" ].to_s,
+									url: comment[ "url" ].to_s,
+									created_at: comment[ "createdAt" ].to_s
+								}
+							end
+						}
+					end
+				end
+
+				def recent_pull_requests_for_sweep( owner:, repo:, cutoff_time: )
+					results = []
+					page = 1
+					max_pages = 50
+					loop do
+						stdout_text, stderr_text, success, = gh_run(
+							"api", "repos/#{owner}/#{repo}/pulls",
+							"--method", "GET",
+							"-f", "state=all",
+							"-f", "sort=updated",
+							"-f", "direction=desc",
+							"-f", "per_page=100",
+							"-f", "page=#{page}"
+						)
+						unless success
+							error_text = gh_error_text( stdout_text: stdout_text, stderr_text: stderr_text, fallback: "unable to list pull requests for review sweep" )
+							raise error_text
+						end
+
+						page_nodes = Array( JSON.parse( stdout_text ) )
+						break if page_nodes.empty?
+						stop_paging = false
+
+						page_nodes.each do |entry|
+							updated_time = parse_time_or_nil( text: entry[ "updated_at" ] )
+							next if updated_time.nil?
+							if updated_time < cutoff_time
+								stop_paging = true
+								next
+							end
+							state = normalise_rest_pull_request_state( entry: entry )
+							next unless config.review_sweep_states.include?( sweep_state_for( pr_state: state ) )
+							results << {
+								number: entry[ "number" ],
+								title: entry[ "title" ].to_s,
+								url: entry[ "html_url" ].to_s,
+								state: state,
+								updated_at: updated_time.utc.iso8601,
+								merged_at: entry[ "merged_at" ].to_s,
+								closed_at: entry[ "closed_at" ].to_s,
+								author: entry.dig( "user", "login" ).to_s
+							}
+						end
+
+						break if stop_paging
+						if page >= max_pages
+							probe_stdout_text, probe_stderr_text, probe_success, = gh_run(
+								"api", "repos/#{owner}/#{repo}/pulls",
+								"--method", "GET",
+								"-f", "state=all",
+								"-f", "sort=updated",
+								"-f", "direction=desc",
+								"-f", "per_page=100",
+								"-f", "page=#{page + 1}"
+							)
+							unless probe_success
+								error_text = gh_error_text( stdout_text: probe_stdout_text, stderr_text: probe_stderr_text, fallback: "unable to verify review sweep pagination limit" )
+								raise error_text
+							end
+							probe_nodes = Array( JSON.parse( probe_stdout_text ) )
+							raise "review sweep pull request pagination exceeded safety limit (#{max_pages} pages)" unless probe_nodes.empty?
+							break
+						end
+
+						page += 1
+					end
+					results
+				end
+
+				# REST /pulls payload normaliser so merged PRs stay distinguishable from closed-unmerged PRs.
+				def normalise_rest_pull_request_state( entry: )
+					base_state = entry[ "state" ].to_s.upcase
+					return "MERGED" if base_state == "CLOSED" && !entry[ "merged_at" ].to_s.strip.empty?
+					base_state
+				end
+
+				# Extracts owner/repository from configured git remote URL.
+				def repository_coordinates
+					remote_url = git_capture!( "config", "--get", "remote.#{config.git_remote}.url" ).strip
+					match = remote_url.match( %r{\A(?:git@|https?://|ssh://git@)?[^/:]+[:/](?<owner>[^/]+)/(?<repo>[^/]+?)(?:\.git)?\z} )
+					return [ match[ :owner ], match[ :repo ] ] unless match.nil?
+
+					stdout_text, = gh_capture_soft( "repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner" )
+					name_with_owner = stdout_text.to_s.strip
+					if name_with_owner.include?( "/" )
+						owner, repo = name_with_owner.split( "/", 2 )
+						return [ owner, repo ] unless owner.to_s.empty? || repo.to_s.empty?
+					end
+
+					repo_name = File.basename( remote_url ).sub( /\.git\z/, "" )
+					return [ "local", repo_name ] unless repo_name.empty?
+					raise "unable to parse owner/repo from remote URL #{remote_url}"
+				end
+
+				# Optional CI override for detached-HEAD contexts where branch-based PR lookup is not possible.
+				def carson_pr_number_override
+					text = ENV.fetch( "CARSON_PR_NUMBER", "" ).to_s.strip
+					return nil if text.empty?
+					Integer( text )
+				rescue ArgumentError
+					raise "invalid CARSON_PR_NUMBER value #{text.inspect}"
+				end
+			end
+		end
+	end
+end

data/lib/carson/runtime/review/gate_support.rb

@@ -0,0 +1,224 @@
+module Carson
+	class Runtime
+		module Review
+			module GateSupport
+			private
+
+				def wait_for_review_warmup
+					return unless config.review_wait_seconds.positive?
+					puts_line "warmup_wait_seconds: #{config.review_wait_seconds}"
+					sleep config.review_wait_seconds
+				end
+
+				# Poll delay between consecutive snapshot reads during convergence checks.
+				def wait_for_review_poll
+					return unless config.review_poll_seconds.positive?
+					puts_line "poll_wait_seconds: #{config.review_poll_seconds}"
+					sleep config.review_poll_seconds
+				end
+
+				# Fetches live PR review state and derives unresolved-thread plus disposition-ack summary.
+				def review_gate_snapshot( owner:, repo:, pr_number: )
+					details = pull_request_details( owner: owner, repo: repo, pr_number: pr_number )
+					pr_author = details.dig( :author, :login ).to_s
+					unresolved_threads = unresolved_thread_entries( details: details )
+					actionable_top_level = actionable_top_level_items( details: details, pr_author: pr_author )
+					acknowledgements = disposition_acknowledgements( details: details, pr_author: pr_author )
+					unacknowledged_actionable = actionable_top_level.reject { |item| acknowledged_by_disposition?( item: item, acknowledgements: acknowledgements ) }
+					{
+						latest_activity: latest_review_activity( details: details ),
+						unresolved_threads: unresolved_threads,
+						actionable_top_level: actionable_top_level,
+						unacknowledged_actionable: unacknowledged_actionable,
+						acknowledgements: acknowledgements
+					}
+				end
+
+				# Deterministic signature used to compare two review snapshots for convergence.
+				def review_gate_signature( snapshot: )
+					{
+						latest_activity: snapshot.fetch( :latest_activity ).to_s,
+						unresolved_urls: snapshot.fetch( :unresolved_threads ).map { |entry| entry.fetch( :url ) }.sort,
+						unacknowledged_urls: snapshot.fetch( :unacknowledged_actionable ).map { |entry| entry.fetch( :url ) }.sort
+					}
+				end
+
+				# Pull request selected by current branch; nil is returned when no PR exists.
+				def current_pull_request_for_branch( branch_name: )
+					stdout_text, stderr_text, success, = gh_run( "pr", "view", "--", branch_name, "--json", "number,title,url,state" )
+					unless success
+						error_text = gh_error_text( stdout_text: stdout_text, stderr_text: stderr_text, fallback: "unable to read PR for branch #{branch_name}" )
+						return nil if error_text.downcase.include?( "no pull requests found" )
+						raise error_text
+					end
+					data = JSON.parse( stdout_text )
+					{
+						number: data.fetch( "number" ),
+						title: data.fetch( "title" ).to_s,
+						url: data.fetch( "url" ).to_s,
+						state: data.fetch( "state" ).to_s
+					}
+				end
+
+				def unresolved_thread_entries( details: )
+					Array( details.fetch( :review_threads ) ).each_with_index.map do |thread, index|
+						next if thread.fetch( :is_resolved )
+						# Outdated threads belong to superseded diffs and should not block current merge readiness.
+						next if thread.fetch( :is_outdated )
+						comments = thread.fetch( :comments )
+						first_comment = comments.first || {}
+						latest_time = comments.map { |entry| entry.fetch( :created_at ) }.max.to_s
+						{
+							url: blank_to( value: first_comment.fetch( :url, "" ), default: "#{details.fetch( :url )}#thread-#{index + 1}" ),
+							author: first_comment.fetch( :author, "" ),
+							created_at: latest_time,
+							outdated: thread.fetch( :is_outdated ),
+							reason: "unresolved_thread"
+						}
+					end.compact
+				end
+
+				# Actionable top-level findings include CHANGES_REQUESTED reviews or risk-keyword findings.
+				def actionable_top_level_items( details:, pr_author: )
+					items = []
+					Array( details.fetch( :comments ) ).each do |comment|
+						next if comment.fetch( :author ) == pr_author
+						next if disposition_prefixed?( text: comment.fetch( :body ) )
+						hits = matched_risk_keywords( text: comment.fetch( :body ) )
+						next if hits.empty?
+						items << {
+							kind: "issue_comment",
+							url: comment.fetch( :url ),
+							author: comment.fetch( :author ),
+							created_at: comment.fetch( :created_at ),
+							reason: "risk_keywords: #{hits.join( ', ' )}"
+						}
+					end
+					Array( details.fetch( :reviews ) ).each do |review|
+						next if review.fetch( :author ) == pr_author
+						next if disposition_prefixed?( text: review.fetch( :body ) )
+						hits = matched_risk_keywords( text: review.fetch( :body ) )
+						changes_requested = review.fetch( :state ) == "CHANGES_REQUESTED"
+						next if hits.empty? && !changes_requested
+						reason = changes_requested ? "changes_requested_review" : "risk_keywords: #{hits.join( ', ' )}"
+						items << {
+							kind: "review",
+							url: review.fetch( :url ),
+							author: review.fetch( :author ),
+							created_at: review.fetch( :created_at ),
+							reason: reason
+						}
+					end
+					deduplicate_findings_by_url( items: items )
+				end
+
+				# Parses acknowledgement messages and extracts referenced review URLs plus disposition.
+				def disposition_acknowledgements( details:, pr_author: )
+					sources = []
+					sources.concat( Array( details.fetch( :comments ) ) )
+					sources.concat( Array( details.fetch( :reviews ) ) )
+					sources.concat( Array( details.fetch( :review_threads ) ).flat_map { |thread| thread.fetch( :comments ) } )
+					sources.map do |entry|
+						next unless entry.fetch( :author, "" ) == pr_author
+						body = entry.fetch( :body, "" ).to_s
+						next unless disposition_prefixed?( text: body )
+						disposition = disposition_token( text: body )
+						next if disposition.nil?
+						target_urls = extract_github_urls( text: body )
+						next if target_urls.empty?
+						{
+							url: entry.fetch( :url, "" ),
+							created_at: entry.fetch( :created_at, "" ),
+							disposition: disposition,
+							target_urls: target_urls
+						}
+					end.compact
+				end
+
+				# True when any disposition acknowledgement references the specific finding URL.
+				def acknowledged_by_disposition?( item:, acknowledgements: )
+					acknowledgements.any? do |ack|
+						Array( ack.fetch( :target_urls ) ).any? { |url| url == item.fetch( :url ) }
+					end
+				end
+
+				# Latest review activity marker used by convergence snapshots.
+				def latest_review_activity( details: )
+					timestamps = []
+					timestamps << details.fetch( :updated_at )
+					timestamps.concat( Array( details.fetch( :comments ) ).map { |entry| entry.fetch( :created_at ) } )
+					timestamps.concat( Array( details.fetch( :reviews ) ).map { |entry| entry.fetch( :created_at ) } )
+					timestamps.concat( Array( details.fetch( :review_threads ) ).flat_map { |thread| thread.fetch( :comments ) }.map { |entry| entry.fetch( :created_at ) } )
+					timestamps.map { |text| parse_time_or_nil( text: text ) }.compact.max&.utc&.iso8601
+				end
+
+				# Writes review gate artefacts using fixed report names in global report output.
+				def write_review_gate_report( report: )
+					markdown_path, json_path = write_report(
+						report: report,
+						markdown_name: REVIEW_GATE_REPORT_MD,
+						json_name: REVIEW_GATE_REPORT_JSON,
+						renderer: method( :render_review_gate_markdown )
+					)
+					puts_line "review_gate_report_markdown: #{markdown_path}"
+					puts_line "review_gate_report_json: #{json_path}"
+				rescue StandardError => e
+					puts_line "review_gate_report_write: SKIP (#{e.message})"
+				end
+
+				# Human-readable review gate report for merge-readiness evidence.
+				def render_review_gate_markdown( report: )
+					lines = []
+					lines << "# Carson Review Gate Report"
+					lines << ""
+					lines << "- Generated at: #{report.fetch( :generated_at )}"
+					lines << "- Branch: #{report.fetch( :branch )}"
+					lines << "- Status: #{report.fetch( :status )}"
+					lines << "- Converged: #{report.fetch( :converged )}"
+					lines << "- Poll attempts: #{report.fetch( :poll_attempts, 0 )}"
+					lines << "- Wait seconds: #{report.fetch( :wait_seconds )}"
+					lines << "- Poll seconds: #{report.fetch( :poll_seconds )}"
+					lines << "- Max polls: #{report.fetch( :max_polls )}"
+					lines << ""
+					lines << "## Pull Request"
+					pr = report[ :pr ]
+					if pr.nil?
+						lines << "- not available"
+					else
+						lines << "- Number: ##{pr.fetch( :number )}"
+						lines << "- Title: #{pr.fetch( :title )}"
+						lines << "- URL: #{pr.fetch( :url )}"
+						lines << "- State: #{pr.fetch( :state )}"
+					end
+					lines << ""
+					lines << "## Block Reasons"
+					if report.fetch( :block_reasons ).empty?
+						lines << "- none"
+					else
+						report.fetch( :block_reasons ).each { |reason| lines << "- #{reason}" }
+					end
+					lines << ""
+					lines << "## Unresolved Threads"
+					if report.fetch( :unresolved_threads ).empty?
+						lines << "- none"
+					else
+						report.fetch( :unresolved_threads ).each do |entry|
+							lines << "- #{entry.fetch( :url )} (author: #{entry.fetch( :author )}, outdated: #{entry.fetch( :outdated )})"
+						end
+					end
+					lines << ""
+					lines << "## Unacknowledged Actionable Top-Level Findings"
+					if report.fetch( :unacknowledged_actionable ).empty?
+						lines << "- none"
+					else
+						report.fetch( :unacknowledged_actionable ).each do |entry|
+							lines << "- #{entry.fetch( :kind )}: #{entry.fetch( :url )} (author: #{entry.fetch( :author )}, reason: #{entry.fetch( :reason )})"
+						end
+					end
+					lines << ""
+					lines.join( "\n" )
+				end
+			end
+		end
+	end
+end

data/lib/carson/runtime/review/query_text.rb

@@ -0,0 +1,164 @@
+module Carson
+	class Runtime
+		module Review
+			module QueryText
+			private
+
+				def pull_request_connection_page_query( connection_name: )
+					case connection_name
+					when "comments"
+						pull_request_comments_page_query
+					when "reviews"
+						pull_request_reviews_page_query
+					when "reviewThreads"
+						pull_request_review_threads_page_query
+					else
+						raise "unsupported pull request connection #{connection_name}"
+					end
+				end
+
+				# GraphQL query kept in one place so gate/sweep consume the same PR payload schema.
+				def pull_request_details_query
+					<<~GRAPHQL
+						query($owner:String!, $repo:String!, $number:Int!) {
+							repository(owner:$owner, name:$repo) {
+								pullRequest(number:$number) {
+									number
+									title
+									url
+									state
+									updatedAt
+									mergedAt
+									closedAt
+									author { login }
+									reviewThreads(first:100) {
+										pageInfo {
+											hasNextPage
+											endCursor
+										}
+										nodes {
+											isResolved
+											isOutdated
+											comments(first:100) {
+												nodes {
+													author { login }
+													body
+													url
+													createdAt
+												}
+											}
+										}
+									}
+									comments(first:100) {
+										pageInfo {
+											hasNextPage
+											endCursor
+										}
+										nodes {
+											author { login }
+											body
+											url
+											createdAt
+										}
+									}
+									reviews(first:100) {
+										pageInfo {
+											hasNextPage
+											endCursor
+										}
+										nodes {
+											author { login }
+											state
+											body
+											url
+											submittedAt
+										}
+									}
+								}
+							}
+						}
+					GRAPHQL
+				end
+
+				# Additional page query for top-level issue comments.
+				def pull_request_comments_page_query
+					<<~GRAPHQL
+						query($owner:String!, $repo:String!, $number:Int!, $after:String!) {
+							repository(owner:$owner, name:$repo) {
+								pullRequest(number:$number) {
+									comments(first:100, after:$after) {
+										pageInfo {
+											hasNextPage
+											endCursor
+										}
+										nodes {
+											author { login }
+											body
+											url
+											createdAt
+										}
+									}
+								}
+							}
+						}
+					GRAPHQL
+				end
+
+				# Additional page query for top-level reviews.
+				def pull_request_reviews_page_query
+					<<~GRAPHQL
+						query($owner:String!, $repo:String!, $number:Int!, $after:String!) {
+							repository(owner:$owner, name:$repo) {
+								pullRequest(number:$number) {
+									reviews(first:100, after:$after) {
+										pageInfo {
+											hasNextPage
+											endCursor
+										}
+										nodes {
+											author { login }
+											state
+											body
+											url
+											submittedAt
+										}
+									}
+								}
+							}
+						}
+					GRAPHQL
+				end
+
+				# Additional page query for review threads.
+				def pull_request_review_threads_page_query
+					<<~GRAPHQL
+						query($owner:String!, $repo:String!, $number:Int!, $after:String!) {
+							repository(owner:$owner, name:$repo) {
+								pullRequest(number:$number) {
+									reviewThreads(first:100, after:$after) {
+										pageInfo {
+											hasNextPage
+											endCursor
+										}
+										nodes {
+											isResolved
+											isOutdated
+											comments(first:100) {
+												nodes {
+													author { login }
+													body
+													url
+													createdAt
+												}
+											}
+										}
+									}
+								}
+							}
+						}
+					GRAPHQL
+				end
+			end
+		end
+	end
+end