fulmine.js 5.19.2 → 5.19.4

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.19.2",
+    "version": "5.19.4",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "exports": {
@@ -149,6 +149,7 @@
         "eslint": "^10.8.0",
         "eslint-config-prettier": "^10.1.8",
         "eslint-plugin-jsdoc": "^64.1.0",
+        "eslint-plugin-sonarjs": "^4.2.0",
         "etag": "^1.8.1",
         "eventsource": "^5.0.0",
         "exit-hook": "^5.1.0",

package/src/adopt.js

@@ -17,15 +17,14 @@ limitations under the License.
 // The two commands that edit a config file rather than source: `npx fulmine.js override` and
 // `npx fulmine.js angular`.
 //
-// `migrate` rewrites `require("express")` in your own files, which is all an application needs. The
-// two cases it cannot reach are both a line in a JSON file that nobody remembers the shape of:
+// `migrate` rewrites `require("express")` in your own files. The two cases it cannot reach are
+// both a line in a JSON file:
 //
-//   override   A framework built on Express does not require it in your code, it requires it in its
-//              own, so there is no specifier to rewrite. Every package manager can answer `express`
-//              with this package instead, for the whole tree, and each one spells it differently.
+//   override   A framework built on Express requires it in its own code, so there is no specifier
+//              to rewrite. Every package manager can answer `express` with this package instead,
+//              and each one spells it differently.
 //   angular    An Angular server bundle is built with esbuild, which inlines every dependency and
-//              cannot load µWS's native binary. Two names in `externalDependencies` fix it, and
-//              nothing in the error message it fails with says so.
+//              cannot load uWS's native binary. Two names in `externalDependencies` fix it.
 
 "use strict";
 
@@ -72,9 +71,9 @@ function indentOf(source) {
 /**
  * Reads a JSON file, or explains why it could not be read rather than throwing a parser error.
  *
- * The read is attempted rather than guarded by an existence check. Both commands go on to write the
- * file they read, and a check on a path followed by a write to the same path is the shape of a race
- * whatever the odds of losing it. `code` is what a caller names the missing file by.
+ * The read is attempted rather than guarded by an existence check: both commands write the file
+ * they read, and a check followed by a write to the same path is a race. `code` is what a caller
+ * names the missing file by.
  *
  * @param {string} file
  * @returns {{data: any, source: string}|{error: string, code: string|undefined}}
@@ -121,7 +120,7 @@ function detectManager(dir, pkg) {
 /**
  * Reads a nested key, and answers undefined rather than throwing on a missing level.
  *
- * @param {any} object
+ * @param {any} object parsed JSON, so its shape is whatever the file held
  * @param {string[]} keys
  * @returns {any}
  */
@@ -137,9 +136,9 @@ function readPath(object, keys) {
 /**
  * Writes a nested key, making the levels above it as it goes.
  *
- * @param {any} object
+ * @param {any} object parsed JSON, so its shape is whatever the file held
  * @param {string[]} keys
- * @param {any} value
+ * @param {any} value whatever belongs at that key
  * @returns {void}
  */
 function writePath(object, keys, value) {
@@ -155,9 +154,7 @@ function writePath(object, keys, value) {
  * npx fulmine.js override [dir] [--dry-run]
  *
  * Puts the substitution in package.json where this project's package manager reads it, and says
- * what to run next. It deliberately does not run the install: the reinstall throws away
- * node_modules, and that is not something a command should do to somebody's working tree without
- * being watched.
+ * what to run next. It does not run the install itself: that throws away node_modules.
  *
  * @param {string[]} argv everything after the command name
  * @returns {number} exit code
@@ -235,9 +232,8 @@ function override(argv) {
 /**
  * Every build target in an angular.json that produces a server bundle.
  *
- * A browser-only build has nothing to declare external: the bundle it makes never loads µWS. What
- * marks a server build is `ssr`, `server` or `outputMode` in its options, which is what `ng add
- * @angular/ssr` writes.
+ * A browser-only build never loads uWS. What marks a server build is `ssr`, `server` or
+ * `outputMode` in its options, which is what `ng add @angular/ssr` writes.
  *
  * @param {any} config the parsed angular.json
  * @returns {{name: string, options: any}[]}
@@ -257,8 +253,8 @@ function serverBuilds(config) {
 /**
  * npx fulmine.js angular [dir] [--dry-run]
  *
- * Declares this package and µWebSockets.js external in every server build, which is what stops
- * esbuild trying to inline a native binary it cannot read.
+ * Declares this package and uWebSockets.js external in every server build, which stops esbuild
+ * trying to inline a native binary it cannot read.
  *
  * @param {string[]} argv everything after the command name
  * @returns {number} exit code
@@ -267,11 +263,9 @@ function angular(argv) {
     const dryRun = argv.includes("--dry-run");
     const given = path.resolve(argv.find((arg) => !arg.startsWith("--")) ?? ".");
 
-    // The argument is either the file or the directory holding it, and which one comes out of
-    // reading it rather than out of a stat: a directory reads as EISDIR and a missing path as
-    // ENOENT, and in both cases the file to look for is angular.json inside it. Asked this way
-    // round because this function goes on to write the file it read, and a check on a path followed
-    // by a write to the same path is the shape of a race whatever the odds of losing it.
+    // The argument is either the file or the directory holding it, told apart by reading it and not
+    // by a stat: a directory reads EISDIR, a missing path ENOENT, and in both cases the file to
+    // look for is angular.json inside it. A stat followed by a write to the same path is a race.
     let file = given;
     let read = readJson(file);
     if ("error" in read && (read.code === "EISDIR" || read.code === "ENOENT")) {

package/src/application.js

@@ -103,6 +103,13 @@ class Application extends Router {
      */
     _isApplication = true;
 
+    /**
+     * Whether express.testing already compiled the routes of this app. Written there and nowhere
+     * else: a second compilation would register everything with uWS twice. See src/testing.js.
+     * @type {boolean|undefined}
+     */
+    _testingCompiled;
+
     /**
      * @param {object} [settings] the options express() takes. uwsOptions goes to uWS and decides
      *   between an HTTP, an HTTPS and an HTTP/3 server; threads sizes the file-reading pool, and 0
@@ -154,11 +161,13 @@ class Application extends Router {
         // was an allocation on every request
         this._request = class extends Request {
             /**
-             * @param {any} req
-             * @param {any} res
-             * @param {any} app
-             * @param {any} [preset]
-             * @param {any} [skipHolder]
+             * The base constructor's arguments, written out rather than spread. See Request.
+             *
+             * @param {import("uWebSockets.js").HttpRequest} req uWS request
+             * @param {import("uWebSockets.js").HttpResponse} res uWS response
+             * @param {Application} app the application this request arrived at
+             * @param {import("./router-utils.js").NativePreset} [preset] a literal registration's constants
+             * @param {import("./router-utils.js").SkipHolder} [skipHolder] where a granted header skip lives
              */
             constructor(req, res, app, preset, skipHolder) {
                 super(req, res, app, preset, skipHolder);
@@ -166,27 +175,15 @@ class Application extends Router {
         };
         this._response = class extends Response {
             /**
-             * @param {any} res
-             * @param {any} req
-             * @param {any} app
+             * The base constructor's arguments, written out rather than spread. See Response.
+             *
+             * @param {import("uWebSockets.js").HttpResponse} res uWS response
+             * @param {Request} req the Request, already built
+             * @param {Application} app the application this request arrived at
              */
             constructor(res, req, app) {
                 super(res, req, app);
             }
-
-            /**
-             * Node counts an explicit writeHead as the head gone out; remembered here so the
-             * automatic OPTIONS reply can refuse to add headers after it, as express's does.
-             *
-             * @param {number} statusCode
-             * @param {string|Record<string, any>} [statusMessage]
-             * @param {Record<string, any>} [headers]
-             * @returns {this}
-             */
-            writeHead(statusCode, statusMessage, headers) {
-                this._headWritten = true;
-                return super.writeHead(statusCode, statusMessage, headers);
-            }
         };
         this.request = this._request.prototype;
         this.response = this._response.prototype;
@@ -242,9 +239,9 @@ class Application extends Router {
         // stores where a Set paid identity hashing and table upkeep per request. A holder object
         // rather than a bare field, because the callable app copies own scalars by value and two
         // copies of a head would disagree; an object rides by reference, the way the Set did
-        this._pending = /** @type {{ head: any }} */ ({ head: null });
+        this._pending = /** @type {{ head: Response|null }} */ ({ head: null });
         // on the per-app prototype layer, not per response, same as the Set was
-        /** @type {any} */ (this.response)._pendingIn = this._pending;
+        /** @type {{_pendingIn?: {head: Response|null}}} */ (this.response)._pendingIn = this._pending;
         this._draining = false;
         // read here, at construction, the way express does; an empty NODE_ENV means development,
         // which the ?? in the shared default would miss
@@ -274,8 +271,8 @@ class Application extends Router {
      * message carries data and not closures. The counter wraps rather than growing without bound,
      * a million tasks being far more than can be outstanding at once.
      *
-     * @param {(value: any) => void} resolve
-     * @param {(err: any) => void} reject
+     * @param {(value: Buffer) => void} resolve
+     * @param {(err: Error) => void} reject
      * @returns {number} the key to send to the worker
      */
     createWorkerTask(resolve, reject) {
@@ -306,11 +303,10 @@ class Application extends Router {
 
     /**
      * A small file through the worker pool, with two things on top: concurrent asks for the same
-     * path share one read, and the bytes of an unchanged file come from a bounded cache,
-     * validated against the stat the caller already paid for, so a touched file is re-read.
-     * A hit completes on a macrotask, which is when a worker's answer would have arrived; code
-     * that passed the suites against worker timing keeps passing against this.
-     * `app.set("file cache", false)` turns the cache off; the shared read stays.
+     * path share one read, and the bytes of an unchanged file come from a bounded cache, validated
+     * against the stat the caller already paid for, so a touched file is re-read. A hit completes
+     * on a macrotask, which is when a worker's answer would have arrived.
+     * `app.set("file cache", false)` turns the cache off, the shared read stays.
      *
      * @param {string} fullpath
      * @param {import("fs").Stats} stat
@@ -407,12 +403,11 @@ class Application extends Router {
             }
             value = value == null ? undefined : value.map((m) => m.toUpperCase());
         } else if (key === "etag") {
-            // The skips are not taken back here. They used to be, because send consults freshness
-            // and the skip branch looked like it had not copied the headers for it, but that
-            // branch reads if-none-match, if-modified-since and cache-control by name whatever
-            // this setting says, see request.js:527, and req.fresh reads nothing else off the
-            // request. Registering a route or a middleware after listen still takes them back,
-            // see router.js:1615: that is a different question, about code the analysis never saw.
+            // The skips are not taken back here. They used to be, because send consults freshness,
+            // but that branch reads if-none-match, if-modified-since and cache-control by name
+            // whatever this setting says, and req.fresh reads nothing else off the request.
+            // Registering a route after listen still takes them back: that is a different
+            // question, about code the analysis never saw
             if (typeof value === "function") {
                 this._settings["etag fn"] = value;
             } else {
@@ -484,12 +479,14 @@ class Application extends Router {
      * is held in a set until it finishes, so close() knows when the last one is done. Native
      * routes and the catch-all both come through here, since both call it on the app.
      *
-     * @param {any} res uWS response
-     * @param {any} req uWS request, readable only during this call
-     * @param {any} [preset] a literal registration's constants, see nativePreset in the router
-     * @param {any} [skipHolder] where a granted header skip lives, forwarded whole: dropping
-     *   it here silently turned every skip off, since the native closures call this override
-     * @returns {any} the request, with the response reachable as request.res
+     * @param {import("uWebSockets.js").HttpResponse} res uWS response
+     * @param {import("uWebSockets.js").HttpRequest} req uWS request, readable only during this call
+     * @param {import("./router-utils.js").NativePreset} [preset] a literal registration's constants,
+     *   see nativePreset in the router
+     * @param {import("./router-utils.js").SkipHolder} [skipHolder] where a granted header skip lives,
+     *   forwarded whole: dropping it here silently turned every skip off, since the native closures
+     *   call this override
+     * @returns {Request} the request, with the response reachable as request.res
      */
     handleRequest(res, req, preset, skipHolder) {
         const request = super.handleRequest(res, req, preset, skipHolder);
@@ -523,8 +520,8 @@ class Application extends Router {
      * what the catch-all runs, and also what a native registration falls back to when it sees a
      * request it must not answer itself, see the case guard in Router#_registerUwsRoute.
      *
-     * @param {any} res the uWS response
-     * @param {any} req the uWS request
+     * @param {import("uWebSockets.js").HttpResponse} res the uWS response
+     * @param {import("uWebSockets.js").HttpRequest} req the uWS request
      */
     _serveGeneric(res, req) {
         const request = this.handleRequest(res, req);
@@ -551,9 +548,8 @@ class Application extends Router {
      *
      * Returns the app and not an `http.Server`, since there is no node server underneath. The app
      * carries `address()`, `close()`, `listening` and the 'listening' and 'close' events; anything
-     * needing a real server, socket.io being the usual case, wants `app.uwsApp`. The callback runs
-     * on the next tick with the bind error, if there was one. A path instead of a port is a unix
-     * socket.
+     * needing a real server, socket.io being the usual case, wants `app.uwsApp`. A path instead of
+     * a port is a unix socket.
      *
      * @param {number|string} [port] port, or a unix socket path; 0 picks a free port
      * @param {string} [host] interface to bind; every interface when omitted
@@ -563,14 +559,12 @@ class Application extends Router {
      */
     listen(port, host, backlog, callback) {
         // With { cluster } the primary has nothing to bind. Each worker binds this same port with
-        // µWS's shared flag, which is SO_REUSEPORT, so the kernel hands each connection to one of
-        // them and the primary is not in the path at all: it forks, replaces a worker that dies,
-        // and nothing else. Everything below this runs in the workers, listen callback included,
-        // so it runs once per worker rather than once.
+        // uWS's shared flag, SO_REUSEPORT, so the kernel hands each connection to one of them and
+        // the primary only forks and replaces a worker that dies. Everything below this runs in the
+        // workers, listen callback included, so once per worker rather than once.
         //
-        // The test is the process and not this app: a second app on a TLS port, one without a
-        // cluster setting of its own, would otherwise take that port here, exclusively, and every
-        // worker would fail on it.
+        // The test is the process and not this app: a second app on a TLS port, without a cluster
+        // setting of its own, would take that port here exclusively and every worker would fail
         if (cluster.isPrimary && isSupervising()) {
             if (this._clusterWorkers > 0 && !this._clusterHandle) {
                 this._clusterHandle = forkWorkers(this._clusterWorkers);
@@ -758,19 +752,18 @@ class Application extends Router {
      * `res.render()` is the one that responds.
      *
      * `app.locals` and `options._locals` are merged into the options, in that order, so a
-     * per-request local wins over an application-wide one. Caching follows the "view cache"
-     * setting unless `options.cache` says otherwise.
-     *
-     * A function in the options position is taken as the callback.
+     * per-request local wins. Caching follows the "view cache" setting unless `options.cache` says
+     * otherwise. A function in the options position is taken as the callback.
      *
      * @param {string} name view name, resolved against the "views" setting
-     * @param {Record<string, any>} [options] locals for the view
+     * @param {Record<string, any>|((err: Error|null, html?: string) => void)} [options] locals for
+     *   the view, or the callback in its place
      * @param {(err: Error|null, html?: string) => void} [callback] receives the rendered view. It
      *   is what render is for, so leaving it out throws, as it does in Express
      */
     render(name, options, callback) {
         if (typeof options === "function") {
-            callback = /** @type {any} */ (options);
+            callback = /** @type {(err: Error|null, html?: string) => void} */ (options);
             options = new NullObject();
         }
         // render exists to hand the result somewhere, so there is always a callback by this point:
@@ -844,15 +837,13 @@ class Application extends Router {
     /**
      * Stops accepting connections, lets in-flight requests finish, then emits 'close'.
      *
-     * Node's server.close(), which Express hands back from listen(), only closes the listen
-     * socket and waits for what is being served; uWS's close() forcefully terminates every
-     * connection, so calling it first aborted whatever a graceful shutdown was waiting for.
-     * It still runs, but only once the last pending response is done, to drop the idle
-     * keep-alive connections nothing else would close.
+     * Node's server.close() only closes the listen socket and waits for what is being served; uWS's
+     * close() terminates every connection, so calling it first aborted whatever a graceful shutdown
+     * was waiting for. It still runs, but only once the last pending response is done, to drop the
+     * idle keep-alive connections nothing else would close.
      *
-     * The callback is the first 'close' listener, so it runs before any added afterwards. Closing
-     * a server that was not listening still calls back, with an ERR_SERVER_NOT_RUNNING error, the
-     * way node does.
+     * The callback is the first 'close' listener. Closing a server that was not listening still
+     * calls back with ERR_SERVER_NOT_RUNNING, the way node does.
      *
      * @param {(err?: Error) => void} [callback] called once closed
      * @returns {this} the app, for chaining
@@ -932,10 +923,9 @@ class Application extends Router {
 // carries. Middleware that takes a whole app and calls it, vhost being the one everybody meets, was
 // given something it could not call.
 //
-// This was tried once before and reverted the same day, because a callable app broke supertest:
-// `request(app)` reads `typeof app === "function"` and wraps whatever it finds in
-// http.createServer, and there was nothing underneath that could serve node's IncomingMessage, so
-// every call timed out. src/node-shim.js is what closes that hole, and it is why this is safe now.
+// Tried once before and reverted the same day, because a callable app broke supertest: `request(app)`
+// reads `typeof app === "function"` and wraps what it finds in http.createServer, and there was
+// nothing underneath that could serve node's IncomingMessage. src/node-shim.js closes that hole.
 module.exports = function (options) {
     return new Application(options)._asCallable();
 };

package/src/cli.js

@@ -18,26 +18,25 @@ limitations under the License.
 // npx fulmine migrate [dir]
 //
 // Rewrites the module specifier and nothing else. An Express 5 app is a Fulmine app already, so
-// there is no code to translate: what there is instead is a short list of things that behave
-// differently, printed at the end, because no rewrite can find those for you.
+// there is no code to translate. The short list of things that behave differently is printed at
+// the end, because no rewrite can find those for you.
 //
 // npx fulmine profile [entry]
 //
-// Prints what listen() worked out about each route and normally keeps to itself: which ones µWS
-// answers on its own, which ones fell back to the ordinary router and why, and which ones were
-// compiled all the way down to a response written at startup.
+// Prints what listen() worked out about each route: which ones uWS answers on its own, which ones
+// fell back to the ordinary router and why, and which ones were compiled into a response.
 //
 // npx fulmine verify [dir]
 //
 // Whether this machine and this project can run it at all: the node version, the C library, the
-// µWebSockets.js binary, the base image a Dockerfile names. See src/verify.js.
+// uWebSockets.js binary, the base image a Dockerfile names. See src/verify.js.
 //
 // npx fulmine override [dir]
 // npx fulmine angular [dir]
 //
-// The two things a project needs that are a line in a JSON file rather than a specifier in a source
-// file: the package manager substitution, for a framework that requires express in its own code,
-// and angular.json's externalDependencies. See src/adopt.js.
+// The two things a project needs that are a line in a JSON file rather than a specifier in a
+// source file: the package manager substitution, for a framework that requires express in its own
+// code, and angular.json's externalDependencies. See src/adopt.js.
 
 const fs = require("fs");
 const path = require("path");
@@ -47,6 +46,9 @@ const { collectRoutes } = require("./testing.js");
 const { verify } = require("./verify.js");
 const { override, angular } = require("./adopt.js");
 
+/** @typedef {import("./application.js").Application} Application */
+/** @typedef {import("./router-utils.js").RouteEntry} RouteEntry */
+
 const FROM = "express";
 const TO = "fulmine.js";
 
@@ -146,14 +148,12 @@ function collectFiles(dir) {
  * A reader for the .ts files of the project being migrated, or null when it has no TypeScript.
  *
  * acorn cannot read TypeScript, and shipping a parser that can would put megabytes into this
- * package for a command most people run once. A TypeScript project already has the compiler, so
- * it is resolved from there. A project without one is told its .ts files were left alone rather
- * than having them quietly skipped, which is what happened before they were looked at at all.
+ * package for a command most people run once. A TypeScript project already has the compiler, so it
+ * is resolved from there. A project without one is told its .ts files were left alone.
  *
- * typescript 7 is the compiler rewritten in Go, and it publishes no JavaScript parser any more:
- * require("typescript") gives back a version number and nothing else. Its scanner survives, on an
- * ESM-only subpath that require() reads on every node this package supports, so 7 gets the token
- * walk and 6 keeps the tree.
+ * typescript 7 is the compiler rewritten in Go and publishes no JavaScript parser any more:
+ * require("typescript") gives back a version number and nothing else. Its scanner survives on an
+ * ESM-only subpath that require() reads, so 7 gets the token walk and 6 keeps the tree.
  *
  * @param {string} target directory being migrated
  * @returns {((source: string, fileName: string, seen?: Set<string>) => {start: number, end: number}[])|null}
@@ -190,7 +190,7 @@ function loadTypeScript(target) {
  *
  * @param {string} source
  * @param {string} fileName decides whether JSX is allowed, so a .tsx angle bracket is not a cast
- * @param {any} ts the compiler
+ * @param {typeof import("typescript")} ts the compiler
  * @param {Set<string>} [seen] as in findSpecifiers
  * @returns {{start: number, end: number}[]}
  */
@@ -205,7 +205,7 @@ function findSpecifiersTypeScript(source, fileName, ts, seen) {
 
     /** @type {{start: number, end: number}[]} */
     const found = [];
-    /** @param {any} node a string literal naming a module */
+    /** @param {import("typescript").StringLiteral} node a string literal naming a module */
     const take = (node) => {
         if (node.text === FROM) {
             found.push({ start: node.getStart(sourceFile), end: node.getEnd() });
@@ -252,7 +252,8 @@ function findSpecifiersTypeScript(source, fileName, ts, seen) {
  *
  * @param {string} source
  * @param {string} fileName decides whether JSX is allowed, as above
- * @param {any} ts the scanner and the two enums loadTypeScript kept
+ * @param {any} ts the scanner and the two enums loadTypeScript kept, from typescript 7's unstable
+ *   API, which the typings this project compiles against do not describe
  * @param {Set<string>} [seen] as in findSpecifiers
  * @returns {{start: number, end: number}[]}
  */
@@ -303,7 +304,7 @@ function findSpecifiersScanner(source, fileName, ts, seen) {
  * @returns {{start: number, end: number}[]|null} null when the file does not parse
  */
 function findSpecifiers(source, seen) {
-    /** @type {any} */
+    /** @type {import("acorn").Program|null|undefined} */
     let tree;
     // A file is either a module or a script and the parser has to be told which. Try module first,
     // since it also accepts everything a script can contain except a bare `return`.
@@ -311,7 +312,7 @@ function findSpecifiers(source, seen) {
         try {
             tree = acorn.parse(source, {
                 ecmaVersion: "latest",
-                sourceType: /** @type {any} */ (sourceType),
+                sourceType: /** @type {"module"|"script"} */ (sourceType),
                 allowReturnOutsideFunction: true,
                 allowAwaitOutsideFunction: true,
                 allowHashBang: true
@@ -327,7 +328,7 @@ function findSpecifiers(source, seen) {
 
     /** @type {{start: number, end: number}[]} */
     const found = [];
-    /** @param {any} node a string literal naming a module */
+    /** @param {import("acorn").Literal & {value: string}} node a string literal naming a module */
     const record = (node) => {
         if (node.value === FROM) {
             found.push({ start: node.start, end: node.end });
@@ -364,8 +365,10 @@ function findSpecifiers(source, seen) {
  * Visits every node. acorn produces plain objects, so the shape is walked rather than dispatched
  * on: a table of node types would have to be kept in step with the parser, and being out of step
  * would mean silently skipping an import.
- * @param {any} node
- * @param {(node: any) => void} visit
+ * @param {any} node an acorn node, or an array or a scalar under one: walked by key, so no shape
+ *   is assumed
+ * @param {(node: any) => void} visit handed every node, loose because the visitor reads edges of
+ *   its own off each
  */
 function walk(node, visit) {
     if (!node || typeof node !== "object") return;
@@ -453,17 +456,16 @@ function findEntry(given) {
 /**
  * Every build of this library the application could load, as the prototype that owns listen().
  *
- * The command runs from its own copy, and the application loads whichever one resolves from its
- * own directory. That is usually the same file and sometimes is not: a global install, an
- * `npx fulmine.js@version`, a workspace that hoisted a second copy, or the `express` name pointing
- * here through an override. Patching only this command's copy leaves the application's own listen()
- * to bind the port, and the command then reports that the file built nothing.
+ * The command runs from its own copy, and the application loads whichever one resolves from its own
+ * directory. That is usually the same file and sometimes not: a global install, an
+ * `npx fulmine.js@version`, a hoisted second copy, or `express` pointing here through an override.
+ * Patching only this command's copy leaves the application's own listen() to bind the port.
  *
- * An app is a callable, so its own prototype is not the one that carries the methods: walk up to
- * whichever link owns listen.
+ * An app is a callable, so its own prototype does not carry the methods: walk up to whichever link
+ * owns listen.
  *
  * @param {string} entry
- * @returns {any[]} the prototypes to stub, this command's copy first
+ * @returns {object[]} the prototypes to stub, this command's copy first
  */
 function listenOwners(entry) {
     const builds = new Set([require("./index.js")]);
@@ -511,7 +513,7 @@ function listenOwners(entry) {
  *
  * @param {string[]} argv
  * @param {string} command the word for the message when there is nothing to load
- * @returns {{apps: any[], entry: string}|null} null once the reason has been printed
+ * @returns {{apps: Application[], entry: string}|null} null once the reason has been printed
  */
 function loadApps(argv, command) {
     const entry = findEntry(argv.find((arg) => !arg.startsWith("--")));
@@ -543,7 +545,7 @@ function loadApps(argv, command) {
     try {
         require(entry);
     } catch (e) {
-        const error = /** @type {any} */ (e);
+        const error = /** @type {Error} */ (e);
         restore();
         console.error(`${path.relative(process.cwd(), entry)} could not be loaded:
 ${error.stack ?? error}`);
@@ -580,16 +582,15 @@ ${error.stack ?? error}`);
 /**
  * Ends the file-reading threads that building an application started.
  *
- * An Application starts one per `threads` in its constructor, and these commands only ever read
- * what compiling the routes decided: nothing here serves a file, so nothing here needs a thread.
- * They are unref'd, so leaving them would not hang the process, but they are threads holding the
- * library the application loaded, and this command is often not the whole process. It also stops
- * them outliving the directory they were loaded from, which is how a test that profiles a copy and
- * then removes it saw "Cannot find module .../src/worker.js" arrive after it had finished.
+ * An Application starts one per `threads` in its constructor, and these commands only read what
+ * compiling the routes decided. They are unref'd, so leaving them would not hang the process, but
+ * they hold the library the application loaded, and this command is often not the whole process.
+ * It also stops them outliving the directory they were loaded from, which is how a test that
+ * profiles a copy and then removes it saw "Cannot find module .../src/worker.js".
  *
- * Best effort throughout: a build with no workers, or a worker already gone, is not an error here.
+ * Best effort throughout: a build with no workers, or a worker already gone, is not an error.
  *
- * @param {any[]} apps
+ * @param {Application[]} apps
  * @returns {void}
  */
 function stopFileWorkers(apps) {
@@ -765,12 +766,11 @@ function matchesWanted(full, method, wanted) {
  *
  * There is no score here on purpose. A percentage of routes is not a percentage of traffic: an
  * application with a thousand cold routes and one hot one that fell back would score well and
- * serve badly. What is printed instead is counted rather than judged, and the advice is only
- * printed for the reasons somebody can actually act on.
+ * serve badly. What is printed is counted rather than judged.
  *
- * @param {any[]} routes
- * @param {any[]} native
- * @param {any[]} declarative
+ * @param {{route: RouteEntry, full: string}[]} routes
+ * @param {{route: RouteEntry, full: string}[]} native
+ * @param {{route: RouteEntry, full: string}[]} declarative
  */
 function printSummary(routes, native, declarative) {
     console.log("\nWhat this adds up to\n");
@@ -815,7 +815,7 @@ function printSummary(routes, native, declarative) {
 }
 
 /**
- * @param {any} app
+ * @param {Application} app the application the entry file built
  * @param {boolean} several whether to say which application this is
  */
 function printProfile(app, several) {