@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/fs/find-up.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @file Walk parent directories to locate a file or directory by name. The
+ *   traversal includes the filesystem root (or the caller-supplied `stopAt`
+ *   boundary) — historically the loop exited at `dir === root` _before_
+ *   visiting root itself, so a match at e.g. `/.foo` was never found. The
+ *   current shape visits root, then breaks.
+ */
+import type { FindUpOptions, FindUpSyncOptions } from './types';
+/**
+ * Find a file or directory by traversing up parent directories. Searches from
+ * the starting directory upward to the filesystem root. Useful for finding
+ * configuration files or project roots.
+ *
+ * @example
+ *   ;```ts
+ *   // Find package.json starting from current directory
+ *   const pkgPath = await findUp('package.json')
+ *
+ *   // Find any of multiple config files
+ *   const configPath = await findUp(['.config.js', '.config.json'])
+ *
+ *   // Find a directory instead of file
+ *   const nodeModules = await findUp('node_modules', { onlyDirectories: true })
+ *   ```
+ *
+ * @param name - Filename(s) to search for.
+ * @param options - Search options including cwd and type filters.
+ *
+ * @returns Normalized absolute path if found, undefined otherwise
+ */
+export declare function findUp(name: string | string[] | readonly string[], options?: FindUpOptions | undefined): Promise<string | undefined>;
+/**
+ * Synchronously find a file or directory by traversing up parent directories.
+ * Searches from the starting directory upward to the filesystem root or
+ * `stopAt` directory. Useful for finding configuration files or project roots
+ * in synchronous contexts.
+ *
+ * @example
+ *   ;```ts
+ *   // Find package.json starting from current directory
+ *   const pkgPath = findUpSync('package.json')
+ *
+ *   // Find .git directory but stop at home directory
+ *   const gitPath = findUpSync('.git', {
+ *     onlyDirectories: true,
+ *     stopAt: process.env.HOME,
+ *   })
+ *
+ *   // Find any of multiple config files
+ *   const configPath = findUpSync(['.eslintrc.js', '.eslintrc.json'])
+ *   ```
+ *
+ * @param name - Filename(s) to search for.
+ * @param options - Search options including cwd, stopAt, and type filters.
+ *
+ * @returns Normalized absolute path if found, undefined otherwise
+ */
+export declare function findUpSync(name: string | string[] | readonly string[], options?: FindUpSyncOptions | undefined): string | undefined;

package/dist/fs/find-up.js

@@ -0,0 +1,152 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var find_up_exports = {};
+__export(find_up_exports, {
+  findUp: () => findUp,
+  findUpSync: () => findUpSync
+});
+module.exports = __toCommonJS(find_up_exports);
+var import_node_process = __toESM(require("node:process"));
+var import_predicates = require("../arrays/predicates");
+var import_abort = require("../process/abort");
+var import_fs = require("../node/fs");
+var import_path = require("../node/path");
+var import_normalize = require("../paths/normalize");
+const abortSignal = (0, import_abort.getAbortSignal)();
+// @__NO_SIDE_EFFECTS__
+async function findUp(name, options) {
+  const { cwd = import_node_process.default.cwd(), signal = abortSignal } = {
+    __proto__: null,
+    ...options
+  };
+  let { onlyDirectories = false, onlyFiles = true } = {
+    __proto__: null,
+    ...options
+  };
+  if (onlyDirectories) {
+    onlyFiles = false;
+  }
+  if (onlyFiles) {
+    onlyDirectories = false;
+  }
+  const fs = (0, import_fs.getNodeFs)();
+  const path = (0, import_path.getNodePath)();
+  let dir = path.resolve(cwd);
+  const { root } = path.parse(dir);
+  const names = (0, import_predicates.isArray)(name) ? name : [name];
+  while (dir) {
+    for (const n of names) {
+      if (signal?.aborted) {
+        return void 0;
+      }
+      const thePath = path.join(dir, n);
+      try {
+        const stats = await fs.promises.stat(thePath);
+        if (!onlyDirectories && stats.isFile()) {
+          return (0, import_normalize.normalizePath)(thePath);
+        }
+        if (!onlyFiles && stats.isDirectory()) {
+          return (0, import_normalize.normalizePath)(thePath);
+        }
+      } catch {
+      }
+    }
+    if (dir === root) {
+      break;
+    }
+    dir = path.dirname(dir);
+  }
+  return void 0;
+}
+// @__NO_SIDE_EFFECTS__
+function findUpSync(name, options) {
+  const { cwd = import_node_process.default.cwd(), stopAt } = {
+    __proto__: null,
+    ...options
+  };
+  let { onlyDirectories = false, onlyFiles = true } = {
+    __proto__: null,
+    ...options
+  };
+  if (onlyDirectories) {
+    onlyFiles = false;
+  }
+  if (onlyFiles) {
+    onlyDirectories = false;
+  }
+  const fs = (0, import_fs.getNodeFs)();
+  const path = (0, import_path.getNodePath)();
+  let dir = path.resolve(cwd);
+  const { root } = path.parse(dir);
+  const stopDir = stopAt ? path.resolve(stopAt) : void 0;
+  const names = (0, import_predicates.isArray)(name) ? name : [name];
+  while (dir) {
+    if (stopDir && dir === stopDir) {
+      for (const n of names) {
+        const thePath = path.join(dir, n);
+        try {
+          const stats = fs.statSync(thePath);
+          if (!onlyDirectories && stats.isFile()) {
+            return (0, import_normalize.normalizePath)(thePath);
+          }
+          if (!onlyFiles && stats.isDirectory()) {
+            return (0, import_normalize.normalizePath)(thePath);
+          }
+        } catch {
+        }
+      }
+      return void 0;
+    }
+    for (const n of names) {
+      const thePath = path.join(dir, n);
+      try {
+        const stats = fs.statSync(thePath);
+        if (!onlyDirectories && stats.isFile()) {
+          return (0, import_normalize.normalizePath)(thePath);
+        }
+        if (!onlyFiles && stats.isDirectory()) {
+          return (0, import_normalize.normalizePath)(thePath);
+        }
+      } catch {
+      }
+    }
+    if (dir === root) {
+      break;
+    }
+    dir = path.dirname(dir);
+  }
+  return void 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  findUp,
+  findUpSync
+});

package/dist/fs/inspect.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @file Filesystem inspection helpers — `stat` / `lstat` wrappers that return
+ *   `undefined` instead of throwing, and the directory / symlink / emptiness
+ *   predicates layered on top. Every entry point catches errors and reduces
+ *   them to a falsy result; callers that need the underlying error code should
+ *   use `node:fs` directly.
+ */
+import type { PathLike } from 'node:fs';
+import type { IsDirEmptyOptions } from './types';
+/**
+ * Check if a path is a directory asynchronously. Returns `true` for
+ * directories, `false` for files or non-existent paths.
+ *
+ * @example
+ *   ;```ts
+ *   if (await isDir('./src')) {
+ *     console.log('src is a directory')
+ *   }
+ *   ```
+ *
+ * @param filepath - Path to check.
+ *
+ * @returns `true` if path is a directory, `false` otherwise
+ */
+export declare function isDir(filepath: PathLike): Promise<boolean>;
+/**
+ * Check if a directory is empty synchronously. A directory is considered empty
+ * if it contains no files after applying ignore patterns. Uses glob patterns to
+ * filter ignored files.
+ *
+ * @example
+ *   ;```ts
+ *   // Check if directory is completely empty
+ *   isDirEmptySync('./build')
+ *
+ *   // Check if directory is empty, ignoring .DS_Store files
+ *   isDirEmptySync('./cache', { ignore: ['.DS_Store'] })
+ *   ```
+ *
+ * @param dirname - Directory path to check.
+ * @param options - Options including ignore patterns.
+ *
+ * @returns `true` if directory is empty (or doesn't exist), `false` otherwise
+ */
+export declare function isDirEmptySync(dirname: PathLike, options?: IsDirEmptyOptions | undefined): boolean;
+/**
+ * Check if a path is a directory synchronously. Returns `true` for directories,
+ * `false` for files or non-existent paths.
+ *
+ * @example
+ *   ;```ts
+ *   if (isDirSync('./src')) {
+ *     console.log('src is a directory')
+ *   }
+ *   ```
+ *
+ * @param filepath - Path to check.
+ *
+ * @returns `true` if path is a directory, `false` otherwise
+ */
+export declare function isDirSync(filepath: PathLike): boolean;
+/**
+ * Check if a path is a symbolic link synchronously. Uses `lstat` to check the
+ * link itself, not the target.
+ *
+ * @example
+ *   ;```ts
+ *   if (isSymlinkSync('./my-link')) {
+ *     console.log('Path is a symbolic link')
+ *   }
+ *   ```
+ *
+ * @param filepath - Path to check.
+ *
+ * @returns `true` if path is a symbolic link, `false` otherwise
+ */
+export declare function isSymlinkSync(filepath: PathLike): boolean;
+/**
+ * Safely get file stats asynchronously, returning undefined on error. Useful
+ * for checking file existence and properties without error handling. Returns
+ * undefined for any error (file not found, permission denied, etc.).
+ *
+ * @example
+ *   ;```ts
+ *   // Check if file exists and get its stats
+ *   const stats = await safeStat('./file.txt')
+ *   if (stats) {
+ *     console.log('File size:', stats.size)
+ *     console.log('Modified:', stats.mtime)
+ *   }
+ *   ```
+ *
+ * @param filepath - Path to check.
+ *
+ * @returns Promise resolving to Stats object, or undefined on error
+ */
+export declare function safeStat(filepath: PathLike): Promise<import("fs").Stats | undefined>;
+/**
+ * Safely get file stats synchronously, returning undefined on error. Useful for
+ * checking file existence and properties without error handling. Returns
+ * undefined for any error (file not found, permission denied, etc.).
+ *
+ * @example
+ *   ;```ts
+ *   // Check if file exists and get its size
+ *   const stats = safeStatSync('./file.txt')
+ *   if (stats) {
+ *     console.log('File size:', stats.size)
+ *     console.log('Is directory:', stats.isDirectory())
+ *   }
+ *   ```
+ *
+ * @param filepath - Path to check.
+ *
+ * @returns Stats object, or undefined on error
+ */
+export declare function safeStatSync(filepath: PathLike): import("fs").BigIntStats | import("fs").Stats | undefined;

package/dist/fs/inspect.js

@@ -0,0 +1,112 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var inspect_exports = {};
+__export(inspect_exports, {
+  isDir: () => isDir,
+  isDirEmptySync: () => isDirEmptySync,
+  isDirSync: () => isDirSync,
+  isSymlinkSync: () => isSymlinkSync,
+  safeStat: () => safeStat,
+  safeStatSync: () => safeStatSync
+});
+module.exports = __toCommonJS(inspect_exports);
+var import_defaults = require("../globs/defaults");
+var import_matcher = require("../globs/matcher");
+var import_fs = require("../node/fs");
+var import_normalize = require("../paths/normalize");
+// @__NO_SIDE_EFFECTS__
+async function isDir(filepath) {
+  return !!(await /* @__PURE__ */ safeStat(filepath))?.isDirectory();
+}
+// @__NO_SIDE_EFFECTS__
+function isDirEmptySync(dirname, options) {
+  const { ignore = import_defaults.defaultIgnore } = {
+    __proto__: null,
+    ...options
+  };
+  const fs = (0, import_fs.getNodeFs)();
+  try {
+    const files = fs.readdirSync(dirname);
+    const { length } = files;
+    if (length === 0) {
+      return true;
+    }
+    const matcher = (0, import_matcher.getGlobMatcher)(
+      ignore,
+      {
+        cwd: (0, import_normalize.pathLikeToString)(dirname)
+      }
+    );
+    let ignoredCount = 0;
+    for (let i = 0; i < length; i += 1) {
+      const file = files[i];
+      if (file && matcher(file)) {
+        ignoredCount += 1;
+      }
+    }
+    return ignoredCount === length;
+  } catch {
+    return false;
+  }
+}
+// @__NO_SIDE_EFFECTS__
+function isDirSync(filepath) {
+  return !!(/* @__PURE__ */ safeStatSync(filepath))?.isDirectory();
+}
+// @__NO_SIDE_EFFECTS__
+function isSymlinkSync(filepath) {
+  const fs = (0, import_fs.getNodeFs)();
+  try {
+    return fs.lstatSync(filepath).isSymbolicLink();
+  } catch {
+  }
+  return false;
+}
+// @__NO_SIDE_EFFECTS__
+async function safeStat(filepath) {
+  const fs = (0, import_fs.getNodeFs)();
+  try {
+    return await fs.promises.stat(filepath);
+  } catch {
+  }
+  return void 0;
+}
+// @__NO_SIDE_EFFECTS__
+function safeStatSync(filepath) {
+  const fs = (0, import_fs.getNodeFs)();
+  try {
+    return fs.statSync(filepath, {
+      __proto__: null,
+      throwIfNoEntry: false
+    });
+  } catch {
+  }
+  return void 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isDir,
+  isDirEmptySync,
+  isDirSync,
+  isSymlinkSync,
+  safeStat,
+  safeStatSync
+});

package/dist/fs/path-cache.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file Cache-invalidation entry point for the allowed-directories list used by
+ *   `safeDelete` / `safeDeleteSync`. Loading this module registers
+ *   `invalidatePathCache` with `paths/rewire.ts` so test-time path overrides
+ *   flush the cache; the registration is the module's only side effect, so
+ *   callers that just need to flush the cache imperatively can call
+ *   `invalidatePathCache()` directly without that side effect repeating.
+ */
+/**
+ * Invalidate the cached allowed directories. Called automatically by the
+ * paths/rewire module when paths are overridden in tests.
+ *
+ * @example
+ *   ;```typescript
+ *   invalidatePathCache()
+ *   // Cached allowed directories are now cleared
+ *   ```
+ *
+ * @internal Used for test rewiring
+ */
+export declare function invalidatePathCache(): void;

package/dist/fs/path-cache.js

@@ -0,0 +1,35 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var path_cache_exports = {};
+__export(path_cache_exports, {
+  invalidatePathCache: () => invalidatePathCache
+});
+module.exports = __toCommonJS(path_cache_exports);
+var import_rewire = require("../paths/rewire");
+var import_internal = require("./_internal");
+function invalidatePathCache() {
+  (0, import_internal.clearAllowedDirectories)();
+}
+(0, import_rewire.registerCacheInvalidation)(invalidatePathCache);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  invalidatePathCache
+});

package/dist/fs/read-dir.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @file Async/sync directory listing — returns directory names only (filtering
+ *   out files), with optional emptiness suppression and natural-order sorting.
+ *   Glob-based ignore patterns are evaluated only when `includeEmpty: false`
+ *   triggers a per-entry emptiness probe.
+ */
+import type { Dirent, PathLike } from 'node:fs';
+import type { ReadDirOptions } from './types';
+/**
+ * Process directory entries and filter for directories. Filters entries to
+ * include only directories, optionally excluding empty ones. Applies ignore
+ * patterns and natural sorting.
+ *
+ * @param dirents - Directory entries from readdir.
+ * @param dirname - Parent directory path.
+ * @param options - Filtering and sorting options.
+ *
+ * @returns Array of directory names, optionally sorted
+ */
+export declare function innerReadDirNames(dirents: Dirent[], dirname: string | undefined, options?: ReadDirOptions | undefined): string[];
+/**
+ * Read directory names asynchronously with filtering and sorting. Returns only
+ * directory names (not files), with optional filtering for empty directories
+ * and glob-based ignore patterns. Results are naturally sorted by default.
+ *
+ * @example
+ *   ;```ts
+ *   // Get all subdirectories, sorted naturally
+ *   const dirs = await readDirNames('./packages')
+ *
+ *   // Get non-empty directories only
+ *   const nonEmpty = await readDirNames('./cache', { includeEmpty: false })
+ *
+ *   // Get directories without sorting
+ *   const unsorted = await readDirNames('./src', { sort: false })
+ *   ```
+ *
+ * @param dirname - Directory path to read.
+ * @param options - Options for filtering and sorting.
+ *
+ * @returns Array of directory names, empty array on error
+ */
+export declare function readDirNames(dirname: PathLike, options?: ReadDirOptions | undefined): Promise<string[]>;
+/**
+ * Read directory names synchronously with filtering and sorting. Returns only
+ * directory names (not files), with optional filtering for empty directories
+ * and glob-based ignore patterns. Results are naturally sorted by default.
+ *
+ * @example
+ *   ;```ts
+ *   // Get all subdirectories, sorted naturally
+ *   const dirs = readDirNamesSync('./packages')
+ *
+ *   // Get non-empty directories only, ignoring node_modules
+ *   const nonEmpty = readDirNamesSync('./src', {
+ *     includeEmpty: false,
+ *     ignore: ['node_modules'],
+ *   })
+ *   ```
+ *
+ * @param dirname - Directory path to read.
+ * @param options - Options for filtering and sorting.
+ *
+ * @returns Array of directory names, empty array on error
+ */
+export declare function readDirNamesSync(dirname: PathLike, options?: ReadDirOptions): string[];

package/dist/fs/read-dir.js

@@ -0,0 +1,86 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var read_dir_exports = {};
+__export(read_dir_exports, {
+  innerReadDirNames: () => innerReadDirNames,
+  readDirNames: () => readDirNames,
+  readDirNamesSync: () => readDirNamesSync
+});
+module.exports = __toCommonJS(read_dir_exports);
+var import_fs = require("../node/fs");
+var import_path = require("../node/path");
+var import_natural = require("../sorts/natural");
+var import_inspect = require("./inspect");
+// @__NO_SIDE_EFFECTS__
+function innerReadDirNames(dirents, dirname, options) {
+  const {
+    ignore,
+    includeEmpty = true,
+    sort = true
+  } = { __proto__: null, ...options };
+  const path = (0, import_path.getNodePath)();
+  const names = dirents.filter(
+    (d) => d.isDirectory() && (includeEmpty || !(0, import_inspect.isDirEmptySync)(path.join(dirname || d.parentPath, d.name), {
+      ignore
+    }))
+  ).map((d) => d.name);
+  return sort ? names.sort(import_natural.naturalCompare) : names;
+}
+// @__NO_SIDE_EFFECTS__
+async function readDirNames(dirname, options) {
+  const fs = (0, import_fs.getNodeFs)();
+  try {
+    return /* @__PURE__ */ innerReadDirNames(
+      await fs.promises.readdir(dirname, {
+        __proto__: null,
+        encoding: "utf8",
+        withFileTypes: true
+      }),
+      String(dirname),
+      options
+    );
+  } catch {
+  }
+  return [];
+}
+// @__NO_SIDE_EFFECTS__
+function readDirNamesSync(dirname, options) {
+  const fs = (0, import_fs.getNodeFs)();
+  try {
+    return /* @__PURE__ */ innerReadDirNames(
+      fs.readdirSync(dirname, {
+        __proto__: null,
+        encoding: "utf8",
+        withFileTypes: true
+      }),
+      String(dirname),
+      options
+    );
+  } catch {
+  }
+  return [];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  innerReadDirNames,
+  readDirNames,
+  readDirNamesSync
+});