wuffle 0.73.3 → 0.75.0

package/lib/apps/github-app/GithubApp.js

@@ -28,6 +28,7 @@ const RequiredEvents = [
 
 /**
  * @typedef {import('./types.js').Installation} Installation
+ * @typedef {import('../../types.js').Octokit} Octokit
  */
 
 /**
@@ -53,8 +54,19 @@ export default function GithubApp(config, app, logger, injector) {
 
   // cached data //////////////////
 
+  /**
+   * @type {Promise<Installation[]> | null}
+   */
   let installations = null;
+
+  /**
+   * @type {Promise<Record<string, Installation>> | null}
+   */
   let installationsByLogin = null;
+
+  /**
+   * @type {Promise<Record<string, Installation>> | null}
+   */
   let installationsById = null;
 
   // reactivity ////////////////////
@@ -71,12 +83,17 @@ export default function GithubApp(config, app, logger, injector) {
   // functionality /////////////////
 
   /**
-   * @return {Promise<import('../../types.js').Octokit>}
+   * @return {Promise<Octokit>}
    */
   function getAppScopedClient() {
     return app.auth();
   }
 
+  /**
+   * Return installations
+   *
+   * @return {Promise<Installation[]>}
+   */
   function getInstallations() {
     installations = installations || fetchInstallations().then(installations => {
 
@@ -90,6 +107,11 @@ export default function GithubApp(config, app, logger, injector) {
     return installations;
   }
 
+  /**
+   * Return installations by ID
+   *
+   * @return {Promise<Record<string, Installation>>}
+   */
   function getInstallationsById() {
 
     installationsById = installationsById || getInstallations().then(
@@ -106,9 +128,9 @@ export default function GithubApp(config, app, logger, injector) {
   /**
    * Get an installation for the given id.
    *
-   * @param {string} id
+   * @param {string|number} id
    *
-   * @return {Promise<Installation?>}
+   * @return {Promise<Installation | undefined>}
    */
   function getInstallationById(id) {
     return getInstallationsById().then(byId => {
@@ -119,7 +141,7 @@ export default function GithubApp(config, app, logger, injector) {
   /**
    * Return map of installations, grouped by org / login.
    *
-   * @return {Promise<Object<String, Installation>>}
+   * @return {Promise<Record<string, Installation>>}
    */
   function getInstallationsByLogin() {
 
@@ -155,6 +177,13 @@ export default function GithubApp(config, app, logger, injector) {
     });
   }
 
+  /**
+   * Return true if installation is enabled.
+   *
+   * @param {Installation} installation
+   *
+   * @return {Promise<boolean>}
+   */
   function isInstallationEnabled(installation) {
 
     const {
@@ -240,10 +269,10 @@ export default function GithubApp(config, app, logger, injector) {
   /**
    * Fetch active installations.
    *
-   * @return {Promise<Array<Installation>>} installations
+   * @return {Promise<Installation[]>} installations
    */
   function fetchInstallations() {
-    return /** @type Promise<Array<Installation>> */ (getAppScopedClient().then(
+    return /** @type Promise<Installation[]> */ (getAppScopedClient().then(
       octokit => octokit.paginate(
         octokit.rest.apps.listInstallations,
         { per_page: 100 }
@@ -253,13 +282,47 @@ export default function GithubApp(config, app, logger, injector) {
 
   // api ///////////////////
 
+  /**
+   * Return an application-scoped octokit client.
+   *
+   * @return {Promise<Octokit>}
+   */
   this.getAppScopedClient = getAppScopedClient;
 
+  /**
+   * Return true if installation is enabled.
+   *
+   * @param {Installation} installation
+   *
+   * @return {Promise<boolean>}
+   */
   this.isInstallationEnabled = isInstallationEnabled;
 
+  /**
+   * Get an installation for the given login.
+   *
+   * This method throws if an installation for the given login does not exist.
+   *
+   * @param {string} login
+   *
+   * @return {Promise<Installation>}
+   */
   this.getInstallationByLogin = getInstallationByLogin;
+
+  /**
+   * Get an installation for the given id.
+   *
+   * @param {string|number} id
+   *
+   * @return {Promise<Installation | undefined>}
+   */
   this.getInstallationById = getInstallationById;
 
+  /**
+   * Return installations
+   *
+   * @return {Promise<Installation[]>}
+   */
   this.getInstallations = getInstallations;
 
 }

package/lib/apps/github-checks/GithubChecks.js

@@ -3,6 +3,8 @@ import { repoAndOwner, Cache } from '../../util/index.js';
 /**
  * This component updates the stored issues based on GitHub events.
  *
+ * It also hooks into `BackgroundSync` to fetch checks for a PR.
+ *
  * @constructor
  *
  * @param {import('../webhook-events/WebhookEvents.js').default} webhookEvents

package/lib/apps/github-comments/GithubComments.js

@@ -1,21 +1,21 @@
-import { repoAndOwner } from '../../util/index.js';
 import { filterUser, filterIssue } from '../../filters.js';
-import gql from 'fake-tag';
 
 
 /**
  * This component updates the stored issues based on GitHub events.
  *
+ * It also hooks into `BackgroundSync` to fetch comments for issues/PRs.
+ *
  * @constructor
  *
  * @param {import('../webhook-events/WebhookEvents.js').default} webhookEvents
  * @param {import('../../events.js').default} events
- * @param {import('../github-client/GithubClient.js').default} githubClient
  * @param {import('../../store.js').default} store
  * @param {import('../issue-filter/IssueFilter.js').default} issueFilter
  * @param {import('../../types.js').Logger } logger
+ * @param {import('./GithubCommentsBackend.js').default} githubCommentsBackend
  */
-export default function GithubComments(webhookEvents, events, githubClient, store, issueFilter, logger) {
+export default function GithubComments(webhookEvents, events, store, issueFilter, logger, githubCommentsBackend) {
 
   const log = logger.child({
     name: 'wuffle:github-comments'
@@ -32,81 +32,10 @@ export default function GithubComments(webhookEvents, events, githubClient, stor
     } = event;
 
     const {
-      id,
-      number
+      id
     } = issue;
 
-    const {
-      repo,
-      owner
-    } = repoAndOwner(issue);
-
-    const github = await githubClient.getOrgScoped(owner);
-
-    const result = await github.graphql(gql`
-
-      fragment CommentInfo on IssueComment {
-        id: databaseId
-        node_id: id
-        body: bodyText
-        created_at: publishedAt
-        authorAssociation,
-        html_url: url,
-        user: author {
-          login
-          avatar_url: avatarUrl,
-          html_url: url
-        }
-      }
-
-      query FetchComments(
-        $repo: String!,
-        $owner: String!,
-        $issue_number: Int!,
-        $after: String
-      ) {
-        repository(name: $repo, owner: $owner) {
-          issueOrPullRequest(number: $issue_number) {
-            ...on Issue {
-              comments(first: 100, after: $after) {
-                edges {
-                  node {
-                    ...CommentInfo
-                  }
-                }
-                pageInfo {
-                  endCursor
-                  hasNextPage
-                }
-                totalCount
-              }
-            }
-            ...on PullRequest {
-              comments(first: 100, after: $after) {
-                edges {
-                  node {
-                    ...CommentInfo
-                  }
-                }
-                pageInfo {
-                  endCursor
-                  hasNextPage
-                }
-                totalCount
-              }
-            }
-          }
-        }
-      }`,
-    {
-      owner,
-      repo,
-      issue_number: number
-    });
-
-    const comments = (
-      result.repository.issueOrPullRequest.comments.edges.map(e => e.node)
-    );
+    const comments = await githubCommentsBackend.getIssueComments(issue);
 
     await store.queueUpdate({
       id,
@@ -115,7 +44,9 @@ export default function GithubComments(webhookEvents, events, githubClient, stor
   });
 
   webhookEvents.on([
-    'issue_comment'
+    'issue_comment.created',
+    'issue_comment.edited',
+    'issue_comment.deleted'
   ], ifEnabled(async ({ payload }) => {
     const {
       action,

package/lib/apps/github-comments/GithubCommentsBackend.js

@@ -0,0 +1,132 @@
+import { repoAndOwner } from '../../util/index.js';
+
+import gql from 'fake-tag';
+
+/**
+ * @typedef { {
+ *   id: number,
+ *   node_id: string,
+ *   body: string,
+ *   created_at: string,
+ *   authorAssociation: string,
+ *   html_url: string,
+ *   user: {
+ *     id: number,
+ *     node_id: string,
+ *     login: string,
+ *     avatar_url: string,
+ *     html_url: string,
+ *     type: string
+ *   }
+ * } } GithubComment
+ *
+ * @typedef { import('../../util/meta.js').Issue } Issue
+ */
+
+
+/**
+ * This component fetches GitHub comments data required for background synchronization.
+ *
+ * @constructor
+ *
+ * @param {import('../github-client/GithubClient.js').default} githubClient
+ */
+export default function GithubCommentsBackend(githubClient) {
+
+  /**
+   * Return comments for given issue.
+   *
+   * @param {Issue} issue
+   *
+   * @return {Promise<GithubComment[]>}
+   */
+  this.getIssueComments = async function(issue) {
+
+    const {
+      number
+    } = issue;
+
+    const {
+      repo,
+      owner
+    } = repoAndOwner(issue);
+
+    const github = await githubClient.getOrgScoped(owner);
+
+    const result = await github.graphql(gql`
+
+      fragment CommentInfo on IssueComment {
+        id: databaseId
+        node_id: id
+        body: bodyText
+        created_at: publishedAt
+        authorAssociation,
+        html_url: url,
+        user: author {
+          login
+          avatar_url: avatarUrl,
+          html_url: url,
+          type: __typename
+          ... on User {
+            id: databaseId
+            node_id: id
+          }
+          ... on Bot {
+            id: databaseId
+            node_id: id
+          }
+        }
+      }
+
+      query FetchComments(
+        $repo: String!,
+        $owner: String!,
+        $issue_number: Int!,
+        $after: String
+      ) {
+        repository(name: $repo, owner: $owner) {
+          issueOrPullRequest(number: $issue_number) {
+            ...on Issue {
+              comments(first: 100, after: $after) {
+                edges {
+                  node {
+                    ...CommentInfo
+                  }
+                }
+                pageInfo {
+                  endCursor
+                  hasNextPage
+                }
+                totalCount
+              }
+            }
+            ...on PullRequest {
+              comments(first: 100, after: $after) {
+                edges {
+                  node {
+                    ...CommentInfo
+                  }
+                }
+                pageInfo {
+                  endCursor
+                  hasNextPage
+                }
+                totalCount
+              }
+            }
+          }
+        }
+      }`,
+    {
+      owner,
+      repo,
+      issue_number: number
+    });
+
+    const comments = /** @type { GithubComment[] } */ (
+      result.repository.issueOrPullRequest.comments.edges.map(e => e.node)
+    );
+
+    return comments;
+  };
+}

package/lib/apps/github-comments/index.js

@@ -1,6 +1,8 @@
 import GithubComments from './GithubComments.js';
+import GithubCommentsBackend from './GithubCommentsBackend.js';
 
 export default {
   __init__: [ 'githubComments' ],
-  githubComments: [ 'type', GithubComments ]
+  githubComments: [ 'type', GithubComments ],
+  githubCommentsBackend: [ 'type', GithubCommentsBackend ]
 };

package/lib/apps/github-issues/GithubIssues.js

@@ -4,8 +4,17 @@ const {
   CLOSES
 } = linkTypes;
 
+/**
+ * @typedef { import('probot').Context } ProbotContext
+ *
+ * @typedef { import('../../columns.js').ColumnDefinition } ColumnDefinition
+ */
 
 /**
+ * Moves GitHub issues between board columns by applying the
+ * corresponding state (open/closed), label, and assignee changes
+ * via the GitHub API.
+ *
  * @constructor
  *
  * @param {any} config
@@ -18,6 +27,16 @@ export default function GithubIssues(config, logger, columns) {
     name: 'wuffle:github-issues'
   });
 
+  /**
+   * Return the assignee update required to add `newAssignee` to the
+   * issue, or an empty object if the assignee is already set or not
+   * provided.
+   *
+   * @param {Object} issue
+   * @param {string|null} newAssignee
+   *
+   * @return {{ assignees?: string[] }}
+   */
   function getAssigneeUpdate(issue, newAssignee) {
 
     if (!newAssignee) {
@@ -39,6 +58,15 @@ export default function GithubIssues(config, logger, columns) {
 
   }
 
+  /**
+   * Return the state update (`open` / `closed`) required to reflect
+   * the new column, or an empty object if no change is needed.
+   *
+   * @param {Object} issue
+   * @param {ColumnDefinition} newColumn
+   *
+   * @return {{ state?: 'open'|'closed' }}
+   */
   function getStateUpdate(issue, newColumn) {
 
     let update = {};
@@ -55,16 +83,29 @@ export default function GithubIssues(config, logger, columns) {
     return update;
   }
 
+  /**
+   * Return the label changes required to reflect the new column:
+   * the column label to add and any other column labels to remove.
+   *
+   * @param {Object} issue
+   * @param {ColumnDefinition} newColumn
+   *
+   * @return {{ addLabels: string[], removeLabels: string[] }}
+   */
   function getLabelUpdate(issue, newColumn) {
 
-    const issueLabels = issue.labels.map(l => l.name);
+    const issueLabels = /** @type { string[] } */ (
+      issue.labels.map(l => l.name)
+    );
 
     const newLabel = newColumn.label;
 
     const addLabels = (!newLabel || issueLabels.includes(newLabel)) ? [] : [ newLabel ];
 
-    const removeLabels = columns.getAll().map(c => c.label).filter(
-      label => label && label !== newLabel && issueLabels.includes(label)
+    const removeLabels = /** @type { string[] } */ (
+      columns.getAll().map(c => c.label).filter(
+        label => label && label !== newLabel && issueLabels.includes(label)
+      )
     );
 
     return {
@@ -73,6 +114,10 @@ export default function GithubIssues(config, logger, columns) {
     };
   }
 
+  /**
+   * @param {ProbotContext} context
+   * @param {number} issue_number
+   */
   function findIssue(context, issue_number) {
 
     const params = context.repo({ issue_number });
@@ -88,12 +133,43 @@ export default function GithubIssues(config, logger, columns) {
       });
   }
 
-  function findAndMoveIssue(context, number, newColumn, newAssignee, test = (issue) => true) {
-    return findIssue(context, number)
-      .then((issue) => issue && test(issue) && moveIssue(context, issue, newColumn, newAssignee));
+  /**
+   * Fetch an issue by number and move it to a new column if the
+   * optional predicate passes. Resolves to `false` if the issue is
+   * not found or the predicate rejects it.
+   *
+   * @param {ProbotContext} context
+   * @param {number} number
+   * @param {ColumnDefinition} newColumn
+   * @param {string|null} newAssignee
+   * @param {(issue: Object) => boolean} [test]
+   *
+   * @return {Promise<void|false>}
+   */
+  async function findAndMoveIssue(context, number, newColumn, newAssignee, test = (issue) => true) {
+    const issue = await findIssue(context, number);
+
+    if (!issue || !test(issue)) {
+      return false;
+    }
+
+    return moveIssue(context, issue, newColumn, newAssignee);
   }
 
-  async function moveReferencedIssues(context, issue, newColumn, newAssignee) {
+  /**
+   * Move all issues referenced via `closes` links in the given issue
+   * or pull request body to a new column.
+   *
+   * Only issues within the same repository are moved.
+   *
+   * @param {ProbotContext} context
+   * @param {Object} issue
+   * @param {ColumnDefinition} newColumn
+   * @param {string|null} [newAssignee=null]
+   *
+   * @return {Promise<(void|false)[]>}
+   */
+  async function moveReferencedIssues(context, issue, newColumn, newAssignee = null) {
 
     // TODO(nikku): do that lazily, i.e. react to PR label changes?
     // would slower the movement but support manual moving-issue with PR
@@ -128,7 +204,18 @@ export default function GithubIssues(config, logger, columns) {
     }));
   }
 
-  function moveIssue(context, issue, newColumn, newAssignee) {
+  /**
+   * Move an issue to a new column, applying state, label, and
+   * assignee updates via the GitHub API.
+   *
+   * @param {ProbotContext} context
+   * @param {Object} issue
+   * @param {ColumnDefinition} newColumn
+   * @param {string|null} [newAssignee=null]
+   *
+   * @return {Promise<void>}
+   */
+  function moveIssue(context, issue, newColumn, newAssignee = null) {
 
     const {
       number: issue_number
@@ -199,22 +286,87 @@ export default function GithubIssues(config, logger, columns) {
       );
     }
 
-    return Promise.all(invocations);
+    return Promise.all(invocations).then(() => {});
   }
 
 
   // api /////////////////////////////
 
+  /**
+   * Move an issue to a new column, applying state, label, and
+   * assignee updates via the GitHub API.
+   *
+   * @param {ProbotContext} context
+   * @param {Object} issue
+   * @param {ColumnDefinition} newColumn
+   * @param {string} [newAssignee]
+   *
+   * @return {Promise<void>}
+   */
   this.moveIssue = moveIssue;
 
+  /**
+   * Move all issues referenced via `closes` links in the given issue
+   * or pull request body to a new column.
+   *
+   * Only issues within the same repository are moved.
+   *
+   * @param {ProbotContext} context
+   * @param {Object} issue
+   * @param {ColumnDefinition} newColumn
+   * @param {string|null} [newAssignee=null]
+   *
+   * @return {Promise<(void|false)[]>}
+   */
   this.moveReferencedIssues = moveReferencedIssues;
 
+  /**
+   * Return the state update (`open` / `closed`) required to reflect
+   * the new column, or an empty object if no change is needed.
+   *
+   * @param {Object} issue
+   * @param {ColumnDefinition} newColumn
+   *
+   * @return {{ state?: 'open'|'closed' }}
+   */
   this.getStateUpdate = getStateUpdate;
 
+  /**
+   * Return the assignee update required to add `newAssignee` to the
+   * issue, or an empty object if the assignee is already set or not
+   * provided.
+   *
+   * @param {Object} issue
+   * @param {string} [newAssignee]
+   *
+   * @return {{ assignees?: string[] }}
+   */
   this.getAssigneeUpdate = getAssigneeUpdate;
 
+  /**
+   * Return the label changes required to reflect the new column:
+   * the column label to add and any other column labels to remove.
+   *
+   * @param {Object} issue
+   * @param {ColumnDefinition} newColumn
+   *
+   * @return {{ addLabels: string[], removeLabels: string[] }}
+   */
   this.getLabelUpdate = getLabelUpdate;
 
+  /**
+   * Fetch an issue by number and move it to a new column if the
+   * optional predicate passes. Resolves to `false` if the issue is
+   * not found or the predicate rejects it.
+   *
+   * @param {ProbotContext} context
+   * @param {number} number
+   * @param {ColumnDefinition} newColumn
+   * @param {string|null} newAssignee
+   * @param {(issue: Object) => boolean} [test]
+   *
+   * @return {Promise<void|false>}
+   */
   this.findAndMoveIssue = findAndMoveIssue;
 
 }

package/lib/apps/github-reviews/GithubReviews.js

@@ -5,6 +5,8 @@ import { filterUser, filterPull } from '../../filters.js';
 /**
  * This component updates the stored issues based on GitHub events.
  *
+ * It also hooks into `BackgroundSync` to fetch reviews for a PR.
+ *
  * @constructor
  *
  * @param {import('../webhook-events/WebhookEvents.js').default} webhookEvents

package/lib/apps/github-statuses/GithubStatuses.js

@@ -5,6 +5,8 @@ import { filterPull } from '../../filters.js';
 /**
  * This component updates synchronizes GitHub statuses with pull requests.
  *
+ * It also hooks into `BackgroundSync` to fetch statuses for a PR.
+ *
  * @constructor
  *
  * @param {import('../webhook-events/WebhookEvents.js').default} webhookEvents