ESLint changes preparing for Prettier (#2153)

Switch from StandardJS to ESLint using flat configuration.
Add Prettier and configuration.

.github/PULL_REQUEST_TEMPLATE.md

@@ -6,9 +6,9 @@ and can be deleted.
 
 Please submit pull requests against the develop branch.
 
-Follow the existing code style. Check the tests succeed, including lint.
+Follow the existing code style. Check the tests succeed, including format and lint.
   npm run test
-  npm run lint
+  npm run check
 
 Don't update the CHANGELOG or command version number. That gets done by maintainers when preparing the release.
 

.github/workflows/tests.yml

@@ -27,5 +27,6 @@ jobs:
       run: npm ci
     - name: npm test
       run: npm test
-    - name: npm run lint
-      run: npm run lint
+    - name: npm run check:lint
+      # switch to full check when have run prettier on all files
+      run: npm run check:lint

.prettierignore

@@ -0,0 +1,10 @@
+# exclude everything, and opt-in to types we want to format
+**.*
+# add the filetypes we want to format
+!**.js
+!**.mjs
+!**.cjs
+!**.ts
+!**.mts
+!**.cts
+!**.json

.prettierrc.js

@@ -0,0 +1,12 @@
+const config = {
+  // plugins: ['prettier-plugin-jsdoc'],
+  singleQuote: true,
+  overrides: [
+    {
+      files: ['tsconfig*.json'],
+      options: { parser: 'jsonc' },
+    },
+  ],
+};
+
+module.exports = config;

CONTRIBUTING.md

@@ -14,10 +14,10 @@ or after six months otherwise.
 
 Pull Requests will be considered. Please submit pull requests against the develop branch.
 
-Follow the existing code style. Check the tests succeed, including lint.
+Follow the existing code style. Check the tests succeed, including format and lint.
 
 - `npm run test`
-- `npm run lint`
+- `npm run check`
 
 Don't update the CHANGELOG or command version number. That gets done by maintainers when preparing the release.
 

eslint.config.js

@@ -0,0 +1,75 @@
+const globals = require('globals');
+const esLintjs = require('@eslint/js');
+const jest = require('eslint-plugin-jest');
+const tseslint = require('typescript-eslint');
+const prettier = require('eslint-config-prettier');
+//const jsdoc = require('eslint-plugin-jsdoc');
+
+// Using tseslint config helper to customise its setup the tseslint way.
+const tsconfigTsFiles = ['**/*.{ts,mts}']; // match "include" in tsconfig.ts.json;
+const tsconfigJsFiles = ['*.{js,mjs}', 'lib/**/*.{js,mjs}']; // match "include" in tsconfig.js.json
+const tseslintConfigs = tseslint.config(
+  {
+    files: tsconfigJsFiles,
+    languageOptions: {
+      parserOptions: { project: './tsconfig.js.json' },
+    },
+    extends: [
+      ...tseslint.configs.recommended,
+    ],
+    rules: {
+      '@typescript-eslint/no-var-requires': 'off', // (tseslint does not autodetect commonjs context )
+    },
+  }, {
+    files: tsconfigTsFiles,
+    languageOptions: {
+      parserOptions: { project: './tsconfig.ts.json' },
+    },
+    extends: [
+      ...tseslint.configs.recommended,
+    ],
+  },
+);
+
+module.exports = [
+  esLintjs.configs.recommended,
+  // jsdoc.configs['flat/recommended'],
+  jest.configs['flat/recommended'],
+  ...tseslintConfigs,
+  prettier, // Do Prettier last so it can override previous configs.
+
+  // Customise rules.
+  {
+    files: ['**/*.{js,mjs,cjs}', '**/*.{ts,mts,cts}'],
+    rules: {
+      'no-else-return': ['error', { allowElseIf: false }],
+
+      // 'jsdoc/tag-lines': 'off',
+      // 'jsdoc/require-jsdoc': 'off',
+      // 'jsdoc/require-param-description': 'off',
+      // 'jsdoc/require-returns-description': 'off',
+    },
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+    },
+  },
+  {
+    files: ['**/*.test.{js,mjs,cjs}'],
+    rules: {
+      'no-unused-vars': 'off', // lots in tests, minimise churn for now
+    }
+  },
+  {
+    files: [...tsconfigTsFiles, ...tsconfigJsFiles],
+    rules: {
+      '@typescript-eslint/ban-ts-comment': ['error', {
+        'ts-expect-error': 'allow-with-description',
+        'ts-ignore': 'allow-with-description',
+        'ts-nocheck': true,
+        'ts-check': true,
+    }],
+    },
+  },
+];

examples/arguments-custom-processing.js

@@ -7,7 +7,7 @@
 const commander = require('commander');
 const program = new commander.Command();
 
-function myParseInt(value, dummyPrevious) {
+function myParseInt(value) {
   // parseInt takes a string and a radix
   const parsedValue = parseInt(value, 10);
   if (isNaN(parsedValue)) {

examples/custom-command-class.js

@@ -10,14 +10,14 @@ class CommandWithTrace extends commander.Command {
     cmd.option('-t, --trace', 'display extra information when run command');
     return cmd;
   }
-};
+}
 
 function inpectCommand(command) {
   // The option value is stored as property on command because we called .storeOptionsAsProperties()
   console.log(`Called '${command.name()}'`);
   console.log(`args: ${command.args}`);
   console.log('opts: %o', command.opts());
-};
+}
 
 const program = new CommandWithTrace('program')
   .option('-v, ---verbose')

examples/options-custom-processing.js

@@ -7,7 +7,7 @@
 const commander = require('commander');
 const program = new commander.Command();
 
-function myParseInt(value, dummyPrevious) {
+function myParseInt(value) {
   // parseInt takes a string and a radix
   const parsedValue = parseInt(value, 10);
   if (isNaN(parsedValue)) {
@@ -24,7 +24,7 @@ function collect(value, previous) {
   return previous.concat([value]);
 }
 
-function commaSeparatedList(value, dummyPrevious) {
+function commaSeparatedList(value) {
   return value.split(',');
 }
 

lib/command.js

@@ -105,6 +105,7 @@ class Command extends EventEmitter {
 
   _getCommandAndAncestors() {
     const result = [];
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
     for (let command = this; command; command = command.parent) {
       result.push(command);
     }
@@ -361,6 +362,7 @@ class Command extends EventEmitter {
   /**
    * Customise or override default help command. By default a help command is automatically added if your command has subcommands.
    *
+   * @example
    *    program.helpCommand('help [cmd]');
    *    program.helpCommand('help [cmd]', 'show help');
    *    program.helpCommand(false); // suppress default help command
@@ -929,7 +931,6 @@ Expecting one of '${allowedValues.join("', '")}'`);
     // Default to using process.argv
     if (argv === undefined) {
       argv = process.argv;
-      // @ts-ignore: unknown property
       if (process.versions && process.versions.electron) {
         parseOptions.from = 'electron';
       }
@@ -945,7 +946,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         userArgs = argv.slice(2);
         break;
       case 'electron':
-        // @ts-ignore: unknown property
+        // @ts-ignore: because defaultApp is an unknown property
         if (process.defaultApp) {
           this._scriptPath = argv[1];
           userArgs = argv.slice(2);
@@ -1097,7 +1098,6 @@ Expecting one of '${allowedValues.join("', '")}'`);
     if (!proc.killed) { // testing mainly to avoid leak warnings during unit tests with mocked spawn
       const signals = ['SIGUSR1', 'SIGUSR2', 'SIGTERM', 'SIGINT', 'SIGHUP'];
       signals.forEach((signal) => {
-        // @ts-ignore
         process.on(signal, () => {
           if (proc.killed === false && proc.exitCode === null) {
             proc.kill(signal);
@@ -1108,7 +1108,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
     // By default terminate process when spawned process terminates.
     const exitCallback = this._exitCallback;
-    proc.on('close', (code, _signal) => {
+    proc.on('close', (code) => {
       code = code ?? 1; // code is null if spawned process terminated due to a signal
       if (!exitCallback) {
         process.exit(code);
@@ -1117,7 +1117,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       }
     });
     proc.on('error', (err) => {
-      // @ts-ignore
+      // @ts-ignore: because err.code is an unknown property  
       if (err.code === 'ENOENT') {
         const executableDirMessage = executableDir
           ? `searched for local subcommand relative to directory '${executableDir}'`
@@ -1127,7 +1127,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
  - if the default executable name is not suitable, use the executableFile option to supply a custom name or path
  - ${executableDirMessage}`;
         throw new Error(executableMissing);
-      // @ts-ignore
+      // @ts-ignore: because err.code is an unknown property
       } else if (err.code === 'EACCES') {
         throw new Error(`'${executableFile}' not executable`);
       }
@@ -1818,6 +1818,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
     if (flag.startsWith('--') && this._showSuggestionAfterError) {
       // Looping to pick up the global options too
       let candidateFlags = [];
+      // eslint-disable-next-line @typescript-eslint/no-this-alias
       let command = this;
       do {
         const moreFlags = command.createHelp().visibleOptions(command)
@@ -1944,6 +1945,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
     if (alias === undefined) return this._aliases[0]; // just return first, for backwards compatibility
 
     /** @type {Command} */
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
     let command = this;
     if (this.commands.length !== 0 && this.commands[this.commands.length - 1]._executableHandler) {
       // assume adding alias for last added executable subcommand, rather than this

lib/help.js

@@ -32,7 +32,7 @@ class Help {
     }
     if (this.sortSubcommands) {
       visibleCommands.sort((a, b) => {
-        // @ts-ignore: overloaded return type
+        // @ts-ignore: because overloaded return type
         return a.name().localeCompare(b.name());
       });
     }
@@ -248,7 +248,7 @@ class Help {
    */
 
   commandDescription(cmd) {
-    // @ts-ignore: overloaded return type
+    // @ts-ignore: because overloaded return type
     return cmd.description();
   }
 
@@ -261,7 +261,7 @@ class Help {
    */
 
   subcommandDescription(cmd) {
-    // @ts-ignore: overloaded return type
+    // @ts-ignore: because overloaded return type
     return cmd.summary() || cmd.description();
   }