Merge branch 'develop' into feature/node-repl

.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,
+        },
+      ],
+    },
+  },
+];

esm.mjs

@@ -12,5 +12,5 @@ export const {
   Command,
   Argument,
   Option,
-  Help
+  Help,
 } = commander;

examples/action-this.js

@@ -2,15 +2,14 @@
 
 // This example is used as an example in the README for the action handler.
 
-// const { Command } = require('commander'); // (normal include)
-const { Command } = require('../'); // include commander in git clone of commander repo
+const { Command } = require('commander');
 const program = new Command();
 
 program
   .command('serve')
   .argument('<script>')
   .option('-p, --port <number>', 'port number', 80)
-  .action(function() {
+  .action(function () {
     console.error('Run script %s on port %s', this.args[0], this.opts().port);
   });
 

examples/alias.js

@@ -2,8 +2,7 @@
 
 // This example shows giving alternative names for a command.
 
-// const { Command } = require('commander'); // (normal include)
-const { Command } = require('../'); // include commander in git clone of commander repo
+const { Command } = require('commander');
 const program = new Command();
 
 program

examples/argument.js

@@ -2,8 +2,7 @@
 
 // This example shows specifying the command arguments using argument() function.
 
-// const { Command } = require('commander'); // (normal include)
-const { Command } = require('../'); // include commander in git clone of commander repo
+const { Command } = require('commander');
 const program = new Command();
 
 program

examples/arguments-custom-processing.js

@@ -4,11 +4,10 @@
 //    Custom argument processing
 //    You may specify a function to do custom processing of argument values.
 
-// const commander = require('commander'); // (normal include)
-const commander = require('../'); // include commander in git clone of commander repo
+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/arguments-extra.js

@@ -2,13 +2,23 @@
 
 // This is used as an example in the README for extra argument features.
 
-// const commander = require('commander'); // (normal include)
-const commander = require('../'); // include commander in git clone of commander repo
+const commander = require('commander');
 const program = new commander.Command();
 
 program
-  .addArgument(new commander.Argument('<drink-size>', 'drink cup size').choices(['small', 'medium', 'large']))
-  .addArgument(new commander.Argument('[timeout]', 'timeout in seconds').default(60, 'one minute'))
+  .addArgument(
+    new commander.Argument('<drink-size>', 'drink cup size').choices([
+      'small',
+      'medium',
+      'large',
+    ]),
+  )
+  .addArgument(
+    new commander.Argument('[timeout]', 'timeout in seconds').default(
+      60,
+      'one minute',
+    ),
+  )
   .action((drinkSize, timeout) => {
     console.log(`Drink size: ${drinkSize}`);
     console.log(`Timeout (s): ${timeout}`);

examples/configure-help.js

@@ -1,6 +1,4 @@
-// const commander = require('commander'); // (normal include)
-const commander = require('../'); // include commander in git clone of commander repo
-
+const commander = require('commander');
 const program = new commander.Command();
 
 // This example shows a simple use of configureHelp.
@@ -10,11 +8,17 @@ const program = new commander.Command();
 
 program.configureHelp({
   sortSubcommands: true,
-  subcommandTerm: (cmd) => cmd.name() // Just show the name, instead of short usage.
+  subcommandTerm: (cmd) => cmd.name(), // Just show the name, instead of short usage.
 });
 
-program.command('zebra <herd-size>', 'African equines with distinctive black-and-white striped coats');
-program.command('aardvark [colour]', 'medium-sized, burrowing, nocturnal mammal');
+program.command(
+  'zebra <herd-size>',
+  'African equines with distinctive black-and-white striped coats',
+);
+program.command(
+  'aardvark [colour]',
+  'medium-sized, burrowing, nocturnal mammal',
+);
 program
   .command('beaver', 'large, semiaquatic rodent')
   .option('--pond')

examples/configure-output.js

@@ -1,26 +1,20 @@
-// const commander = require('commander'); // (normal include)
-const commander = require('../'); // include commander in git clone of commander repo
-
+const commander = require('commander');
 const program = new commander.Command();
 
 function errorColor(str) {
   // Add ANSI escape codes to display text in red.
   return `\x1b[31m${str}\x1b[0m`;
 }
 
-program
-  .configureOutput({
-    // Visibly override write routines as example!
-    writeOut: (str) => process.stdout.write(`[OUT] ${str}`),
-    writeErr: (str) => process.stdout.write(`[ERR] ${str}`),
-    // Output errors in red.
-    outputError: (str, write) => write(errorColor(str))
-  });
+program.configureOutput({
+  // Visibly override write routines as example!
+  writeOut: (str) => process.stdout.write(`[OUT] ${str}`),
+  writeErr: (str) => process.stdout.write(`[ERR] ${str}`),
+  // Output errors in red.
+  outputError: (str, write) => write(errorColor(str)),
+});
 
-program
-  .version('1.2.3')
-  .option('-c, --compress')
-  .command('sub-command');
+program.version('1.2.3').option('-c, --compress').command('sub-command');
 
 program.parse();
 

examples/custom-command-class.js

@@ -1,7 +1,5 @@
 #!/usr/bin/env node
-
-// const commander = require('commander'); // (normal include)
-const commander = require('../'); // include commander in git clone of commander repo
+const commander = require('commander');
 
 // Use a class override to customise the command and its subcommands.
 
@@ -12,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')
@@ -34,11 +32,9 @@ program
     inpectCommand(command);
   });
 
-program
-  .command('build <target>')
-  .action((buildTarget, options, command) => {
-    inpectCommand(command);
-  });
+program.command('build <target>').action((buildTarget, options, command) => {
+  inpectCommand(command);
+});
 
 program.parse();