@cjser/clean-stack 6.0.0-cjser.2 → 7.0.0-cjser.2

package/dist-cjser/index.cjs

@@ -26,7 +26,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// packages/@cjser/clean-stack/index.js
+// packages/@cjser/clean-stack.tmp-24-1793723115467/index.js
 var index_exports = {};
 __export(index_exports, {
   default: () => cleanStack
@@ -34,52 +34,102 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 var import_escape_string_regexp = __toESM(require("@cjser/escape-string-regexp"), 1);
 var import_url_extras = require("@cjser/url-extras");
-var extractPathRegex = /\s+at.*[(\s](.*)\)?/;
-var pathRegex = /^(?:(?:(?:node|node:[\w/]+|(?:(?:node:)?internal\/[\w/]*|.*node_modules\/(?:babel-polyfill|pirates)\/.*)?\w+)(?:\.js)?:\d+:\d+)|native)/;
-var simplePathRegex = /^\w+\.js:\d+:\d+$/;
+var frameStartRegex = new RegExp("^\\s+at\\b", "v");
+var pathRegex = new RegExp("^(?:(?:node|node:[\\w\\-\\/]+|internal\\/[\\w\\/]+(?<!\\/)|\\w+)(?:\\.js)?:\\d+:\\d+|native$)", "v");
+var asyncPrefixRegex = new RegExp("^(?:async|new) ", "v");
+var bareFrameEndRegex = new RegExp(":(?:\\d+:\\d+|0x[\\da-f]+)$", "v");
+var simplePathRegex = new RegExp("^\\w+\\.js:\\d+:\\d+$", "v");
+function getFrame(line) {
+  const frameStart = frameStartRegex.exec(line);
+  if (!frameStart) {
+    return void 0;
+  }
+  const end = line.trimEnd().length;
+  if (line[end - 1] === ")") {
+    let depth = 0;
+    let pathStart = -1;
+    for (let index = frameStart[0].length; index < end; index++) {
+      const character = line[index];
+      if (character === "(") {
+        if (depth === 0) {
+          pathStart = index + 1;
+        }
+        depth++;
+      } else if (character === ")" && depth > 0) {
+        depth--;
+      }
+    }
+    if (pathStart !== -1) {
+      const path2 = line.slice(pathStart, end - 1);
+      return path2 === "" ? void 0 : { path: path2, pathIndex: pathStart, hasFunctionName: true };
+    }
+  }
+  const rest = line.slice(frameStart[0].length, end).trimStart();
+  const path = asyncPrefixRegex.test(rest) ? rest.slice(rest.indexOf(" ") + 1) : rest;
+  return path === "native" || bareFrameEndRegex.test(path) ? { path, pathIndex: end - path.length, hasFunctionName: false } : void 0;
+}
 function cleanStack(stack, { pretty = false, basePath, pathFilter } = {}) {
-  var _a;
+  var _a, _b;
   if (typeof stack !== "string") {
     return void 0;
   }
-  const basePathRegex = basePath && new RegExp(`(file://)?${(0, import_escape_string_regexp.default)(basePath.replaceAll("\\", "/"))}/?`, "g");
+  const slashedBasePath = basePath == null ? void 0 : basePath.replaceAll("\\", "/");
+  const isAbsoluteBasePath = Boolean(slashedBasePath == null ? void 0 : slashedBasePath.startsWith("/"));
+  const isWindowsDrivePath = new RegExp("^[A-Za-z]:", "v").test(slashedBasePath ?? "");
+  const normalizedBasePath = slashedBasePath == null ? void 0 : slashedBasePath.split("/").filter((segment) => segment !== "").join("/");
+  let basePathPrefix = "";
+  if (isAbsoluteBasePath) {
+    basePathPrefix = "(?:file:///?|/{1,2})";
+  } else if (isWindowsDrivePath) {
+    basePathPrefix = "(?:file:///)?";
+  }
+  const basePathBoundary = normalizedBasePath === "" ? "" : "(?:/|$)";
+  const basePathRegex = basePath && new RegExp(`^${basePathPrefix}${(0, import_escape_string_regexp.default)(normalizedBasePath)}${basePathBoundary}`, "gv");
   let homeDirectory = "";
   if (pretty) {
-    const os = (_a = process.getBuiltinModule) == null ? void 0 : _a.call(process, "node:os");
+    const os = (_b = (_a = globalThis.process) == null ? void 0 : _a.getBuiltinModule) == null ? void 0 : _b.call(_a, "node:os");
     homeDirectory = os ? os.homedir().replaceAll("\\", "/") : "";
+    while (homeDirectory.length > 1 && homeDirectory.endsWith("/")) {
+      homeDirectory = homeDirectory.slice(0, -1);
+    }
   }
-  return stack.replaceAll("\\", "/").split("\n").filter((line) => {
-    const pathMatches = line.match(extractPathRegex);
-    if (!(pathMatches == null ? void 0 : pathMatches[1])) {
+  const lines = stack.split("\n").map((rawLine) => {
+    const frame = getFrame(rawLine);
+    return {
+      line: frame ? rawLine.replaceAll("\\", "/") : rawLine,
+      path: frame == null ? void 0 : frame.path.replaceAll("\\", "/"),
+      pathIndex: frame == null ? void 0 : frame.pathIndex,
+      hasFunctionName: frame == null ? void 0 : frame.hasFunctionName
+    };
+  });
+  return lines.filter(({ path, hasFunctionName }) => {
+    if (path === void 0) {
       return true;
     }
-    const match = pathMatches[1];
-    if (match.includes(".app/Contents/Resources/electron.asar") || match.includes(".app/Contents/Resources/default_app.asar") || match.includes("node_modules/electron/dist/resources/electron.asar") || match.includes("node_modules/electron/dist/resources/default_app.asar")) {
+    const isInternalPath = pathRegex.test(path) && (hasFunctionName || !simplePathRegex.test(path));
+    if (isInternalPath || path.includes(".app/Contents/Resources/electron.asar") || path.includes(".app/Contents/Resources/default_app.asar") || path.includes("node_modules/electron/dist/resources/electron.asar") || path.includes("node_modules/electron/dist/resources/default_app.asar") || path.includes("node_modules/babel-polyfill/") || path.includes("node_modules/pirates/")) {
       return false;
     }
-    if (simplePathRegex.test(match)) {
-      return true;
-    }
-    if (pathRegex.test(match)) {
-      return false;
+    return pathFilter ? pathFilter(path) : true;
+  }).filter(({ line }) => line.trim() !== "").map(({ line, path, pathIndex }) => {
+    if (path === void 0 || !basePathRegex && !pretty) {
+      return line;
     }
-    return pathFilter ? pathFilter(match) : true;
-  }).filter((line) => line.trim() !== "").map((line) => {
+    let newPath = path;
     if (basePathRegex) {
-      line = line.replace(basePathRegex, "");
+      newPath = newPath.replaceAll(basePathRegex, "");
     }
     if (pretty) {
-      line = line.replace(extractPathRegex, (m, p1) => {
-        let filePath = p1;
-        if (filePath.startsWith("file://")) {
-          filePath = (0, import_url_extras.fileURLToPath)(filePath);
-        }
-        if (homeDirectory) {
-          filePath = filePath.replace(homeDirectory, "~");
+      if (newPath.startsWith("file://") && !new RegExp("[#?]|%0[ad]", "iv").test(newPath)) {
+        try {
+          newPath = (0, import_url_extras.fileURLToPath)(newPath).replaceAll("\\", "/");
+        } catch {
         }
-        return m.replace(p1, filePath);
-      });
+      }
+      if (homeDirectory && (newPath === homeDirectory || newPath.startsWith(homeDirectory + "/"))) {
+        newPath = "~" + newPath.slice(homeDirectory.length);
+      }
     }
-    return line;
+    return line.slice(0, pathIndex) + newPath + line.slice(pathIndex + path.length);
   }).join("\n");
 }

package/index.d.ts

@@ -5,23 +5,33 @@ export type Options = {
 	- `/Users/sindresorhus/dev/clean-stack/unicorn.js:2:15` → `~/dev/clean-stack/unicorn.js:2:15`
 	- `file:///Users/sindresorhus/dev/clean-stack/unicorn.js:2:15` → `~/dev/clean-stack/unicorn.js:2:15`
 
-	When enabled, file URLs are converted to regular paths for better readability and IDE integration.
+	When enabled, file URLs are converted to regular paths for better readability and IDE integration. URLs that cannot be converted, contain `?` or `#`, or decode to a line break are left unchanged.
+
+	`pretty` and `basePath` only rewrite frame paths. Backslashes become `/` throughout each frame. Error message text is preserved except for blank lines; lines shaped like frames are treated as frames.
 
 	@default false
 	*/
 	readonly pretty?: boolean;
 
 	/**
-	Remove the given base path from stack trace file paths, effectively turning absolute paths into relative ones.
+	Remove the given base path from stack trace file paths, effectively turning absolute paths into relative ones. It will also transform absolute file URLs into relative paths.
+
+	Supports absolute or relative paths, either separator, and the filesystem root. A leading slash only matches absolute paths. Relative base paths do not match inside `file:///`, except Windows drive paths such as `C:/Users`.
 
-	Example with `'/Users/sindresorhus/dev/clean-stack/'` as `basePath`:
+	Example with `'/Users/sindresorhus/dev/clean-stack'` as `basePath`:
 
 	`/Users/sindresorhus/dev/clean-stack/unicorn.js:2:15` → `unicorn.js:2:15`
+
+	`basePath` matches before file URLs are decoded, so `/Users/John Doe/dev` does not match `file:///Users/John%20Doe/dev`. After a match, remaining URL escapes stay encoded, even with `pretty`.
+
+	Frames like `at fn (unicorn.js:2:15)` are removed because they resemble old internal Node.js frames. Cleaning again after `basePath` produces this form can therefore drop frames for files directly in the base path. Paths with a directory, like `at fn (src/unicorn.js:2:15)`, and bare frames like `at unicorn.js:2:15` are unaffected.
 	*/
 	readonly basePath?: string;
 
 	/**
-	Remove the stack lines where the given function returns `false`. The function receives the path part of the stack line.
+	Remove stack lines where the callback returns `false`. It receives the path without the closing parenthesis, with `/` separators, before `basePath` or `pretty` is applied. A pathless frame such as `at async Promise.all (index 0)` yields `index 0`.
+
+	Balanced parentheses in function names, such as `at render (partial) (/base/a.js:6:9)`, and paths, such as `C:/Program Files (x86)/app.js:1:1`, are supported. Unbalanced parentheses in a function name, such as `at a(b (/base/a.js:6:9)`, can cause part of the name to be included in the path.
 
 	@example
 	```
@@ -47,8 +57,8 @@ export type Options = {
 /**
 Clean up error stack traces. Removes the mostly unhelpful internal Node.js entries.
 
-@param stack - The `stack` property of an `Error`.
-@returns The cleaned stack or `undefined` if the given `stack` is `undefined`.
+@param stack - The `stack` property of an `Error`, or `undefined`.
+@returns The cleaned stack or `undefined` if the given `stack` is not a string.
 
 @example
 ```

package/index.js

@@ -1,81 +1,194 @@
 import escapeStringRegexp from '@cjser/escape-string-regexp';
 import {fileURLToPath} from '@cjser/url-extras';
 
-const extractPathRegex = /\s+at.*[(\s](.*)\)?/;
-const pathRegex = /^(?:(?:(?:node|node:[\w/]+|(?:(?:node:)?internal\/[\w/]*|.*node_modules\/(?:babel-polyfill|pirates)\/.*)?\w+)(?:\.js)?:\d+:\d+)|native)/;
-const simplePathRegex = /^\w+\.js:\d+:\d+$/;
+// A frame is indented, so a line that starts with `at` in the first column is text.
+const frameStartRegex = /^\s+at\b/v;
+// A `node:` module name is not limited to word characters, as names such as
+// `node:internal/fs/cp/cp-sync` and `node:internal/tls/secure-context` contain a dash. A
+// bare `internal/` path keeps its old shape, so that a project of its own keeps at
+// least the frames whose name holds a dash.
+const pathRegex = /^(?:(?:node|node:[\w\-\/]+|internal\/[\w\/]+(?<!\/)|\w+)(?:\.js)?:\d+:\d+|native$)/v;
+// The only prefixes V8 puts on a frame that has no function name.
+const asyncPrefixRegex = /^(?:async|new) /v;
+// A bare frame has no parentheses to end it, so it is recognised by the location it ends
+// in: `:line:column` for a file, as in `at /a/b.js:1:2`, or `:0x…` for the offset of a
+// WebAssembly function. The colon is part of that, so `/a/0xdeadbeef` is text, and it
+// keeps the scan to the colons of the line.
+const bareFrameEndRegex = /:(?:\d+:\d+|0x[\da-f]+)$/v;
+const simplePathRegex = /^\w+\.js:\d+:\d+$/v;
+
+// A stack frame is `at <function name> (<path>)`, or just `at <path>` when there is no
+// function name. A line has to start with `at` for either form, so an error message that
+// merely holds ` at ` is never mistaken for a frame, which is what `frameStartRegex` is
+// for. A frame also has to end the way a frame ends, so that an indented line of a
+// multi-line error message, such as `    at least one plugin is broken`, is text and can
+// never be handed to `pathFilter`.
+//
+// The path is found by index and not by a regex, as a path can hold both a space and a
+// parenthesis, as in `C:/Program Files (x86)/app.js:1:1`, which a regex has to
+// backtrack over. `pathIndex` is where the path starts in the line, and
+// `hasFunctionName` tells a bare simple relative path, which may be the user's own, from
+// the same name inside `at fn (…)`, which is an old internal Node.js frame.
+function getFrame(line) {
+	const frameStart = frameStartRegex.exec(line);
+	if (!frameStart) {
+		return undefined;
+	}
+
+	// Trailing whitespace is part of neither form of the path, and a CRLF line keeps
+	// its `\r`.
+	const end = line.trimEnd().length;
+
+	// `at fn (/a/b.js:1:2)` — the path is what sits inside the parenthesis the frame ends
+	// with. A function name can hold a balanced parenthesis of its own, as V8 prints a
+	// computed key verbatim, and a path can hold one too, as in
+	// `C:/Program Files (x86)/app.js:1:1` or `paren)dir/app.js`, so the one to take is the
+	// last that is not inside another.
+	if (line[end - 1] === ')') {
+		let depth = 0;
+		let pathStart = -1;
+		for (let index = frameStart[0].length; index < end; index++) {
+			const character = line[index];
+			if (character === '(') {
+				if (depth === 0) {
+					pathStart = index + 1;
+				}
+
+				depth++;
+			} else if (character === ')' && depth > 0) {
+				depth--;
+			}
+		}
+
+		if (pathStart !== -1) {
+			const path = line.slice(pathStart, end - 1);
+			return path === '' ? undefined : {path, pathIndex: pathStart, hasFunctionName: true};
+		}
+	}
+
+	// `at /a/b.js:1:2`, and the `async` or `new` form of it. Everything after `at` is
+	// the path, so that a path holding a space survives. `at native` is the one bare
+	// frame without a line and column.
+	const rest = line.slice(frameStart[0].length, end).trimStart();
+	const path = asyncPrefixRegex.test(rest) ? rest.slice(rest.indexOf(' ') + 1) : rest;
+	// The path is the tail of the line, so `pathIndex` holds for the trimmed and the
+	// `async`/`new` form too.
+	return path === 'native' || bareFrameEndRegex.test(path)
+		? {path, pathIndex: end - path.length, hasFunctionName: false}
+		: undefined;
+}
 
 export default function cleanStack(stack, {pretty = false, basePath, pathFilter} = {}) {
 	if (typeof stack !== 'string') {
 		return undefined;
 	}
 
-	const basePathRegex = basePath && new RegExp(`(file://)?${escapeStringRegexp(basePath.replaceAll('\\', '/'))}/?`, 'g');
+	// Windows separators become `/`, and empty segments are dropped so that `/dev`,
+	// `//server/dev`, and `/dev/` name the same base path. A base path that started with
+	// a slash only ever matches an absolute path, as `dev/a.js` is not below `/dev`.
+	const slashedBasePath = basePath?.replaceAll('\\', '/');
+	const isAbsoluteBasePath = Boolean(slashedBasePath?.startsWith('/'));
+	const isWindowsDrivePath = /^[A-Za-z]:/v.test(slashedBasePath ?? '');
+	const normalizedBasePath = slashedBasePath?.split('/').filter(segment => segment !== '').join('/');
+
+	// The base path must be the *whole* leading part of a path, otherwise
+	// `/Users/foo/dev` would truncate `/Users/foo/development` into `elopment`. A file
+	// URL carries its own leading slash, so `file:///dev` matches as `/dev` does. A
+	// Windows drive path is absolute in practice, and a relative base path is not, so
+	// only the former may reach behind `file:///`.
+	let basePathPrefix = '';
+	if (isAbsoluteBasePath) {
+		basePathPrefix = '(?:file:///?|/{1,2})';
+	} else if (isWindowsDrivePath) {
+		basePathPrefix = '(?:file:///)?';
+	}
+
+	const basePathBoundary = normalizedBasePath === '' ? '' : '(?:/|$)';
+	const basePathRegex = basePath && new RegExp(`^${basePathPrefix}${escapeStringRegexp(normalizedBasePath)}${basePathBoundary}`, 'gv');
 
 	let homeDirectory = '';
 	if (pretty) {
-		const os = process.getBuiltinModule?.('node:os');
+		const os = globalThis.process?.getBuiltinModule?.('node:os');
 		homeDirectory = os ? os.homedir().replaceAll('\\', '/') : '';
+		// `HOME` can end with separators, which the comparison below would double.
+		while (homeDirectory.length > 1 && homeDirectory.endsWith('/')) {
+			homeDirectory = homeDirectory.slice(0, -1);
+		}
 	}
 
-	return stack.replaceAll('\\', '/')
-		.split('\n')
-		.filter(line => {
-			const pathMatches = line.match(extractPathRegex);
-			if (!pathMatches?.[1]) {
+	const lines = stack.split('\n').map(rawLine => {
+		const frame = getFrame(rawLine);
+
+		// Windows separators become `/`, but only in a stack frame. An error message can
+		// hold a path of its own, and that text must survive untouched. The separators
+		// do not change the length of the line, so `pathIndex` stays valid.
+		return {
+			line: frame ? rawLine.replaceAll('\\', '/') : rawLine,
+			path: frame?.path.replaceAll('\\', '/'),
+			pathIndex: frame?.pathIndex,
+			hasFunctionName: frame?.hasFunctionName,
+		};
+	});
+
+	return lines
+		.filter(({path, hasFunctionName}) => {
+			if (path === undefined) {
 				return true; // Keep lines without paths (like error messages)
 			}
 
-			const match = pathMatches[1];
-
-			// Filter out Electron internal paths
+			// Filter out Electron internal paths, and internal Node.js paths. A bare simple
+			// relative path like `foo.js:1:1` matches the Node.js pattern, so it is
+			// exempted from that part only. The user's `pathFilter` still applies to it.
+			const isInternalPath = pathRegex.test(path) && (hasFunctionName || !simplePathRegex.test(path));
 			if (
-				match.includes('.app/Contents/Resources/electron.asar')
-				|| match.includes('.app/Contents/Resources/default_app.asar')
-				|| match.includes('node_modules/electron/dist/resources/electron.asar')
-				|| match.includes('node_modules/electron/dist/resources/default_app.asar')
+				isInternalPath
+				|| path.includes('.app/Contents/Resources/electron.asar')
+				|| path.includes('.app/Contents/Resources/default_app.asar')
+				|| path.includes('node_modules/electron/dist/resources/electron.asar')
+				|| path.includes('node_modules/electron/dist/resources/default_app.asar')
+				|| path.includes('node_modules/babel-polyfill/')
+				|| path.includes('node_modules/pirates/')
 			) {
 				return false;
 			}
 
-			// Keep simple relative paths like 'foo.js:1:1'
-			if (simplePathRegex.test(match)) {
-				return true;
+			return pathFilter ? pathFilter(path) : true;
+		})
+		.filter(({line}) => line.trim() !== '')
+		.map(({line, path, pathIndex}) => {
+			if (path === undefined || (!basePathRegex && !pretty)) {
+				return line;
 			}
 
-			// Filter out internal Node.js paths
-			if (pathRegex.test(match)) {
-				return false;
-			}
+			// `basePath` and `pretty` only ever apply to the path of a stack frame,
+			// never to the error message or the function name.
+			let newPath = path;
 
-			// Apply user's path filter if provided
-			return pathFilter ? pathFilter(match) : true;
-		})
-		.filter(line => line.trim() !== '')
-		.map(line => {
 			if (basePathRegex) {
-				line = line.replace(basePathRegex, '');
+				newPath = newPath.replaceAll(basePathRegex, '');
 			}
 
 			if (pretty) {
-				line = line.replace(extractPathRegex, (m, p1) => {
-					let filePath = p1;
-
-					// Convert file:// URLs to regular paths first
-					if (filePath.startsWith('file://')) {
-						filePath = fileURLToPath(filePath);
-					}
-
-					// Then replace home directory with ~ (only if homeDirectory is not empty)
-					if (homeDirectory) {
-						filePath = filePath.replace(homeDirectory, '~');
-					}
+				// Convert file:// URLs to regular paths first. A stack can hold anything,
+				// so a URL we cannot convert is left as-is instead of throwing. `?` and
+				// `#` are left alone too, as they truncate the frame at that character,
+				// and so is `%0A`/`%0D`, as decoding it splits the frame into two lines.
+				if (newPath.startsWith('file://') && !/[#?]|%0[ad]/iv.test(newPath)) {
+					try {
+						// The path a file URL stands for is native, and so uses `\` on
+						// Windows, while the rest of the stack has already become `/`.
+						newPath = fileURLToPath(newPath).replaceAll('\\', '/');
+					} catch {}
+				}
 
-					return m.replace(p1, filePath);
-				});
+				// Then replace home directory with ~, but only when the path really
+				// lives in it, so `/Users/sindresorhus-2` is left alone.
+				if (homeDirectory && (newPath === homeDirectory || newPath.startsWith(homeDirectory + '/'))) {
+					newPath = '~' + newPath.slice(homeDirectory.length);
+				}
 			}
 
-			return line;
+			return line.slice(0, pathIndex) + newPath + line.slice(pathIndex + path.length);
 		})
 		.join('\n');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cjser/clean-stack",
-  "version": "6.0.0-cjser.2",
+  "version": "7.0.0-cjser.2",
   "description": "Clean up error stack traces",
   "license": "MIT",
   "repository": {
@@ -8,11 +8,7 @@
     "url": "https://code.moenext.com/3rdeye/cjser.git"
   },
   "funding": "https://github.com/sponsors/sindresorhus",
-  "author": {
-    "name": "Sindre Sorhus",
-    "email": "sindresorhus@gmail.com",
-    "url": "https://sindresorhus.com"
-  },
+  "author": "Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)",
   "type": "module",
   "exports": {
     "types": "./index.d.ts",
@@ -21,10 +17,10 @@
   },
   "sideEffects": false,
   "engines": {
-    "node": ">=20"
+    "node": ">=22.3"
   },
   "scripts": {
-    "test": "xo && ava"
+    "test": "xo && node --test test.js"
   },
   "files": [
     "index.js",
@@ -44,8 +40,7 @@
     "@cjser/url-extras": "0.1.0-cjser.2"
   },
   "devDependencies": {
-    "ava": "^6.4.1",
-    "xo": "^0.56.0"
+    "xo": "^5.0.1"
   },
   "xo": {
     "rules": {
@@ -55,18 +50,18 @@
   "types": "./index.d.ts",
   "main": "./dist-cjser/index.cjs",
   "cjser": {
-    "sourceVersion": "6.0.0",
+    "sourceVersion": "7.0.0",
     "cjserVersion": 2,
     "original": {
       "name": "clean-stack",
-      "version": "6.0.0",
+      "version": "7.0.0",
       "exports": {
         "types": "./index.d.ts",
         "default": "./index.js"
       },
       "repository": "sindresorhus/clean-stack",
       "dependencies": {
-        "escape-string-regexp": "5.0.0",
+        "escape-string-regexp": "^5.0.0",
         "url-extras": "^0.1.0"
       },
       "files": [
@@ -74,7 +69,7 @@
         "index.d.ts"
       ],
       "scripts": {
-        "test": "xo && ava"
+        "test": "xo && node --test test.js"
       }
     }
   }

package/readme.md

@@ -42,13 +42,13 @@ Error: Missing unicorn
 
 ### cleanStack(stack, options?)
 
-Returns the cleaned stack or `undefined` if the given `stack` is `undefined`.
+Returns the cleaned stack or `undefined` if the given `stack` is not a string.
 
 #### stack
 
 Type: `string | undefined`
 
-The `stack` property of an [`Error`](https://github.com/microsoft/TypeScript/blob/eac073894b172ec719ca7f28b0b94fc6e6e7d4cf/lib/lib.es5.d.ts#L972-L976).
+The `stack` property of an [`Error`](https://github.com/microsoft/TypeScript/blob/eac073894b172ec719ca7f28b0b94fc6e6e7d4cf/lib/lib.es5.d.ts#L972-L976), or `undefined`.
 
 #### options
 
@@ -64,7 +64,9 @@ Prettify the file paths in the stack:
 - `/Users/sindresorhus/dev/clean-stack/unicorn.js:2:15` → `~/dev/clean-stack/unicorn.js:2:15`
 - `file:///Users/sindresorhus/dev/clean-stack/unicorn.js:2:15` → `~/dev/clean-stack/unicorn.js:2:15`
 
-When enabled, file URLs are converted to regular paths for better readability and IDE integration.
+When enabled, file URLs are converted to regular paths for better readability and IDE integration. URLs that cannot be converted, contain `?` or `#`, or decode to a line break are left unchanged.
+
+`pretty` and `basePath` only rewrite frame paths. Backslashes become `/` throughout each frame. Error message text is preserved except for blank lines; lines shaped like frames are treated as frames.
 
 ##### basePath
 
@@ -72,15 +74,26 @@ Type: `string?`
 
 Remove the given base path from stack trace file paths, effectively turning absolute paths into relative ones. It will also transform absolute file URLs into relative paths.
 
+Supports absolute or relative paths, either separator, and the filesystem root. A leading slash only matches absolute paths. Relative base paths do not match inside `file:///`, except Windows drive paths such as `C:/Users`.
+
 Example with `'/Users/sindresorhus/dev/clean-stack'` as `basePath`:
 
 `/Users/sindresorhus/dev/clean-stack/unicorn.js:2:15` → `unicorn.js:2:15`
 
+> [!NOTE]
+> `basePath` matches before file URLs are decoded, so `/Users/John Doe/dev` does not match `file:///Users/John%20Doe/dev`. After a match, remaining URL escapes stay encoded, even with `pretty`.
+
+> [!NOTE]
+> Frames like `at fn (unicorn.js:2:15)` are removed because they resemble old internal Node.js frames. Cleaning again after `basePath` produces this form can therefore drop frames for files directly in the base path. Paths with a directory, like `at fn (src/unicorn.js:2:15)`, and bare frames like `at unicorn.js:2:15` are unaffected.
+
 ##### pathFilter
 
 Type: `(path: string) => boolean`
 
-Remove the stack lines where the given function returns `false`. The function receives the path part of the stack line.
+Remove stack lines where the callback returns `false`. It receives the path without the closing parenthesis, with `/` separators, before `basePath` or `pretty` is applied. A pathless frame such as `at async Promise.all (index 0)` yields `index 0`.
+
+> [!NOTE]
+> Balanced parentheses in function names, such as `at render (partial) (/base/a.js:6:9)`, and paths, such as `C:/Program Files (x86)/app.js:1:1`, are supported. Unbalanced parentheses in a function name, such as `at a(b (/base/a.js:6:9)`, can cause part of the name to be included in the path.
 
 ```js
 import cleanStack from 'clean-stack';