Merge pull request #1066 from chromaui/cody/cap-2200-eslint-add-jsdoc…

…-config

Enable `eslint-plugin-jsdoc` ESLint rule

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);

eslint.config.mjs

@@ -1,6 +1,6 @@
 import eslint from '@eslint/js';
 import comments from '@eslint-community/eslint-plugin-eslint-comments/configs';
-// import jsdoc from 'eslint-plugin-jsdoc';
+import jsdoc from 'eslint-plugin-jsdoc';
 import noSecrets from 'eslint-plugin-no-secrets';
 import prettier from 'eslint-plugin-prettier';
 import security from 'eslint-plugin-security';
@@ -186,31 +186,31 @@ export default [
     },
   },
   // lint jsdoc
-  //   {
-  //     files: ['**/*.js', '**/*.ts'],
-  //     plugins: {
-  //       jsdoc,
-  //     },
-  //     rules: {
-  //       ...jsdoc.configs['flat/recommended-typescript'].rules,
-  //       'jsdoc/require-jsdoc': [
-  //         'error',
-  //         {
-  //           publicOnly: true,
-  //           require: { ClassDeclaration: true, FunctionDeclaration: true },
-  //           enableFixer: false,
-  //         },
-  //       ],
-  //       'jsdoc/require-returns': ['warn', { enableFixer: true }],
-  //       'jsdoc/sort-tags': [
-  //         'error',
-  //         {
-  //           tagSequence: [{ tags: ['param'] }, { tags: ['returns'] }],
-  //         },
-  //       ],
-  //       'jsdoc/tag-lines': ['error', 'any', { startLines: 1 }],
-  //     },
-  //   },
+  {
+    files: ['**/*.js', '**/*.ts'],
+    plugins: {
+      jsdoc,
+    },
+    rules: {
+      ...jsdoc.configs['flat/recommended-typescript'].rules,
+      'jsdoc/require-jsdoc': [
+        'error',
+        {
+          publicOnly: true,
+          require: { ClassDeclaration: true, FunctionDeclaration: true },
+          enableFixer: false,
+        },
+      ],
+      'jsdoc/require-returns': ['warn', { enableFixer: true }],
+      'jsdoc/sort-tags': [
+        'error',
+        {
+          tagSequence: [{ tags: ['param'] }, { tags: ['returns'] }],
+        },
+      ],
+      'jsdoc/tag-lines': ['error', 'any', { startLines: 1 }],
+    },
+  },
   // sort your imports
   {
     plugins: {

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