Improve contributor docs refs count script (#17)

The script to count the number of references to the contributor-docs
throughout comments in MetaMask repositories has never provided accurate
counts. Upon reviewing this script, I noticed that while comments posted
directly to pull requests were included in the count, comments posted as
a part of reviews, which are separate types in the GitHub GraphQL API,
were excluded. This resulted in a smaller count than expected.

In addition, the cutoff for data that the script used — 5000 maximum
comments per repo — hasn't been particularly useful. We need to define
_some_ kind of cutoff because it would be impractical to pull all
comments from all time, but since we use this script to gauge progress
toward OKRs, it helps us better to define a fixed target, in this case
4/1/2023, the start of the first quarter where the Shared Libraries team
began working on the contributor docs. In addition, the output of this
script now breaks down the counts per quarter instead of giving a lump
sum. Here is an example:

```
About to retrieve data. Please be patient, this could take a while:

✔ Retrieving data for core since 2023-04-01T00:00:00.000Z
✔ Retrieving data for design-tokens since 2023-04-01T00:00:00.000Z
✔ Retrieving data for metamask-extension since 2023-04-01T00:00:00.000Z
✔ Retrieving data for metamask-mobile since 2023-04-01T00:00:00.000Z
✔ Retrieving data for snaps since 2023-04-01T00:00:00.000Z

----------------------

Number of references to contributor-docs by repository:

- core
  - Q2-2023: 0
  - Q3-2023: 0
  - Q4-2023: 2
  - Q1-2024: 1
- design-tokens
  - Q2-2023: 0
  - Q3-2023: 0
  - Q4-2023: 0
  - Q1-2024: 0
- metamask-extension
  - Q2-2023: 0
  - Q3-2023: 0
  - Q4-2023: 0
  - Q1-2024: 2
- metamask-mobile
  - Q2-2023: 0
  - Q3-2023: 0
  - Q4-2023: 0
  - Q1-2024: 4
- snaps
  - Q2-2023: 0
  - Q3-2023: 0
  - Q4-2023: 0
  - Q1-2024: 0

Total number of references: 9
```

Author: mcmire

src/github/pull-request-comments-query.ts

@@ -19,15 +19,26 @@ export type GitHubComment = {
     };
   };
   body: string;
+  createdAt: string;
   updatedAt: string;
 };
 
-type GitHubPullRequest = {
+type GitHubReview = {
+  id: string;
+  comments: {
+    nodes: GitHubComment[];
+  };
+};
+
+export type GitHubPullRequest = {
   number: number;
   comments: {
     nodes: GitHubComment[];
-    pageInfo: GitHubPageInfo;
   };
+  reviews: {
+    nodes: GitHubReview[];
+  };
+  createdAt: string;
   updatedAt: string;
 };
 
@@ -63,6 +74,8 @@ const QUERY = `
       pullRequests(first: 100, orderBy: { field: UPDATED_AT, direction: DESC }, after: $after) {
         nodes {
           number
+          createdAt
+          updatedAt
           comments(first: 100, orderBy: { field: UPDATED_AT, direction: DESC }) {
             nodes {
               author {
@@ -75,10 +88,31 @@ const QUERY = `
                 }
               }
               body
+              createdAt
               updatedAt
             }
           }
-          updatedAt
+          reviews(first: 40) {
+            nodes {
+              id
+              comments(first: 100) {
+                nodes {
+                  author {
+                    __typename
+                    login
+                    ...on User {
+                      metamaskOrganization: organization(login: "MetaMask") {
+                        login
+                      }
+                    }
+                  }
+                  body
+                  createdAt
+                  updatedAt
+                }
+              }
+            }
+          }
         }
         pageInfo {
           endCursor
@@ -96,10 +130,10 @@ const QUERY = `
 `;
 
 /**
- * When requesting a collection of resources, the GitHub API returns a maximum
- * of 100 at a time. This function is used to retrieve a "page" of the most
- * recent comments made on pull requests submitted for the given MetaMask
- * repository.
+ * Executes a GraphQL query to retrieve the most recent comments posted on pull
+ * requests submitted for the given MetaMask repository, ordered from latest to
+ * earliest. A cursor may be provided to retrieve a particular "page" of pull
+ * requests.
  *
  * @param args - The arguments.
  * @param args.repositoryName - The name of the repository.
@@ -114,7 +148,7 @@ export async function makeGitHubPullRequestCommentsQuery({
   after: string | undefined;
 }): Promise<GitHubPullRequestCommentsQueryResponse> {
   log(
-    `Fetching pull requests for ${repositoryName}${
+    `Executing GraphQL query to fetch pull requests for ${repositoryName}${
       after ? ` (after: ${after})` : ''
     }`,
   );

src/scripts/count-references-to-contributor-docs/cli.ts

@@ -1,22 +1,34 @@
 import ora from 'ora';
 
-import { countCommentsWithReferencesToContributorDocs } from './utils';
+import { tallyCommentsWithReferencesToContributorDocsByQuarter } from './utils';
+import type { TalliedQuarter } from './utils';
+import { log } from '../../logging-utils';
 
-const INTERESTING_REPOSITORY_NAMES = [
+/**
+ * The repositories we want to scan.
+ */
+const REPOSITORY_NAMES = [
   'core',
   'design-tokens',
   'metamask-extension',
   'metamask-mobile',
   'snaps',
-];
+] as const;
+
+type RepositoryName = typeof REPOSITORY_NAMES[number];
 
-const MAX_NUMBER_OF_COMMENTS_PER_REPO = 5000;
+/**
+ * It is not necessary for us to query all of the pull requests or pull requests
+ * comments for all time; we only need those since at least Q2 2023, which is
+ * when the Shared Libraries decided to start working on the contributor docs.
+ */
+const START_DATE = new Date(Date.UTC(2023, 3, 1));
 
 main().catch(console.error);
 
 /**
  * This script counts the number of references to the `contributor-docs` repo
- * across the primary repositories used by the MetaMask Core lane.
+ * across a selection of MetaMask repositories.
  */
 async function main() {
   const spinner = ora();
@@ -25,23 +37,46 @@ async function main() {
     'About to retrieve data. Please be patient, this could take a while:\n',
   );
 
-  let total = 0;
-  // Can't do this in parallel or else we get rate limits
-  for (const repositoryName of INTERESTING_REPOSITORY_NAMES) {
-    spinner.start(`Retrieving data for ${repositoryName}`);
+  const quartersByRepositoryName: Partial<
+    Record<RepositoryName, TalliedQuarter[]>
+  > = {};
+  // NOTE: We can't do this in parallel or else we'll get rate limits.
+  for (const repositoryName of REPOSITORY_NAMES) {
+    spinner.start(
+      `Retrieving data for ${repositoryName} since ${START_DATE.toISOString()}`,
+    );
+    log('');
     try {
-      total += await countCommentsWithReferencesToContributorDocs({
-        repositoryName,
-        sampleSize: MAX_NUMBER_OF_COMMENTS_PER_REPO,
-      });
+      const quarters =
+        await tallyCommentsWithReferencesToContributorDocsByQuarter({
+          repositoryName,
+          since: START_DATE,
+        });
+      quartersByRepositoryName[repositoryName] = quarters;
       spinner.succeed();
     } catch (error) {
       spinner.fail();
       throw error;
     }
   }
 
-  console.log(
-    `\nNumber of comments with references to contributor documentation: ${total}`,
+  const grandTotal = Object.values(quartersByRepositoryName).reduce(
+    (sum1, quarters) => {
+      return sum1 + quarters.reduce((sum2, quarter) => sum2 + quarter.total, 0);
+    },
+    0,
   );
+
+  console.log('\n----------------------\n');
+  console.log('Number of references to contributor-docs by repository:\n');
+  for (const [repositoryName, quarters] of Object.entries(
+    quartersByRepositoryName,
+  )) {
+    console.log(`- ${repositoryName}`);
+
+    for (const quarter of quarters) {
+      console.log(`  - ${quarter.name}: ${quarter.total}`);
+    }
+  }
+  console.log(`\nTotal number of references: ${grandTotal}`);
 }