Standardize comments

.eslintrc.js

@@ -1,8 +1,8 @@
 // @ts-check
-// TODO [eslint@>9.5]: Use `.ts` extension to get more type checking for this file.
-// TODO [engine:node@>=18]: Upgrade `tseslint`.
-// TODO [engine:node@>=18]: Use `eslint-define-config` to get type checking for this file.
-// TODO [engine:node@>=18]: Use `eslint-plugin-jsdoc` to get JSDoc linting.
+// TODO(@lishaduck) [eslint@>9.5]: Use `.ts` extension to get more type checking for this file.
+// TODO(@lishaduck) [engine:node@>=18]: Upgrade `tseslint`.
+// TODO(@lishaduck) [engine:node@>=18]: Use `eslint-define-config` to get type checking for this file.
+// TODO(@lishaduck) [engine:node@>=18]: Use `eslint-plugin-jsdoc` to get JSDoc linting.
 
 module.exports = {
   root: true,
@@ -18,10 +18,19 @@ module.exports = {
     'plugin:@typescript-eslint/stylistic-type-checked',
     'prettier'
   ],
-  plugins: ['n', 'security', 'promise', 'unicorn', '@typescript-eslint'],
+  plugins: [
+    'n',
+    'todo-plz',
+    'security',
+    'promise',
+    'unicorn',
+    '@typescript-eslint'
+  ],
   parser: '@typescript-eslint/parser',
   parserOptions: {
-    EXPERIMENTAL_useProjectService: true
+    // A stable, but experimental, option to speed up linting.
+    // It's also more feature complete, as it relies on the TypeScript Language Service.
+    EXPERIMENTAL_useProjectService: true // TODO(@lishaduck) [typescript-eslint@>=8]: Rename to `projectService`.
   },
   env: {
     node: true
@@ -59,52 +68,59 @@ module.exports = {
     'unicorn/no-array-reduce': 'off',
     'unicorn/prefer-module': 'off',
     'unicorn/prefer-node-protocol': 'error',
-    'unicorn/expiring-todo-comments': 'warn',
     '@typescript-eslint/no-var-requires': 'off',
     '@typescript-eslint/no-empty-function': 'off',
     '@typescript-eslint/no-unused-vars': ['error', {argsIgnorePattern: '^_'}],
     '@typescript-eslint/switch-exhaustiveness-check': 'error',
     '@typescript-eslint/consistent-type-definitions': ['error', 'type'],
     'default-case': 'off',
-    'n/shebang': 'off', // TODO [eslint-plugin-n@>=17]: Turn on 'n/hashbang'. For now, `shebang` is buggy.
-    '@eslint-community/eslint-comments/require-description': 'error',
-    strict: ['error', 'global'],
-    'unicorn/import-style': [
-      'error',
+    'n/shebang': 'off', // TODO(@lishaduck) [eslint-plugin-n@>=17]: Turn on 'n/hashbang'. For now, `shebang` is buggy.
+    '@typescript-eslint/ban-ts-comment': [
+      'warn',
+      {
+        'ts-expect-error': {descriptionFormat: '^\\(TS\\d+\\): .+$'},
+        'ts-check': false
+      }
+    ],
+    'unicorn/expiring-todo-comments': 'warn',
+    'todo-plz/ticket-ref': [
+      'warn',
+      // Emulate `ban-untagged-todo` from deno_lint.
       {
-        styles: {
-          chalk: {
-            named: true
-          }
-        }
+        commentPattern: String.raw`(TODO|FIXME)\(@[a-zA-Z0-9_-]+\)( \[.+\])?:`,
+        terms: ['TODO', 'FIXME'],
+        description: 'For example: `TODO(@username): Make this awesomer.``'
       }
     ],
+    '@eslint-community/eslint-comments/require-description': 'error',
+    strict: ['error', 'global'],
+    'unicorn/import-style': ['off'], // TODO(@lishaduck): Re-enable this once we use ESM.
     'unicorn/no-null': 'off',
     'unicorn/prevent-abbreviations': 'off',
-    'no-fallthrough': 'off', // TS checks for this, and TSESLint doesn't provide an alternative.
+    'no-fallthrough': 'off', // TSESLint doesn't provide an alternative, and TS checks for this anyway.
 
-    // TODO: Once there are no more `any`s, start enforcing these rules.
+    // TODO(@lishaduck): Once there are no more `any`s, start enforcing these rules.
     '@typescript-eslint/no-unsafe-assignment': 'off',
     '@typescript-eslint/no-unsafe-argument': 'off',
     '@typescript-eslint/no-unsafe-member-access': 'off',
     '@typescript-eslint/no-unsafe-call': 'off',
     '@typescript-eslint/no-unsafe-return': 'off',
 
-    // TODO: Enable stricter promise rules.
+    // TODO(@lishaduck): Enable stricter promise rules.
     '@typescript-eslint/no-misused-promises': 'off',
     '@typescript-eslint/no-floating-promises': 'off',
     'promise/catch-or-return': 'off',
     'promise/always-return': 'off',
 
-    // TODO: Security issues that should eventually get fixed.
+    // TODO(@lishaduck): Security issues that should eventually get fixed.
     'security/detect-object-injection': 'off',
     'security/detect-non-literal-fs-filename': 'off',
     'security/detect-non-literal-require': 'off',
-    'security/detect-unsafe-regex': 'off', // TODO: Add `eslint-plugin-regexp` and fix these issues.
+    'security/detect-unsafe-regex': 'off', // TODO(@lishaduck): Add `eslint-plugin-regexp` and fix these issues.
 
-    // TODO: Enable rules that require newer versions of Node.js when we bump the minimum version.
-    'unicorn/prefer-string-replace-all': 'off', // TODO [engine:node@>=15]: Enable this rule.
-    'unicorn/prefer-at': 'off' // TODO [engine:node@>=16.6]: Enable this rule.
+    // TODO(@lishaduck): Enable rules that require newer versions of Node.js when we bump the minimum version.
+    'unicorn/prefer-string-replace-all': 'off', // TODO(@lishaduck) [engine:node@>=15]: Enable this rule.
+    'unicorn/prefer-at': 'off' // TODO(@lishaduck) [engine:node@>=16.6]: Enable this rule.
   },
   overrides: [
     {
@@ -113,7 +129,7 @@ module.exports = {
         'n/no-process-exit': 'off',
         'n/no-missing-require': 'off',
         '@typescript-eslint/ban-ts-comment': 'off',
-        '@typescript-eslint/unbound-method': 'off' // TODO: Fix this warning. @lishaduck just got confused.
+        '@typescript-eslint/unbound-method': 'off' // TODO(@lishaduck): Fix this warning. I just got confused.
       }
     },
     {

bin/elm-review

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
 
-// TODO: With ESM, this should use TLA.
-
+// TODO(@lishaduck): With ESM, this should use TLA.
 require('../lib/main')();

lib/app-wrapper.js

@@ -84,7 +84,7 @@ function initWithWorker(elmModulePath, flags) {
   );
 
   return {
-    // @ts-expect-error - This is a `Worker`, which doesn't conform to the `App` interface.
+    // @ts-expect-error(TS2740): This is a `Worker`, which doesn't conform to the `App` interface.
     ports: new Proxy(worker, elmPortsInterfaceProxy)
   };
 }
@@ -108,7 +108,7 @@ function send(port) {
 function subscribe(port) {
   // eslint-disable-next-line promise/prefer-await-to-callbacks -- Callbacks are still needed here.
   return (callback) => {
-    // @ts-expect-error - TS dislikes casting `T` to `unknown` for some reason.
+    // @ts-expect-error(TS2345): TS dislikes casting `T` to `unknown` for some reason.
     listeners[port].push(callback);
   };
 }

lib/autofix.js

@@ -106,7 +106,7 @@ function askConfirmationToFixWithOptions(options, app, elmVersion) {
         filesToFix.map((file) => {
           const filePath = path.resolve(basePath, file.path);
           if (filePath.endsWith('.elm')) {
-            // TODO Make this async
+            // TODO(@jfmengels): Make this asynchronous.
             return formatFileContent(options, file, filePath);
           }
 
@@ -120,8 +120,8 @@ function askConfirmationToFixWithOptions(options, app, elmVersion) {
 
       let dependencies;
       if (modifiedElmJson) {
-        // TODO Check if source-directories have changed, and if so, load/unload the necessary files.
-        // TODO Check if dependencies have changed before we do this
+        // TODO(@jfmengels): Check if source-directories have changed, and if so, load/unload the necessary files.
+        // TODO(@jfmengels): Check if dependencies have changed before we do this.
         dependencies = await ProjectDependencies.collect(
           options,
           JSON.parse(modifiedElmJson.source),

lib/build.js

@@ -418,7 +418,7 @@ function compileElmProject(
         console.log(
           ErrorMessage.report(
             options,
-            // @ts-expect-error - `wrap-ansi` is funky.
+            // @ts-expect-error(TS2349): `wrap-ansi` is funky.
             new ErrorMessage.CustomError(title, wrap(message, 80) + '\n\n')
           )
         );
@@ -471,7 +471,7 @@ function compilationError(options, stderr) {
       console.log(stderr);
     }
 
-    // TODO Handle this better
+    // TODO(@jfmengels): Handle this better.
 
     exit(1);
   }
@@ -560,7 +560,7 @@ async function buildElmParser(options, reviewElmJson) {
     ),
     // Needed when the user has `"type": "module"` in their package.json.
     // Our output is CommonJS.
-    // TODO: Switch to a .cjs file instead.
+    // TODO(@lishaduck): Switch to a .cjs file instead.
     FS.mkdirp(options.generatedCodePackageJson()).then(() =>
       FS.writeFile(
         path.join(options.generatedCodePackageJson(), 'package.json'),

lib/elm-binary.js

@@ -57,7 +57,7 @@ A few options:
  */
 function getElmVersion(elmBinary) {
   const result = spawn.sync(elmBinary, ['--version'], {
-    // @ts-expect-error -- The types are outdated.
+    // @ts-expect-error(TS2769): The types are outdated.
     silent: true,
     env: process.env
   });
@@ -79,16 +79,16 @@ function getElmVersion(elmBinary) {
 function downloadDependenciesOfElmJson(elmBinary, elmJsonPath) {
   const result = spawn.sync(elmBinary, ['make', '--report=json'], {
     cwd: path.dirname(elmJsonPath),
-    // @ts-expect-error -- The types are outdated.
+    // @ts-expect-error(TS2769): The types are outdated.
     silent: false,
     env: process.env
   });
 
   if (result.status !== 0) {
     const error = JSON.parse(result.stderr.toString());
-    // TODO Check for other kinds of errors
+    // TODO(@jfmengels): Check for other kinds of errors.
     if (error.title !== 'NO INPUT') {
-      // TODO Print error nicely
+      // TODO(@jfmengels): Print the error nicely.
       throw new Error(error);
     }
   }

lib/elm-files.js

@@ -60,7 +60,7 @@ async function getProjectFiles(options, elmSyntaxVersion) {
     ({files}) => files.length === 0
   );
 
-  // TODO Have a different message depending on how directories were chosen (CLI directories, application, package)
+  // TODO(@jfmengels): Have a different message depending on how directories were chosen (CLI directories, application, package).
   if (options.directoriesToAnalyze.length > 0 && emptyDirectories.length > 0) {
     throw new ErrorMessage.CustomError(
       'NO FILES FOUND',

lib/error-message.js

@@ -105,8 +105,7 @@ function formatJson(debug, error, defaultPath) {
     type: 'error',
     title: error.title,
     path: error.path ?? defaultPath,
-    // TODO We currently strip the colors, but it would be nice to keep them
-    // so that editors can have nicer error messages
+    // TODO(@jfmengels): We currently strip the colors, but it would be nice to keep them so that editors can have nicer error messages.
     message: [stripAnsi(error.message.trim())],
     stack: debug && error.stack ? stripAnsi(error.stack) : undefined
   };

lib/init.js

@@ -1,6 +1,6 @@
 const fs = require('graceful-fs');
 const path = require('node:path');
-// TODO [engine:node@>=16.7.0]: Use native `cp`.
+// TODO(@lishaduck) [engine:node@>=16.7.0]: Use native `cp`.
 const fsExtra = require('fs-extra');
 const chalk = require('chalk');
 const prompts = require('prompts');

lib/module-cache.js

@@ -15,7 +15,7 @@ const Cache = require('./cache');
  */
 function subscribe(options, app) {
   AppState.subscribe(app.ports.cacheFile, ({source, ast}) =>
-    // TODO Do this in a thread
+    // TODO(@jfmengels): Do this work in a thread.
     cacheFile(options, Hash.hash(source), ast)
   );
 }

lib/new-package.js

@@ -2,7 +2,7 @@ const path = require('node:path');
 const childProcess = require('node:child_process');
 const chalk = require('chalk');
 const prompts = require('prompts');
-// TODO [engine:node@>=16.7.0]: Use native `cp`.
+// TODO(@lishaduck) [engine:node@>=16.7.0]: Use native `cp`.
 const fsExtra = require('fs-extra');
 const Init = require('./init');
 const Spinner = require('./spinner');

lib/options.js

@@ -596,7 +596,7 @@ ${Flags.buildFlag(subcommand, Flags.reportFlag)}`
     reportErrorAndExit(
       new ErrorMessage.CustomError(
         'COMMAND REQUIRES NETWORK ACCESS',
-        // @ts-expect-error - `wrap-ansi` is funky.
+        // @ts-expect-error(TS2349): `wrap-ansi` is funky.
         wrap(
           `I can't use ${chalk.cyan('--template')} in ${chalk.cyan(
             'offline'
@@ -619,7 +619,7 @@ Otherwise, I recommend you try to gain network access and initialize your config
     reportErrorAndExit(
       new ErrorMessage.CustomError(
         'COMMAND REQUIRES NETWORK ACCESS',
-        // @ts-expect-error - `wrap-ansi` is funky.
+        // @ts-expect-error(TS2349): `wrap-ansi` is funky.
         wrap(
           `I can't use ${chalk.yellow('new-package')} in ${chalk.cyan(
             'offline'
@@ -666,7 +666,7 @@ ${Flags.buildFlag(subcommand, Flags.gitHubAuthFlag)}`
  * @returns {never}
  */
 function reportErrorAndExit(errorToReport) {
-  // @ts-expect-error - Handle this later
+  // @ts-expect-error(TS2345): Handle this later
   console.log(ErrorMessage.report({}, errorToReport));
 
   exit(1);

lib/parse-elm-worker.js

@@ -45,7 +45,7 @@ function workerParseElm({source, elmParserPath}) {
   return promisifyPort({
     subscribeTo: app.ports.parseResult,
     sendThrough: app.ports.requestParsing,
-    // @ts-expect-error - TS wants an `ElmJson`, but we're giving a string.
+    // @ts-expect-error(TS2322): TS wants an `ElmJson`, but we're giving a string.
     data: source
   });
 }

lib/project-json-files.js

@@ -60,8 +60,8 @@ async function getElmJson(options, elmVersion, name, packageVersion) {
   }
 }
 
-// TODO Empty this cache at some point?
-// Note that we might need it in watch and fix mode, but not otherwise.
+// TODO(@jfmengels): Empty this cache at some point?
+//   Note that we might need it in watch and fix mode, but not otherwise.
 /** @type {Map<string, Promise<PackageElmJson>>} */
 const elmJsonInElmHomePromises = new Map();
 
@@ -176,7 +176,7 @@ async function readFromPackagesWebsite(
   packageVersion,
   file
 ) {
-  // TODO [engine:node@>=18]: We can use `fetch` now.
+  // TODO(@lishaduck) [engine:node@>=21]: We can use `fetch` now.
   const response = await got(
     `https://package.elm-lang.org/packages/${packageName}/${packageVersion}/${file}`
   );

lib/remote-template.js

@@ -103,7 +103,7 @@ async function downloadTemplateElmJson(template, commit) {
   const {repoName, pathToFolder} = template;
   const pathToFolderAsUrl = pathToFolder ? `/${pathToFolder}` : '';
 
-  // TODO [engine:node@>=18]: We can use `fetch` now.
+  // TODO(@lishaduck) [engine:node@>=21]: We can use `fetch` now.
   const response = await got(
     `https://raw.githubusercontent.com/${repoName}/${commit}${pathToFolderAsUrl}/elm.json`
   ).catch((error) => {
@@ -270,7 +270,7 @@ async function makeGitHubApiRequest(options, url, handleNotFound) {
 
   Debug.log(`Making API request to GitHub: ${url}`);
   try {
-    // TODO [engine:node@>=18]: We can use `fetch` now.
+    // TODO(@lishaduck) [engine:node@>=21]: We can use `fetch` now.
     const response = await got(url, parameters);
 
     return response.body;

lib/result-cache-json.js

@@ -17,7 +17,7 @@ function replacer(_key, value_) {
   }
 
   if (typeof value === 'object') {
-    // TODO Serialize Dicts also
+    // TODO(@jfmengels): Also support serializing `Dict`s.
     // if (value.$ === -1) {
     //   return {
     //     $: '$D',

lib/result-cache.js

@@ -18,8 +18,9 @@ let worker = null;
 const resultCache = new Map();
 const promisesToResolve = new Map();
 
-// TODO Create an alternate version of Options used in elm-app-worker.
-// Depending on whether this is running in a worker or not, the options will be slightly different.
+// TODO(@jfmengels): Create an alternate version of Options used in
+//   `elm-app-worker`. Depending on whether this is running in a worker or not,
+//   the options will be slightly different.
 /**
  * Load cache results.
  *
@@ -30,7 +31,7 @@ const promisesToResolve = new Map();
  * @returns {Promise<void>}
  */
 async function load(options, ignoredDirs, ignoredFiles, cacheFolder) {
-  // TODO Make caching work for all of these
+  // TODO(@jfmengels): Make caching work for all of these combinations.
   if (
     options.debug ||
     options.directoriesToAnalyze.length > 0 ||

lib/runner.js

@@ -146,8 +146,12 @@ async function initializeApp(options, elmModulePath, reviewElmJson, appHash) {
     }
   );
   const extraFilesP = requestedExtraFilesP.then(ExtraFiles.collect);
-  // @ts-expect-error - `r` isn't assigned yet. Seems legit.
-  AppState.subscribe(app.ports.requestReadingFiles, r);
+  AppState.subscribe(
+    // @ts-expect-error(TS2345): Type 'string' is not assignable to type 'ExtraFileRequest'.
+    app.ports.requestReadingFiles,
+    // @ts-expect-error(TS2454): `r` isn't assigned yet. Seems legit.
+    r
+  );
 
   ModuleCache.subscribe(options, app);
   Autofix.subscribe(options, app, reviewElmJson['elm-version']);
@@ -180,7 +184,7 @@ async function initializeApp(options, elmModulePath, reviewElmJson, appHash) {
   );
 
   const {elmJsonData, elmFiles, sourceDirectories, readme} =
-    // @ts-expect-error - Options is `Options`, not `ReviewOptions`.
+    // @ts-expect-error(TS2345): Options is `Options`, not `ReviewOptions`.
     await getProjectFiles(options, elmSyntaxVersion);
   const projectDepsP = ProjectDependencies.collect(
     options,