Add function to load known MetaMask repos

If a user passes a bare identifier on the command line, like this:

```
yarn dlx @metamask/module-lint utils
```

then we assume that they want to lint the `MetaMask/utils` repository.
However we have to double-check that the repo they want to lint actually
exists. They shouldn't be able to do this, for instance:

```
yarn dlx @metamask/module-lint asdlsdfl
```

The way we do this is by pulling the list of repositories that sit under
the MetaMask GitHub organization. We exclude forks as well as archived
repos. This list is cached for an hour so that future runs of the tool
do not cause the rate limit for the GitHub API to be exceeded.

package.json

@@ -48,7 +48,8 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@metamask/utils": "^8.2.0"
+    "@metamask/utils": "^8.2.0",
+    "execa": "^5.1.1"
   },
   "devDependencies": {
     "@lavamoat/allow-scripts": "^2.3.1",

src/ensure-metamask-repositories-loaded.test.ts

@@ -0,0 +1,43 @@
+import execa from 'execa';
+
+import { ensureMetaMaskRepositoriesLoaded } from './ensure-metamask-repositories-loaded';
+import type { PrimaryExecaFunction } from '../tests/helpers';
+import { mockExeca } from '../tests/helpers';
+
+jest.mock('execa');
+
+const execaMock = jest.mocked<PrimaryExecaFunction>(execa);
+
+describe('ensureMetaMaskRepositoriesLoaded', () => {
+  it('requests the repositories under the MetaMask GitHub organization, limiting the data to just a few fields', async () => {
+    mockExeca(execaMock, [
+      {
+        args: [
+          'gh',
+          ['api', 'orgs/MetaMask/repos', '--cache', '1h', '--paginate'],
+        ],
+        result: {
+          stdout: JSON.stringify([
+            { name: 'utils', fork: false, archived: false, extra: 'info' },
+            { name: 'logo', fork: false, archived: false },
+            {
+              name: 'ethjs-util',
+              fork: true,
+              archived: false,
+              something: 'else',
+            },
+            { name: 'test-snaps', fork: true, archived: true },
+          ]),
+        },
+      },
+    ]);
+
+    const gitHubRepositories = await ensureMetaMaskRepositoriesLoaded();
+    expect(gitHubRepositories).toStrictEqual([
+      { name: 'utils', fork: false, archived: false },
+      { name: 'logo', fork: false, archived: false },
+      { name: 'ethjs-util', fork: true, archived: false },
+      { name: 'test-snaps', fork: true, archived: true },
+    ]);
+  });
+});

src/ensure-metamask-repositories-loaded.ts

@@ -0,0 +1,42 @@
+import execa from 'execa';
+
+/**
+ * The information about a GitHub repository that we care about. Primarily,
+ * we want to know whether repos are forks or have been archived, because we
+ * don't want to lint them.
+ */
+type GitHubRepository = {
+  name: string;
+  fork: boolean;
+  archived: boolean;
+};
+
+/**
+ * Requests data for the repositories listed under MetaMask's GitHub
+ * organization via the GitHub API, or returns the results from a previous call.
+ * The data is cached for an hour to prevent unnecessary calls to the GitHub
+ * API.
+ *
+ * @returns The list of repositories (whether previously or newly cached).
+ */
+export async function ensureMetaMaskRepositoriesLoaded(): Promise<
+  GitHubRepository[]
+> {
+  const { stdout } = await execa('gh', [
+    'api',
+    'orgs/MetaMask/repos',
+    '--cache',
+    '1h',
+    '--paginate',
+  ]);
+  const fullGitHubRepositories = JSON.parse(stdout);
+  return fullGitHubRepositories.map(
+    (fullGitHubRepository: Record<string, unknown>) => {
+      return {
+        name: fullGitHubRepository.name,
+        fork: fullGitHubRepository.fork,
+        archived: fullGitHubRepository.archived,
+      };
+    },
+  );
+}

tests/helpers.ts

@@ -1,4 +1,11 @@
 import { createSandbox } from '@metamask/utils/node';
+import type {
+  ExecaChildProcess,
+  Options as ExecaOptions,
+  ExecaReturnValue,
+} from 'execa';
+import { mock } from 'jest-mock-extended';
+import { inspect, isDeepStrictEqual } from 'util';
 
 import { createModuleLogger, projectLogger } from '../src/logging-utils';
 
@@ -8,6 +15,15 @@ export const log = createModuleLogger(projectLogger, 'tests');
 
 export { withinSandbox };
 
+/**
+ * `execa` can be called multiple ways. This is the way that we use it.
+ */
+export type PrimaryExecaFunction = (
+  file: string,
+  args?: readonly string[] | undefined,
+  options?: ExecaOptions | undefined,
+) => ExecaChildProcess;
+
 /**
  * Uses Jest's fake timers to fake Date only.
  */
@@ -31,3 +47,62 @@ export function fakeDateOnly() {
     ],
   });
 }
+
+/**
+ * Builds an object that represents a successful result returned by `execa`.
+ * This kind of object is usually a bit cumbersome to build because it's a
+ * promise with extra properties glommed on to it (so it has a strange type). We
+ * use `jest-mock-extended` to help with this.
+ *
+ * @param overrides - Properties you want to add to the result object.
+ * @returns The complete `execa` result object.
+ */
+export function buildExecaResult(
+  overrides: Partial<ExecaReturnValue> = { stdout: '' },
+): ExecaChildProcess {
+  return Object.assign(mock<ExecaChildProcess>(), overrides);
+}
+
+/**
+ * Mocks different invocations of `execa` to do different things.
+ *
+ * @param execaMock - The mocked version of `execa` (as obtained via
+ * `jest.mocked`).
+ * @param invocationMocks - Specifies outcomes of different invocations of
+ * `execa`. Each object in this array has `args` (the expected arguments to
+ * `execa`) and either `result` (properties of an ExecaResult object, such as
+ * `all: true`) or `error` (an Error).
+ */
+export function mockExeca(
+  execaMock: jest.MockedFn<PrimaryExecaFunction>,
+  invocationMocks: ({
+    args: Parameters<PrimaryExecaFunction>;
+  } & (
+    | {
+        result?: Partial<ExecaReturnValue>;
+      }
+    | {
+        error?: Error;
+      }
+  ))[],
+) {
+  execaMock.mockImplementation((...args): ExecaChildProcess => {
+    for (const invocationMock of invocationMocks) {
+      if (isDeepStrictEqual(args, invocationMock.args)) {
+        if ('error' in invocationMock && invocationMock.error) {
+          throw invocationMock.error;
+        }
+        if ('result' in invocationMock && invocationMock.result) {
+          return buildExecaResult(invocationMock.result);
+        }
+        throw new Error(
+          `No result or error was provided for execa() invocation ${inspect(
+            args,
+          )}`,
+        );
+      }
+    }
+
+    throw new Error(`Unmocked invocation of execa() with ${inspect(args)}`);
+  });
+}

yarn.lock

@@ -1012,6 +1012,7 @@ __metadata:
     eslint-plugin-n: ^15.7.0
     eslint-plugin-prettier: ^4.2.1
     eslint-plugin-promise: ^6.1.1
+    execa: ^5.1.1
     jest: ^28.1.3
     jest-it-up: ^2.0.2
     jest-mock-extended: ^3.0.5