Add label to remove an item in Azure DevOps

Fixes dotnet#416

Add a new label that sets the work item status of a linked item to "Removed".

Author: BillWagner

DotNet.DocsTools/GitHubObjects/QuestIssueOrPullRequest.cs

@@ -255,7 +255,7 @@ private protected QuestIssueOrPullRequest(JsonElement issueNode, string organiza
         UpdatedAt = ResponseExtractors.GetUpdatedAtValueOrNow(issueNode);
 
         Assignees = [ ..ResponseExtractors.GetChildArrayElements(issueNode, "assignees", item =>
-            Actor.FromJsonElement(item)).Where(actor => actor is not null)];
+            Actor.FromJsonElement(item)).Where(actor => actor is not null)!];
 
         Labels = ResponseExtractors.GetChildArrayElements(issueNode, "labels", item => GitHubLabel.FromJsonElement(item, default)!); 
         Comments = [.. ResponseExtractors.GetChildArrayElements(issueNode, "comments", item =>
@@ -268,7 +268,7 @@ private protected QuestIssueOrPullRequest(JsonElement issueNode, string organiza
 
         StoryPointSize?[] points = ResponseExtractors.GetChildArrayElements(issueNode, "projectItems", item =>
             StoryPointSize.OptionalFromJsonElement(item));
-        ProjectStoryPoints = [ ..points.Where(p => p is not null).ToArray()];
+        ProjectStoryPoints = [ ..points.Where(p => p is not null).ToArray()!];
 
         // check state. If re-opened, don't reference the (not correct) closing PR
         if (includeTimeLine)

actions/sequester/ImportIssues/Program.cs

@@ -117,6 +117,7 @@ private static async Task<QuestGitHubService> CreateService(ImportOptions option
                 options.AzureDevOps.AreaPath,
                 options.ImportTriggerLabel,
                 options.ImportedLabel,
+                options.UnlinkLabel,
                 options.ParentNodes,
                 options.WorkItemTags);
     }

actions/sequester/Quest2GitHub/Models/QuestWorkItem.cs

@@ -1,6 +1,5 @@
 using DotNet.DocsTools.GitHubObjects;
 using DotNet.DocsTools.Utility;
-using Microsoft.DotnetOrg.Ospo;
 
 namespace Quest2GitHub.Models;
 
@@ -354,8 +353,7 @@ public static string BuildDescriptionFromIssue(QuestIssueOrPullRequest issue, st
         }
     }
 
-    static internal async Task<QuestWorkItem?> UpdateWorkItemAsync(QuestWorkItem questItem,
-        QuestIssueOrPullRequest ghIssue,
+    public async Task UpdateWorkItemAsync(QuestIssueOrPullRequest ghIssue,
         QuestClient questClient,
         OspoClient? ospoClient,
         WorkItemProperties issueProperties)
@@ -368,15 +366,15 @@ public static string BuildDescriptionFromIssue(QuestIssueOrPullRequest issue, st
             questAssigneeID = await questClient.GetIDFromEmail(ghAssigneeEmailAddress);
         }
         List<JsonPatchDocument> patchDocument = [];
-        if (issueProperties.ParentNodeId != questItem.ParentWorkItemId)
+        if (issueProperties.ParentNodeId != ParentWorkItemId)
         {
-            if (questItem.ParentWorkItemId != 0)
+            if (ParentWorkItemId != 0)
             {
                 // Remove the existing parent relation.
                 patchDocument.Add(new JsonPatchDocument
                 {
                     Operation = Op.Remove,
-                    Path = "/relations/" + questItem.ParentRelationIndex,
+                    Path = "/relations/" + ParentRelationIndex,
                 });
             };
             if (issueProperties.ParentNodeId != 0)
@@ -401,7 +399,7 @@ public static string BuildDescriptionFromIssue(QuestIssueOrPullRequest issue, st
                 });
             }
         }
-        if ((questAssigneeID is not null) && (questAssigneeID?.Id != questItem.AssignedToId))
+        if ((questAssigneeID is not null) && (questAssigneeID?.Id != AssignedToId))
         {
             // build patch document for assignment.
             JsonPatchDocument assignPatch = new()
@@ -413,7 +411,7 @@ public static string BuildDescriptionFromIssue(QuestIssueOrPullRequest issue, st
             patchDocument.Add(assignPatch);
         }
         Console.WriteLine(issueProperties.IssueLogString);
-        if (issueProperties.WorkItemState != questItem.State)
+        if (issueProperties.WorkItemState != State)
         {
             patchDocument.Add(new JsonPatchDocument
             {
@@ -422,7 +420,7 @@ public static string BuildDescriptionFromIssue(QuestIssueOrPullRequest issue, st
                 Value = issueProperties.WorkItemState,
             });
         }
-        if (issueProperties.IterationPath != questItem.IterationPath)
+        if (issueProperties.IterationPath != IterationPath)
         {
             patchDocument.Add(new JsonPatchDocument
             {
@@ -431,7 +429,7 @@ public static string BuildDescriptionFromIssue(QuestIssueOrPullRequest issue, st
                 Value = issueProperties.IterationPath,
             });
         }
-        if (issueProperties.StoryPoints != (questItem.StoryPoints ?? 0))
+        if (issueProperties.StoryPoints != (StoryPoints ?? 0))
         {
             patchDocument.Add(new JsonPatchDocument
             {
@@ -441,7 +439,7 @@ public static string BuildDescriptionFromIssue(QuestIssueOrPullRequest issue, st
                 Value = issueProperties.StoryPoints,
             });
         }
-        if (issueProperties.Priority != questItem.Priority)
+        if (issueProperties.Priority != Priority)
         {
             patchDocument.Add(new JsonPatchDocument
             {
@@ -451,7 +449,7 @@ public static string BuildDescriptionFromIssue(QuestIssueOrPullRequest issue, st
             });
         }
         var tags = from t in issueProperties.Tags
-                   where !questItem.Tags.Contains(t)
+                   where !Tags.Contains(t)
                    select t;
         if (tags.Any())
         {
@@ -475,16 +473,57 @@ public static string BuildDescriptionFromIssue(QuestIssueOrPullRequest issue, st
                 From = default,
                 Value = BuildDescriptionFromIssue(ghIssue, null)
             });
-            JsonElement jsonDocument = await questClient.PatchWorkItem(questItem.Id, patchDocument);
+            JsonElement jsonDocument = await questClient.PatchWorkItem(Id, patchDocument);
             newItem = WorkItemFromJson(jsonDocument);
         }
         if (!ghIssue.IsOpen && (ghIssue.ClosingPRUrl is not null))
         {
-            newItem = await questItem.AddClosingPR(questClient, ghIssue.ClosingPRUrl) ?? newItem;
+            newItem = await AddClosingPR(questClient, ghIssue.ClosingPRUrl) ?? newItem;
+        }
+    }
+
+    public async Task RemoveWorkItem(QuestIssueOrPullRequest ghIssue,
+        QuestClient questClient,
+        WorkItemProperties issueProperties)
+    {
+        List<JsonPatchDocument> patchDocument = [];
+        patchDocument.Add(new JsonPatchDocument
+        {
+            Operation = Op.Add,
+            Path = "/fields/System.State",
+            Value = "Removed",
+        });
+        var tags = from t in issueProperties.Tags
+                   where !Tags.Contains(t)
+                   select t;
+        if (tags.Any())
+        {
+            string azDoTags = string.Join(";", tags);
+            patchDocument.Add(new JsonPatchDocument
+            {
+                Operation = Op.Add,
+                Path = "/fields/System.Tags",
+                Value = azDoTags
+            });
+        }
+
+        QuestWorkItem? newItem = default;
+        if (patchDocument.Count != 0)
+        {
+            // If any updates are needed, add the description.
+            patchDocument.Add(new JsonPatchDocument
+            {
+                Operation = Op.Add,
+                Path = "/fields/System.Description",
+                From = default,
+                Value = BuildDescriptionFromIssue(ghIssue, null)
+            });
+            JsonElement jsonDocument = await questClient.PatchWorkItem(Id, patchDocument);
+            newItem = WorkItemFromJson(jsonDocument);
         }
-        return newItem;
     }
 
+
     /// <summary>
     /// Construct a work item from the JSON document.
     /// </summary>

actions/sequester/Quest2GitHub/Options/ImportOptions.cs

@@ -47,6 +47,20 @@ public sealed record class ImportOptions
     /// </remarks>
     public required string ImportedLabel { get; init; } = ":pushpin: seQUESTered";
 
+    /// <summary>
+    /// The label used to indicate that a previously linked issue should be removed
+    /// from Azure Devops.  Defaults to <c>💣 vanQUEST</c>.
+    /// </summary>
+    /// Assign this from an environment variable with the following key, <c>ImportOptions__UnlinkLabel</c>:
+    /// <code>
+    /// env:  # Defaults to '💣 vanQUEST'
+    ///   ImportOptions__ImportedLabel: ':smile: example'
+    /// </code>
+    /// If your label has an emoji in it, you must specify this using the GitHub emoji colon syntax:
+    /// <a href="https://github.com/ikatyang/emoji-cheat-sheet"></a>
+    /// </remarks>
+    public required string UnlinkLabel { get; init; } = ":bomb: vanQUEST";
+
     /// <summary>
     /// The set of labels where specific parent nodes should be used.
     /// </summary>

actions/sequester/Quest2GitHub/QuestGitHubService.cs

@@ -22,6 +22,7 @@ namespace Quest2GitHub;
 /// <param name="areaPath">The area path for work items from this repo</param>
 /// <param name="importTriggerLabelText">The text of the label that triggers an import</param>
 /// <param name="importedLabelText">The text of the label that indicates an issue has been imported</param>
+/// <param name="removeLinkItemText">The text of the label that indicates an issue should be removed</param>
 /// <param name="parentNodes">A dictionary of label / parent ID pairs.</param>
 /// <remarks>
 /// The OAuth token takes precedence over the GitHub token, if both are 
@@ -36,6 +37,7 @@ public class QuestGitHubService(
     string areaPath,
     string importTriggerLabelText,
     string importedLabelText,
+    string removeLinkItemText,
     List<ParentForLabel> parentNodes,
     IEnumerable<LabelToTagMap> tagMap) : IDisposable
 {
@@ -46,6 +48,7 @@ public class QuestGitHubService(
 
     private GitHubLabel? _importTriggerLabel;
     private GitHubLabel? _importedLabel;
+    private GitHubLabel? _removeLinkedItemLabel;
     private QuestIteration[]? _allIterations;
 
     /// <summary>
@@ -57,7 +60,7 @@ public class QuestGitHubService(
     /// <returns></returns>
     public async Task ProcessIssues(string organization, string repository, int duration)
     {
-        if (_importTriggerLabel is null || _importedLabel is null)
+        if (_importTriggerLabel is null || _importedLabel is null  || _removeLinkedItemLabel is null)
         {
             await RetrieveLabelIdsAsync(organization, repository);
         }
@@ -97,7 +100,7 @@ async Task ProcessItems(IAsyncEnumerable<QuestIssueOrPullRequest> items)
         {
             await foreach (QuestIssueOrPullRequest item in items)
             {
-                if (item.Labels.Any(l => (l.Id == _importTriggerLabel?.Id) || (l.Id == _importedLabel?.Id)))
+                if (item.Labels.Any(l => (l.Id == _importTriggerLabel?.Id) || (l.Id == _importedLabel?.Id) || (l.Id == _removeLinkedItemLabel?.Id)))
                 {
                     var issueProperties = new WorkItemProperties(item, _allIterations, tagMap, parentNodes);
 
@@ -157,7 +160,7 @@ async IAsyncEnumerable<QuestIssueOrPullRequest> QueryAllOpenIssuesOrPullRequests
     /// <returns>A task representing the current operation</returns>
     public async Task ProcessIssue(string gitHubOrganization, string gitHubRepository, int issueNumber)
     {
-        if (_importTriggerLabel is null || _importedLabel is null)
+        if (_importTriggerLabel is null || _importedLabel is null || _removeLinkedItemLabel is null)
         {
             await RetrieveLabelIdsAsync(gitHubOrganization, gitHubRepository);
         }
@@ -183,41 +186,23 @@ public async Task ProcessIssue(string gitHubOrganization, string gitHubRepositor
         // Evaluate the labels to determine the right action.
         bool request = ghIssue.Labels.Any(l => l.Id == _importTriggerLabel?.Id);
         bool sequestered = ghIssue.Labels.Any(l => l.Id == _importedLabel?.Id);
+        bool vanquished = ghIssue.Labels.Any(l => l.Id == _removeLinkedItemLabel?.Id);
         // Only query AzDo if needed:
-        QuestWorkItem? questItem = (request || sequestered)
+        QuestWorkItem? questItem = (request || sequestered || vanquished)
             ? await FindLinkedWorkItemAsync(ghIssue)
             : null;
 
         var issueProperties = new WorkItemProperties(ghIssue, _allIterations, tagMap, parentNodes);
 
-        // The order here is important to avoid a race condition that causes
-        // an issue to be triggered multiple times.
-        // First, if an issue is open and the trigger label is added, link or 
-        // update. Update is safe, because it will only update the quest issue's
-        // state or assigned field. That can't trigger a new GH action run.
-        if (request)
+        Task workDone = (request, sequestered, vanquished, questItem) switch
         {
-            if (questItem is null)
-            {
-                questItem = await LinkIssueAsync(ghIssue, issueProperties);
-            }
-            else if (questItem is not null)
-            {
-                // This allows a human to force a manual update: just add the trigger label.
-                // Note that it updates even if the item is closed.
-                await QuestWorkItem.UpdateWorkItemAsync(questItem, ghIssue, _azdoClient, _ospoClient, issueProperties);
-
-            }
-            // Next, if the item is already linked, consider any updates.
-            // It's important that adding the linked label is the last
-            // mutation done in the linking process. That way, the GH Action
-            // does get triggered again. The second trigger will check for any updates
-            // a human made to assigned or state while the initial run was taking place.
-        }
-        else if (sequestered && questItem is not null)
-        {
-            await QuestWorkItem.UpdateWorkItemAsync(questItem, ghIssue, _azdoClient, _ospoClient, issueProperties);
-        }
+            (false, false, false,        _) => Task.CompletedTask, // No labels. Do nothing.
+            (    _,     _,  true,     null) => Task.CompletedTask, // Unlink, but no link. Do nothing.
+            (    _,     _, false,     null) => LinkIssueAsync(ghIssue, issueProperties), // No link, but one of the link labels was applied.
+            (    _,     _,  true, not null) => questItem.RemoveWorkItem(ghIssue, _azdoClient, issueProperties), // Unlink.
+            (    _,     _, false, not null) => questItem.UpdateWorkItemAsync(ghIssue, _azdoClient, _ospoClient, issueProperties), // update
+        };
+        await workDone;
     }
 
     /// <summary>
@@ -338,6 +323,7 @@ private async Task RetrieveLabelIdsAsync(string org, string repo)
         {
             if (label.Name == importTriggerLabelText) _importTriggerLabel = label;
             if (label.Name == importedLabelText) _importedLabel = label;
+            if (label.Name == removeLinkItemText) _removeLinkedItemLabel = label;
         }
     }