Bump to v1.0.5, strict type checks, generate types

Though a lot of changes, each one is relatively small, they're all
thematically related, and all tests still pass.

Note a lot of these descriptions also come from
mbland/test-page-opener#23 or commit
mbland/test-page-opener@01a79f6.

- Added `settings.jsdoc.preferredTypes.Object = "object"` to .eslintrc
  to enable "Object.<..., ...>" syntax in a JSDoc `@typedef`. Got rid of
  some extra whitespaces in .eslintrc, too.
  - https://github.com/gajus/eslint-plugin-jsdoc/blob/b60cbb027b03b4f6d509933b0dca8681dbe47206/docs/rules/check-types.md#why-not-capital-case-everything
  - https://github.com/gajus/eslint-plugin-jsdoc/blob/b60cbb027b03b4f6d509933b0dca8681dbe47206/docs/settings.md#settings-to-configure-check-types-and-no-undefined-types

- Updated jsconfig.json to specify:
  ```json
  "lib": [
    "ES2022"
  ],
  "module": "node16",
  "target": "es2020",
  "strict": true,
  "exclude": [
    "node_modules/**",
    "coverage*/**",
    "jsdoc/**"
  ]
  ```
  The "lib", "modules", and "target" lines are to ensure compatibility
  with Node v18, and there's no more disabling `strictNullChecks` and
  `noImplicitAny` after `"strict": true`. Most of the changes in this
  commit are a result of removing those two options.

- Added @types/{chai,node} to devDependencies and added a `pnpm
  typecheck` command. Now the whole project and its dependencies pass
  strict type checking.

- Updated everything under test/ to be strictly TypeScript compliant.

- Updated `pnpm test:ci` to incorporate `pnpm jsdoc` and `pnpm
  typecheck`. Added 'jsdoc' to devDependencies to enable this.

- Added a `pnpm prepack` script to generate types and a package.json
  `"types"` entry.

- Updated all local import paths to add '.js' or 'index.js' and added
  JSDoc comments everywhere reqired by `pnpm typecheck`.

- Added null checks and corresponding tests everywhere reqired by `pnpm
  typecheck`.

Author: mbland

.eslintrc

@@ -1,7 +1,7 @@
 {
-  "env" : {
+  "env": {
     "node": true,
-    "es2023" : true
+    "es2023": true
   },
   "parserOptions": {
     "ecmaVersion": "latest",
@@ -25,7 +25,7 @@
       ]
     }
   ],
-  "rules" : {
+  "rules": {
     "@stylistic/js/comma-dangle": [
       "error", "never"
     ],
@@ -50,5 +50,12 @@
     "no-console": [
       "error", { "allow": [ "warn", "error" ]}
     ]
+  },
+  "settings": {
+    "jsdoc": {
+      "preferredTypes": {
+        "Object": "object"
+      }
+    }
   }
 }

.gitignore

@@ -10,4 +10,6 @@ node_modules/
 out/
 pnpm-debug.log
 tmp/
+types/
 *.log
+*.tgz

README.md

@@ -55,7 +55,7 @@ Running the wrapper will generate the local `file://` URL to the generated
 `index.html` file, e.g.:
 
 ```text
-file:///path/to/jsdoc/output/jsdoc-cli-wrapper/1.0.4/index.html
+file:///path/to/jsdoc/output/jsdoc-cli-wrapper/1.0.5/index.html
 ```
 
 You can click on or copy this link to open it in your browser. You can also open
@@ -99,10 +99,10 @@ This wrapper resolves both of these minor annoyances.
 ```sh
 $ pnpm jsdoc
 
-> [email protected].4 jsdoc /path/to/jsdoc-cli-wrapper
+> [email protected].5 jsdoc /path/to/jsdoc-cli-wrapper
 > node index.js -c jsdoc.json .
 
-file:///path/to/jsdoc-cli-wrapper/jsdoc/jsdoc-cli-wrapper/1.0.4/index.html
+file:///path/to/jsdoc-cli-wrapper/jsdoc/jsdoc-cli-wrapper/1.0.5/index.html
 ```
 
 Of course, your own project would use `jsdoc-cli-wrapper` instead of `node

ci/vitest.config.js

@@ -1,3 +1,4 @@
+// @ts-nocheck
 import { defineConfig, mergeConfig } from 'vitest/config'
 import baseConfig from '../vitest.config'
 

jsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "checkJs": true,
+    "lib": [
+      "ES2022"
+    ],
+    "module": "node16",
+    "target": "es2020",
+    "strict": true
+  },
+  "exclude": [
+    "node_modules/**",
+    "coverage/**",
+    "jsdoc/**"
+  ]
+}

lib/index.js

@@ -8,30 +8,32 @@ import { spawn } from 'node:child_process'
 import { access, readdir, readFile, rm } from 'node:fs/promises'
 import path from 'node:path'
 
+export const INSTALL_HINT = 'Run \'pnpm add [-g|-D] jsdoc\' ' +
+  'to install JSDoc: https://jsdoc.app'
+
 /**
  * Result of the `jsdoc` execution
  * @typedef {object} RunJsdocResults
  * @property {number} exitCode - 0 on success, nonzero on failure
- * @property {string} indexHtml - path to the generated index.html file
+ * @property {string} [indexHtml] - path to the generated index.html file
  */
 
 /**
  * Removes the existing JSDoc directory, runs `jsdoc`, and emits the result path
  * @param {string[]} argv - JSDoc command line interface arguments
- * @param {object} env - environment variables, presumably process.env
+ * @param {EnvVars} env - environment variables, presumably process.env
  * @param {string} platform - the process.platform string
  * @returns {Promise<RunJsdocResults>} result of `jsdoc` execution
  * @throws if `jsdoc` isn't found or can't execute
  */
 export async function runJsdoc(argv, env, platform) {
+  /** @type {string} */
   let jsdocPath
 
   try {
     jsdocPath = await getPath('jsdoc', env, platform)
-  } catch {
-    return Promise.reject(
-      'Run \'pnpm add -g jsdoc\' to install JSDoc: https://jsdoc.app'
-    )
+  } catch (err) {
+    return Promise.reject(err instanceof Error ? err : INSTALL_HINT)
   }
 
   const {destination, willGenerate} = await analyzeArgv(argv)
@@ -62,22 +64,26 @@ export async function runJsdoc(argv, env, platform) {
  */
 export const pathKey = platform => platform !== 'win32' ? 'PATH' : 'Path'
 
+/** @typedef {Object<string,string|undefined>} EnvVars */
+
 /**
  * Returns the full path to the specified command
  * @param {string} cmdName - command to find in env[pathKey(platform)]
- * @param {object} env - environment variables, presumably process.env
+ * @param {EnvVars} env - environment variables, presumably process.env
  * @param {string} platform - the process.platform string
  * @returns {Promise<string>} path to the command
  * @throws if `jsdoc` isn't found
  */
 export async function getPath(cmdName, env, platform) {
   const pk = pathKey(platform)
+  const pathVar = env[pk]
+  if (!pathVar) throw new Error(`"${pk}" environment variable not defined`)
 
   // pnpm will install both the original script and versions ending with .CMD
   // and .ps1. We'll just default to .CMD.
   if (platform === 'win32') cmdName += '.CMD'
 
-  for (const p of env[pk].split(path.delimiter)) {
+  for (const p of pathVar.split(path.delimiter)) {
     try {
       const candidate = path.join(p, cmdName)
       await access(candidate)
@@ -103,7 +109,11 @@ export async function getPath(cmdName, env, platform) {
  * @returns {Promise<ArgvResults>} analysis results
  */
 export async function analyzeArgv(argv) {
-  const validArg = nextArg => nextArg !== undefined && !nextArg.startsWith('-')
+  /**
+   * @param {(string|undefined)} nextArg - next argument after current one
+   * @returns {boolean} true if defined and not another flag, false otherwise
+   */
+  function validArg(nextArg) { return !!nextArg && !nextArg.startsWith('-') }
   let destination, cmdLineDest, willGenerate = true
 
   for (let i = 0; i !== argv.length; ++i) {
@@ -178,7 +188,8 @@ export async function analyzeArgv(argv) {
  * @returns {string} str with comments, trailing commas replaced by space
  */
 export function stripJsonComments(str) {
-  let inString, escaped, comment, comma, result = []
+  let inString = false, escaped = false, comment = null, comma = null
+  let result = []
 
   for (let i = 0; i !== str.length; ++i) {
     let c = str[i]

package.json

@@ -1,16 +1,22 @@
 {
   "name": "jsdoc-cli-wrapper",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "JSDoc command line interface wrapper",
   "main": "index.js",
   "bin": "./index.js",
+  "types": "./types/index.d.ts",
   "scripts": {
     "lint": "eslint --color --max-warnings 0 .",
     "test": "vitest",
-    "test:ci": "eslint --color --max-warnings 0 . && vitest run -c ci/vitest.config.js",
-    "jsdoc": "node index.js -c jsdoc.json ."
+    "test:ci": "pnpm lint && pnpm typecheck && vitest run -c ci/vitest.config.js && pnpm jsdoc",
+    "typecheck": "npx -p typescript tsc -p jsconfig.json --noEmit --pretty",
+    "jsdoc": "node index.js -c jsdoc.json .",
+    "prepack": "npx -p typescript tsc ./index.js --allowJs --declaration --declarationMap --emitDeclarationOnly --outDir types"
   },
-  "files": [ "lib/**" ],
+  "files": [
+    "lib/**",
+    "types/**"
+  ],
   "keywords": [
     "jsdoc",
     "JavaScript"
@@ -25,13 +31,17 @@
   "repository": "https://github.com/mbland/jsdoc-cli-wrapper",
   "bugs": "https://github.com/mbland/jsdoc-cli-wrapper/issues",
   "devDependencies": {
-    "@stylistic/eslint-plugin-js": "^1.5.1",
-    "@vitest/coverage-istanbul": "^1.1.0",
-    "@vitest/coverage-v8": "^1.1.0",
-    "@vitest/ui": "^1.1.0",
+    "@stylistic/eslint-plugin-js": "^1.5.3",
+    "@types/chai": "^4.3.11",
+    "@types/node": "^20.10.7",
+    "@vitest/coverage-istanbul": "^1.1.3",
+    "@vitest/coverage-v8": "^1.1.3",
+    "@vitest/ui": "^1.1.3",
     "eslint": "^8.56.0",
-    "eslint-plugin-jsdoc": "^46.9.1",
+    "eslint-plugin-jsdoc": "^46.10.1",
     "eslint-plugin-vitest": "^0.3.20",
-    "vitest": "^1.1.0"
+    "jsdoc": "^4.0.2",
+    "typescript": "^5.3.3",
+    "vitest": "^1.1.3"
   }
 }