chai 5.1.0 → 5.1.2

package/README.md

@@ -98,9 +98,9 @@ import { expect, use } from 'chai';  // Creates local variables `expect` and `us
 ### Usage with Mocha
 
 ```bash
-mocha spec.js -r chai/register-assert  # Using Assert style
-mocha spec.js -r chai/register-expect  # Using Expect style
-mocha spec.js -r chai/register-should  # Using Should style
+mocha spec.js --require chai/register-assert.js  # Using Assert style
+mocha spec.js --require chai/register-expect.js  # Using Expect style
+mocha spec.js --require chai/register-should.js  # Using Should style
 ```
 
 [Read more about these styles in our docs](http://chaijs.com/guide/styles/).

package/chai.js

@@ -37,7 +37,9 @@ __export(utils_exports, {
   hasProperty: () => hasProperty,
   inspect: () => inspect2,
   isNaN: () => isNaN2,
+  isNumeric: () => isNumeric,
   isProxyEnabled: () => isProxyEnabled,
+  isRegExp: () => isRegExp2,
   objDisplay: () => objDisplay,
   overwriteChainableMethod: () => overwriteChainableMethod,
   overwriteMethod: () => overwriteMethod,
@@ -57,14 +59,22 @@ __export(check_error_exports, {
   getConstructorName: () => getConstructorName,
   getMessage: () => getMessage
 });
+function isErrorInstance(obj) {
+  return obj instanceof Error || Object.prototype.toString.call(obj) === "[object Error]";
+}
+__name(isErrorInstance, "isErrorInstance");
+function isRegExp(obj) {
+  return Object.prototype.toString.call(obj) === "[object RegExp]";
+}
+__name(isRegExp, "isRegExp");
 function compatibleInstance(thrown, errorLike) {
-  return errorLike instanceof Error && thrown === errorLike;
+  return isErrorInstance(errorLike) && thrown === errorLike;
 }
 __name(compatibleInstance, "compatibleInstance");
 function compatibleConstructor(thrown, errorLike) {
-  if (errorLike instanceof Error) {
+  if (isErrorInstance(errorLike)) {
     return thrown.constructor === errorLike.constructor || thrown instanceof errorLike.constructor;
-  } else if (errorLike.prototype instanceof Error || errorLike === Error) {
+  } else if ((typeof errorLike === "object" || typeof errorLike === "function") && errorLike.prototype) {
     return thrown.constructor === errorLike || thrown instanceof errorLike;
   }
   return false;
@@ -72,7 +82,7 @@ function compatibleConstructor(thrown, errorLike) {
 __name(compatibleConstructor, "compatibleConstructor");
 function compatibleMessage(thrown, errMatcher) {
   const comparisonString = typeof thrown === "string" ? thrown : thrown.message;
-  if (errMatcher instanceof RegExp) {
+  if (isRegExp(errMatcher)) {
     return errMatcher.test(comparisonString);
   } else if (typeof errMatcher === "string") {
     return comparisonString.indexOf(errMatcher) !== -1;
@@ -82,7 +92,7 @@ function compatibleMessage(thrown, errMatcher) {
 __name(compatibleMessage, "compatibleMessage");
 function getConstructorName(errorLike) {
   let constructorName = errorLike;
-  if (errorLike instanceof Error) {
+  if (isErrorInstance(errorLike)) {
     constructorName = errorLike.constructor.name;
   } else if (typeof errorLike === "function") {
     constructorName = errorLike.name;
@@ -293,6 +303,10 @@ function normaliseOptions({
   return options;
 }
 __name(normaliseOptions, "normaliseOptions");
+function isHighSurrogate(char) {
+  return char >= "\uD800" && char <= "\uDBFF";
+}
+__name(isHighSurrogate, "isHighSurrogate");
 function truncate(string, length, tail = truncator) {
   string = String(string);
   const tailLength = tail.length;
@@ -301,7 +315,11 @@ function truncate(string, length, tail = truncator) {
     return tail;
   }
   if (stringLength > length && stringLength > tailLength) {
-    return `${string.slice(0, length - tailLength)}${tail}`;
+    let end = length - tailLength;
+    if (end > 0 && isHighSurrogate(string[end - 1])) {
+      end = end - 1;
+    }
+    return `${string.slice(0, end)}${tail}`;
   }
   return string;
 }
@@ -578,7 +596,7 @@ function inspectObject(object, options) {
   }
   options.truncate -= 4;
   options.seen = options.seen || [];
-  if (options.seen.indexOf(object) >= 0) {
+  if (options.seen.includes(object)) {
     return "[Circular]";
   }
   options.seen.push(object);
@@ -629,7 +647,8 @@ var errorKeys = [
   "lineNumber",
   "columnNumber",
   "number",
-  "description"
+  "description",
+  "cause"
 ];
 function inspectObject2(error, options) {
   const properties = Object.getOwnPropertyNames(error).filter((key) => errorKeys.indexOf(key) === -1);
@@ -643,6 +662,11 @@ function inspectObject2(error, options) {
   }
   message = message ? `: ${message}` : "";
   options.truncate -= message.length + 5;
+  options.seen = options.seen || [];
+  if (options.seen.includes(error)) {
+    return "[Circular]";
+  }
+  options.seen.push(error);
   const propertyContents = inspectList(properties.map((key) => [key, error[key]]), options, inspectProperty);
   return `${name}${message}${propertyContents ? ` { ${propertyContents} }` : ""}`;
 }
@@ -805,8 +829,8 @@ var config = {
    *
    *     chai.config.includeStack = true;  // enable stack on error
    *
-   * @param {Boolean}
-   * @api public
+   * @param {boolean}
+   * @public
    */
   includeStack: false,
   /**
@@ -818,8 +842,8 @@ var config = {
    * will be true when the assertion has requested a diff
    * be shown.
    *
-   * @param {Boolean}
-   * @api public
+   * @param {boolean}
+   * @public
    */
   showDiff: true,
   /**
@@ -838,8 +862,8 @@ var config = {
    *
    *     chai.config.truncateThreshold = 0;  // disable truncating
    *
-   * @param {Number}
-   * @api public
+   * @param {number}
+   * @public
    */
   truncateThreshold: 40,
   /**
@@ -856,8 +880,8 @@ var config = {
    * This feature is automatically disabled regardless of this config value
    * in environments that don't support proxies.
    *
-   * @param {Boolean}
-   * @api public
+   * @param {boolean}
+   * @public
    */
   useProxy: true,
   /**
@@ -875,7 +899,7 @@ var config = {
    *     chai.config.proxyExcludedKeys = ['then', 'inspect'];
    *
    * @param {Array}
-   * @api public
+   * @public
    */
   proxyExcludedKeys: ["then", "catch", "inspect", "toJSON"],
   /**
@@ -887,18 +911,18 @@ var config = {
    *
    *     // use a custom comparator
    *     chai.config.deepEqual = (expected, actual) => {
-   *        return chai.util.eql(expected, actual, {
-   *           comparator: (expected, actual) => {
-   *              // for non number comparison, use the default behavior
-   *              if(typeof expected !== 'number') return null;
-   *              // allow a difference of 10 between compared numbers
-   *              return typeof actual === 'number' && Math.abs(actual - expected) < 10
-   *           }
-   *        })
+   *         return chai.util.eql(expected, actual, {
+   *             comparator: (expected, actual) => {
+   *                 // for non number comparison, use the default behavior
+   *                 if(typeof expected !== 'number') return null;
+   *                 // allow a difference of 10 between compared numbers
+   *                 return typeof actual === 'number' && Math.abs(actual - expected) < 10
+   *             }
+   *         })
    *     };
    *
    * @param {Function}
-   * @api public
+   * @public
    */
   deepEqual: null
 };
@@ -1152,12 +1176,16 @@ function regexpEqual(leftHandOperand, rightHandOperand) {
 }
 __name(regexpEqual, "regexpEqual");
 function entriesEqual(leftHandOperand, rightHandOperand, options) {
-  if (leftHandOperand.size !== rightHandOperand.size) {
+  try {
+    if (leftHandOperand.size !== rightHandOperand.size) {
+      return false;
+    }
+    if (leftHandOperand.size === 0) {
+      return true;
+    }
+  } catch (sizeError) {
     return false;
   }
-  if (leftHandOperand.size === 0) {
-    return true;
-  }
   var leftHandItems = [];
   var rightHandItems = [];
   leftHandOperand.forEach(/* @__PURE__ */ __name(function gatherEntries(key, value) {
@@ -1809,6 +1837,14 @@ function getName(fn) {
   return fn.name;
 }
 __name(getName, "getName");
+function isRegExp2(obj) {
+  return Object.prototype.toString.call(obj) === "[object RegExp]";
+}
+__name(isRegExp2, "isRegExp");
+function isNumeric(obj) {
+  return ["Number", "BigInt"].includes(type(obj));
+}
+__name(isNumeric, "isNumeric");
 
 // lib/chai/core/assertions.js
 var { flag: flag2 } = utils_exports;
@@ -1995,6 +2031,15 @@ Assertion.addProperty("true", function() {
     flag2(this, "negate") ? false : true
   );
 });
+Assertion.addProperty("numeric", function() {
+  const object = flag2(this, "object");
+  this.assert(
+    ["Number", "BigInt"].includes(type(object)),
+    "expected #{this} to be numeric",
+    "expected #{this} to not be numeric",
+    flag2(this, "negate") ? false : true
+  );
+});
 Assertion.addProperty("callable", function() {
   const val = flag2(this, "object");
   const ssfi = flag2(this, "ssfi");
@@ -2143,22 +2188,17 @@ Assertion.addMethod("eqls", assertEql);
 function assertAbove(n, msg) {
   if (msg)
     flag2(this, "message", msg);
-  var obj = flag2(this, "object"), doLength = flag2(this, "doLength"), flagMsg = flag2(this, "message"), msgPrefix = flagMsg ? flagMsg + ": " : "", ssfi = flag2(this, "ssfi"), objType = type(obj).toLowerCase(), nType = type(n).toLowerCase(), errorMessage, shouldThrow = true;
+  var obj = flag2(this, "object"), doLength = flag2(this, "doLength"), flagMsg = flag2(this, "message"), msgPrefix = flagMsg ? flagMsg + ": " : "", ssfi = flag2(this, "ssfi"), objType = type(obj).toLowerCase(), nType = type(n).toLowerCase();
   if (doLength && objType !== "map" && objType !== "set") {
     new Assertion(obj, flagMsg, ssfi, true).to.have.property("length");
   }
   if (!doLength && (objType === "date" && nType !== "date")) {
-    errorMessage = msgPrefix + "the argument to above must be a date";
-  } else if (nType !== "number" && (doLength || objType === "number")) {
-    errorMessage = msgPrefix + "the argument to above must be a number";
-  } else if (!doLength && (objType !== "date" && objType !== "number")) {
+    throw new AssertionError(msgPrefix + "the argument to above must be a date", void 0, ssfi);
+  } else if (!isNumeric(n) && (doLength || isNumeric(obj))) {
+    throw new AssertionError(msgPrefix + "the argument to above must be a number", void 0, ssfi);
+  } else if (!doLength && (objType !== "date" && !isNumeric(obj))) {
     var printObj = objType === "string" ? "'" + obj + "'" : obj;
-    errorMessage = msgPrefix + "expected " + printObj + " to be a number or a date";
-  } else {
-    shouldThrow = false;
-  }
-  if (shouldThrow) {
-    throw new AssertionError(errorMessage, void 0, ssfi);
+    throw new AssertionError(msgPrefix + "expected " + printObj + " to be a number or a date", void 0, ssfi);
   }
   if (doLength) {
     var descriptor = "length", itemsCount;
@@ -2197,9 +2237,9 @@ function assertLeast(n, msg) {
   }
   if (!doLength && (objType === "date" && nType !== "date")) {
     errorMessage = msgPrefix + "the argument to least must be a date";
-  } else if (nType !== "number" && (doLength || objType === "number")) {
+  } else if (!isNumeric(n) && (doLength || isNumeric(obj))) {
     errorMessage = msgPrefix + "the argument to least must be a number";
-  } else if (!doLength && (objType !== "date" && objType !== "number")) {
+  } else if (!doLength && (objType !== "date" && !isNumeric(obj))) {
     var printObj = objType === "string" ? "'" + obj + "'" : obj;
     errorMessage = msgPrefix + "expected " + printObj + " to be a number or a date";
   } else {
@@ -2245,9 +2285,9 @@ function assertBelow(n, msg) {
   }
   if (!doLength && (objType === "date" && nType !== "date")) {
     errorMessage = msgPrefix + "the argument to below must be a date";
-  } else if (nType !== "number" && (doLength || objType === "number")) {
+  } else if (!isNumeric(n) && (doLength || isNumeric(obj))) {
     errorMessage = msgPrefix + "the argument to below must be a number";
-  } else if (!doLength && (objType !== "date" && objType !== "number")) {
+  } else if (!doLength && (objType !== "date" && !isNumeric(obj))) {
     var printObj = objType === "string" ? "'" + obj + "'" : obj;
     errorMessage = msgPrefix + "expected " + printObj + " to be a number or a date";
   } else {
@@ -2293,9 +2333,9 @@ function assertMost(n, msg) {
   }
   if (!doLength && (objType === "date" && nType !== "date")) {
     errorMessage = msgPrefix + "the argument to most must be a date";
-  } else if (nType !== "number" && (doLength || objType === "number")) {
+  } else if (!isNumeric(n) && (doLength || isNumeric(obj))) {
     errorMessage = msgPrefix + "the argument to most must be a number";
-  } else if (!doLength && (objType !== "date" && objType !== "number")) {
+  } else if (!doLength && (objType !== "date" && !isNumeric(obj))) {
     var printObj = objType === "string" ? "'" + obj + "'" : obj;
     errorMessage = msgPrefix + "expected " + printObj + " to be a number or a date";
   } else {
@@ -2341,9 +2381,9 @@ Assertion.addMethod("within", function(start, finish, msg) {
   }
   if (!doLength && (objType === "date" && (startType !== "date" || finishType !== "date"))) {
     errorMessage = msgPrefix + "the arguments to within must be dates";
-  } else if ((startType !== "number" || finishType !== "number") && (doLength || objType === "number")) {
+  } else if ((!isNumeric(start) || !isNumeric(finish)) && (doLength || isNumeric(obj))) {
     errorMessage = msgPrefix + "the arguments to within must be numbers";
-  } else if (!doLength && (objType !== "date" && objType !== "number")) {
+  } else if (!doLength && (objType !== "date" && !isNumeric(obj))) {
     var printObj = objType === "string" ? "'" + obj + "'" : obj;
     errorMessage = msgPrefix + "expected " + printObj + " to be a number or a date";
   } else {
@@ -2659,14 +2699,16 @@ function assertThrows(errorLike, errMsgMatcher, msg) {
     flag2(this, "message", msg);
   var obj = flag2(this, "object"), ssfi = flag2(this, "ssfi"), flagMsg = flag2(this, "message"), negate = flag2(this, "negate") || false;
   new Assertion(obj, flagMsg, ssfi, true).is.a("function");
-  if (errorLike instanceof RegExp || typeof errorLike === "string") {
+  if (isRegExp2(errorLike) || typeof errorLike === "string") {
     errMsgMatcher = errorLike;
     errorLike = null;
   }
-  var caughtErr;
+  let caughtErr;
+  let errorWasThrown = false;
   try {
     obj();
   } catch (err) {
+    errorWasThrown = true;
     caughtErr = err;
   }
   var everyArgIsUndefined = errorLike === void 0 && errMsgMatcher === void 0;
@@ -2680,12 +2722,23 @@ function assertThrows(errorLike, errMsgMatcher, msg) {
     } else if (errorLike) {
       errorLikeString = check_error_exports.getConstructorName(errorLike);
     }
+    let actual = caughtErr;
+    if (caughtErr instanceof Error) {
+      actual = caughtErr.toString();
+    } else if (typeof caughtErr === "string") {
+      actual = caughtErr;
+    } else if (caughtErr && (typeof caughtErr === "object" || typeof caughtErr === "function")) {
+      try {
+        actual = check_error_exports.getConstructorName(caughtErr);
+      } catch (_err) {
+      }
+    }
     this.assert(
-      caughtErr,
+      errorWasThrown,
       "expected #{this} to throw " + errorLikeString,
       "expected #{this} to not throw an error but #{act} was thrown",
       errorLike && errorLike.toString(),
-      caughtErr instanceof Error ? caughtErr.toString() : typeof caughtErr === "string" ? caughtErr : caughtErr && check_error_exports.getConstructorName(caughtErr)
+      actual
     );
   }
   if (errorLike && caughtErr) {
@@ -2722,7 +2775,7 @@ function assertThrows(errorLike, errMsgMatcher, msg) {
   }
   if (caughtErr && errMsgMatcher !== void 0 && errMsgMatcher !== null) {
     var placeholder = "including";
-    if (errMsgMatcher instanceof RegExp) {
+    if (isRegExp2(errMsgMatcher)) {
       placeholder = "matching";
     }
     var isCompatibleMessage = check_error_exports.compatibleMessage(caughtErr, errMsgMatcher);
@@ -2791,18 +2844,18 @@ function closeTo(expected, delta, msg) {
   if (msg)
     flag2(this, "message", msg);
   var obj = flag2(this, "object"), flagMsg = flag2(this, "message"), ssfi = flag2(this, "ssfi");
-  new Assertion(obj, flagMsg, ssfi, true).is.a("number");
-  if (typeof expected !== "number" || typeof delta !== "number") {
-    flagMsg = flagMsg ? flagMsg + ": " : "";
-    var deltaMessage = delta === void 0 ? ", and a delta is required" : "";
-    throw new AssertionError(
-      flagMsg + "the arguments to closeTo or approximately must be numbers" + deltaMessage,
-      void 0,
-      ssfi
-    );
-  }
+  new Assertion(obj, flagMsg, ssfi, true).is.numeric;
+  let message = "A `delta` value is required for `closeTo`";
+  if (delta == void 0)
+    throw new AssertionError(flagMsg ? `${flagMsg}: ${message}` : message, void 0, ssfi);
+  new Assertion(delta, flagMsg, ssfi, true).is.numeric;
+  message = "A `expected` value is required for `closeTo`";
+  if (expected == void 0)
+    throw new AssertionError(flagMsg ? `${flagMsg}: ${message}` : message, void 0, ssfi);
+  new Assertion(expected, flagMsg, ssfi, true).is.numeric;
+  const abs = /* @__PURE__ */ __name((x) => x < 0n ? -x : x, "abs");
   this.assert(
-    Math.abs(obj - expected) <= delta,
+    abs(obj - expected) <= delta,
     "expected #{this} to be close to " + expected + " +/- " + delta,
     "expected #{this} not to be close to " + expected + " +/- " + delta
   );
@@ -3126,8 +3179,8 @@ function loadShould() {
       operator
     }, should2.fail);
   };
-  should2.equal = function(val1, val2, msg) {
-    new Assertion(val1, msg).to.equal(val2);
+  should2.equal = function(actual, expected, message) {
+    new Assertion(actual, message).to.equal(expected);
   };
   should2.Throw = function(fn, errt, errs, msg) {
     new Assertion(fn, msg).to.Throw(errt, errs);
@@ -3136,8 +3189,8 @@ function loadShould() {
     new Assertion(val, msg).to.exist;
   };
   should2.not = {};
-  should2.not.equal = function(val1, val2, msg) {
-    new Assertion(val1, msg).to.not.equal(val2);
+  should2.not.equal = function(actual, expected, msg) {
+    new Assertion(actual, msg).to.not.equal(expected);
   };
   should2.not.Throw = function(fn, errt, errs, msg) {
     new Assertion(fn, msg).to.not.Throw(errt, errs);
@@ -3248,8 +3301,8 @@ assert.isNotNull = function(val, msg) {
 assert.isNaN = function(val, msg) {
   new Assertion(val, msg, assert.isNaN, true).to.be.NaN;
 };
-assert.isNotNaN = function(val, msg) {
-  new Assertion(val, msg, assert.isNotNaN, true).not.to.be.NaN;
+assert.isNotNaN = function(value, message) {
+  new Assertion(value, message, assert.isNotNaN, true).not.to.be.NaN;
 };
 assert.exists = function(val, msg) {
   new Assertion(val, msg, assert.exists, true).to.exist;
@@ -3263,11 +3316,11 @@ assert.isUndefined = function(val, msg) {
 assert.isDefined = function(val, msg) {
   new Assertion(val, msg, assert.isDefined, true).to.not.equal(void 0);
 };
-assert.isCallable = function(val, msg) {
-  new Assertion(val, msg, assert.isCallable, true).is.callable;
+assert.isCallable = function(value, message) {
+  new Assertion(value, message, assert.isCallable, true).is.callable;
 };
-assert.isNotCallable = function(val, msg) {
-  new Assertion(val, msg, assert.isNotCallable, true).is.not.callable;
+assert.isNotCallable = function(value, message) {
+  new Assertion(value, message, assert.isNotCallable, true).is.not.callable;
 };
 assert.isObject = function(val, msg) {
   new Assertion(val, msg, assert.isObject, true).to.be.a("object");
@@ -3293,6 +3346,12 @@ assert.isNumber = function(val, msg) {
 assert.isNotNumber = function(val, msg) {
   new Assertion(val, msg, assert.isNotNumber, true).to.not.be.a("number");
 };
+assert.isNumeric = function(val, msg) {
+  new Assertion(val, msg, assert.isNumeric, true).is.numeric;
+};
+assert.isNotNumeric = function(val, msg) {
+  new Assertion(val, msg, assert.isNotNumeric, true).is.not.numeric;
+};
 assert.isFinite = function(val, msg) {
   new Assertion(val, msg, assert.isFinite, true).to.be.finite;
 };
@@ -3305,8 +3364,8 @@ assert.isNotBoolean = function(val, msg) {
 assert.typeOf = function(val, type3, msg) {
   new Assertion(val, msg, assert.typeOf, true).to.be.a(type3);
 };
-assert.notTypeOf = function(val, type3, msg) {
-  new Assertion(val, msg, assert.notTypeOf, true).to.not.be.a(type3);
+assert.notTypeOf = function(value, type3, message) {
+  new Assertion(value, message, assert.notTypeOf, true).to.not.be.a(type3);
 };
 assert.instanceOf = function(val, type3, msg) {
   new Assertion(val, msg, assert.instanceOf, true).to.be.instanceOf(type3);
@@ -3451,12 +3510,12 @@ assert.throws = function(fn, errorLike, errMsgMatcher, msg) {
   var assertErr = new Assertion(fn, msg, assert.throws, true).to.throw(errorLike, errMsgMatcher);
   return flag(assertErr, "object");
 };
-assert.doesNotThrow = function(fn, errorLike, errMsgMatcher, msg) {
+assert.doesNotThrow = function(fn, errorLike, errMsgMatcher, message) {
   if ("string" === typeof errorLike || errorLike instanceof RegExp) {
     errMsgMatcher = errorLike;
     errorLike = null;
   }
-  new Assertion(fn, msg, assert.doesNotThrow, true).to.not.throw(errorLike, errMsgMatcher);
+  new Assertion(fn, message, assert.doesNotThrow, true).to.not.throw(errorLike, errMsgMatcher);
 };
 assert.operator = function(val, operator, val2, msg) {
   var ok;

package/eslint.config.js

@@ -0,0 +1,12 @@
+import jsdoc from "eslint-plugin-jsdoc";
+
+export default [
+  jsdoc.configs["flat/recommended"],
+  {
+    rules: {
+      "jsdoc/require-param-description": "off",
+      "jsdoc/require-returns-description": "off",
+      "jsdoc/tag-lines": ["error", "any", { startLines: 1 }],
+    },
+  },
+];

package/lib/chai/assertion.js

@@ -18,37 +18,37 @@ import * as util from './utils/index.js';
  * be assigned during instantiation by passing arguments to this constructor:
  *
  * - `object`: This flag contains the target of the assertion. For example, in
- *   the assertion `expect(numKittens).to.equal(7);`, the `object` flag will
- *   contain `numKittens` so that the `equal` assertion can reference it when
- *   needed.
+ * the assertion `expect(numKittens).to.equal(7);`, the `object` flag will
+ * contain `numKittens` so that the `equal` assertion can reference it when
+ * needed.
  *
  * - `message`: This flag contains an optional custom error message to be
- *   prepended to the error message that's generated by the assertion when it
- *   fails.
+ * prepended to the error message that's generated by the assertion when it
+ * fails.
  *
  * - `ssfi`: This flag stands for "start stack function indicator". It
- *   contains a function reference that serves as the starting point for
- *   removing frames from the stack trace of the error that's created by the
- *   assertion when it fails. The goal is to provide a cleaner stack trace to
- *   end users by removing Chai's internal functions. Note that it only works
- *   in environments that support `Error.captureStackTrace`, and only when
- *   `Chai.config.includeStack` hasn't been set to `false`.
+ * contains a function reference that serves as the starting point for
+ * removing frames from the stack trace of the error that's created by the
+ * assertion when it fails. The goal is to provide a cleaner stack trace to
+ * end users by removing Chai's internal functions. Note that it only works
+ * in environments that support `Error.captureStackTrace`, and only when
+ * `Chai.config.includeStack` hasn't been set to `false`.
  *
  * - `lockSsfi`: This flag controls whether or not the given `ssfi` flag
- *   should retain its current value, even as assertions are chained off of
- *   this object. This is usually set to `true` when creating a new assertion
- *   from within another assertion. It's also temporarily set to `true` before
- *   an overwritten assertion gets called by the overwriting assertion.
+ * should retain its current value, even as assertions are chained off of
+ * this object. This is usually set to `true` when creating a new assertion
+ * from within another assertion. It's also temporarily set to `true` before
+ * an overwritten assertion gets called by the overwriting assertion.
  *
  * - `eql`: This flag contains the deepEqual function to be used by the assertion.
  *
- * @param {Mixed} obj target of the assertion
- * @param {String} msg (optional) custom error message
+ * @param {unknown} obj target of the assertion
+ * @param {string} msg (optional) custom error message
  * @param {Function} ssfi (optional) starting point for removing stack frames
- * @param {Boolean} lockSsfi (optional) whether or not the ssfi flag is locked
- * @api private
+ * @param {boolean} lockSsfi (optional) whether or not the ssfi flag is locked
+ * @returns {unknown}
+ * @private
  */
-
 export function Assertion (obj, msg, ssfi, lockSsfi) {
   util.flag(this, 'ssfi', ssfi || Assertion);
   util.flag(this, 'lockSsfi', lockSsfi);
@@ -111,13 +111,13 @@ Assertion.overwriteChainableMethod = function (name, fn, chainingBehavior) {
  * Executes an expression and check expectations. Throws AssertionError for reporting if test doesn't pass.
  *
  * @name assert
- * @param {Philosophical} expression to be tested
- * @param {String|Function} message or function that returns message to display if expression fails
- * @param {String|Function} negatedMessage or function that returns negatedMessage to display if negated expression fails
- * @param {Mixed} expected value (remember to check for negation)
- * @param {Mixed} actual (optional) will default to `this.obj`
- * @param {Boolean} showDiff (optional) when set to `true`, assert will display a diff in addition to the message if expression fails
- * @api private
+ * @param {unknown} expression to be tested
+ * @param {string | Function} message or function that returns message to display if expression fails
+ * @param {string | Function} negatedMessage or function that returns negatedMessage to display if negated expression fails
+ * @param {unknown} expected value (remember to check for negation)
+ * @param {unknown} actual (optional) will default to `this.obj`
+ * @param {boolean} showDiff (optional) when set to `true`, assert will display a diff in addition to the message if expression fails
+ * @private
  */
 
 Assertion.prototype.assert = function (expr, msg, negateMsg, expected, _actual, showDiff) {
@@ -152,7 +152,7 @@ Assertion.prototype.assert = function (expr, msg, negateMsg, expected, _actual,
  *
  * Quick reference to stored `actual` value for plugin developers.
  *
- * @api private
+ * @private
  */
 Object.defineProperty(Assertion.prototype, '_obj',
   { get: function () {