fulmine.js 5.19.2 → 5.19.4

package/src/utils.js

@@ -28,6 +28,21 @@ const ms = require("ms");
 const fs = require("fs");
 const { Stats } = require("fs");
 
+/** @typedef {import("./request.js")} Request */
+/** @typedef {import("./response.js")} Response */
+/**
+ * An error with the http-errors fields on it, which are what `res.status(err.status || 500)`, the
+ * error page and the body parsers read. None is required: a plain throw carries none of them.
+ * @typedef {Error & {
+ *   status?: number,
+ *   statusCode?: number,
+ *   expose?: boolean,
+ *   code?: string,
+ *   type?: string,
+ *   types?: string[]
+ * }} HttpError
+ */
+
 const EMPTY_REGEX = new RegExp(``);
 
 // what express hands qs for a query string. allowPrototypes keeps a key named "constructor" or
@@ -231,11 +246,9 @@ function patternToRegex(pattern, isPrefix = false, caseSensitive = true, strict
     let lastWildcardEnd = -1;
     // What path-to-regexp calls the wildcard backtrack: the literal text written since the last
     // wildcard. Once a wildcard has eaten slashes, a later one in the same path is held to a single
-    // segment, or the two would divide the path between them in more than one way and the regex
-    // would have to backtrack to find out which. /*a/*b against /x/y/ is the case that shows it:
-    // express refuses it under strict routing, and a second greedy wildcard accepts it.
-    // the text written since the last capture of any kind, and the text written since the last
-    // wildcard, which are the two path-to-regexp weighs
+    // segment, or the two would divide the path in more than one way and the regex would have to
+    // backtrack. /*a/*b against /x/y/ shows it: express refuses it under strict routing.
+    // Two counters: text since the last capture of any kind, and text since the last wildcard
     let backtrack = "";
     let wildcardBacktrack = "";
     let lastCaptureWasWildcard = false;
@@ -405,16 +418,13 @@ function patternToRegex(pattern, isPrefix = false, caseSensitive = true, strict
             i++;
 
             // When a :parameter precedes this group, that parameter is the one that gives ground
-            // while backtracking, so this one must not swallow the separator as well. Express
-            // splits /a.b.c against /:file{.:ext} as file=a.b, ext=c, which only works if ext
-            // cannot contain a dot. After static text there is nothing to give ground, so the
-            // parameter takes everything: /file{.:ext} against /file.tar.gz gives ext=tar.gz.
-            // The whole of it, not its first character: /:foo{abc:bar} against /123abcabc splits as
-            // foo=123 and bar=abc on express, and reading the separator as "a" left bar unable to
-            // match its own text, so the group never matched and foo took the segment whole. More
-            // than one character cannot go in a class, so it is written as a lookahead, and either
-            // way the parameter is still allowed to be exactly the separator, as path-to-regexp
-            // writes it.
+            // while backtracking, so this one must not swallow the separator too. Express splits
+            // /a.b.c against /:file{.:ext} as file=a.b, ext=c, which only works if ext cannot
+            // contain a dot. After static text nothing gives ground, so the parameter takes
+            // everything: /file{.:ext} against /file.tar.gz gives ext=tar.gz.
+            // The whole separator, not its first character: /:foo{abc:bar} against /123abcabc
+            // splits as foo=123 and bar=abc on express, and reading it as "a" left bar unable to
+            // match its own text. More than one character cannot go in a class, so it is a lookahead
             const colon = groupContent.indexOf(":");
             const separator = lastTokenWasParam && colon > 0 ? groupContent.slice(0, colon) : "";
             const escapedSeparator = separator.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -445,13 +455,11 @@ function patternToRegex(pattern, isPrefix = false, caseSensitive = true, strict
                 }
             }
             if (lastWildcard && lastWildcardEnd === regexPattern.length) {
-                // A wildcard immediately before the group. `(?<w>[^]+)(?:group)?` can never let
-                // the group match, because the wildcard is greedy and the group may be empty, and
-                // making the wildcard lazy is not the same thing either: it gives the trailing
-                // slash away, and /*path{.:ext} against /a/b/ then loses the empty last segment.
-                // path-to-regexp writes the two branches out instead, group first and the
-                // wildcard greedy in both, so that is what goes here. The second branch captures
-                // the same parameter under a name of its own, which is what uniqueGroupName is for.
+                // A wildcard immediately before the group. `(?<w>[^]+)(?:group)?` can never let the
+                // group match, because the wildcard is greedy and the group may be empty, and a
+                // lazy wildcard is not the same thing either: it gives the trailing slash away, and
+                // /*path{.:ext} against /a/b/ loses the empty last segment. path-to-regexp writes
+                // the two branches out instead, group first and the wildcard greedy in both
                 const second = uniqueGroupName(lastWildcard.name);
                 wildcardNames.push(second);
                 const withWildcard = regexPattern.slice(lastWildcard.start);
@@ -619,13 +627,13 @@ const NOT_A_LITERAL = /[:*{}\\]/;
  *
  * The answer is structural: no position where two different literals meet, and, when neither path
  * can change length, the same number of segments. `/orders/:id` and `/invoices/:id` cannot both
- * match, `/users/:id` and `/users/me` can. The caller reads "do not know" as yes, so every doubt
- * answers true: saying two paths overlap only costs a native registration, while missing one lets
- * µWS answer a request that belonged to an earlier route.
+ * match, `/users/:id` and `/users/me` can. The caller reads "do not know" as yes: saying two paths
+ * overlap only costs a native registration, while missing one lets uWS answer a request that
+ * belonged to an earlier route.
  *
  * A parameter is not the only shape that matches more than itself. A wildcard and an optional group
- * do too, and reading `{:opt}` or `*splat` as the literal text it is written as reported "cannot
- * overlap" for a route that plainly could, which took the earlier route's turn away.
+ * do too, and reading `{:opt}` or `*splat` as literal text reported "cannot overlap" for a route
+ * that plainly could.
  *
  * @param {string} a
  * @param {string} b
@@ -759,11 +767,8 @@ function acceptParams(str) {
 //
 // The keys are media types, so an application uses a handful and the ceiling is never approached.
 // It is here because application code is free to hand res.type() something a client sent, and an
-// unbounded map keyed on that is a leak the client controls.
-//
-// Clearing beats evicting one entry at a time: the few types an application really uses are back
-// within a few requests, whereas refusing new entries once full would let a flood of invented
-// values lock the real ones out for the life of the process.
+// unbounded map keyed on that is a leak the client controls. Clearing beats evicting one at a
+// time: refusing new entries once full would let a flood of invented values lock the real ones out.
 const MEMO_LIMIT = 512;
 
 /**
@@ -772,8 +777,9 @@ const MEMO_LIMIT = 512;
  * The wrapped function must never answer undefined, since that is what the cache reads as a miss.
  * The mime lookups here answer false for something they do not know, which caches correctly.
  *
- * @param {(key: string) => any} fn
- * @returns {(key: string) => any}
+ * @template T
+ * @param {(key: string) => T} fn
+ * @returns {(key: string) => T}
  */
 function memoizeByString(fn) {
     const cache = new Map();
@@ -818,7 +824,7 @@ function normalizeType(type) {
  * unicode escapes, so a string in the body cannot close a script tag in an HTML page that embeds
  * the response.
  *
- * @param {any} value
+ * @param {unknown} value whatever the handler passed to res.json
  * @param {any} [replacer] the "json replacer" setting
  * @param {string|number} [spaces] the "json spaces" setting
  * @param {boolean} [escape] the "json escape" setting
@@ -855,14 +861,12 @@ const ENCODING_ANY = ENCODING_BR | ENCODING_GZIP | ENCODING_DEFLATE | ENCODING_Z
 /**
  * The encoding to answer with, read straight off Accept-Encoding rather than through negotiator:
  * the header is a short list of names with an optional q, and building a Negotiator per response
- * to read it costs more than the scan does.
+ * costs more than the scan does. The tie-break is negotiator's, for the list the compression module
+ * hands it: brotli first, then gzip, then deflate, and identity last.
  *
- * The tie-break is negotiator's, for the list the compression module hands it: brotli first, then
- * gzip, then deflate, and identity last.
- *
- * Only the encodings named in `allowed` are on offer, since the caller may not be able to
- * produce all three: express.static offers the two it can have lying on disk. An uncompressed
- * answer is always on offer, and is what an empty header ends up choosing.
+ * Only the encodings named in `allowed` are on offer, since the caller may not produce all three:
+ * express.static offers the two it can have lying on disk. An uncompressed answer is always on
+ * offer, and is what an empty header chooses.
  *
  * @param {string} accept the header, or "" when the request carried none
  * @param {number} allowed ENCODING_BR, ENCODING_ZSTD, ENCODING_GZIP and ENCODING_DEFLATE, or'd
@@ -989,12 +993,10 @@ const defaultSettings = {
     // The native µWS router matches bytes, so the compiler in _compileOptimizedRoutes only hands
     // it routes whose earlier siblings it can prove agree under either case rule.
     "declarative responses": true,
-    // on. Off hands every request to the ordinary chain instead of letting µWS match what it can,
+    // on. Off hands every request to the ordinary chain instead of letting uWS match what it can,
     // which is slower and answers the same. Not a tuning knob: it exists so one application can be
-    // served both ways and the two sets of answers compared, which tests the optimizer against the
-    // rest of the framework without a second framework to compare with. See
-    // `npm run fuzz -- --self`. A compiled response needs a native registration to hang on, so this
-    // takes "declarative responses" with it.
+    // served both ways and the answers compared, see `npm run fuzz -- --self`. A compiled response
+    // needs a native registration to hang on, so this takes "declarative responses" with it
     "native routes": true,
     // off: with a window set, the size and mtime of a file served by sendFile are remembered for
     // it, which is one syscall less per request and a file that can be served as it was a moment
@@ -1053,13 +1055,17 @@ function cachedStat(file, ttl) {
 /**
  * A duration setting as milliseconds: false is off, a string is read by ms, a number is itself.
  *
- * @param {any} value
+ * @param {string|number|boolean|undefined} value the setting as the application wrote it
  * @param {string} name for the error, which names the setting the application wrote
  * @returns {number}
  */
 function durationSetting(value, name) {
     const parsed =
-        value === false || value === undefined ? 0 : typeof value === "string" ? ms(/** @type {any} */ (value)) : value;
+        value === false || value === undefined
+            ? 0
+            : typeof value === "string"
+              ? ms(/** @type {import("ms").StringValue} */ (value))
+              : value;
     if (typeof parsed !== "number" || !(parsed >= 0)) {
         throw new TypeError(`${name} must be a duration`);
     }
@@ -1140,8 +1146,9 @@ function deprecated(oldMethod, newMethod, full = false) {
  * request, each time picking up after the route it just ran, and Array.findIndex has no way to
  * start anywhere but the beginning.
  *
- * @param {any[]} arr
- * @param {(item: any, index: number, arr: any[]) => boolean} fn
+ * @template T
+ * @param {T[]} arr
+ * @param {(item: T, index: number, arr: T[]) => boolean} fn
  * @param {number} [index] where to start
  * @returns {number} the index, or -1
  */
@@ -1176,7 +1183,7 @@ function decode(path) {
  *
  * @param {string} value
  * @returns {string}
- * @throws {any} carrying status 400 when the value cannot be decoded
+ * @throws {HttpError} carrying status 400 when the value cannot be decoded
  */
 function decodeParam(value) {
     // the common case, and worth the check: a parameter is usually a number or a word, and
@@ -1189,7 +1196,8 @@ function decodeParam(value) {
     } catch {
         // a URIError, not an Error: express throws what decodeURIComponent threw, so an error
         // handler written as `err instanceof URIError` has to keep working here
-        const err = /** @type {any} */ (new URIError(`Failed to decode param '${value}'`));
+        /** @type {HttpError} */
+        const err = new URIError(`Failed to decode param '${value}'`);
         err.status = 400;
         err.statusCode = 400;
         err.expose = true;
@@ -1274,8 +1282,8 @@ function parseHttpDate(date) {
  * no longer the current one, which is a 412 rather than a 304: the client asked to be stopped if
  * anything had changed.
  *
- * @param {any} req
- * @param {any} res
+ * @param {Request} req
+ * @param {Response} res
  * @returns {boolean}
  */
 function isPreconditionFailure(req, res) {
@@ -1296,7 +1304,8 @@ function isPreconditionFailure(req, res) {
     // if-unmodified-since
     const unmodifiedSince = parseHttpDate(req.headers["if-unmodified-since"]);
     if (!isNaN(unmodifiedSince)) {
-        const lastModified = parseHttpDate(res.get("Last-Modified"));
+        // cast because res.get answers an array for set-cookie, and never for this one
+        const lastModified = parseHttpDate(/** @type {string|undefined} */ (res.get("Last-Modified")));
         return isNaN(lastModified) || lastModified > unmodifiedSince;
     }
 
@@ -1345,7 +1354,7 @@ function statTag(stat, weak) {
  * ETag comes from its size and mtime while a body's comes from its contents.
  *
  * @param {{weak: boolean}} options
- * @returns {(body: any, encoding?: BufferEncoding) => string}
+ * @returns {(body: string|Buffer|import("fs").Stats, encoding?: BufferEncoding) => string}
  */
 function createETagGenerator(options) {
     return function generateETag(body, encoding) {
@@ -1367,24 +1376,26 @@ function createETagGenerator(options) {
  * and sending the whole file. It may carry either an ETag or a date, and a date only counts when
  * it matches Last-Modified exactly.
  *
- * @param {any} req
- * @param {any} res
+ * @param {Request} req
+ * @param {Response} res
  * @returns {boolean}
  */
 function isRangeFresh(req, res) {
-    const ifRange = req.headers["if-range"];
+    // folded to one string, as every header but set-cookie is
+    const ifRange = /** @type {string|undefined} */ (req.headers["if-range"]);
     if (!ifRange) {
         return true;
     }
 
     // if-range as etag
     if (ifRange.indexOf('"') !== -1) {
-        const etag = res.get("etag");
+        const etag = /** @type {string|undefined} */ (res.get("etag"));
         return Boolean(etag && ifRange.indexOf(etag) !== -1);
     }
 
     // if-range as modified date
-    const lastModified = res.get("Last-Modified");
+    // cast because res.get answers an array for set-cookie, and never for this one
+    const lastModified = /** @type {string|undefined} */ (res.get("Last-Modified"));
     return parseHttpDate(lastModified) <= parseHttpDate(ifRange);
 }
 
@@ -1489,10 +1500,9 @@ const HEADER_VALUE = /[^\t\x20-\x7e\x80-\xff]/;
  * One of node's header errors, built the way node builds it.
  *
  * Assigning the code is not the whole of it. Node also puts the code in the first line of the
- * stack, by naming the error "TypeError [THE_CODE]" while V8 formats that line and then taking
- * the name back off. Whatever prints a stack therefore says which code it was, and the default
- * error page prints exactly that: without this, the same refusal reads "TypeError:" here and
- * "TypeError [ERR_INVALID_CHAR]:" behind Express. Found by fuzzing against express.
+ * stack, by naming the error "TypeError [THE_CODE]" while V8 formats that line and then taking the
+ * name back off. The default error page prints exactly that: without this, the same refusal reads
+ * "TypeError:" here and "TypeError [ERR_INVALID_CHAR]:" behind Express. Found by fuzzing.
  *
  * @param {string} message
  * @param {string} code
@@ -1506,16 +1516,73 @@ function headerError(message, code) {
     void err.stack;
     // back to the prototype's "TypeError", which is what node leaves behind. Cast because Error
     // declares name as always present, and this deletes the own property to uncover it again
-    delete (/** @type {any} */ (err).name);
+    delete (/** @type {{name?: string}} */ (err).name);
     err.code = code;
     return err;
 }
 
+/**
+ * node's ERR_HTTP_HEADERS_SENT, for a head that can no longer change: "set" from setHeader,
+ * "remove" from removeHeader, "write" from writeHead, which is how node words each one.
+ *
+ * @param {string} verb
+ * @returns {NodeJS.ErrnoException}
+ */
+function headersSentError(verb) {
+    /** @type {NodeJS.ErrnoException} */
+    const err = new Error(`Cannot ${verb} headers after they are sent to the client`);
+    // the first line of the stack reads as node's, see headerError
+    err.name = "Error [ERR_HTTP_HEADERS_SENT]";
+    void err.stack;
+    delete (/** @type {{name?: string}} */ (err).name);
+    err.code = "ERR_HTTP_HEADERS_SENT";
+    return err;
+}
+
+/**
+ * Applies the headers a writeHead call carries, in either of node's shapes, (status, headers) or
+ * (status, reason, headers), and answers the reason phrase when there was one. Shared with the
+ * middleware that hooks writeHead: what it decides at the head has to see these first, the way
+ * on-headers applies them before its listeners run.
+ *
+ * @param {{setHeader(name: string, value: import("http").OutgoingHttpHeader|undefined): unknown}} res
+ * @param {string|import("http").OutgoingHttpHeaders|import("http").OutgoingHttpHeader[]} [statusMessage]
+ * @param {import("http").OutgoingHttpHeaders|import("http").OutgoingHttpHeader[]} [headers]
+ * @returns {string|undefined} the reason phrase
+ */
+function applyWriteHead(res, statusMessage, headers) {
+    let reason;
+    if (typeof statusMessage === "string") {
+        reason = statusMessage;
+    } else if (!headers) {
+        // the two-argument shape, where what looked like a reason phrase is the headers
+        headers = statusMessage;
+    }
+    if (Array.isArray(headers)) {
+        // node takes a flat list here, name then value, and not a list of pairs. An odd length is
+        // the caller's mistake and node names the argument in what it throws
+        if (headers.length % 2 !== 0) {
+            /** @type {NodeJS.ErrnoException} */
+            const err = new TypeError(`The argument 'headers' is invalid. Received ${JSON.stringify(headers)}`);
+            err.code = "ERR_INVALID_ARG_VALUE";
+            throw err;
+        }
+        for (let i = 0; i < headers.length; i += 2) {
+            res.setHeader(/** @type {string} */ (headers[i]), headers[i + 1]);
+        }
+    } else if (headers) {
+        for (const header in headers) {
+            res.setHeader(header, headers[header]);
+        }
+    }
+    return reason;
+}
+
 /**
  * Refuses a header name that is not an HTTP token, the way node's setHeader does and with its
  * error, so an application catching ERR_INVALID_HTTP_TOKEN behind Express catches it here.
  *
- * @param {any} name
+ * @param {unknown} name whatever a caller passed as a header name, which is what is being checked
  * @returns {void}
  * @throws {TypeError} if the name is not a token, which includes not being a string
  */
@@ -1567,7 +1634,7 @@ function validateHeaderValue(name, value) {
  * again is what turns one bad header into a dead process.
  *
  * @param {string} name
- * @param {any} value
+ * @param {any} value whatever a caller passed as a header value
  * @returns {boolean}
  */
 function headerIsWritable(name, value) {
@@ -1589,21 +1656,39 @@ const STAT_ERROR_STATUS = { ENAMETOOLONG: 404, ENOTDIR: 404, ENOENT: 404 };
  * of that handler as 500. The message is the status's own name, as http-errors writes it.
  *
  * @param {number} status
- * @returns {any}
+ * @param {string} [message] the status text unless given, as http-errors has it
+ * @returns {HttpError}
  */
-function httpError(status) {
-    const message = statuses.message[status] ?? "Error";
-    const err = /** @type {any} */ (new Error(message));
+function httpError(status, message = statuses.message[status] ?? "Error") {
+    /** @type {HttpError} */
+    const err = new Error(message);
     // http-errors names these BadRequestError, ForbiddenError and so on, and the name is what the
     // error page shows: an application looking at a 400 sees the same word Express shows it. Set
     // before anything reads the stack, which V8 formats on first read
-    err.name = `${message.replace(/\W/g, "")}Error`;
+    err.name = httpErrorName(status);
     err.expose = status < 500;
     err.statusCode = status;
     err.status = status;
     return err;
 }
 
+/**
+ * The name http-errors gives an error for a status, NotFoundError for 404: each word of the status
+ * text capitalised and run together, plus Error unless it already ends in it, which is how
+ * "Internal Server Error" stays InternalServerError.
+ *
+ * @param {number} status
+ * @returns {string}
+ */
+function httpErrorName(status) {
+    const name = (statuses.message[status] ?? "Error")
+        .split(" ")
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join("")
+        .replace(/[^ _0-9a-z]/gi, "");
+    return name.endsWith("Error") ? name : name + "Error";
+}
+
 /**
  * Marks an fs error the way send does before it is handed on, so an error handler reading
  * err.status or err.statusCode finds what it would find behind Express. The three properties are
@@ -1612,8 +1697,8 @@ function httpError(status) {
  *
  * The error itself is returned rather than a new one, so its errno, code, syscall and path survive.
  *
- * @param {any} err
- * @returns {any} the same error
+ * @param {HttpError} err the fs error, which carries its errno and path
+ * @returns {HttpError} the same error
  */
 function asStatError(err) {
     err.expose = false;
@@ -1626,8 +1711,7 @@ function asStatError(err) {
 // A constructor whose instances have no prototype, so a key from a request body or a query string
 // cannot reach Object.prototype. Typed as returning a plain record: without that, assigning one
 // reads as assigning `any`, which resets narrowing instead of removing undefined from it.
-/** @type {new () => Record<string, any>} */
-const NullObject = /** @type {any} */ (function () {});
+const NullObject = /** @type {new () => Record<string, any>} */ (/** @type {unknown} */ (function () {}));
 NullObject.prototype = Object.create(null);
 
 module.exports = {
@@ -1679,6 +1763,9 @@ module.exports = {
     withUtf8Charset,
     asStatError,
     httpError,
+    httpErrorName,
+    headersSentError,
+    applyWriteHead,
     EMPTY_REGEX,
     settingsEpoch
 };

package/src/verify.js

@@ -16,16 +16,12 @@ limitations under the License.
 
 // npx fulmine verify
 //
-// Whether this machine, and the image it will be deployed in, can run the thing at all. Not
-// whether the application behaves the same, which is what the test suite and `differences` are
-// for: this is the question that comes before it, and it is the one that costs an hour when the
-// answer is no and nobody asked.
+// Whether this machine, and the image it will be deployed in, can run the thing at all. Not whether
+// the application behaves the same, which is the test suite's job.
 //
-// There is a µWebSockets.js binary underneath, and a binary has requirements a package does not:
-// it is built per platform, per architecture and per node ABI, and it is linked against glibc. An
-// Alpine image, a node version the pinned build has no binary for, a musl base chosen by a
-// Dockerfile written before any of this: each one fails at require time, in a container, in CI,
-// with a message about a missing module that says nothing about what to do.
+// There is a uWebSockets.js binary underneath, built per platform, per architecture and per node
+// ABI, and linked against glibc. An Alpine image, a node version with no binary for it, a musl
+// base: each one fails at require time with a message about a missing module.
 //
 // Thirty seconds here instead.
 
@@ -34,7 +30,7 @@ limitations under the License.
 const fs = require("fs");
 const path = require("path");
 
-// The oldest glibc the pinned µWS binaries are built against. A runtime older than this loads the
+// The oldest glibc the pinned uWS binaries are built against. A runtime older than this loads the
 // file and then fails on a symbol, which is a worse error than not finding it at all.
 const MIN_GLIBC = "2.38";
 
@@ -44,8 +40,8 @@ const MIN_NODE = require("../package.json").engines.node.replace(/[^0-9.]/g, "")
 const MIN_NODE_MAJOR = MIN_NODE.split(".")[0];
 const SWAP_IMAGE = `node:${MIN_NODE_MAJOR}-trixie-slim`;
 
-// What a project may carry that needs a different API here rather than none. Everything that just
-// works, and everything that only wants a faster built-in, is `npx fulmine migrate`'s business.
+// What a project may carry that needs a different API here. Everything that just works is
+// `npx fulmine migrate`'s business.
 const NEEDS_A_LOOK = {
     "socket.io": "attach it with io.attachApp(app.uwsApp), not io.attach(server): there is no node socket to take over",
     ws: "the websocket server is µWS's own, through app.ws(path, behavior)",
@@ -55,9 +51,8 @@ const NEEDS_A_LOOK = {
 };
 
 /**
- * One line of the report. Three levels, and only one of them is a failure: an image that cannot
- * load the binary stops the deployment, while a dependency that wants a different call is
- * something to read, not something to fail a pipeline over.
+ * One line of the report. Only "no" is a failure: an image that cannot load the binary stops the
+ * deployment, a dependency that wants a different call does not.
  *
  * @param {"ok"|"note"|"no"} level
  * @param {string} what
@@ -92,9 +87,8 @@ function atLeast(version, minimum) {
 /**
  * The node this is running on, against what the package asks for.
  *
- * The version arrives as an argument rather than being read here, so the answer for a node this
- * machine is not running is testable from the machine it is not running on. Every check below
- * takes what it judges for the same reason.
+ * The version is an argument rather than read here, so a node this machine is not running is still
+ * testable. Every check below takes what it judges for the same reason.
  *
  * @param {string} [running] defaults to the node running this
  * @param {string} [required] defaults to what package.json asks for
@@ -115,15 +109,15 @@ function checkNode(running = process.versions.node, required = require("../packa
  * @returns {string|undefined}
  */
 function currentGlibc() {
-    return /** @type {any} */ (process.report.getReport()).header.glibcVersionRuntime;
+    return /** @type {{header: {glibcVersionRuntime?: string}}} */ (process.report.getReport()).header
+        .glibcVersionRuntime;
 }
 
 /**
  * Whether the C library is the one the binaries are linked against. Only linux has two of them.
  *
- * Both arguments are required, and deliberately: undefined is the answer that means musl, and a
- * default parameter fires on an explicit undefined, so a default here would quietly turn the musl
- * case into whatever this machine happens to run. Reading the machine is the caller's job.
+ * Both arguments are required on purpose: undefined means musl, and a default parameter fires on
+ * an explicit undefined, so a default would turn the musl case into whatever this machine runs.
  *
  * @param {string} platform
  * @param {string|undefined} glibc the runtime glibc, absent on musl
@@ -152,9 +146,8 @@ function checkLibc(platform, glibc) {
 }
 
 /**
- * Whether there is a µWebSockets.js binary for this platform, architecture and node ABI, which is
- * the failure that greets everyone who tries an unusual combination. The file is named rather than
- * loaded first, so the answer says which of the three does not line up.
+ * Whether there is a uWebSockets.js binary for this platform, architecture and node ABI. The file
+ * is named rather than loaded, so the answer says which of the three does not line up.
  *
  * @param {string} [platform]
  * @param {string} [arch]
@@ -214,12 +207,11 @@ function checkBinary(platform = process.platform, arch = process.arch, abi = pro
  */
 function abiToNode(abi) {
     const known = { 108: "18", 115: "20", 127: "22", 131: "23", 137: "24", 147: "26" };
-    return /** @type {any} */ (known)[abi] ?? `ABI ${abi}`;
+    return known[abi] ?? `ABI ${abi}`;
 }
 
 /**
- * The base images a Dockerfile names, which is where the musl question is usually answered without
- * anybody meaning to.
+ * The base images a Dockerfile names, which is where the musl question is usually answered.
  *
  * @param {string} dir the project being verified
  * @returns {ReturnType<typeof result>[]}
@@ -278,7 +270,7 @@ function checkDependencies(dir) {
     const installed = { ...pkg.dependencies, ...pkg.devDependencies };
     for (const name of Object.keys(NEEDS_A_LOOK)) {
         if (installed[name]) {
-            results.push(result("note", `${name} needs a different API here`, /** @type {any} */ (NEEDS_A_LOOK)[name]));
+            results.push(result("note", `${name} needs a different API here`, NEEDS_A_LOOK[name]));
         }
     }
     return results;
@@ -309,8 +301,7 @@ function verify(argv) {
             console.log(`        ${detail}`);
         }
     }
-    // only a blocked start is a failure. A dependency that wants a different call is worth
-    // reading and is not worth failing a pipeline over
+    // only a blocked start is a failure, a dependency that wants a different call is not
     const blocking = results.filter((entry) => entry.level === "no").length;
     const notes = results.filter((entry) => entry.level === "note").length;
     console.log(

package/src/view.js

@@ -73,9 +73,8 @@ module.exports = class View {
     }
 
     /**
-     * The first of the configured roots that actually holds this template, or undefined when none
-     * of them does. `views` may be a single directory or a list, and the list is searched in order,
-     * so an application can put its own templates in front of a package's.
+     * The first configured root that holds this template, or undefined. `views` may be one
+     * directory or a list, and the list is searched in order.
      *
      * @param {string} name template file name, relative to a root
      * @returns {string|undefined} absolute path to the file that exists
@@ -100,10 +99,9 @@ module.exports = class View {
     /**
      * Renders the template through its engine.
      *
-     * The callback is always delivered asynchronously, even when the engine answers on the spot.
-     * `sync` is still true only if the engine called back before this function returned, and in
-     * that case the callback is pushed to the next tick, so a caller never has to handle both
-     * orders. Express normalises it the same way.
+     * The callback is always delivered asynchronously, even when the engine answers on the spot:
+     * `sync` is true only if the engine called back before this returned, and then the callback
+     * goes to the next tick. Express does the same.
      *
      * @param {Record<string, any>} options locals and engine options, passed through untouched
      * @param {Function} callback called with whatever the engine passed, which is normally
@@ -115,7 +113,7 @@ module.exports = class View {
         this.engine(
             this.path,
             options,
-            /** @this {any} */ function onRender() {
+            /** @this {unknown} */ function onRender() {
                 if (!sync) {
                     return callback.apply(this, arguments);
                 }