diff --git a/README.md b/README.md index 20299dd..2b4a59d 100644 --- a/README.md +++ b/README.md @@ -153,6 +153,11 @@ version (`--major-label`, `--minor-label` and `--patch-label` rename them). It r and a later run removes only those, never a label a person added. It needs `GITHUB_TOKEN` with `pull-requests: write`. Without write access, as on a pull request from a fork, it writes the job summary, warns and succeeds. +With `--fail-on major`, a breaking change fails the check, and the comment says how to go ahead: add the +`breaking-allowed` label (`--allow-label` renames it). Adding the label runs the workflow again, provided it runs on +the `labeled` and `unlabeled` events, and the check passes with the change labelled `breaking`. So a breaking change is +caught, labelled for release-drafter, and merged only once someone says it is intended. + ### Provider specs Before it had a command per source, the tool took two provider specs, and `diff` still does, unchanged, for the builds diff --git a/src/assembly-differ/PullRequests/Comment.cs b/src/assembly-differ/PullRequests/Comment.cs index fc43392..33fcd29 100644 --- a/src/assembly-differ/PullRequests/Comment.cs +++ b/src/assembly-differ/PullRequests/Comment.cs @@ -17,11 +17,24 @@ public static class Comment /// GitHub refuses a comment over 65536 characters; the details stop well before that. private const int MaxLength = 60000; - public static string Render(JsonElement report, IReadOnlyCollection labels) + public static string Render(JsonElement report, IReadOnlyCollection labels, Gate gate = Gate.None, string allowLabel = "") { var body = new StringBuilder(); body.AppendLine(Marker); body.AppendLine(LabelsMarkerPrefix + string.Join(",", labels) + " -->"); + switch (gate) + { + case Gate.Blocked: + body.AppendLine( + allowLabel.Length > 0 + ? $"> [!CAUTION]\n> This check fails on this change. If it is intended, add the `{allowLabel}` label to allow it.\n" + : "> [!CAUTION]\n> This check fails on this change.\n" + ); + break; + case Gate.Allowed: + body.AppendLine($"> [!NOTE]\n> The `{allowLabel}` label allows this change.\n"); + break; + } if (report.TryGetProperty("firstRelease", out var first) && first.GetBoolean()) { diff --git a/src/assembly-differ/PullRequests/PullRequestCommand.cs b/src/assembly-differ/PullRequests/PullRequestCommand.cs index a02f7ca..0089de0 100644 --- a/src/assembly-differ/PullRequests/PullRequestCommand.cs +++ b/src/assembly-differ/PullRequests/PullRequestCommand.cs @@ -5,10 +5,19 @@ using System.Net; using System.Text.Json; using System.Threading.Tasks; +using Differ; using Nullean.Argh; namespace Differ.PullRequests; +/// Whether a change at --fail-on holds the check back. +public enum Gate +{ + None, + Allowed, + Blocked, +} + internal sealed class PullRequestCommand { /// @@ -20,22 +29,28 @@ internal sealed class PullRequestCommand /// hidden marker and updated, and the labels this tool set are recorded in it: a later run swaps only those, never a /// label a person added. It needs GITHUB_TOKEN with pull-requests: write. Without write access, as on a pull request /// from a fork, it writes the job summary, warns and succeeds; outside a pull request it writes the job summary only. + /// With --fail-on, a change at that level fails the check until someone adds the allow label, breaking-allowed by + /// default; the workflow has to run on the labeled and unlabeled events too, so adding the label runs it again. /// /// The api-changes.json a command wrote with --format json. /// The repository as owner/name; defaults to GITHUB_REPOSITORY. /// The pull request number; defaults to the one in GITHUB_EVENT_PATH. + /// Exit with code 4 when the suggested version change is at least this, unless the pull request has the allow label; none never fails. + /// The label that allows a change at --fail-on, so the check passes; empty allows none. /// The label for a Major change, matching release-drafter's; empty sets none. /// The label for a Minor change; empty sets none. /// The label for a Patch change; empty sets none. /// Leave the comment alone. /// Leave the labels alone. /// assembly-differ release build/output/MyLib.1.3.0.nupkg -f json -o build/output - /// assembly-differ pull-request build/output/api-changes.json + /// assembly-differ pull-request build/output/api-changes.json --fail-on major [CommandName("pull-request")] public async Task PullRequest( [Argument] string report, string? repository = null, int? pullRequest = null, + SuggestedVersionChange failOn = SuggestedVersionChange.None, + string allowLabel = "breaking-allowed", string majorLabel = "breaking", string minorLabel = "feature", string patchLabel = "", @@ -53,43 +68,64 @@ public async Task PullRequest( using var document = JsonDocument.Parse(await File.ReadAllTextAsync(report)); var root = document.RootElement; - var suggested = root.GetProperty("suggestedVersionChange").GetString(); + var suggestedText = root.GetProperty("suggestedVersionChange").GetString(); + var suggested = Enum.Parse(suggestedText!, ignoreCase: true); var label = suggested switch { - "Major" => majorLabel, - "Minor" => minorLabel, - "Patch" => patchLabel, + SuggestedVersionChange.Major => majorLabel, + SuggestedVersionChange.Minor => minorLabel, + SuggestedVersionChange.Patch => patchLabel, _ => "", }; string[] wanted = labels && label.Length > 0 ? [label] : []; - var body = Comment.Render(root, wanted); + var gated = failOn > SuggestedVersionChange.None && suggested >= failOn; + + repository ??= Env("GITHUB_REPOSITORY"); + pullRequest ??= PullRequestFromEvent(); + var token = Env("GITHUB_TOKEN") ?? Env("GH_TOKEN"); + var onPullRequest = repository is not null && pullRequest is not null && !string.IsNullOrEmpty(token); + var api = new Uri(Env("GITHUB_API_URL") ?? "https://api.github.com"); + using var github = onPullRequest ? new GitHubApi(api, token!, repository!, pullRequest!.Value) : null; + + // the labels decide whether a change at --fail-on is allowed, so they are read first + IReadOnlyCollection present = []; + if (github is not null) + { + try + { + present = await github.Labels(); + } + catch (Exception e) when (e is GitHubApiException or System.Net.Http.HttpRequestException) + { + Console.Error.WriteLine($"[diff] could not read pull request #{pullRequest} in {repository}: {e.Message}"); + return 1; + } + } + var allowed = gated && allowLabel.Length > 0 && present.Contains(allowLabel, StringComparer.OrdinalIgnoreCase); + var gate = !gated ? Gate.None : allowed ? Gate.Allowed : Gate.Blocked; + var body = Comment.Render(root, wanted, gate, allowLabel); var summary = Env("GITHUB_STEP_SUMMARY"); if (!string.IsNullOrEmpty(summary)) await File.AppendAllTextAsync(summary, body + Environment.NewLine); - repository ??= Env("GITHUB_REPOSITORY"); - pullRequest ??= PullRequestFromEvent(); + var exitCode = Verdict(gate, suggested, failOn, allowLabel, onPullRequest); if (repository is null || pullRequest is null) { Console.WriteLine("[diff] Not a pull request: wrote the job summary only"); - return 0; + return exitCode; } - - var token = Env("GITHUB_TOKEN") ?? Env("GH_TOKEN"); - if (string.IsNullOrEmpty(token)) + if (github is null) { Console.Error.WriteLine("[diff] warning: GITHUB_TOKEN is not set, so the pull request is left as it is"); - return 0; + return exitCode; } - var api = new Uri(Env("GITHUB_API_URL") ?? "https://api.github.com"); - using var github = new GitHubApi(api, token, repository, pullRequest.Value); try { var existing = await github.FindComment(Comment.Marker); if (labels) - await SetLabels(github, existing is { } e ? Comment.LabelsIn(e.Body) : [], wanted); + await SetLabels(github, present, existing is { } e ? Comment.LabelsIn(e.Body) : [], wanted); if (comment) { if (existing is { } found) @@ -98,7 +134,7 @@ public async Task PullRequest( await github.CreateComment(body); } Console.WriteLine($"[diff] Updated pull request #{pullRequest} in {repository}: {suggested}{(wanted.Length > 0 ? $", labelled {wanted[0]}" : "")}"); - return 0; + return exitCode; } catch (GitHubApiException e) when (e.Status is HttpStatusCode.Forbidden or HttpStatusCode.NotFound or HttpStatusCode.Unauthorized) { @@ -106,7 +142,7 @@ public async Task PullRequest( Console.Error.WriteLine( $"[diff] warning: the token cannot write to pull request #{pullRequest} ({(int)e.Status}), as on a pull request from a fork; wrote the job summary only" ); - return 0; + return exitCode; } catch (Exception e) when (e is GitHubApiException or System.Net.Http.HttpRequestException) { @@ -115,10 +151,31 @@ public async Task PullRequest( } } + /// The exit code: 4 when a change at --fail-on is not allowed, with a line saying why and what to do. + private static int Verdict(Gate gate, SuggestedVersionChange suggested, SuggestedVersionChange failOn, string allowLabel, bool onPullRequest) + { + switch (gate) + { + case Gate.Allowed: + Console.WriteLine($"[diff] The {suggested} change is allowed by the {allowLabel} label"); + return 0; + case Gate.Blocked: + var how = onPullRequest && allowLabel.Length > 0 ? $"; add the {allowLabel} label to the pull request to allow it" : ""; + Console.Error.WriteLine($"[diff] The {suggested} change is at least --fail-on {failOn.ToString().ToLowerInvariant()}{how}"); + return 4; + default: + return 0; + } + } + /// Removes the labels this tool set before and no longer wants, and adds the ones it wants. - private static async Task SetLabels(GitHubApi github, IReadOnlyCollection setBefore, IReadOnlyCollection wanted) + private static async Task SetLabels( + GitHubApi github, + IReadOnlyCollection present, + IReadOnlyCollection setBefore, + IReadOnlyCollection wanted + ) { - var present = await github.Labels(); foreach (var stale in setBefore.Except(wanted, StringComparer.OrdinalIgnoreCase)) if (present.Contains(stale, StringComparer.OrdinalIgnoreCase)) await github.RemoveLabel(stale); diff --git a/tests/assembly-differ.Tests/.snapshots/CommandsTests/Help.pull-request.cc54f021.verified.txt b/tests/assembly-differ.Tests/.snapshots/CommandsTests/Help.pull-request.cc54f021.verified.txt index 39876aa..c764014 100644 --- a/tests/assembly-differ.Tests/.snapshots/CommandsTests/Help.pull-request.cc54f021.verified.txt +++ b/tests/assembly-differ.Tests/.snapshots/CommandsTests/Help.pull-request.cc54f021.verified.txt @@ -11,6 +11,9 @@ Global options: Options: --repository The repository as owner/name; defaults to GITHUB_REPOSITORY. [default: null] --pull-request The pull request number; defaults to the one in GITHUB_EVENT_PATH. [default: default] + --fail-on Exit with code 4 when the suggested version change is at least this, unless the pull request has the allow label; none never fails. [default: none] + One of: + --allow-label The label that allows a change at --fail-on, so the check passes; empty allows none. [default: breaking-allowed] --major-label The label for a Major change, matching release-drafter's; empty sets none. [default: breaking] --minor-label The label for a Minor change; empty sets none. [default: feature] --patch-label The label for a Patch change; empty sets none. [default: ] @@ -23,8 +26,10 @@ Notes: hidden marker and updated, and the labels this tool set are recorded in it: a later run swaps only those, never a label a person added. It needs GITHUB_TOKEN with pull-requests: write. Without write access, as on a pull request from a fork, it writes the job summary, warns and succeeds; outside a pull request it writes the job summary only. + With --fail-on, a change at that level fails the check until someone adds the allow label, breaking-allowed by + default; the workflow has to run on the labeled and unlabeled events too, so adding the label runs it again. Examples: assembly-differ release build/output/MyLib.1.3.0.nupkg -f json -o build/output - assembly-differ pull-request build/output/api-changes.json + assembly-differ pull-request build/output/api-changes.json --fail-on major diff --git a/tests/assembly-differ.Tests/PullRequestTests.cs b/tests/assembly-differ.Tests/PullRequestTests.cs index 3c361d6..62e3e32 100644 --- a/tests/assembly-differ.Tests/PullRequestTests.cs +++ b/tests/assembly-differ.Tests/PullRequestTests.cs @@ -93,6 +93,66 @@ public async Task Takes_off_its_label_when_nothing_changes_any_more() github.Comments.Should().ContainSingle().Which.Body.Should().Contain("suggested version change **None**"); } + [Test] + public async Task Fails_a_breaking_change_until_the_allow_label_is_added() + { + using var fixture = Scenarios.Create("method-removed"); + using var github = new FakeGitHub(); + var report = await ReportFor(fixture, "report"); + + var (blocked, _) = await PullRequest(github, fixture, report, true, "--fail-on", "major"); + + blocked.ExitCode.Should().Be(4); + blocked.Error.Should().Contain("add the breaking-allowed label to the pull request to allow it"); + github.Labels.Should().Equal("breaking"); + github.Comments.Should().ContainSingle().Which.Body.Should().Contain("add the `breaking-allowed` label to allow it"); + + // the author agrees: adding the label runs the workflow again + github.Labels.Add("breaking-allowed"); + var (allowed, _) = await PullRequest(github, fixture, report, true, "--fail-on", "major"); + + allowed.ExitCode.Should().Be(0, allowed.Error); + allowed.Out.Should().Contain("The Major change is allowed by the breaking-allowed label"); + github.Labels.Should().Equal("breaking", "breaking-allowed"); + github.Comments.Should().ContainSingle().Which.Body.Should().Contain("The `breaking-allowed` label allows this change."); + } + + [Test] + public async Task A_change_below_fail_on_passes() + { + using var fixture = Scenarios.Create("method-added"); + using var github = new FakeGitHub(); + + var (result, _) = await PullRequest(github, fixture, await ReportFor(fixture, "report"), true, "--fail-on", "major"); + + result.ExitCode.Should().Be(0, result.Error); + github.Labels.Should().Equal("feature"); + } + + [Test] + public async Task The_allow_label_can_be_renamed() + { + using var fixture = Scenarios.Create("method-removed"); + using var github = new FakeGitHub(); + github.Labels.Add("api-break-ok"); + + var (result, _) = await PullRequest(github, fixture, await ReportFor(fixture, "report"), true, "--fail-on", "major", "--allow-label", "api-break-ok"); + + result.ExitCode.Should().Be(0, result.Error); + } + + [Test] + public async Task Outside_a_pull_request_fail_on_still_applies() + { + using var fixture = Scenarios.Create("method-removed"); + using var github = new FakeGitHub(); + + var (result, _) = await PullRequest(github, fixture, await ReportFor(fixture, "report"), false, "--fail-on", "major"); + + result.ExitCode.Should().Be(4); + result.Error.Should().Contain("The Major change is at least --fail-on major").And.NotContain("add the"); + } + [Test] public async Task Never_removes_a_label_a_person_added() { @@ -135,7 +195,7 @@ public async Task Fails_with_a_message_when_GitHub_cannot_be_reached() var result = await Cli.RunInAsync(fixture.Root, environment, "pull-request", report, "--repository", "owner/repo", "--pull-request", "7"); result.ExitCode.Should().Be(1); - result.Error.Should().StartWith("[diff] could not update pull request #7 in owner/repo:").And.NotContain(" at "); + result.Error.Should().StartWith("[diff] could not read pull request #7 in owner/repo:").And.NotContain(" at "); } [Test]