Fix lint errors from eslint-plugin-jsdoc

bin-src/init.ts

@@ -104,6 +104,11 @@ const intializeChromatic = async ({
   }
 };
 
+/**
+ * The main entrypoint for `chromatic init`.
+ *
+ * @param argv A list of arguments passed.
+ */
 export async function main(argv: string[]) {
   const { flags } = meow(
     `

bin-src/main.ts

@@ -1,5 +1,10 @@
 import { run } from '../node-src';
 
+/**
+ * The main entrypoint for the CLI.
+ *
+ * @param argv A list of arguments passed.
+ */
 export async function main(argv: string[]) {
   const { code } = await run({ argv });
 

bin-src/trace.ts

@@ -32,6 +32,11 @@ import { Context } from '../node-src/types';
 
 const { STORYBOOK_BASE_DIR, STORYBOOK_CONFIG_DIR, WEBPACK_STATS_FILE } = process.env;
 
+/**
+ * The main entrypoint for `chromatic trace`.
+ *
+ * @param argv A list of arguments passed.
+ */
 export async function main(argv: string[]) {
   const { flags, input } = meow(
     `

bin-src/trim-stats-file.ts

@@ -15,10 +15,14 @@ const isUserCode = ({ name, moduleName = name }: { name?: string; moduleName?: s
  * `.trimmed.json` as file extension.
  *
  * Usage examples:
- *   yarn chromatic trim-stats-file
- *   yarn chromatic trim-stats-file ./path/to/preview-stats.json
+ * yarn chromatic trim-stats-file
+ * yarn chromatic trim-stats-file ./path/to/preview-stats.json
+ *
+ * @param argv A list of arguments passed.
+ * @param argv."0" The stats file location passed in as a positional argument.
+ *
+ * @returns The file path to the trimmed stats file.
  */
-
 export async function main([statsFile = './storybook-static/preview-stats.json']) {
   try {
     const stats = await readStatsFile(statsFile);

node-src/git/findAncestorBuildWithCommit.ts

@@ -43,14 +43,15 @@ export interface AncestorBuildsQueryResult {
  *
  * The purpose here is to allow us to substitute a build with a known clean commit for TurboSnap.
  *
- * @param {Context} context
- * @param {int} number The build number to start searching from
- * @param {object} options Page size and limit options
- * @param {int} options.page How many builds to fetch each time
- * @param {int} options.steps How far back to look
+ * @param ctx The context set when executing the CLI.
+ * @param ctx.client The GraphQL client within the context.
+ * @param buildNumber The build number to start searching from
+ * @param options Page size and limit options
+ * @param options.page How many builds to fetch each time
+ * @param options.limit How many builds to gather per query.
  *
- * @returns {Build | void} A build to be substituted
- * */
+ * @returns A build to be substituted
+ */
 export async function findAncestorBuildWithCommit(
   { client }: Pick<Context, 'client'>,
   buildNumber: number,

node-src/git/generateGitRepository.ts

@@ -44,15 +44,22 @@ async function generateCommit(
   return { hash, committedAt: Number.parseInt(committedAt, 10) };
 }
 
-// Take a repository description in the following format:
-//  [[name, parentNames]], where:
-//    - name is a string
-//    - parentNames can be false (no parent), a single string or array of strings
-//
-// This function will take such a description and create a git repository with commits
-// following the structure above. Note commit times are assumed to be increasing down the list.
-//
-// Returns a map: name => commitHash
+/**
+ * Take a repository description in the following format:
+ *  [[name, parentNames]], where:
+ *    - name is a string
+ *    - parentNames can be false (no parent), a single string or array of strings
+ *
+ * This function will take such a description and create a git repository with commits
+ * following the structure above. Note commit times are assumed to be increasing down the list.
+ *
+ * Returns a map: name => commitHash
+ *
+ * @param runGit A function for running Git commands.
+ * @param description A description of the Git history to use.
+ *
+ * @returns The commit map of the generated repository.
+ */
 export default async function generateGitRepository(runGit, description) {
   await runGit(`git init`);
   await runGit(`git config user.email test@test.com`);

node-src/git/getBaselineBuilds.ts

@@ -38,6 +38,16 @@ interface BaselineCommitsQueryResult {
   };
 }
 
+/**
+ * Get a list of baseline builds from the Index service
+ *
+ * @param ctx The context set when executing the CLI.
+ * @param options Options to pass to the Index query.
+ * @param options.branch The branch name.
+ * @param options.parentCommits A list of parent commit hashes.
+ *
+ * @returns A list of baseline builds, if available.
+ */
 export async function getBaselineBuilds(
   ctx: Pick<Context, 'options' | 'client' | 'git'>,
   { branch, parentCommits }: { branch: string; parentCommits: string[] }

node-src/git/getBranchFromMergeQueuePullRequestNumber.ts

@@ -19,6 +19,15 @@ interface MergeQueueOriginalBranchQueryResult {
   };
 }
 
+/**
+ * Get branch name from a pull request number via the Index service.
+ *
+ * @param ctx The context set when executing the CLI.
+ * @param options Options to pass to the Index query.
+ * @param options.number The pull request number.
+ *
+ * @returns The branch name, if available.
+ */
 export async function getBranchFromMergeQueuePullRequestNumber(
   ctx: Pick<Context, 'options' | 'client' | 'git'>,
   { number }: { number: number }

node-src/git/getChangedFilesWithReplacement.ts

@@ -17,9 +17,14 @@ interface BuildWithCommitInfo {
  * If the historical build's commit doesn't exist (for instance if it has been rebased and force-
  * pushed away), find the nearest ancestor build that *does* have a valid commit, and return
  * the differences, along with the two builds (for tracking purposes).
+ *
+ * @param ctx The context set when executing the CLI.
+ * @param build The build details for gathering changed files.
+ *
+ * @returns A list of changed files for the build, adding a replacement build if necessary.
  */
 export async function getChangedFilesWithReplacement(
-  context: Context,
+  ctx: Context,
   build: BuildWithCommitInfo
 ): Promise<{ changedFiles: string[]; replacementBuild?: BuildWithCommitInfo }> {
   try {
@@ -30,21 +35,21 @@ export async function getChangedFilesWithReplacement(
     const changedFiles = await getChangedFiles(build.commit);
     return { changedFiles };
   } catch (err) {
-    context.log.debug(
+    ctx.log.debug(
       `Got error fetching commit for #${build.number}(${build.commit}): ${err.message}`
     );
 
     if (/(bad object|uncommitted changes)/.test(err.message)) {
-      const replacementBuild = await findAncestorBuildWithCommit(context, build.number);
+      const replacementBuild = await findAncestorBuildWithCommit(ctx, build.number);
 
       if (replacementBuild) {
-        context.log.debug(
+        ctx.log.debug(
           `Found replacement build for #${build.number}(${build.commit}): #${replacementBuild.number}(${replacementBuild.commit})`
         );
         const changedFiles = await getChangedFiles(replacementBuild.commit);
         return { changedFiles, replacementBuild };
       }
-      context.log.debug(`Couldn't find replacement for #${build.number}(${build.commit})`);
+      ctx.log.debug(`Couldn't find replacement for #${build.number}(${build.commit})`);
     }
 
     // If we can't find a replacement or the error doesn't match, just throw

node-src/git/getCommitAndBranch.test.ts

@@ -1,6 +1,8 @@
 import envCi from 'env-ci';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { Logger } from '../lib/log';
+import { Context } from '../types';
 import * as mergeQueue from './getBranchFromMergeQueuePullRequestNumber';
 import getCommitAndBranch from './getCommitAndBranch';
 import * as git from './git';
@@ -15,7 +17,8 @@ const hasPreviousCommit = vi.mocked(git.hasPreviousCommit);
 const getBranchFromMergeQueue = vi.mocked(mergeQueue.getBranchFromMergeQueuePullRequestNumber);
 const mergeQueueBranchMatch = vi.mocked(git.mergeQueueBranchMatch);
 
-const log = { info: vi.fn(), warn: vi.fn(), debug: vi.fn() };
+const log = { info: vi.fn(), warn: vi.fn(), debug: vi.fn() } as unknown as Logger;
+const ctx = { log } as unknown as Context;
 
 const processEnv = process.env;
 beforeEach(() => {
@@ -47,7 +50,7 @@ const commitInfo = {
 
 describe('getCommitAndBranch', () => {
   it('returns commit and branch info', async () => {
-    const info = await getCommitAndBranch({ log });
+    const info = await getCommitAndBranch(ctx);
     expect(info).toMatchObject({
       branch: 'main',
       commit: '48e0c83fadbf504c191bc868040b7a969a4f1feb',
@@ -68,7 +71,7 @@ describe('getCommitAndBranch', () => {
     });
     getBranch.mockResolvedValue('HEAD');
     getCommit.mockImplementation((commit) => Promise.resolve({ commit, ...commitInfo }));
-    const info = await getCommitAndBranch({ log });
+    const info = await getCommitAndBranch(ctx);
     expect(info).toMatchObject({
       branch: 'ci-branch',
       commit: 'ci-commit',
@@ -84,49 +87,49 @@ describe('getCommitAndBranch', () => {
       prBranch: 'ci-pr-branch',
     });
     getBranch.mockResolvedValue('HEAD');
-    const info = await getCommitAndBranch({ log });
+    const info = await getCommitAndBranch(ctx);
     expect(info).toMatchObject({ branch: 'ci-pr-branch' });
   });
 
   it('removes origin/ prefix in branch name', async () => {
     getBranch.mockResolvedValue('origin/master');
-    const info = await getCommitAndBranch({ log });
+    const info = await getCommitAndBranch(ctx);
     expect(info).toMatchObject({ branch: 'master' });
   });
 
   it('throws when there is only one commit, CI', async () => {
     envCi.mockReturnValue({ isCi: true });
     hasPreviousCommit.mockResolvedValue(false);
-    await expect(getCommitAndBranch({ log })).rejects.toThrow('Found only one commit');
+    await expect(getCommitAndBranch(ctx)).rejects.toThrow('Found only one commit');
   });
 
   it('does NOT throw when there is only one commit, non-CI', async () => {
     envCi.mockReturnValue({ isCi: false });
     hasPreviousCommit.mockResolvedValue(false);
-    const info = await getCommitAndBranch({ log });
+    const info = await getCommitAndBranch(ctx);
     expect(info).toMatchObject({});
   });
 
   describe('with branchName', () => {
     it('uses provided branchName as branch', async () => {
-      const info = await getCommitAndBranch({ log }, { branchName: 'foobar' });
+      const info = await getCommitAndBranch(ctx);
       expect(info).toMatchObject({ branch: 'foobar' });
     });
 
     it('does not remove origin/ prefix in branch name', async () => {
-      const info = await getCommitAndBranch({ log }, { branchName: 'origin/foobar' });
+      const info = await getCommitAndBranch(ctx);
       expect(info).toMatchObject({ branch: 'origin/foobar' });
     });
   });
 
   describe('with patchBaseRef', () => {
     it('uses provided patchBaseRef as branch', async () => {
-      const info = await getCommitAndBranch({ log }, { patchBaseRef: 'foobar' });
+      const info = await getCommitAndBranch(ctx);
       expect(info).toMatchObject({ branch: 'foobar' });
     });
 
     it('prefers branchName over patchBaseRef', async () => {
-      const info = await getCommitAndBranch({ log }, { branchName: 'foo', patchBaseRef: 'bar' });
+      const info = await getCommitAndBranch(ctx);
       expect(info).toMatchObject({ branch: 'foo' });
     });
   });
@@ -137,7 +140,7 @@ describe('getCommitAndBranch', () => {
       process.env.CHROMATIC_BRANCH = 'feature';
       process.env.CHROMATIC_SLUG = 'chromaui/chromatic';
       getCommit.mockImplementation((commit) => Promise.resolve({ commit, ...commitInfo }));
-      const info = await getCommitAndBranch({ log });
+      const info = await getCommitAndBranch(ctx);
       expect(info).toMatchObject({
         branch: 'feature',
         commit: 'f78db92d',
@@ -157,15 +160,15 @@ describe('getCommitAndBranch', () => {
         .mockRejectedValueOnce(
           new Error('fatal: bad object 48e0c83fadbf504c191bc868040b7a969a4f1feb')
         );
-      const info = await getCommitAndBranch({ log });
+      const info = await getCommitAndBranch(ctx);
       expect(info).toMatchObject({ branch: 'feature', commit: 'f78db92d' });
       expect(log.warn).toHaveBeenCalledWith(expect.stringMatching('Commit f78db92 does not exist'));
     });
 
     it('does not remove origin/ prefix in branch name', async () => {
       process.env.CHROMATIC_SHA = 'f78db92d';
       process.env.CHROMATIC_BRANCH = 'origin/feature';
-      const info = await getCommitAndBranch({ log });
+      const info = await getCommitAndBranch(ctx);
       expect(info).toMatchObject({ branch: 'origin/feature' });
     });
   });
@@ -177,7 +180,7 @@ describe('getCommitAndBranch', () => {
       process.env.GITHUB_REPOSITORY = 'chromaui/github';
       process.env.GITHUB_SHA = '3276c796';
       getCommit.mockResolvedValue({ commit: 'c11da9a9', ...commitInfo });
-      const info = await getCommitAndBranch({ log });
+      const info = await getCommitAndBranch(ctx);
       expect(getCommit).toHaveBeenCalledWith('github');
       expect(info).toMatchObject({
         branch: 'github',
@@ -190,22 +193,18 @@ describe('getCommitAndBranch', () => {
     it('throws on missing variable', async () => {
       process.env.GITHUB_EVENT_NAME = 'pull_request';
       process.env.GITHUB_HEAD_REF = 'github';
-      await expect(getCommitAndBranch({ log })).rejects.toThrow(
-        'Missing GitHub environment variable'
-      );
+      await expect(getCommitAndBranch(ctx)).rejects.toThrow('Missing GitHub environment variable');
       process.env.GITHUB_HEAD_REF = '';
       process.env.GITHUB_SHA = '3276c796';
-      await expect(getCommitAndBranch({ log })).rejects.toThrow(
-        'Missing GitHub environment variable'
-      );
+      await expect(getCommitAndBranch(ctx)).rejects.toThrow('Missing GitHub environment variable');
     });
 
     it('throws on cross-fork PR (where refs are equal)', async () => {
       process.env.GITHUB_EVENT_NAME = 'pull_request';
       process.env.GITHUB_BASE_REF = 'github';
       process.env.GITHUB_HEAD_REF = 'github';
       process.env.GITHUB_SHA = '3276c796';
-      await expect(getCommitAndBranch({ log })).rejects.toThrow('Cross-fork PR builds unsupported');
+      await expect(getCommitAndBranch(ctx)).rejects.toThrow('Cross-fork PR builds unsupported');
     });
   });
 
@@ -216,7 +215,7 @@ describe('getCommitAndBranch', () => {
       process.env.TRAVIS_PULL_REQUEST_BRANCH = 'travis';
       process.env.TRAVIS_PULL_REQUEST_SLUG = 'chromaui/travis';
       getCommit.mockImplementation((commit) => Promise.resolve({ commit, ...commitInfo }));
-      const info = await getCommitAndBranch({ log });
+      const info = await getCommitAndBranch(ctx);
       expect(info).toMatchObject({
         branch: 'travis',
         commit: 'ef765ac7',
@@ -228,23 +227,18 @@ describe('getCommitAndBranch', () => {
     it('throws on missing variable', async () => {
       process.env.TRAVIS_EVENT_TYPE = 'pull_request';
       process.env.TRAVIS_PULL_REQUEST_SHA = 'ef765ac7';
-      await expect(getCommitAndBranch({ log })).rejects.toThrow(
-        'Missing Travis environment variable'
-      );
+      await expect(getCommitAndBranch(ctx)).rejects.toThrow('Missing Travis environment variable');
     });
   });
 
   describe('with mergeQueue branch', () => {
     it('uses PRs branchName as branch instead of temporary mergeQueue branch', async () => {
       mergeQueueBranchMatch.mockResolvedValue(4);
       getBranchFromMergeQueue.mockResolvedValue('branch-before-merge-queue');
-      const info = await getCommitAndBranch(
-        { log },
-        {
-          branchName:
-            'this-is-merge-queue-branch-format/main/pr-4-48e0c83fadbf504c191bc868040b7a969a4f1feb',
-        }
-      );
+      const info = await getCommitAndBranch(ctx, {
+        branchName:
+          'this-is-merge-queue-branch-format/main/pr-4-48e0c83fadbf504c191bc868040b7a969a4f1feb',
+      });
       expect(info).toMatchObject({ branch: 'branch-before-merge-queue' });
     });
   });