Refactor most of the remaining queries and mutations. (#281)

* Remove unused query type

* Use new style query for default branch

Use the updated ScalarQuery class for the default branch query.

Write tests for the new navigation and the new query result type.

* consolidate label queries

There were four different sets of identical code that queried for labels and created a label object from them. Consolidate them in one GitHubLabel object that now supports both a scalar and an enumeration query.

* Refactor What's New query

Modify the What's New query for pull requests merged in a sprint to the new enumeration query.

* Refactor Files in PR query

Move the Files in PR query to the new interface driven format.

* code review

* Refactor mutations

* Code review

Clean up unnecessary usings, add Xml comments.

Author: BillWagner

DotNet.DocsTools/GitHubObjects/BankruptcyIssue.cs

@@ -48,20 +48,26 @@ query FindIssuesForBankruptcyQuery($organization: String!, $repository: String!,
         }
         """;
 
-    public static GraphQLPacket GetQueryPacket(BankruptcyIssueVariables variables) =>
-        new()
-        {
-            query = OpenIssuesForBankruptcyQuery,
-            variables =
-            {
-                ["organization"] = variables.Organization,
-                ["repository"] = variables.Repository,
-            }
-        };
+    public static GraphQLPacket GetQueryPacket(BankruptcyIssueVariables variables, bool isScalar) => isScalar
+        ? throw new InvalidOperationException("This query doesn't support scalar queries")
+        : new()
+          {
+              query = OpenIssuesForBankruptcyQuery,
+              variables =
+              {
+                  ["organization"] = variables.Organization,
+                  ["repository"] = variables.Repository,
+              }
+          };
 
     public static BankruptcyIssue FromJsonElement(JsonElement element, BankruptcyIssueVariables unused) => 
         new(element);
 
+    public static IEnumerable<string> NavigationToNodes(bool isScalar) =>
+        isScalar
+            ? throw new InvalidOperationException("This query doesn't support scalar queries")
+            : ["repository", "issues"];
+
     public BankruptcyIssue(JsonElement element) : base(element)
     {
         Author = Actor.FromJsonElement(ResponseExtractors.GetAuthorChildElement(element));

DotNet.DocsTools/GitHubObjects/CloseBankruptyIssueMutation.cs

@@ -0,0 +1,63 @@
+using DotNet.DocsTools.GraphQLQueries;
+using DotNetDocs.Tools.GitHubCommunications;
+
+namespace DotNet.DocsTools.GitHubObjects;
+
+/// <summary>
+/// Variables for the CloseBankruptcyIssueMutation.
+/// </summary>
+/// <param name="NodeID">The node ID for the issue to close.</param>
+/// <param name="LabelID">The label ID (typically for a "won't fix" label) to add before closing.</param>
+/// <param name="CommentText">The comment text to add to the issue as a close message.</param>
+public readonly record struct CloseBankruptcyIssueVariables(string NodeID, string LabelID, string CommentText);
+
+/// <summary>
+/// Mutation to close an issue.
+/// </summary>
+public class CloseBankruptyIssueMutation : IGitHubMutation<CloseBankruptyIssueMutation, CloseBankruptcyIssueVariables>
+{
+    private const string mutationPacketText = """
+        mutation AddLabels($nodeID: ID!, $labelIDs: [ID!]!, $commentText: String!) {
+          addLabelsToLabelable(input: {
+            labelableId:$nodeID
+            labelIds:$labelIDs
+            clientMutationId:"dotnet-docs-tools"
+          }) {
+            labelable {
+              __typename
+            }
+            clientMutationId
+          }
+          addComment(input: {
+            subjectId:$nodeID,
+            body:$commentText,
+            clientMutationId: "dotnet-docs-tools"
+          }) {
+            clientMutationId
+          }
+          closeIssue(input: {
+            issueId:$nodeID,
+            clientMutationId: "dotnet-docs-tools"
+          }) {
+            clientMutationId
+         }
+        }
+        """;
+
+    /// <summary>
+    /// Construct the GraphQL packet for closing an issue.
+    /// </summary>
+    /// <param name="variables">The variables that determines which issue to close.</param>
+    /// <returns>The GraphQL packet object.</returns>
+    public static GraphQLPacket GetMutationPacket(CloseBankruptcyIssueVariables variables) =>
+        new()
+        {
+            query = mutationPacketText,
+            variables = 
+            {
+                ["nodeID"] = variables.NodeID,
+                ["labelIDs"] = new[] { variables.LabelID },
+                ["commentText"] = variables.CommentText
+            }
+        };
+}

DotNet.DocsTools/GitHubObjects/DefaultBranch.cs

@@ -0,0 +1,45 @@
+using DotNetDocs.Tools.GitHubCommunications;
+using System.Text.Json;
+
+namespace DotNet.DocsTools.GitHubObjects;
+
+public readonly record struct DefaultBranchVariables(string Organization, string Repository);
+public record DefaultBranch : IGitHubQueryResult<DefaultBranch, DefaultBranchVariables>
+{
+    private const string Query = """
+      query GetDefaultBranch($organization: String!, $repository: String!) {
+        repository(owner: $organization, name: $repository) {
+          defaultBranchRef {
+            name
+          }
+        }
+      }
+      """;
+
+    public static GraphQLPacket GetQueryPacket(DefaultBranchVariables variables, bool isScalar) => isScalar
+        ? new()
+        {
+            query = Query,
+            variables =
+            {
+                ["organization"] = variables.Organization,
+                ["repository"] = variables.Repository,
+            }
+        }
+        : throw new InvalidOperationException("This query doesn't support enumerations");
+
+    public static IEnumerable<string> NavigationToNodes(bool isScalar) =>
+        isScalar
+            ? ["repository", "defaultBranchRef"]
+            : throw new InvalidOperationException("This query doesn't support array queries");
+
+    public string DefaultBranchName { get; }
+
+    private DefaultBranch(string defaultBranchName) => DefaultBranchName = defaultBranchName;
+
+    public static DefaultBranch FromJsonElement(JsonElement branchRefNode, DefaultBranchVariables _)
+    {
+        var branchName = ResponseExtractors.StringProperty(branchRefNode, "name");
+        return new DefaultBranch(branchName);
+    }
+}

DotNet.DocsTools/GitHubObjects/GitHubLabel.cs

@@ -1,12 +1,96 @@
-using System.Text.Json;
+using DotNetDocs.Tools.GitHubCommunications;
+using System.Text.Json;
 
 namespace DotNet.DocsTools.GitHubObjects;
 
+/// <summary>
+/// The variables for finding a GitHub label query.
+/// </summary>
+/// <param name="Organization">The GitHub organization</param>
+/// <param name="Repository">The GitHub repository</param>
+/// <param name="labelText">The text of the label.</param>
+/// <remarks>For labels with emojis, the `:` prefix and suffix may be used to
+/// describe the emoji.
+/// </remarks>
+public readonly record struct FindLabelQueryVariables(string Organization, string Repository, string labelText);
+
 /// <summary>
 /// Record type for a GitHub label
 /// </summary>
-public sealed record GitHubLabel
+public sealed record GitHubLabel : IGitHubQueryResult<GitHubLabel, FindLabelQueryVariables>
 {
+    private static readonly string allLabels = """
+    query EnumerateLabels($organization: String!, $repository: String!, $cursor:String) {
+      repository(owner: $organization, name: $repository) {
+        labels(first: 50, after: $cursor) {
+          pageInfo {
+            hasNextPage
+            endCursor
+          }
+          nodes {
+            name
+            id
+          }
+        }
+      }
+    }
+    """;
+
+    private const string findLabel = """
+        query FindLabel($labelName: String!, $organization: String!, $repository: String!) {
+          repository(owner:$organization, name:$repository) {
+            label(name: $labelName) {
+              id
+              name
+            }
+          }
+        }
+        """;
+
+    public static GraphQLPacket GetQueryPacket(FindLabelQueryVariables variables, bool isScalar) => isScalar
+        ? new()
+        {
+            query = findLabel,
+            variables =
+            {
+                ["organization"] = variables.Organization,
+                ["repository"] = variables.Repository,
+                ["labelName"] = variables.labelText
+            }
+        }
+        : new()
+        {
+            query = allLabels,
+            variables =
+            {
+                ["organization"] = variables.Organization,
+                ["repository"] = variables.Repository
+            }
+        };
+
+    public static IEnumerable<string> NavigationToNodes(bool isScalar) => isScalar
+        ? ["repository", "label"]
+        : ["repository", "labels"];
+
+    /// <summary>
+    /// Construct a GitHub label from a JsonElement
+    /// </summary>
+    /// <param name="labelElement"></param>
+    /// <exception cref="ArgumentException"></exception>
+    private GitHubLabel(string name, string id) =>
+        (Name, Id) = (name, id);
+
+    public static GitHubLabel? FromJsonElement(JsonElement element, FindLabelQueryVariables variables) =>
+        element.ValueKind switch
+        { 
+            JsonValueKind.Null => null,
+            JsonValueKind.Object => new GitHubLabel(
+                name: ResponseExtractors.StringProperty(element, "name"),
+                id: ResponseExtractors.StringProperty(element, "id")
+            ),
+            _ => throw new ArgumentException("Must be an object", nameof(element))
+       };
+
     /// <summary>
     /// The name of the label.
     /// </summary>
@@ -20,20 +104,5 @@ public sealed record GitHubLabel
     /// all GH objects, this would be in the common base type.
     /// </remarks>
     public string Id { get; }
-
-    /// <summary>
-    /// Construct a GitHub label from a JsonElement
-    /// </summary>
-    /// <param name="labelElement"></param>
-    /// <exception cref="ArgumentException"></exception>
-    public GitHubLabel(JsonElement labelElement)
-    {
-        if (labelElement.ValueKind != JsonValueKind.Object)
-        {
-            throw new ArgumentException("Must be an object", nameof(labelElement));
-        }
-        Name = ResponseExtractors.StringProperty(labelElement, "name")!;
-        Id = ResponseExtractors.StringProperty(labelElement, "id")!;
-    }
 }
 

DotNet.DocsTools/GitHubObjects/IGitHubQueryResult.cs

@@ -20,14 +20,29 @@ public interface IGitHubQueryResult<TResult, TVariables> where TResult : IGitHub
     /// <param name="variables">
     /// An instance of a record whose members are transformed into the dictionary for the query.
     /// </param>
+    /// <param name="isScalar">True to return the query for a scalar query. False for an enumeration query.</param>
     /// <returns>The Packet structure for the query.</returns>
-    public static abstract GraphQLPacket GetQueryPacket(TVariables variables);
+    public static abstract GraphQLPacket GetQueryPacket(TVariables variables, bool isScalar);
 
     /// <summary>
     /// Construct the <typeparamref name="TResult"/> object from the JsonElement.
     /// </summary>
     /// <param name="element">The Json element representing one object.</param>
     /// <returns>An instance of the result type.</returns>
-    public static abstract TResult FromJsonElement(JsonElement element, TVariables variables);
+    public static abstract TResult? FromJsonElement(JsonElement element, TVariables variables);
 
+    /// <summary>
+    /// Retrieve the path to the correct data node from the "data" JsonElement node.
+    /// </summary>
+    /// <param name="isScalar">True if the query is a scalar query. False if it's enumerating an array</param>
+    /// <returns>
+    /// The sequence of node names to traverse from the "data" node to the node representing
+    /// the object being returned.
+    /// </returns>
+    /// <remarks>
+    /// For scalar queries, this navigation should return the node containing the result.
+    /// For array queries, this navigation should return the parent of the "nodes" element,
+    /// where the "nodes" element contains the array being enumerated.
+    /// </remarks>
+    public static abstract IEnumerable<string> NavigationToNodes(bool isScalar);
 }

DotNet.DocsTools/GitHubObjects/Issue.cs

@@ -2,38 +2,18 @@
 
 namespace DotNet.DocsTools.GitHubObjects;
 
-public abstract record Issue
+public abstract record Issue : IssueOrPullRequest
 { 
-    public Issue(JsonElement element)
+    public Issue(JsonElement element) : base(element)
     {
-        Id = ResponseExtractors.GetIdValue(element);
-        Number = element.GetProperty("number").GetInt32();
-        Title = ResponseExtractors.GetTitleValue(element);
         Body = ResponseExtractors.GetBodyValue(element);
     }
 
     /// <summary>
-    /// The node ID for the issue.
+    /// The body of the issue
     /// </summary>
     /// <remarks>
-    /// Every GitHub object has a unique node ID. This is used to identify the issue. 
-    /// It may be that every query uses the nodeID. I haven't verified that yet. If that
-    /// turns out to be true, then this property should be moved to the base class.
+    /// This is the body of the issue as markdown text.
     /// </remarks>
-    public string Id { get; }
-
-    /// <summary> 
-    /// Retrieve the issue number.
-    /// </summary>
-    public int Number { get; }
-
-    /// <summary>
-    /// The title of the issue.
-    /// </summary>
-    public string Title { get; }
-
-    /// <summary>
-    /// The body of the issue
-    /// </summary>
     public string? Body { get; }
 }

DotNet.DocsTools/GitHubObjects/IssueOrPullRequest.cs

@@ -0,0 +1,44 @@
+using System.Text.Json;
+
+namespace DotNet.DocsTools.GitHubObjects;
+
+/// <summary>
+/// This is the base class for any query result representing an issue or pull request.
+/// </summary>
+/// <remarks>
+/// GitHub's object model has a common type for issue and PR, so we probably should too.
+/// This represents that common base type.
+/// </remarks>
+public abstract record IssueOrPullRequest
+{
+    /// <summary>
+    /// Construct this record from the JsonElement.
+    /// </summary>
+    /// <param name="element">The Json object that represents the issue or PR.</param>
+    public IssueOrPullRequest(JsonElement element)
+    {
+        Id = ResponseExtractors.GetIdValue(element);
+        Number = element.GetProperty("number").GetInt32();
+        Title = ResponseExtractors.GetTitleValue(element);
+    }
+
+    /// <summary>
+    /// The node ID for the issue.
+    /// </summary>
+    /// <remarks>
+    /// Every GitHub object has a unique node ID. This is used to identify the issue. 
+    /// It may be that every query uses the nodeID. I haven't verified that yet. If that
+    /// turns out to be true, then this property should be moved to the base class.
+    /// </remarks>
+    public string Id { get; }
+
+    /// <summary> 
+    /// Retrieve the issue or PR number.
+    /// </summary>
+    public int Number { get; }
+
+    /// <summary>
+    /// The title of the issue or PR.
+    /// </summary>
+    public string Title { get; }
+}