diff --git a/.github/workflows/ensure-alphabetize.yml b/.github/workflows/ensure-alphabetize.yml index 39fd2991..23aedca1 100644 --- a/.github/workflows/ensure-alphabetize.yml +++ b/.github/workflows/ensure-alphabetize.yml @@ -8,12 +8,18 @@ on: paths: - "Gemfile" - "script/alphabetize" + - "script/suggest-alphabetize" + - "lib/alphabetize*.rb" + - "test/alphabetize_suggestions_test.rb" - ".github/workflows/ensure-alphabetize.yml" - "_data/**" pull_request: paths: - "Gemfile" - "script/alphabetize" + - "script/suggest-alphabetize" + - "lib/alphabetize*.rb" + - "test/alphabetize_suggestions_test.rb" - ".github/workflows/ensure-alphabetize.yml" - "_data/**" @@ -28,6 +34,8 @@ jobs: uses: ruby/setup-ruby@de492cf36cbab201753d720ce4f4e336cd688c94 # v1.336.0 with: bundler-cache: true + - name: Test formatting suggestions + run: bundle exec ruby test/alphabetize_suggestions_test.rb - name: Ensure Orgs are sorted run: | bundle exec script/alphabetize diff --git a/.github/workflows/suggest-alphabetize.yml b/.github/workflows/suggest-alphabetize.yml new file mode 100644 index 00000000..a1fc331d --- /dev/null +++ b/.github/workflows/suggest-alphabetize.yml @@ -0,0 +1,31 @@ +name: Suggest organization formatting + +on: + pull_request_target: + types: [opened, synchronize, reopened] + paths: + - "_data/*.yml" + +permissions: + contents: read + pull-requests: write + +concurrency: + group: suggest-alphabetize-${{ github.event.pull_request.number }} + cancel-in-progress: true + +jobs: + suggest: + runs-on: ubuntu-24.04 + timeout-minutes: 5 + steps: + # Never check out PR code: this job has permission to post reviews. + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: ruby/setup-ruby@de492cf36cbab201753d720ce4f4e336cd688c94 # v1.336.0 + - name: Suggest canonical organization formatting + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PR_NUMBER: ${{ github.event.pull_request.number }} + run: ruby script/suggest-alphabetize diff --git a/lib/alphabetize.rb b/lib/alphabetize.rb new file mode 100644 index 00000000..a6be4863 --- /dev/null +++ b/lib/alphabetize.rb @@ -0,0 +1,19 @@ +# frozen_string_literal: true + +require 'yaml' + +module Alphabetize + def self.organization_list?(key, value) + key.is_a?(String) && value.is_a?(Array) && value.all?(String) + end + + def self.format(contents) + data = YAML.safe_load(contents) + valid = data.is_a?(Hash) && data.all? { |key, value| organization_list?(key, value) } + raise ArgumentError, 'Organization data must map group names to lists of strings' unless valid + + output = data.sort_by { |key, _value| key.upcase }.to_h.transform_values { |value| value.uniq.sort_by(&:upcase) } + # Preserve the data file's header comment and canonical spacing. + contents.lines.first + output.to_yaml.gsub(/^(.+?):$/, "\n\\1:").gsub(/^- /, ' - ').gsub(/\A---\n/m, '') + end +end diff --git a/lib/alphabetize_suggestions.rb b/lib/alphabetize_suggestions.rb new file mode 100644 index 00000000..0e3cd1b0 --- /dev/null +++ b/lib/alphabetize_suggestions.rb @@ -0,0 +1,79 @@ +# frozen_string_literal: true + +require 'digest' +require 'open3' +require 'tempfile' +require_relative 'alphabetize' + +module AlphabetizeSuggestions + def self.visible_lines(patch) + line = 0 + patch.to_s.lines.each_with_object(Set.new) do |text, lines| + if (match = text.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/)) + line = match[1].to_i + elsif text.start_with?(' ', '+') + lines << line + line += 1 + end + end + end + + def self.diff(original, formatted, context: 0) + Tempfile.create('alphabetize-original') do |before| + Tempfile.create('alphabetize-formatted') do |after| + before.write(original) + after.write(formatted) + [before, after].each(&:flush) + output, error, status = Open3.capture3('diff', "-U#{context}", '--', before.path, after.path) + raise "Cannot generate formatting diff: #{error}" unless [0, 1].include?(status.exitstatus) + + output + end + end + end + + def self.replacement(original, formatted) + before = original.lines + after = formatted.lines + prefix = 0 + prefix += 1 while prefix < [before.length, after.length].min && before[prefix] == after[prefix] + suffix = 0 + suffix += 1 while suffix < [before.length, after.length].min - prefix && before[-suffix - 1] == after[-suffix - 1] + count = before.length - prefix - suffix + [count.zero? ? prefix : prefix + 1, count, after.slice(prefix, after.length - prefix - suffix)] + end + + def self.comment(path, start, count, replacement, original) + if count.zero? + anchor = [start, 1].max + replacement = start.zero? ? replacement + [original.first] : [original[anchor - 1]] + replacement + start = anchor + count = 1 + end + text = replacement.join + text += "\n" unless text.empty? || text.end_with?("\n") + fence = '`' * [3, text.scan(/`+/).map(&:length).max.to_i + 1].max + body = "Alphabetize and normalize organization data:\n\n#{fence}suggestion\n#{text}#{fence}" + marker = "" + result = { path: path, line: start + count - 1, side: 'RIGHT', body: "#{body}\n#{marker}" } + result.merge!(start_line: start, start_side: 'RIGHT') if count > 1 + result + end + + def self.for_file(path, original, patch) + raise ArgumentError, 'Unsafe organization data path' unless path.match?(%r{\A_data/[A-Za-z0-9_-]+\.yml\z}) + + formatted = Alphabetize.format(original) + return [[], false, ''] if formatted == original + + visible = visible_lines(patch) + # One replacement keeps moves atomic, even when only their source is in the PR diff. + suggestion = comment(path, *replacement(original, formatted), original.lines) + first = suggestion.fetch(:start_line, suggestion.fetch(:line)) + reviewable = (first..suggestion.fetch(:line)).all? { |line| visible.include?(line) } + incomplete = !reviewable || suggestion.fetch(:body).bytesize >= 60_000 + comments = incomplete ? [] : [suggestion] + fallback = diff(original, formatted, context: 3) + [comments, incomplete, "--- a/#{path}\n+++ b/#{path}\n#{fallback.lines.drop(2).join}"] + end +end diff --git a/script/alphabetize b/script/alphabetize index e1a2ce84..192f4487 100755 --- a/script/alphabetize +++ b/script/alphabetize @@ -3,27 +3,10 @@ # Alphabetizes the content of all YAML files in the _data directory -require 'open-uri' -require 'json' -require 'yaml' +require_relative '../lib/alphabetize' files = Dir["#{File.expand_path('../_data/', File.dirname(__FILE__))}/*.yml"] files.each do |file| - contents = File.read(file) - comment = contents.lines.first - - data = YAML.safe_load(contents) - data = data.sort_by { |k, _v| k.upcase } - - output = {} - data.each do |key, value| - value = value.uniq.sort_by(&:upcase) - output[key] = value - end - - # Add extra line break between groups, indent arrays, and strip header - formatted_output = comment + output.to_yaml.gsub(/^(.+?):$/, "\n\\1:").gsub(/^- /, ' - ').gsub(/\A---\n/m, '') - - File.write(file, formatted_output) + File.write(file, Alphabetize.format(File.read(file))) end diff --git a/script/suggest-alphabetize b/script/suggest-alphabetize new file mode 100755 index 00000000..713e25f4 --- /dev/null +++ b/script/suggest-alphabetize @@ -0,0 +1,75 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +require 'base64' +require 'json' +require 'open3' +require_relative '../lib/alphabetize_suggestions' + +def api(path, body = nil, paginate: false) + args = ['gh', 'api', path] + args += ['--paginate', '--slurp'] if paginate + args += ['--method', 'POST', '--input', '-'] if body + output, error, status = Open3.capture3(*args, stdin_data: body ? JSON.generate(body) : '') + abort "GitHub API request failed: #{error}" unless status.success? + + JSON.parse(output) +end + +repo = ENV.fetch('GITHUB_REPOSITORY') +number = Integer(ENV.fetch('PR_NUMBER')) +pr = api("repos/#{repo}/pulls/#{number}") +abort 'Pull request is not open' unless pr.fetch('state') == 'open' +head = pr.fetch('head').fetch('sha') +files = api("repos/#{repo}/pulls/#{number}/files?per_page=100", paginate: true).flatten +existing = api("repos/#{repo}/pulls/#{number}/comments?per_page=100", paginate: true).flatten +comments = [] +patches = [] +incomplete = false +files.each do |file| + path = file.fetch('filename') + next unless path.match?(%r{\A_data/[^/]+\.yml\z}) && file.fetch('status') != 'removed' + + abort 'Unsafe organization data path' unless path.match?(%r{\A_data/[A-Za-z0-9_-]+\.yml\z}) + head_repo = pr.fetch('head').fetch('repo').fetch('full_name') + pinned = api("repos/#{head_repo}/contents/#{path}?ref=#{head}") + abort "Pull request file changed during formatting: #{path}; wait for its next run." unless pinned.fetch('sha') == file.fetch('sha') + blob = api("repos/#{head_repo}/git/blobs/#{file.fetch('sha')}") + abort "Organization data is too large: #{path}" if blob.fetch('size') > 1_000_000 + original = Base64.strict_decode64(blob.fetch('content').delete("\n")).force_encoding(Encoding::UTF_8) + abort "Organization data is not valid UTF-8: #{path}" unless original.valid_encoding? + suggestions, partial, patch = AlphabetizeSuggestions.for_file(path, original, file['patch']) + patches << patch unless patch.empty? + incomplete ||= partial + comments.concat(suggestions) +end +comments.reject! do |comment| + marker = comment.fetch(:body).lines.last.strip + existing.any? do |old| + old.fetch('user').fetch('login') == 'github-actions[bot]' && old['commit_id'] == head && old.fetch('body').include?(marker) + end +end +abort 'Too many formatting suggestions; run script/alphabetize locally.' if comments.length > 50 +body = 'Suggested organization-data formatting fixes.' +if incomplete + patch = patches.join("\n") + fence = '`' * [3, patch.scan(/`+/).map(&:length).max.to_i + 1].max + body += "\n\nSome corrections are outside the PR diff and cannot be inline suggestions. " \ + "Run `bundle exec script/alphabetize` and commit the result, or apply this complete formatting patch:\n\n" \ + "#{fence}diff\n#{patch}#{fence}" +end +abort 'Formatting patch is too large; run script/alphabetize locally.' if body.bytesize > 60_000 +marker = "" +reviews = api("repos/#{repo}/pulls/#{number}/reviews?per_page=100", paginate: true).flatten +already_posted = reviews.any? do |review| + review.fetch('user').fetch('login') == 'github-actions[bot]' && review.fetch('body').include?(marker) +end +if comments.empty? && (!incomplete || already_posted) + puts 'No new inline formatting suggestions to post.' +else + current = api("repos/#{repo}/pulls/#{number}") + abort 'Pull request changed during formatting; wait for its next run.' unless current.fetch('head').fetch('sha') == head + api("repos/#{repo}/pulls/#{number}/reviews", + { commit_id: head, event: 'COMMENT', body: "#{body}\n#{marker}", comments: comments }) + puts "Posted #{comments.length} formatting suggestions." +end diff --git a/test/alphabetize_suggestions_test.rb b/test/alphabetize_suggestions_test.rb new file mode 100644 index 00000000..855b987c --- /dev/null +++ b/test/alphabetize_suggestions_test.rb @@ -0,0 +1,271 @@ +# frozen_string_literal: true + +require 'minitest/autorun' +require 'base64' +require 'fileutils' +require 'json' +require 'tmpdir' +require_relative '../lib/alphabetize_suggestions' + +class AlphabetizeSuggestionsTest < Minitest::Test + def test_sorting_and_spacing_match_the_existing_canonical_format + original = "# Organizations\n\nZebra: \n - zoo\n - apple\n - apple\n\nAlpha:\n - bee\n" + expected = "# Organizations\n\nAlpha:\n - bee\n\nZebra:\n - apple\n - zoo\n" + + assert_equal expected, Alphabetize.format(original) + assert_equal expected, Alphabetize.format(expected) + end + + module ReviewFixtures + def run_review(existing: false, stale: false, extra_file: false, patch: "@@ -1,3 +1,3 @@\n # Data\n \n+Test: \n", **options) + Dir.mktmpdir do |dir| + original = options.fetch(:original, "# Data\n\nTest: \n - org\n") + fixture = { + 'repo' => 'example/repo', 'existing' => existing, 'stale' => stale, + 'original' => original, 'patch' => patch, 'extra_file' => extra_file, + 'mismatched_blob' => options.fetch(:mismatched_blob, false) + } + File.write("#{dir}/fixture.json", JSON.generate(fixture)) + write_github_stub(dir) + output, status = Open3.capture2e( + { 'PATH' => "#{dir}:#{ENV.fetch('PATH')}", 'FIXTURE_DIR' => dir, + 'GITHUB_REPOSITORY' => 'example/repo', 'PR_NUMBER' => '123' }, + Gem.ruby, File.expand_path('../script/suggest-alphabetize', __dir__) + ) + posted = File.exist?("#{dir}/review.json") ? JSON.parse(File.read("#{dir}/review.json")) : nil + [output, status, posted] + end + end + + def write_github_stub(dir) + File.write("#{dir}/gh", <<~RUBY) + #!#{Gem.ruby} + require #{File.expand_path('../lib/alphabetize_suggestions', __dir__).inspect} + require 'json' + require 'base64' + dir = ENV.fetch('FIXTURE_DIR') + f = JSON.parse(File.read("\#{dir}/fixture.json")) + path = ARGV.fetch(1) + response = case path + when 'repos/example/repo/pulls/123' + count_path = "\#{dir}/calls" + count = File.exist?(count_path) ? File.read(count_path).to_i : 0 + File.write(count_path, count + 1) + { state: 'open', head: { sha: f['stale'] && count.positive? ? 'changed' : 'head', + repo: { full_name: 'contributor/fork' } } } + when /\\/files\\?/ + files = [{ filename: '_data/test.yml', status: 'modified', sha: 'blob', patch: f['patch'] }] + files << { filename: '_data/other.yml', status: 'modified', sha: 'other', patch: nil } if f['extra_file'] + [files] + when /\\/comments\\?/ + comments = AlphabetizeSuggestions.for_file('_data/test.yml', f['original'], f['patch']).first + [f['existing'] ? comments.map { |c| { user: { login: 'github-actions[bot]' }, commit_id: 'head', body: c[:body] } } : []] + when 'repos/contributor/fork/contents/_data/test.yml?ref=head' + { sha: f['mismatched_blob'] ? 'different-blob' : 'blob' } + when 'repos/contributor/fork/contents/_data/other.yml?ref=head' + { sha: 'other' } + when 'repos/contributor/fork/git/blobs/blob' + { size: f['original'].bytesize, content: Base64.strict_encode64(f['original']) } + when 'repos/contributor/fork/git/blobs/other' + { size: f['original'].bytesize, content: Base64.strict_encode64(f['original']) } + when /\\/reviews\\?/ + [[]] + when 'repos/example/repo/pulls/123/reviews' + File.write("\#{dir}/review.json", STDIN.read) + {} + else + abort "Unexpected API request: \#{ARGV.inspect}" + end + puts JSON.generate(response) + RUBY + FileUtils.chmod(0o755, "#{dir}/gh") + end + end + + class AlphabetizeReviewTest < Minitest::Test + include ReviewFixtures + + def test_posts_review_on_exact_head_commit + output, status, review = run_review + + assert status.success?, output + assert_equal 'head', review.fetch('commit_id') + assert_equal 'COMMENT', review.fetch('event') + assert_equal '_data/test.yml', review.fetch('comments').first.fetch('path') + assert_includes review.fetch('comments').first.fetch('body'), "Test:\n" + end + + def test_does_not_repeat_existing_bot_suggestions + output, status, review = run_review(existing: true) + + assert status.success?, output + assert_nil review + end + + def test_does_not_post_to_a_changed_head + output, status, review = run_review(stale: true) + + refute status.success?, output + assert_nil review + assert_includes output, 'Pull request changed' + end + + def test_rejects_file_from_a_transient_head_even_if_head_returns_to_original + output, status, review = run_review(mismatched_blob: true) + + refute status.success?, output + assert_nil review + assert_includes output, 'Pull request file changed during formatting' + end + + def test_canonical_non_ascii_yaml_does_not_produce_suggestions_or_fallback + original = "# Data\n\nC\u00f4te:\n - org\n" + output, status, review = run_review(original: original, patch: nil) + + assert status.success?, output + assert_nil review + assert_includes output, 'No new inline formatting suggestions' + end + + def test_non_ascii_names_are_preserved_in_real_corrections + output, status, review = run_review(original: "# Data\n\nC\u00f4te: \n - org\n") + + assert status.success?, output + assert_includes review.fetch('comments').first.fetch('body'), "C\u00f4te:\n" + end + + def test_posts_patch_when_inline_comments_are_impossible + output, status, review = run_review(patch: nil) + + assert status.success?, output + assert_empty review.fetch('comments') + assert_includes review.fetch('body'), '```diff' + assert_includes review.fetch('body'), 'outside the PR diff' + end + + def test_fallback_patch_formats_inline_only_files_too + output, status, review = run_review(extra_file: true) + + assert status.success?, output + assert_equal(['_data/test.yml'], review.fetch('comments').map { |comment| comment.fetch('path') }) + patch = review.fetch('body').split("```diff\n", 2).last.split('```', 2).first + Dir.mktmpdir do |dir| + FileUtils.mkdir_p("#{dir}/_data") + original = "# Data\n\nTest: \n - org\n" + %w[test other].each { |name| File.write("#{dir}/_data/#{name}.yml", original) } + result, applied = Open3.capture2e('git', 'apply', '-', stdin_data: patch, chdir: dir) + assert applied.success?, result + %w[test other].each do |name| + assert_equal Alphabetize.format(original), File.read("#{dir}/_data/#{name}.yml") + end + end + end + end + + def test_inline_suggestions_for_whitespace_and_reordering + original = "# Organizations\n\nTest: \n - zebra\n - alpha\n" + comments, incomplete, patch = AlphabetizeSuggestions.for_file( + '_data/test.yml', original, "@@ -1,3 +1,5 @@\n # Organizations\n \n-Test:\n+Test: \n+ - zebra\n+ - alpha\n" + ) + + refute incomplete + assert_equal 1, comments.length + assert(comments.all? { |comment| comment[:side] == 'RIGHT' }) + assert_includes patch, "--- a/_data/test.yml\n+++ b/_data/test.yml\n" + assert_includes comments.map { |comment| comment[:body] }.join, '```suggestion' + assert(comments.all? { |comment| comment[:line] <= 5 }) + lines = original.lines + comments.sort_by { |comment| -comment.fetch(:line) }.each do |comment| + first = comment.fetch(:start_line, comment.fetch(:line)) + text = comment.fetch(:body).split("```suggestion\n", 2).last.split('```', 2).first + lines[first - 1, comment.fetch(:line) - first + 1] = text.lines + end + assert_equal Alphabetize.format(original), lines.join + end + + def test_insertions_anchor_to_an_existing_line + comment = AlphabetizeSuggestions.comment('_data/test.yml', 2, 0, ["new\n"], %W[first\n second\n]) + + assert_equal 2, comment[:line] + assert_includes comment[:body], "```suggestion\nsecond\nnew\n```" + first = AlphabetizeSuggestions.comment('_data/test.yml', 0, 0, ["new\n"], ["first\n"]) + assert_equal 1, first[:line] + assert_includes first[:body], "```suggestion\nnew\nfirst\n```" + end + + def test_multiline_and_deletion_suggestions + comment = AlphabetizeSuggestions.comment('_data/test.yml', 3, 2, [], []) + + assert_equal 3, comment[:start_line] + assert_equal 4, comment[:line] + assert_equal 'RIGHT', comment[:start_side] + assert_includes comment[:body], "```suggestion\n```" + end + + def test_corrections_outside_the_pr_diff_have_a_patch_fallback + original = "# Organizations\n\nTest:\n - zebra\n - alpha\n" + comments, incomplete, patch = AlphabetizeSuggestions.for_file( + '_data/test.yml', original, "@@ -1 +1 @@\n-# Old\n+# Organizations\n" + ) + + assert_empty comments + assert incomplete + assert_includes patch, '+ - zebra' + assert_includes patch, '- - zebra' + Dir.mktmpdir do |dir| + FileUtils.mkdir_p("#{dir}/_data") + File.write("#{dir}/_data/test.yml", original) + output, status = Open3.capture2e('git', 'apply', '-', stdin_data: patch, chdir: dir) + assert status.success?, output + assert_equal Alphabetize.format(original), File.read("#{dir}/_data/test.yml") + end + end + + def test_moves_are_not_offered_as_partial_deletion_suggestions + original = "# Data\n\nTest:\n - zebra\n - alpha\n - beta\n" + comments, incomplete, patch = AlphabetizeSuggestions.for_file( + '_data/test.yml', original, "@@ -3,1 +3,2 @@\n Test:\n+ - zebra\n" + ) + + assert_empty comments + assert incomplete + assert_includes patch, '- - zebra' + assert_includes patch, '+ - zebra' + end + + def test_atomic_replacement_spans_separated_moves + original = "# Data\n\nTest:\n - zebra\n - alpha\n - gamma\n - beta\n" + formatted = Alphabetize.format(original) + start, count, replacement = AlphabetizeSuggestions.replacement(original, formatted) + lines = original.lines + lines[start - 1, count] = replacement + + assert_equal formatted, lines.join + assert_equal YAML.safe_load(original).values.flatten.sort, YAML.safe_load(lines.join).values.flatten.sort + end + + def test_unsafe_paths_are_rejected_before_patch_generation + paths = ["_data/test\n+++ b/other.yml", "_data/test\t.yml", '_data/"test.yml', + '_data/test\\057other.yml', '_data/../other.yml', "_data/test\0.yml"] + paths.each do |path| + assert_raises(ArgumentError) { AlphabetizeSuggestions.for_file(path, "# Data\n\nTest: \n - org\n", nil) } + end + end + + def test_deleted_lines_do_not_advance_the_new_side_coordinates + lines = AlphabetizeSuggestions.visible_lines("@@ -8,3 +8,3 @@\n unchanged\n-deleted\n+added\n last\n") + + assert_equal Set[8, 9, 10], lines + end + + def test_untrusted_yaml_is_never_deserialized_into_objects + assert_raises(Psych::DisallowedClass) { Alphabetize.format("--- !ruby/object:Object {}\n") } + assert_raises(ArgumentError) { Alphabetize.format("# Data\nGroup: not-a-list\n") } + end + + def test_markdown_fences_in_data_cannot_escape_suggestion + comment = AlphabetizeSuggestions.comment('_data/test.yml', 1, 1, [" - ```\n"], []) + + assert_includes comment[:body], "````suggestion\n - ```\n````" + end +end