eslint-config-uphold 6.11.0 → 6.13.0

package/README.md

@@ -154,6 +154,7 @@ This config includes custom Uphold-specific rules, under `uphold-plugin`.
 | [`database-migration-filename-format`](#database-migration-filename-format) | False                      | False |
 | [`explicit-sinon-use-fake-timers`](#explicit-sinon-use-fake-timers)         | True                       | False |
 | [`no-trailing-period-in-log-messages`](#no-trailing-period-in-log-messages) | True                       | True  |
+| [`require-comment-punctuation`](#require-comment-punctuation)               | True                       | True  |
 
 #### `database-migration-filename-format`
 
@@ -221,6 +222,50 @@ logger.error('An error occurred.'); // ❌ Remove the trailing period.
   }]
   ```
 
+#### `require-comment-punctuation`
+
+Requires `//` comment blocks to end with punctuation on the last line. Valid endings are `.`, `:`, `;`, `?`, `!`, or paired triple backticks (`` ``` ``). This helps maintain consistency in code comments.
+
+**Valid:**
+
+````js
+// This is a comment with a period.
+// Is this a question?
+// This is important!
+// ``` let foo = 1 + 2 ```
+````
+
+**Invalid:**
+
+- ❌ Missing punctuation.
+
+  ```js
+  // This is a comment without punctuation
+  // Comment with unmatched backticks ```
+  ```
+
+**Options:**
+
+- `exclusionPrefixes` - An array of strings. Comments starting with these prefixes (after `//`) are excluded from the rule:
+
+  ```js
+  'uphold-plugin/require-comment-punctuation': ['error', {
+    exclusionPrefixes: ['TODO:', 'FIXME:', 'NOTE:']
+  }]
+  ```
+
+  With this config, comments like `// TODO: implement this` will not require punctuation.
+
+- `additionalAllowedEndings` - An array of strings to extend the default allowed endings (`.`, `:`, `;`, `?`, `!`, `` ``` ``):
+
+  ```js
+  'uphold-plugin/require-comment-punctuation': ['error', {
+    additionalAllowedEndings: [')']
+  }]
+  ```
+
+  With this config, comments ending with `)` will also be considered valid.
+
 ### Test configs
 
 This package includes individual exported configs for multiple test frameworks:
@@ -258,6 +303,20 @@ import { jest, mocha, vitest } from 'eslint-config-uphold/configs';
 > [!NOTE]
 > Test configs use top-level `await` for dynamic module detection and are **ESM-only**. If your project uses CommonJS, your `eslint.config.mjs` still supports `import()` and top-level `await`.
 
+### Custom parsers
+
+From [ESLint's docs > Configure a Parser](https://eslint.org/docs/latest/use/configure/parser):
+
+> You can use custom parsers to convert JavaScript code into an abstract syntax tree for ESLint to evaluate. You might want to add a custom parser if your code isn’t compatible with ESLint’s default parser, Espree.
+>
+> (...)
+>
+> The following third-party parsers are known to be compatible with ESLint:
+>
+> - [Esprima](https://www.npmjs.com/package/esprima)
+> - [@babel/eslint-parser](https://www.npmjs.com/package/@babel/eslint-parser) - A wrapper around the Babel parser that makes it compatible with ESLint.
+> - [@typescript-eslint/parser](https://www.npmjs.com/package/@typescript-eslint/parser) - A parser that converts TypeScript into an ESTree-compatible form so it can be used in ESLint.
+
 ## Upgrading ESLint
 
 See the [ESLint repo](https://github.com/eslint/eslint#semantic-versioning-policy) for ESLint's guidelines on semantic versioning.
@@ -269,6 +328,10 @@ This is down to the fact that no guarantee is made that minor upgrades do not ca
 The downside here is a package update is required for any security or other bug fixes.
 The benefit however is the included rules are always guaranteed to be stable.
 
+## Migration guide
+
+See the [MIGRATIONS.md](MIGRATIONS.md) file for migration guides between versions v5 and v6, v6 and v7.
+
 ## Release process
 
 The release of a version is automated via the [release](https://github.com/uphold/eslint-config-uphold/.github/workflows/release.yml) GitHub workflow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-config-uphold",
-  "version": "6.11.0",
+  "version": "6.13.0",
   "description": "Uphold-flavored ESLint config",
   "keywords": [
     "config",
@@ -35,13 +35,10 @@
     "test": "node --test $(find test -name '*.test.js')"
   },
   "dependencies": {
-    "@babel/core": "^7.28.6",
-    "@babel/eslint-parser": "^7.28.6",
-    "@stylistic/eslint-plugin": "^5.7.0",
+    "@stylistic/eslint-plugin": "^5.7.1",
     "dayjs": "^1.11.19",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-jsdoc": "^62.2.0",
-    "eslint-plugin-mocha": "^11.2.0",
+    "eslint-plugin-jsdoc": "^62.5.1",
     "eslint-plugin-n": "^17.23.2",
     "eslint-plugin-prettier": "^5.5.5",
     "eslint-plugin-promise": "^7.2.1",
@@ -49,17 +46,18 @@
     "eslint-plugin-sort-imports-requires": "^2.0.0",
     "eslint-plugin-sort-keys-fix": "^1.1.2",
     "eslint-plugin-sql-template": "^3.1.0",
-    "globals": "^17.0.0"
+    "globals": "^17.3.0"
   },
   "devDependencies": {
     "@fastify/pre-commit": "^2.2.1",
-    "@types/node": "^22.19.7",
+    "@types/node": "^22.19.8",
     "@uphold/github-changelog-generator": "^4.0.2",
     "@vitest/eslint-plugin": "^1.6.6",
     "eslint": "~9.39.2",
-    "eslint-plugin-jest": "^29.12.1",
-    "prettier": "^3.8.0",
-    "release-it": "^19.2.3",
+    "eslint-plugin-jest": "^29.12.2",
+    "eslint-plugin-mocha": "^11.2.0",
+    "prettier": "^3.8.1",
+    "release-it": "^19.2.4",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.54.0"
   },

package/src/configs/common.js

@@ -374,7 +374,8 @@ export const upholdPluginConfig = {
   },
   rules: {
     ...(isSinonAvailable && { 'uphold-plugin/explicit-sinon-use-fake-timers': 'error' }),
-    'uphold-plugin/no-trailing-period-in-log-messages': 'error'
+    'uphold-plugin/no-trailing-period-in-log-messages': 'error',
+    'uphold-plugin/require-comment-punctuation': 'error'
   }
 };
 

package/src/configs/typescript.js

@@ -138,6 +138,7 @@ export async function createTypeScriptConfig(moduleType = 'module', { ecmaVersio
         },
         rules: {
           ...eslintRules,
+          '@typescript-eslint/array-type': ['error', { default: 'array-simple', readonly: 'array-simple' }],
           '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_.+' }],
           'no-unused-expressions': 'off',
           'no-unused-vars': 'off'

package/src/index.js

@@ -6,6 +6,7 @@ import { defineConfig } from 'eslint/config';
 import {
   eslintRules,
   jsdocPluginConfigJavaScript,
+  nodePluginConfig,
   promisePluginConfig,
   sortDestructureKeysConfig,
   sortImportsRequiresConfig,
@@ -13,7 +14,6 @@ import {
   sqlTemplateConfig,
   stylisticConfig
 } from './configs/common.js';
-import babelParser from '@babel/eslint-parser';
 import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
 import globals from 'globals';
 import js from '@eslint/js';
@@ -35,17 +35,8 @@ import stylistic from '@stylistic/eslint-plugin';
  */
 
 const languageOptions = {
-  ecmaVersion: 2020,
-  globals: {
-    ...globals.jasmine,
-    ...globals.jest,
-    ...globals.mocha,
-    ...globals.node
-  },
-  parser: babelParser,
-  parserOptions: {
-    requireConfigFile: false
-  },
+  ecmaVersion: 2022,
+  globals: globals.node,
   sourceType: 'module'
 };
 
@@ -68,8 +59,8 @@ const upholdBaseConfig = defineConfig([
       '@stylistic': stylistic,
       jsdoc,
       mocha,
-      // To be renamed to `n` on next major release.
-      'node-plugin': nodePlugin,
+      // eslint-disable-next-line id-length
+      n: nodePlugin,
       // @ts-expect-error Outdated types for `eslint-plugin-promise`.
       promise,
       // @ts-expect-error Outdated types for `eslint-plugin-sort-destructure-keys`.
@@ -82,27 +73,16 @@ const upholdBaseConfig = defineConfig([
     },
     rules: {
       ...eslintRules,
+      ...nodePluginConfig.rules,
       ...promisePluginConfig.rules,
       ...sortDestructureKeysConfig.rules,
       ...sortImportsRequiresConfig.rules,
       ...sortKeysFixConfig.rules,
       ...sqlTemplateConfig.rules,
       ...stylisticConfig.rules,
-      // Mocha rules to be removed on next major release.
-      'mocha/no-exclusive-tests': 'error',
-      'mocha/no-identical-title': 'error',
-      'mocha/no-nested-tests': 'error',
-      'mocha/no-sibling-hooks': 'error',
-      'node-plugin/no-mixed-requires': 'error',
-      'node-plugin/no-new-require': 'error',
-      'node-plugin/no-path-concat': 'error',
-      'node-plugin/no-process-env': 'error',
-      'node-plugin/no-process-exit': 'error',
-      'node-plugin/no-restricted-import': 'error',
-      'node-plugin/no-restricted-require': 'error',
-      'node-plugin/no-sync': 'error',
       'uphold-plugin/explicit-sinon-use-fake-timers': 'error',
-      'uphold-plugin/no-trailing-period-in-log-messages': 'error'
+      'uphold-plugin/no-trailing-period-in-log-messages': 'error',
+      'uphold-plugin/require-comment-punctuation': 'error'
     }
   }
 ]);
@@ -118,8 +98,8 @@ const upholdBinScriptsConfig = {
   languageOptions,
   name: 'uphold/scripts',
   rules: {
-    'no-console': 'off',
-    'node-plugin/no-process-exit': 'off'
+    'n/no-process-exit': 'off',
+    'no-console': 'off'
   }
 };
 

package/src/rules/index.js

@@ -7,9 +7,11 @@
 import databaseMigrationFilenameFormat from './database-migration-filename-format.js';
 import explicitSinonUseFakeTimers from './explicit-sinon-use-fake-timers.js';
 import noTrailingPeriodInLogMessages from './no-trailing-period-in-log-messages.js';
+import requireCommentPunctuation from './require-comment-punctuation.js';
 
 export default {
   'database-migration-filename-format': databaseMigrationFilenameFormat,
   'explicit-sinon-use-fake-timers': explicitSinonUseFakeTimers,
-  'no-trailing-period-in-log-messages': noTrailingPeriodInLogMessages
+  'no-trailing-period-in-log-messages': noTrailingPeriodInLogMessages,
+  'require-comment-punctuation': requireCommentPunctuation
 };

package/src/rules/no-trailing-period-in-log-messages.js

@@ -100,7 +100,7 @@ const noTrailingPeriodInLogMessages = {
     /**
      * Extracts the log method name from a callee node.
      * @param {import('estree').Node} callee - Callee node to analyze.
-     * @returns {string|null} Method name if it's a log method, null otherwise.
+     * @returns {string | null} Method name if it's a log method, null otherwise.
      */
     function getLogMethodName(callee) {
       if (callee.type === 'MemberExpression') {

package/src/rules/require-comment-punctuation.js

@@ -0,0 +1,341 @@
+/**
+ * @typedef {import('estree').Comment} Comment
+ * @typedef {Comment & { range: [number, number], loc: import('estree').SourceLocation }} CommentWithRange
+ * @typedef {{
+ *   comment: CommentWithRange,
+ *   isDirective: boolean,
+ *   isExcluded: boolean,
+ *   isFullLine: boolean,
+ *   valueTrimmed: string
+ * }} CommentInfo
+ */
+
+/**
+ * Constants.
+ */
+
+// Allowed endings for the last line in a `//` comment block.
+const ALLOWED_ENDINGS = Object.freeze(['.', ':', ';', '?', '!', '```']);
+
+// Directive prefixes that have semantic meaning and should not be style-linted.
+const DIRECTIVE_PREFIXES = Object.freeze([
+  '@ts-',
+  'c8 ',
+  'eslint ',
+  'eslint-',
+  'global ',
+  'istanbul ',
+  'prettier-ignore',
+  'v8 '
+]);
+
+/**
+ * Has Paired Triple Backticks.
+ * @param {string} trimmedEnd The comment text trimmed only on the right side.
+ * @returns {boolean} True if the comment contains at least two instances of ```, and they're a multiple of two.
+ */
+function hasPairedTripleBackticks(trimmedEnd) {
+  const matches = trimmedEnd.match(/```/g);
+
+  return Boolean(matches && matches.length >= 2 && matches.length % 2 === 0);
+}
+
+/**
+ * Ends with Allowed Punctuation.
+ * @param {string} trimmedEnd The comment text trimmed only on the right side.
+ * @param {string[]} allowedEndings The list of allowed endings.
+ * @returns {boolean} True if the trimmed comment text ends with allowed punctuation.
+ */
+function endsWithAllowedPunctuation(trimmedEnd, allowedEndings) {
+  return allowedEndings.some(ending => {
+    if (ending === '```') {
+      return trimmedEnd.endsWith(ending) && hasPairedTripleBackticks(trimmedEnd);
+    }
+
+    return trimmedEnd.endsWith(ending);
+  });
+}
+
+// Pre-compile frequently used regexes to avoid repeated allocation.
+const PUNCT_RE = new RegExp(/[^\w\s]/);
+
+/**
+ * Is Punctuation Character.
+ * @param {string|undefined} ch The character to check.
+ * @returns {boolean} True if the character is a punctuation character.
+ */
+function isPunctuationChar(ch) {
+  return !!ch && PUNCT_RE.test(ch);
+}
+
+/**
+ * Is Directive Comment.
+ * - These comments have semantic meaning and should not be style-linted.
+ * @param {string} trimmed Comment text with whitespace trimmed on both ends.
+ * @returns {boolean} Returns true if this comment is an ESLint/TS/prettier/coverage directive.
+ */
+function isDirectiveComment(trimmed) {
+  if (!trimmed) {
+    return false;
+  }
+
+  if (trimmed === 'eslint') {
+    return true;
+  }
+
+  return DIRECTIVE_PREFIXES.some(prefix => trimmed.startsWith(prefix));
+}
+
+/**
+ * Is Full-Line Comment.
+ * (i.e. it is a full-line comment, not a trailing inline comment).
+ * @param {import('eslint').SourceCode} sourceCode The ESLint source code object.
+ * @param {CommentWithRange} comment The comment token.
+ * @returns {boolean} True if the comment starts at the first non-whitespace character of the line.
+ */
+function isFullLineComment(sourceCode, comment) {
+  const line = sourceCode.lines[comment.loc.start.line - 1] || '';
+  const before = line.slice(0, comment.loc.start.column);
+
+  return /^[\t ]*$/.test(before);
+}
+
+/**
+ * Is Line Comment With Range.
+ * @param {Comment} comment The comment token.
+ * @returns {comment is CommentWithRange} True if the comment is a line comment with range/loc metadata.
+ */
+function isLineCommentWithRange(comment) {
+  return comment.type === 'Line' && Boolean(comment.range && comment.loc);
+}
+
+/**
+ * Normalize rule options.
+ * @param {{ exclusionPrefixes?: string[], additionalAllowedEndings?: string[] }} rawOptions The raw options.
+ * @returns {{ exclusionPrefixes: string[], allowedEndings: string[] }} Normalized options.
+ */
+function normalizeOptions(rawOptions) {
+  const exclusionPrefixes = rawOptions.exclusionPrefixes || [];
+  const additionalAllowedEndings = rawOptions.additionalAllowedEndings || [];
+  const allowedEndings = [...ALLOWED_ENDINGS, ...additionalAllowedEndings];
+
+  return { allowedEndings, exclusionPrefixes };
+}
+
+/**
+ * Get Index to Insert Period Before Trailing Whitespace.
+ * - Compute where to insert a period so it lands before trailing whitespace.
+ * @param {import('eslint').SourceCode} sourceCode The ESLint source code object.
+ * @param {CommentWithRange} comment The comment token.
+ * @returns {number} The index in sourceCode.text where the period should be inserted.
+ */
+function getInsertIndexBeforeTrailingWhitespace(sourceCode, comment) {
+  const raw = sourceCode.text.slice(comment.range[0], comment.range[1]);
+  const trailingWhitespace = raw.match(/\s*$/)?.[0].length || 0;
+
+  return comment.range[1] - trailingWhitespace;
+}
+
+/**
+ * `require-comment-punctuation` ESLint rule definition.
+ * @type {import('eslint').Rule.RuleModule}
+ */
+const requireCommentPunctuation = {
+  create(context) {
+    const { sourceCode } = context;
+    /** @type {{ exclusionPrefixes?: string[], additionalAllowedEndings?: string[] }} */
+    const rawOptions = context.options[0] || {};
+    const { allowedEndings, exclusionPrefixes } = normalizeOptions(rawOptions);
+    const allowedEndingsText = [...new Set(allowedEndings)].join(', ');
+
+    /**
+     * Check if comment should be excluded based on exclusion prefixes.
+     * @param {string} trimmed The trimmed comment text.
+     * @returns {boolean} True if comment should be excluded.
+     */
+    function isExcludedComment(trimmed) {
+      return exclusionPrefixes.some(prefix => trimmed.startsWith(prefix));
+    }
+
+    /**
+     * Decide if two comments should be grouped into the same block.
+     * @param {CommentInfo} previousInfo The previous comment info.
+     * @param {CommentInfo} nextInfo The next comment info.
+     * @returns {boolean} True if the comments should be grouped.
+     */
+    function shouldJoinBlock(previousInfo, nextInfo) {
+      const adjacentLine = nextInfo.comment.loc.start.line === previousInfo.comment.loc.end.line + 1;
+
+      return adjacentLine && previousInfo.isFullLine && nextInfo.isFullLine;
+    }
+
+    /**
+     * Find the last non-empty comment in a block.
+     * @param {CommentInfo[]} block The block of line comments to check.
+     * @returns {CommentInfo | null} The last meaningful comment, or null.
+     */
+    function findLastMeaningfulInfo(block) {
+      /** @type {CommentInfo | null} */
+      let lastMeaningful = null;
+
+      for (const info of block) {
+        // should not happen; directives break blocks.
+        if (info.isDirective || info.isExcluded) {
+          return null;
+        }
+
+        if (info.valueTrimmed.length > 0) {
+          lastMeaningful = info;
+        }
+      }
+
+      return lastMeaningful;
+    }
+
+    /**
+     * Check Block for punctuation.
+     * - Enforce punctuation on the last *meaningful* line of the block.
+     * - If the block ends with blank `//` lines, we skip those and check the
+     * last non-empty comment.
+     * @param {CommentInfo[]} block The block of line comments to check.
+     */
+    function checkBlock(block) {
+      if (!block.length) {
+        return;
+      }
+
+      const lastMeaningful = findLastMeaningfulInfo(block);
+
+      if (!lastMeaningful) {
+        return;
+      }
+
+      // Compute right-trimmed value lazily to avoid unnecessary work.
+      const trimmedEnd = lastMeaningful.comment.value.trimEnd();
+
+      if (endsWithAllowedPunctuation(trimmedEnd, allowedEndings)) {
+        return;
+      }
+
+      if (trimmedEnd.endsWith('```') && !hasPairedTripleBackticks(trimmedEnd)) {
+        context.report({
+          loc: lastMeaningful.comment.loc,
+          messageId: 'unpairedBackticks'
+        });
+
+        return;
+      }
+
+      context.report({
+        data: { allowedEndings: allowedEndingsText },
+        fix(fixer) {
+          const insertAt = getInsertIndexBeforeTrailingWhitespace(sourceCode, lastMeaningful.comment);
+
+          // Attempt to replace a single trailing disallowed punctuation mark
+          // (e.g. `,`) with a period instead of appending, to avoid outputs
+          // like `comma,.`. We only replace when the last non-whitespace
+          // character is a single punctuation character (not part of a
+          // multi-character punctuation like `..` or triple backticks).
+          const lastNonWsIndex = insertAt - 1;
+          const lastChar = sourceCode.text.charAt(lastNonWsIndex);
+          const prevChar = sourceCode.text.charAt(lastNonWsIndex - 1);
+          const lastCharIsSinglePunctuation = isPunctuationChar(lastChar) && !isPunctuationChar(prevChar);
+
+          // If it's a single backtick we avoid replacing because triple
+          // backtick handling is done separately above.
+          if (lastCharIsSinglePunctuation && lastChar !== '`') {
+            return fixer.replaceTextRange([lastNonWsIndex, insertAt], '.');
+          }
+
+          return fixer.insertTextBeforeRange([insertAt, insertAt], '.');
+        },
+        loc: lastMeaningful.comment.loc,
+        messageId: 'missingPunctuation'
+      });
+    }
+
+    return {
+      Program() {
+        /** @type {CommentWithRange[]} */
+        const lineComments = sourceCode.getAllComments().filter(isLineCommentWithRange);
+
+        /** @type {CommentInfo[]} */
+        const commentInfos = lineComments.map(comment => {
+          const valueTrimmed = comment.value.trim();
+
+          return {
+            comment,
+            isDirective: isDirectiveComment(valueTrimmed),
+            isExcluded: isExcludedComment(valueTrimmed),
+            isFullLine: isFullLineComment(sourceCode, comment),
+            valueTrimmed
+          };
+        });
+
+        /** @type {CommentInfo[]} */
+        let currentBlock = [];
+
+        for (const info of commentInfos) {
+          // Directives and excluded comments are always their own "block" and are ignored.
+          if (info.isDirective || info.isExcluded) {
+            checkBlock(currentBlock);
+            currentBlock = [];
+            continue;
+          }
+
+          if (currentBlock.length === 0) {
+            currentBlock.push(info);
+            continue;
+          }
+
+          const previousInfo = currentBlock[currentBlock.length - 1];
+
+          // Only group full-line comments. Trailing inline comments are checked individually.
+          if (shouldJoinBlock(previousInfo, info)) {
+            currentBlock.push(info);
+          } else {
+            checkBlock(currentBlock);
+            currentBlock = [info];
+          }
+        }
+
+        checkBlock(currentBlock);
+      }
+    };
+  },
+  meta: {
+    docs: {
+      description: 'Require `//` comment blocks to end with punctuation on the last line.'
+    },
+    fixable: 'code',
+    messages: {
+      missingPunctuation: 'Line comment must end with one of: {{allowedEndings}}.',
+      unpairedBackticks: 'Line comment ends with unpaired triple backticks (```).'
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          additionalAllowedEndings: {
+            description: 'Additional endings to allow beyond the defaults (., :, ;, ?, !, ```).',
+            items: { type: 'string' },
+            type: 'array'
+          },
+          exclusionPrefixes: {
+            description: 'Comments starting with these strings (after `//`) are excluded from the rule.',
+            items: { type: 'string' },
+            type: 'array'
+          }
+        },
+        type: 'object'
+      }
+    ],
+    type: 'suggestion'
+  }
+};
+
+/**
+ * Export `require-comment-punctuation` rule.
+ */
+
+export default requireCommentPunctuation;