@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/fs/types.d.ts

@@ -0,0 +1,291 @@
+/**
+ * @file Public type surface for `fs/*` modules — option shapes, encoding union,
+ *   and result records. Pure types only; no runtime side effects so this module
+ *   stays cheap to import everywhere.
+ */
+import type { Abortable } from 'node:events';
+import type { ObjectEncodingOptions, OpenMode } from 'node:fs';
+import type { JsonReviver } from '../json/types';
+import type { Remap } from '../objects/types';
+/**
+ * Supported text encodings for Node.js Buffers. Includes ASCII, UTF-8/16,
+ * base64, binary, and hexadecimal encodings.
+ */
+export type BufferEncoding = 'ascii' | 'utf8' | 'utf-8' | 'utf16le' | 'ucs2' | 'ucs-2' | 'base64' | 'base64url' | 'latin1' | 'binary' | 'hex';
+/**
+ * Options for asynchronous `findUp` operations.
+ */
+export interface FindUpOptions {
+    /**
+     * Starting directory for the search.
+     *
+     * @default process.cwd()
+     */
+    cwd?: string | undefined;
+    /**
+     * Only match directories, not files.
+     *
+     * @default false
+     */
+    onlyDirectories?: boolean | undefined;
+    /**
+     * Only match files, not directories.
+     *
+     * @default true
+     */
+    onlyFiles?: boolean | undefined;
+    /**
+     * Abort signal to cancel the search operation.
+     */
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Options for synchronous `findUpSync` operations.
+ */
+export interface FindUpSyncOptions {
+    /**
+     * Starting directory for the search.
+     *
+     * @default process.cwd()
+     */
+    cwd?: string | undefined;
+    /**
+     * Directory to stop searching at (inclusive). When provided, search will stop
+     * at this directory even if the root hasn't been reached.
+     */
+    stopAt?: string | undefined;
+    /**
+     * Only match directories, not files.
+     *
+     * @default false
+     */
+    onlyDirectories?: boolean | undefined;
+    /**
+     * Only match files, not directories.
+     *
+     * @default true
+     */
+    onlyFiles?: boolean | undefined;
+}
+/**
+ * Options for checking if a directory is empty.
+ */
+export interface IsDirEmptyOptions {
+    /**
+     * Glob patterns for files to ignore when checking emptiness. Files matching
+     * these patterns are not counted.
+     *
+     * @default defaultIgnore
+     */
+    ignore?: string[] | readonly string[] | undefined;
+}
+/**
+ * Represents any valid JSON content type.
+ */
+export type JsonContent = unknown;
+/**
+ * Options for reading directories with filtering and sorting.
+ */
+export interface ReadDirOptions {
+    /**
+     * Glob patterns for directories to ignore.
+     *
+     * @default undefined
+     */
+    ignore?: string[] | readonly string[] | undefined;
+    /**
+     * Include empty directories in results. When `false`, empty directories are
+     * filtered out.
+     *
+     * @default true
+     */
+    includeEmpty?: boolean | undefined;
+    /**
+     * Sort directory names alphabetically using natural sort order.
+     *
+     * @default true
+     */
+    sort?: boolean | undefined;
+}
+/**
+ * Options for reading files with encoding and abort support. Can be either an
+ * options object, an encoding string, or null.
+ */
+export type ReadFileOptions = Remap<ObjectEncodingOptions & Abortable & {
+    flag?: OpenMode | undefined;
+}> | BufferEncoding | null;
+/**
+ * Options for reading and parsing JSON files.
+ */
+export type ReadJsonOptions = Remap<ReadFileOptions & {
+    /**
+     * Whether to throw errors on parse failure. When `false`, returns
+     * `undefined` on error instead of throwing.
+     *
+     * @default true
+     */
+    throws?: boolean | undefined;
+    /**
+     * JSON reviver function to transform parsed values. Same as the second
+     * parameter to `JSON.parse()`.
+     *
+     * Note: when a `reviver` is passed, the read-result cache is bypassed —
+     * function identity isn't safely hashable and the reviver can transform the
+     * same bytes into a different shape.
+     */
+    reviver?: Parameters<typeof JSON.parse>[1] | undefined;
+    /**
+     * Opt out of the process-scoped read-result cache. Default `true` (cache
+     * ON). Set to `false` when staleness must be observed — e.g. file-watcher
+     * tooling that wants to see live disk state on every call. The cache
+     * validates entries with a `stat()` (inode + size + mtime) on every hit, so
+     * the default-on path is safe for everyday use.
+     *
+     * @default true
+     */
+    cache?: boolean | undefined;
+}>;
+/**
+ * Options for read operations with abort support.
+ */
+export interface ReadOptions extends Abortable {
+    /**
+     * Character encoding to use for reading.
+     *
+     * @default 'utf8'
+     */
+    encoding?: BufferEncoding | string | undefined;
+    /**
+     * File system flag for reading behavior.
+     *
+     * @default 'r'
+     */
+    flag?: string | undefined;
+}
+/**
+ * Options for file/directory removal operations.
+ */
+export interface RemoveOptions {
+    /**
+     * Force deletion even outside normally safe directories. When `false`,
+     * prevents deletion outside temp, cacache, and ~/.socket.
+     *
+     * @default true for safe directories, false otherwise
+     */
+    force?: boolean | undefined;
+    /**
+     * Maximum number of retry attempts on failure.
+     *
+     * @default 3
+     */
+    maxRetries?: number | undefined;
+    /**
+     * Recursively delete directories and contents.
+     *
+     * @default true
+     */
+    recursive?: boolean | undefined;
+    /**
+     * Delay in milliseconds between retry attempts.
+     *
+     * @default 200
+     */
+    retryDelay?: number | undefined;
+    /**
+     * Abort signal to cancel the operation.
+     */
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Options for safe read operations that don't throw on errors.
+ */
+export interface SafeReadOptions extends ReadOptions {
+    /**
+     * Default value to return on read failure. If not provided, `undefined` is
+     * returned on error.
+     */
+    defaultValue?: unknown | undefined;
+}
+/**
+ * Result of file readability validation. Contains lists of valid and invalid
+ * file paths.
+ */
+export interface ValidateFilesResult {
+    /**
+     * File paths that passed validation and are readable.
+     */
+    validPaths: string[];
+    /**
+     * File paths that failed validation (unreadable, permission denied, or
+     * non-existent). Common with Yarn Berry PnP virtual filesystem, pnpm
+     * symlinks, or filesystem race conditions.
+     */
+    invalidPaths: string[];
+}
+/**
+ * Options for writing JSON files with formatting control.
+ */
+export interface WriteJsonOptions extends WriteOptions {
+    /**
+     * End-of-line sequence to use.
+     *
+     * @example
+     *   ;```ts
+     *   // Windows-style line endings
+     *   writeJson('data.json', data, { EOL: '\r\n' })
+     *   ```
+     *
+     * @default '\n'
+     */
+    EOL?: string | undefined;
+    /**
+     * Whether to add a final newline at end of file.
+     *
+     * @default true
+     */
+    finalEOL?: boolean | undefined;
+    /**
+     * JSON replacer function to transform values during stringification. Same as
+     * the second parameter to `JSON.stringify()`.
+     */
+    replacer?: JsonReviver | undefined;
+    /**
+     * Number of spaces for indentation, or string to use for indentation.
+     *
+     * @example
+     *   ;```ts
+     *   // Use tabs instead of spaces
+     *   writeJson('data.json', data, { spaces: '\t' })
+     *
+     *   // Use 4 spaces for indentation
+     *   writeJson('data.json', data, { spaces: 4 })
+     *   ```
+     *
+     * @default 2
+     */
+    spaces?: number | string | undefined;
+}
+/**
+ * Options for write operations with encoding and mode control.
+ */
+export interface WriteOptions extends Abortable {
+    /**
+     * Character encoding for writing.
+     *
+     * @default 'utf8'
+     */
+    encoding?: BufferEncoding | string | undefined;
+    /**
+     * File mode (permissions) to set. Uses standard Unix permission bits (e.g.,
+     * 0o644).
+     *
+     * @default 0o666 (read/write for all, respecting umask)
+     */
+    mode?: number | undefined;
+    /**
+     * File system flag for write behavior.
+     *
+     * @default 'w' (create or truncate)
+     */
+    flag?: string | undefined;
+}

package/dist/fs/types.js

@@ -0,0 +1,18 @@
+"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 __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 types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/fs/unique.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @file Generate a unique filepath by appending `-1`, `-2`, … before the
+ *   extension until the path is free. Useful for "save next to existing" flows
+ *   where overwriting silently would be wrong (PDF reports, exports, etc.).
+ */
+import type { PathLike } from 'node:fs';
+/**
+ * Generate a unique filepath by adding number suffix if the path exists.
+ * Appends `-1`, `-2`, etc. before the file extension until a non-existent path
+ * is found. Useful for creating files without overwriting existing ones.
+ *
+ * @example
+ *   ;```ts
+ *   // If 'report.pdf' exists, returns 'report-1.pdf'
+ *   const uniquePath = uniqueSync('./report.pdf')
+ *
+ *   // If 'data.json' and 'data-1.json' exist, returns 'data-2.json'
+ *   const path = uniqueSync('./data.json')
+ *
+ *   // If 'backup' doesn't exist, returns 'backup' unchanged
+ *   const backupPath = uniqueSync('./backup')
+ *   ```
+ *
+ * @param filepath - Desired file path.
+ *
+ * @returns Normalized unique filepath (original if it doesn't exist, or with
+ *   number suffix)
+ */
+export declare function uniqueSync(filepath: PathLike): string;

package/dist/fs/unique.js

@@ -0,0 +1,51 @@
+"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 unique_exports = {};
+__export(unique_exports, {
+  uniqueSync: () => uniqueSync
+});
+module.exports = __toCommonJS(unique_exports);
+var import_fs = require("../node/fs");
+var import_path = require("../node/path");
+var import_normalize = require("../paths/normalize");
+// @__NO_SIDE_EFFECTS__
+function uniqueSync(filepath) {
+  const fs = (0, import_fs.getNodeFs)();
+  const path = (0, import_path.getNodePath)();
+  const filepathStr = String(filepath);
+  if (!fs.existsSync(filepathStr)) {
+    return (0, import_normalize.normalizePath)(filepathStr);
+  }
+  const dirname = path.dirname(filepathStr);
+  const ext = path.extname(filepathStr);
+  const basename = path.basename(filepathStr, ext);
+  let counter = 1;
+  let uniquePath;
+  do {
+    uniquePath = path.join(dirname, `${basename}-${counter}${ext}`);
+    counter++;
+  } while (fs.existsSync(uniquePath));
+  return (0, import_normalize.normalizePath)(uniquePath);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  uniqueSync
+});

package/dist/fs/validate.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @file Pre-flight readability check for file lists. Used to filter out paths
+ *   that exist in glob results but cannot be opened — Yarn Berry PnP virtual
+ *   filesystem entries, pnpm symlinks pointing into a missing
+ *   content-addressable store, or filesystem races during CI runs.
+ */
+import type { ValidateFilesResult } from './types';
+/**
+ * Validate that file paths are readable before processing. Filters out files
+ * from glob results that cannot be accessed (common with Yarn Berry PnP virtual
+ * filesystem, pnpm content-addressable store symlinks, or filesystem race
+ * conditions in CI/CD environments).
+ *
+ * This defensive pattern prevents ENOENT errors when files exist in glob
+ * results but are not accessible via standard filesystem operations.
+ *
+ * @example
+ *   ```ts
+ *   import { validateFiles } from '@socketsecurity/lib/fs/validate'
+ *
+ *   const files = ['package.json', '.pnp.cjs/virtual-file.json']
+ *   const { validPaths, invalidPaths } = validateFiles(files)
+ *
+ *   console.log(`Valid: ${validPaths.length}`)
+ *   console.log(`Invalid: ${invalidPaths.length}`)
+ *   ```
+ *
+ * @example
+ *   ;```ts
+ *   // Typical usage in Socket CLI commands
+ *   const packagePaths = await getPackageFilesForScan(targets)
+ *   const { validPaths } = validateFiles(packagePaths)
+ *   await sdk.uploadManifestFiles(orgSlug, validPaths)
+ *   ```
+ *
+ * @param filepaths - Array of file paths to validate.
+ *
+ * @returns Object with `validPaths` (readable) and `invalidPaths` (unreadable)
+ */
+export declare function validateFiles(filepaths: string[] | readonly string[]): ValidateFilesResult;

package/dist/fs/validate.js

@@ -0,0 +1,46 @@
+"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 validate_exports = {};
+__export(validate_exports, {
+  validateFiles: () => validateFiles
+});
+module.exports = __toCommonJS(validate_exports);
+var import_fs = require("../node/fs");
+// @__NO_SIDE_EFFECTS__
+function validateFiles(filepaths) {
+  const fs = (0, import_fs.getNodeFs)();
+  const validPaths = [];
+  const invalidPaths = [];
+  const { R_OK } = fs.constants;
+  for (const filepath of filepaths) {
+    try {
+      fs.accessSync(filepath, R_OK);
+      validPaths.push(filepath);
+    } catch {
+      invalidPaths.push(filepath);
+    }
+  }
+  return { __proto__: null, validPaths, invalidPaths };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  validateFiles
+});

package/dist/fs/write-json.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @file JSON writers that match the wire-format conventions a tool ecosystem
+ *   expects: configurable indentation, configurable EOL, trailing newline by
+ *   default. The `stringify` helper is exported so callers that already have an
+ *   `fs` handle can render a buffer without round-tripping through this
+ *   module's writers.
+ */
+import type { PathLike } from 'node:fs';
+import type { JsonReviver } from '../json/types';
+import type { WriteJsonOptions } from './types';
+/**
+ * Stringify JSON with custom formatting options. Formats JSON with configurable
+ * line endings and indentation.
+ *
+ * @param json - Value to stringify.
+ * @param EOL - End-of-line sequence.
+ * @param finalEOL - Whether to add final newline.
+ * @param replacer - JSON replacer function.
+ * @param spaces - Indentation spaces or string.
+ *
+ * @returns Formatted JSON string
+ */
+export declare function stringify(json: unknown, EOL: string, finalEOL: boolean, replacer: JsonReviver | undefined, spaces?: number | string): string;
+/**
+ * Write JSON content to a file asynchronously with formatting. Stringifies the
+ * value with configurable indentation and line endings. Automatically adds a
+ * final newline by default for POSIX compliance.
+ *
+ * @example
+ *   ;```ts
+ *   // Write formatted JSON with default 2-space indentation
+ *   await writeJson('./data.json', { name: 'example', version: '1.0.0' })
+ *
+ *   // Write with custom indentation
+ *   await writeJson('./config.json', config, { spaces: 4 })
+ *
+ *   // Write with tabs instead of spaces
+ *   await writeJson('./data.json', data, { spaces: '\t' })
+ *
+ *   // Write without final newline
+ *   await writeJson('./inline.json', obj, { finalEOL: false })
+ *
+ *   // Write with Windows line endings
+ *   await writeJson('./win.json', data, { EOL: '\r\n' })
+ *   ```
+ *
+ * @param filepath - Path to write to.
+ * @param jsonContent - Value to stringify and write.
+ * @param options - Write options including formatting and encoding.
+ *
+ * @returns Promise that resolves when write completes
+ */
+export declare function writeJson(filepath: PathLike, jsonContent: unknown, options?: WriteJsonOptions | string): Promise<void>;
+/**
+ * Write JSON content to a file synchronously with formatting. Stringifies the
+ * value with configurable indentation and line endings. Automatically adds a
+ * final newline by default for POSIX compliance.
+ *
+ * @example
+ *   ;```ts
+ *   // Write formatted JSON with default 2-space indentation
+ *   writeJsonSync('./package.json', pkg)
+ *
+ *   // Write with custom indentation
+ *   writeJsonSync('./tsconfig.json', tsconfig, { spaces: 4 })
+ *
+ *   // Write with tabs for indentation
+ *   writeJsonSync('./data.json', data, { spaces: '\t' })
+ *
+ *   // Write compacted (no indentation)
+ *   writeJsonSync('./compact.json', data, { spaces: 0 })
+ *   ```
+ *
+ * @param filepath - Path to write to.
+ * @param jsonContent - Value to stringify and write.
+ * @param options - Write options including formatting and encoding.
+ */
+export declare function writeJsonSync(filepath: PathLike, jsonContent: unknown, options?: WriteJsonOptions | string | undefined): void;

package/dist/fs/write-json.js

@@ -0,0 +1,83 @@
+"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 write_json_exports = {};
+__export(write_json_exports, {
+  stringify: () => stringify,
+  writeJson: () => writeJson,
+  writeJsonSync: () => writeJsonSync
+});
+module.exports = __toCommonJS(write_json_exports);
+var import_fs = require("../node/fs");
+var import_json = require("../primordials/json");
+var import_string = require("../primordials/string");
+const NEWLINE_REGEX = /\n/g;
+// @__NO_SIDE_EFFECTS__
+function stringify(json, EOL, finalEOL, replacer, spaces = 2) {
+  const EOF = finalEOL ? EOL : "";
+  const str = (0, import_json.JSONStringify)(json, replacer, spaces);
+  return `${(0, import_string.StringPrototypeReplace)(str, NEWLINE_REGEX, EOL)}${EOF}`;
+}
+async function writeJson(filepath, jsonContent, options) {
+  const opts = typeof options === "string" ? { encoding: options } : options;
+  const { EOL, finalEOL, replacer, spaces, ...fsOptions } = {
+    __proto__: null,
+    ...opts
+  };
+  const fs = (0, import_fs.getNodeFs)();
+  const jsonString = /* @__PURE__ */ stringify(
+    jsonContent,
+    EOL || "\n",
+    finalEOL !== void 0 ? finalEOL : true,
+    replacer,
+    spaces
+  );
+  await fs.promises.writeFile(filepath, jsonString, {
+    encoding: "utf8",
+    ...fsOptions,
+    __proto__: null
+  });
+}
+function writeJsonSync(filepath, jsonContent, options) {
+  const opts = typeof options === "string" ? { encoding: options } : options;
+  const { EOL, finalEOL, replacer, spaces, ...fsOptions } = {
+    __proto__: null,
+    ...opts
+  };
+  const fs = (0, import_fs.getNodeFs)();
+  const jsonString = /* @__PURE__ */ stringify(
+    jsonContent,
+    EOL || "\n",
+    finalEOL !== void 0 ? finalEOL : true,
+    replacer,
+    spaces
+  );
+  fs.writeFileSync(filepath, jsonString, {
+    encoding: "utf8",
+    ...fsOptions,
+    __proto__: null
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  stringify,
+  writeJson,
+  writeJsonSync
+});