githubData.js

import gql from 'graphql-tag';

// TODO: split query into search + virtualized table to improve caching
// TODO: implement query pagination to allow getting more than 100 items
// TODO: more precise filtering of the timeline items (only checking for comments right now)

/**
 * Fragment indicating the values and structure of all issue objects fetched
 * using the github queries below.
 */
const ISSUE_FRAGMENT = gql`
  fragment GetIssueInfo on Issue {
    id
    title
    authorAssociation
    author {
      login
      url
    }
    repository {
      name
      url
    }
    labels(first: 100, orderBy: { field: NAME, direction: ASC }) {
      nodes {
        name
        color
      }
    }
    number
    url
    createdAt
  }
`;

/**
 * Fragment indicating the values and structure of all PR objects fetched using
 * the github queries below.
 */
const PR_FRAGMENT = gql`
  fragment GetPRInfo on PullRequest {
    id
    title
    authorAssociation
    author {
      login
      url
    }
    repository {
      name
      url
    }
    labels(first: 100, orderBy: { field: NAME, direction: ASC }) {
      nodes {
        name
        color
      }
    }
    number
    url
    createdAt
  }
`;

/**
 * Query to perform a GitHub search and fetch all "Issues" (Issues and PRs) that
 * match a given query. We can use this graphQL query and GitHub's powerful
 * search syntax to only fetch items which were created by users who are not
 * employees. Use makeNewSearch to construct a search query paramter that finds
 * PRs and Issues that are open and not created/commented by an employee.
 *
 * Note that due to the nature of the typically large search query, this GraphQL
 * query may take a few seconds to execute.
 *
 * @param {string} query The GitHub search query to search with.
 */
const SEARCH_NEW_ITEMS_QUERY = gql`
  query SearchResults($query: String!) {
    search(query: $query, type: ISSUE, first: 100) {
      nodes {
        __typename
        ...GetIssueInfo
        ...GetPRInfo
      }
      issueCount
    }
    rateLimit {
      limit
      cost
      remaining
      resetAt
    }
  }
  ${PR_FRAGMENT}
  ${ISSUE_FRAGMENT}
`;

/**
 * Query to perform a GitHub search and fetch all "Issues" (Issues and PRs) that
 * match several given queries. We can use this graphQL query and GitHub's
 * powerful search syntax to only fetch items which are considered stale.
 *
 * In this case, a "stale" item is an item that received a response from an
 * employee but then received no other response from an employee for at least a
 * certain duration. GitHub's search syntax doesn't quite allow us to get all
 * this information in a single search, so the query is split into two separate
 * searches:
 *     * definitelyStale - Issues or PRs that were not created by an employee, have
 * at least one comment from an employee, and were last updated before the
 * stale threshold. "Last updated" in GitHub terms can mean a variety of things
 * (including comments from other users), so this query doesn't catch issues or
 * PRs that are active but haven't received an employee response in awhile. The
 * query for this search is generated by makeDefStaleSearch.
 *     * maybeStale - Issues or PRs that were not created by a an employee, and were
 * created before the stale threshold but updated after it. As GitHub search
 * cannot determine if an employee has commented within a certain time, this
 * search fetches the TimeLine items of each issue/pr candidate, expecting the
 * application to use this data to determine which Issues/PRs have received
 * employee follow up. The query for this search is generated by
 * makeDefStaleSearch, and the results from this search can be filtered using
 * filterMaybeStaleItems.
 *
 * Note that due to the nature of the typically large search query, this GraphQL
 * query may take a few seconds to execute.
 *
 * @param {string} queryDefStale The GitHub search query to search for
 *     definitelyStale items. Use makeDefStaleSearch to make this query.
 * @param {string} queryMaybeStale The GitHub search query to search for
 *     maybeStale items. Use makeMaybeStaleSearch to make this query.
 * @param {string} timeSince An ISO Date string indicating the threshold to use
 *     for considering items to be stale (ex. two weeks before today).
 */
const SEARCH_STALE_ITEMS_QUERY = gql`
  query SearchResults(
    $queryDefStale: String!
    $queryMaybeStale: String!
    $timeSince: DateTime!
  ) {
    definitelyStale: search(query: $queryDefStale, type: ISSUE, first: 100) {
      issueCount
      nodes {
        __typename
        ...GetIssueInfo
        ...GetPRInfo
      }
    }
    maybeStale: search(query: $queryMaybeStale, type: ISSUE, first: 100) {
      issueCount
      nodes {
        __typename
        ...GetIssueInfo
        ...GetPRInfo
        ... on Issue {
          timelineItems(since: $timeSince, last: 100) {
            nodes {
              ... on Comment {
                id
                author {
                  login
                }
                updatedAt
              }
            }
          }
        }
        ... on PullRequest {
          timelineItems(since: $timeSince, last: 100) {
            nodes {
              ... on Comment {
                id
                author {
                  login
                }
                updatedAt
              }
            }
          }
        }
      }
    }
    rateLimit {
      limit
      cost
      remaining
      resetAt
    }
  }
  ${PR_FRAGMENT}
  ${ISSUE_FRAGMENT}
`;

/**
 * Utility function to create a search query that looks for items that haven't
 * received an employee response yet. See SEARCH_NEW_ITEMS_QUERY for more
 * information on how to use this function.
 *
 * The returned query finds Issues/PRs matching the following criteria:
 *     * On a repository in `repos`
 *     * Was not authored or commented on by anyone in `users`
 *     * Does not have a label in `ignoreLabels`
 *     * Is currently open
 *
 * @param {string[]} users GitHub logins (usernames, not emails) to treat as
 *     employees.
 * @param {string[]} repos Repositories to pull Issues and PRs from.
 * @param {string[]} ignoreLabels Labels (ex. "bug") to ignore when searching.
 *     Issues and PRs with any of these labels will be excluded from results.
 * @returns {string} A GitHub search query to use as an input to
 *     SEARCH_NEW_ITEMS_QUERY
 */

function makeNewSearch(users, repos, ignoreLabels) {
  return `${repos.map((r) => `repo:${r}`).join(' ')} ${users
    .map((u) => `-author:${u} -commenter:${u}`)
    .join(' ')} ${ignoreLabels.map((l) => `-label:${l}`).join(' ')} is:open`;
}

/**
 * Utility function to create a search query that looks for items that are
 * definitely stale. See SEARCH_STALE_ITEMS_QUERY for more information on how
 * to use this function.
 *
 * The returned query finds Issues/PRs matching the following criteria:
 *     * On a repository in `repos`
 *     * Was not authored anyone in `users`
 *     * Has received a comment by someone in `users`
 *     * Does not have a label in `ignoreLabels`
 *     * Is currently open
 *     * Was last updated before or on `date`.
 *
 * @param {string[]} users GitHub logins (usernames, not emails) to treat as
 *     employees.
 * @param {string[]} repos Repositories to pull Issues and PRs from.
 * @param {string[]} ignoreLabels Labels (ex. "bug") to ignore when searching.
 *     Issues and PRs with any of these labels will be excluded from results.
 * @param {Date} date A Date to treat as the threshold to considering an item to
 *     be stale (ex. two weeks before today).
 * @returns {string} A GitHub search query to use as an input to
 *     SEARCH_STALE_ITEMS_QUERY
 */
function makeDefStaleSearch(users, repos, ignoreLabels, date) {
  return `${repos.map((r) => `repo:${r}`).join(' ')} ${users
    .map((u) => `-author:${u} commenter:${u}`)
    .join(' ')} ${ignoreLabels
    .map((l) => `-label:${l}`)
    .join(' ')} is:open updated:<=${date.toISOString()}`;
}

/**
 * Utility function to create a search query that looks for items that might be
 * stale. See SEARCH_STALE_ITEMS_QUERY for more information on how to use this
 * function.
 *
 * The returned query finds Issues/PRs matching the following criteria:
 *     * On a repository in `repos`
 *     * Was not authored anyone in `users`
 *     * Has received a comment by someone in `users`
 *     * Does not have a label in `ignoreLabels`
 *     * Is currently open
 *     * Was last updated after `date`
 *     * Was created before or on `date`
 *
 * @param {string[]} users GitHub logins (usernames, not emails) to treat as
 *     employees.
 * @param {string[]} repos Repositories to pull Issues and PRs from.
 * @param {string[]} ignoreLabels Labels (ex. "bug") to ignore when searching.
 *     Issues and PRs with any of these labels will be excluded from results.
 * @param {Date} date A Date to treat as the threshold to considering an item to
 *     be stale (ex. two weeks before today).
 * @returns {string} A GitHub search query to use as an input to
 *     SEARCH_STALE_ITEMS_QUERY
 */
function makeMaybeStaleSearch(users, repos, ignoreLabels, date) {
  return `${repos.map((r) => `repo:${r}`).join(' ')} ${users
    .map((u) => `-author:${u} commenter:${u}`)
    .join(' ')} ${ignoreLabels
    .map((l) => `-label:${l}`)
    .join(
      ' '
    )} is:open updated:>${date.toISOString()} created:<=${date.toISOString()}`;
}

/**
 * Filter SEARCH_STALE_ITEMS_QUERY.maybeStale.nodes based on which users are
 * considered employees. This function checks the `timelineItems` to see if the
 * Issue/PR has received a comment from an employee after the date in which it
 * is considered stale, and returns only items that are stale by this test.
 *
 * @param {{ timelineItems: { nodes: any[] } }[]} items An array of Issues/PRs
 *     with a timeline
 * @param {string[]} employeeLogins A list of GitHub logins to treat as
 *     employees
 * @param {Date} staleDate A date to treat as the threshold of being stale (ex.
 *     two weeks before today).
 * @returns {{ timelineItems: { nodes: any[] } }[]} The items paramter array
 *     with the stale Issues/PRs removed.
 */
function filterMaybeStaleItems(items, employeeLogins, staleDate) {
  const employeeSet = new Set(employeeLogins);
  return items.filter((n) =>
    n.timelineItems.nodes.every((c) =>
      c?.author && employeeSet.has(c.author.login)
        ? new Date(c.updatedAt) <= staleDate
        : true
    )
  );
}

/**
 * Get some useful information about the user we are currently authenticated as.
 * This query is used to both test the authentication mechanism and fetch
 * information about the account that can be used to provide helpful
 * suggestions in the settings.
 *
 * @param {?string} repoCursor An endCursor to paginate over the repositories
 *     with.
 */
const GET_CUR_USER_INFO_QUERY = gql`
  query($repoCursor: String) {
    viewer {
      login
      repositories(
        affiliations: [OWNER, COLLABORATOR, ORGANIZATION_MEMBER]
        first: 100
        after: $repoCursor
      ) {
        nodes {
          nameWithOwner
        }
      }
    }
  }
`;

/**
 * Run a GraphQL query to get information about new and stale items for a given
 * set of repositories. In this case, new items are Issues/PRs that have not
 * received a response from an employee, and stale items are Issues/PRs that
 * have received an employee response but have not received a follow up for
 * longer than a certain period of time. For more information about the exact
 * process used to determine which item is new/stale, check out the
 * SEARCH_NEW_ITEMS_QUERY and SEARCH_STALE_ITEMS_QUERY queries.
 *
 * Note: this function currently is limited to 100 items per new/stale. This
 * will be fixed when query pagination is implemented.
 *
 * @param {any} client Apollo GraphQL client to use to query the GitHub GraphQL
 *     API. Must be preloaded with the proper credentials.
 * @param {string[]} options.scanRepos The repositories to scan, in "org/name"
 *     format.
 * @param {string[]} options.companyUsers Login names of GitHub accounts
 *     associated with employees. This value is used to determine which items
 *     have received a response from someone in the company. Login names should be
 *     usernames not emails (ex. "prototypicalpro")
 * @param {string[]} options.ignoreLabels Issue/PR labels to exclude (ex."bug").
 *     All issues/PRs with these labels will be excluded from the results.
 * @param {number} options.staleTime Duration in milliseconds that a item should
 *     remain inactive for it to be considered stale.
 * @returns {{
 *   newSearchCount: number;
 *   newSearchItems: object[];
 *   staleSearchCount: number;
 *   staleSearchItems: object[];
 * }}
 *     An object containing the results of the queries. The "items" arrays will contain objects of either
 *     ISSUE_FRAGMENT or PR_FRAGMENT structure.
 */
export async function findDashboardItems(client, options) {
  const { scanRepos, companyUsers, staleTime, ignoreLabels } = options;
  const staleDate = new Date(Date.now() - staleTime);
  // fetch all the data
  const [newRes, staleRes] = await Promise.all([
    client.query({
      query: SEARCH_NEW_ITEMS_QUERY,
      variables: {
        query: makeNewSearch(companyUsers, scanRepos, ignoreLabels),
      },
    }),
    client.query({
      query: SEARCH_STALE_ITEMS_QUERY,
      variables: {
        queryDefStale: makeDefStaleSearch(
          companyUsers,
          scanRepos,
          ignoreLabels,
          staleDate
        ),
        queryMaybeStale: makeMaybeStaleSearch(
          companyUsers,
          scanRepos,
          ignoreLabels,
          staleDate
        ),
        timeSince: staleDate.toISOString(),
      },
    }),
  ]);
  // if every comment by an employee is stale, then the issue is stale
  const filteredMaybeItems = filterMaybeStaleItems(
    staleRes.data.maybeStale.nodes,
    companyUsers,
    staleDate
  );
  return {
    newSearchCount: Math.max(
      newRes.data.search.issueCount,
      newRes.data.search.nodes.length
    ),
    newSearchItems: newRes.data.search.nodes,
    staleSearchCount:
      Math.max(
        staleRes.data.definitelyStale.issueCount,
        staleRes.data.definitelyStale.nodes.length
      ) + filteredMaybeItems.length,
    staleSearchItems: staleRes.data.definitelyStale.nodes.concat(
      filteredMaybeItems
    ),
  };
}

/**
 * Get some useful information about the user we are currently authenticated as.
 * This function can both test the authentication mechanism and fetch
 * information about the account that can be used to provide helpful
 * suggestions in the settings.
 *
 * @param {any} client Apollo GraphQL client to use to query the GitHub GraphQL
 *     API.
 * @param {string} token GitHub personal access token to use for authenticating
 *     this request
 * @returns {Promise} A promise containing the result of the
 *     GET_CUR_USER_INFO_QUERY. Will thrown an exception if the supplied token
 *     is invalid.
 */
export async function getUserInfo(client, token) {
  const { data } = await client.query({
    query: GET_CUR_USER_INFO_QUERY,
    fetchPolicy: 'network-only',
    context: {
      headers: {
        authorization: `Bearer ${token}`,
      },
    },
  });
  return data;
}