@socketsecurity/lib 5.18.2 → 5.19.0

package/dist/argv/flags.d.ts

@@ -1,3 +1,12 @@
+/**
+ * @fileoverview Common flag utilities for Socket CLI applications.
+ * Provides consistent flag checking (quiet, silent, verbose, debug, dry-run,
+ * etc.) across Socket projects, accepting either parsed flag objects or raw
+ * argv arrays.
+ */
+/**
+ * Flag values object from parsed arguments.
+ */
 export interface FlagValues {
     [key: string]: unknown;
     quiet?: boolean;
@@ -22,6 +31,97 @@ export interface FlagValues {
  * Can be parsed flag values, process.argv array, or undefined (uses process.argv).
  */
 export type FlagInput = FlagValues | string[] | readonly string[] | undefined;
+/**
+ * Common flag definitions for parseArgs configuration.
+ * Can be spread into parseArgs options for consistency.
+ */
+export declare const COMMON_FLAGS: {
+    all: {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    changed: {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    coverage: {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    cover: {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    debug: {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    'dry-run': {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    fix: {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    force: {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    help: {
+        type: 'boolean';
+        default: boolean;
+        short: string;
+        description: string;
+    };
+    json: {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    quiet: {
+        type: 'boolean';
+        default: boolean;
+        short: string;
+        description: string;
+    };
+    silent: {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    staged: {
+        type: 'boolean';
+        default: boolean;
+        description: string;
+    };
+    update: {
+        type: 'boolean';
+        default: boolean;
+        short: string;
+        description: string;
+    };
+    verbose: {
+        type: 'boolean';
+        default: boolean;
+        short: string;
+        description: string;
+    };
+    watch: {
+        type: 'boolean';
+        default: boolean;
+        short: string;
+        description: string;
+    };
+};
 /**
  * Get the appropriate log level based on flags.
  * Returns 'silent', 'error', 'warn', 'info', 'verbose', or 'debug'.
@@ -190,94 +290,3 @@ export declare function isVerbose(input?: FlagInput): boolean;
  * ```
  */
 export declare function isWatch(input?: FlagInput): boolean;
-/**
- * Common flag definitions for parseArgs configuration.
- * Can be spread into parseArgs options for consistency.
- */
-export declare const COMMON_FLAGS: {
-    all: {
-        type: "boolean";
-        default: boolean;
-        description: string;
-    };
-    changed: {
-        type: "boolean";
-        default: boolean;
-        description: string;
-    };
-    coverage: {
-        type: "boolean";
-        default: boolean;
-        description: string;
-    };
-    cover: {
-        type: "boolean";
-        default: boolean;
-        description: string;
-    };
-    debug: {
-        type: "boolean";
-        default: boolean;
-        description: string;
-    };
-    "dry-run": {
-        type: "boolean";
-        default: boolean;
-        description: string;
-    };
-    fix: {
-        type: "boolean";
-        default: boolean;
-        description: string;
-    };
-    force: {
-        type: "boolean";
-        default: boolean;
-        description: string;
-    };
-    help: {
-        type: "boolean";
-        default: boolean;
-        short: string;
-        description: string;
-    };
-    json: {
-        type: "boolean";
-        default: boolean;
-        description: string;
-    };
-    quiet: {
-        type: "boolean";
-        default: boolean;
-        short: string;
-        description: string;
-    };
-    silent: {
-        type: "boolean";
-        default: boolean;
-        description: string;
-    };
-    staged: {
-        type: "boolean";
-        default: boolean;
-        description: string;
-    };
-    update: {
-        type: "boolean";
-        default: boolean;
-        short: string;
-        description: string;
-    };
-    verbose: {
-        type: "boolean";
-        default: boolean;
-        short: string;
-        description: string;
-    };
-    watch: {
-        type: "boolean";
-        default: boolean;
-        short: string;
-        description: string;
-    };
-};

package/dist/argv/flags.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -49,6 +50,93 @@ __export(flags_exports, {
 module.exports = __toCommonJS(flags_exports);
 var import_node_process = __toESM(require("node:process"));
 const processArg = [...import_node_process.default.argv];
+const COMMON_FLAGS = {
+  all: {
+    type: "boolean",
+    default: false,
+    description: "Target all files"
+  },
+  changed: {
+    type: "boolean",
+    default: false,
+    description: "Target changed files"
+  },
+  coverage: {
+    type: "boolean",
+    default: false,
+    description: "Run with coverage"
+  },
+  cover: {
+    type: "boolean",
+    default: false,
+    description: "Run with coverage (alias)"
+  },
+  debug: {
+    type: "boolean",
+    default: false,
+    description: "Enable debug output"
+  },
+  "dry-run": {
+    type: "boolean",
+    default: false,
+    description: "Perform a dry run"
+  },
+  fix: {
+    type: "boolean",
+    default: false,
+    description: "Automatically fix issues"
+  },
+  force: {
+    type: "boolean",
+    default: false,
+    description: "Force the operation"
+  },
+  help: {
+    type: "boolean",
+    default: false,
+    short: "h",
+    description: "Show help"
+  },
+  json: {
+    type: "boolean",
+    default: false,
+    description: "Output as JSON"
+  },
+  quiet: {
+    type: "boolean",
+    default: false,
+    short: "q",
+    description: "Suppress output"
+  },
+  silent: {
+    type: "boolean",
+    default: false,
+    description: "Suppress all output"
+  },
+  staged: {
+    type: "boolean",
+    default: false,
+    description: "Target staged files"
+  },
+  update: {
+    type: "boolean",
+    default: false,
+    short: "u",
+    description: "Update snapshots/deps"
+  },
+  verbose: {
+    type: "boolean",
+    default: false,
+    short: "v",
+    description: "Verbose output"
+  },
+  watch: {
+    type: "boolean",
+    default: false,
+    short: "w",
+    description: "Watch mode"
+  }
+};
 function getLogLevel(input) {
   if (isQuiet(input)) {
     return "silent";
@@ -187,93 +275,6 @@ function isWatch(input) {
   }
   return !!input.watch;
 }
-const COMMON_FLAGS = {
-  all: {
-    type: "boolean",
-    default: false,
-    description: "Target all files"
-  },
-  changed: {
-    type: "boolean",
-    default: false,
-    description: "Target changed files"
-  },
-  coverage: {
-    type: "boolean",
-    default: false,
-    description: "Run with coverage"
-  },
-  cover: {
-    type: "boolean",
-    default: false,
-    description: "Run with coverage (alias)"
-  },
-  debug: {
-    type: "boolean",
-    default: false,
-    description: "Enable debug output"
-  },
-  "dry-run": {
-    type: "boolean",
-    default: false,
-    description: "Perform a dry run"
-  },
-  fix: {
-    type: "boolean",
-    default: false,
-    description: "Automatically fix issues"
-  },
-  force: {
-    type: "boolean",
-    default: false,
-    description: "Force the operation"
-  },
-  help: {
-    type: "boolean",
-    default: false,
-    short: "h",
-    description: "Show help"
-  },
-  json: {
-    type: "boolean",
-    default: false,
-    description: "Output as JSON"
-  },
-  quiet: {
-    type: "boolean",
-    default: false,
-    short: "q",
-    description: "Suppress output"
-  },
-  silent: {
-    type: "boolean",
-    default: false,
-    description: "Suppress all output"
-  },
-  staged: {
-    type: "boolean",
-    default: false,
-    description: "Target staged files"
-  },
-  update: {
-    type: "boolean",
-    default: false,
-    short: "u",
-    description: "Update snapshots/deps"
-  },
-  verbose: {
-    type: "boolean",
-    default: false,
-    short: "v",
-    description: "Verbose output"
-  },
-  watch: {
-    type: "boolean",
-    default: false,
-    short: "w",
-    description: "Watch mode"
-  }
-};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   COMMON_FLAGS,

package/dist/argv/parse.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @fileoverview Argument parsing utilities for CLI applications.
+ * Wraps the vendored yargs-parser with a Node.js parseArgs-compatible surface
+ * for booleans, strings, arrays, aliases, defaults, and coercion.
+ */
 /**
  * Yargs parser result interface.
  */
@@ -9,47 +14,57 @@ interface YargsArguments extends Record<string, unknown> {
  * Options for configuring argument parsing, similar to Node.js util.parseArgs.
  */
 export interface ParseArgsOptionsConfig {
-    // Whether the option accepts multiple values (array).
     multiple?: boolean | undefined;
-    // Short alias for the option (single character).
     short?: string | undefined;
-    // Type of the option value.
     type?: 'boolean' | 'string' | undefined;
-    // Default value for the option.
     default?: unknown | undefined;
-    // Transform function to coerce parsed values.
     coerce?: (value: unknown) => unknown | undefined;
 }
 /**
  * Configuration object for parseArgs function, similar to Node.js util.parseArgs.
  */
 export interface ParseArgsConfig {
-    // Command-line arguments to parse (defaults to process.argv.slice(2)).
     args?: readonly string[] | undefined;
-    // Options configuration object.
     options?: Record<string, ParseArgsOptionsConfig> | undefined;
-    // Whether to throw on unknown options (default: true).
     strict?: boolean | undefined;
-    // Whether to populate tokens array (not implemented, for API compatibility).
     tokens?: boolean | undefined;
-    // Whether to allow positional arguments after options.
     allowPositionals?: boolean | undefined;
-    // Whether to allow negative numbers as option values.
     allowNegative?: boolean | undefined;
-    // Advanced yargs-parser configuration passthrough.
     configuration?: Record<string, boolean | string> | undefined;
 }
 /**
  * Result of parsing command-line arguments.
  */
 export interface ParsedArgs<T = Record<string, unknown>> {
-    // Parsed option values.
     values: T;
-    // Positional arguments (non-option arguments).
     positionals: string[];
-    // Raw parsed arguments object from yargs-parser.
     raw: YargsArguments;
 }
+/**
+ * Common parseArgs configuration for Socket registry scripts.
+ */
+export declare const commonParseArgsConfig: ParseArgsConfig;
+/**
+ * Extract positional arguments from process.argv.
+ * Useful for commands that accept file paths or other positional parameters.
+ *
+ * @example
+ * ```typescript
+ * // process.argv = ["node", "script.js", "src", "lib", "--verbose"]
+ * getPositionalArgs()  // ["src", "lib"]
+ * ```
+ */
+export declare function getPositionalArgs(startIndex?: number): string[];
+/**
+ * Check if a specific flag is present in argv.
+ *
+ * @example
+ * ```typescript
+ * hasFlag('verbose')  // true if --verbose is in process.argv
+ * hasFlag('force', ['--force', '--quiet'])  // true
+ * ```
+ */
+export declare function hasFlag(flag: string, argv?: string[]): boolean;
 /**
  * Parse command-line arguments with a Node.js parseArgs-compatible API.
  * Uses yargs-parser internally for robust argument parsing.
@@ -79,29 +94,4 @@ export declare function parseArgs<T = Record<string, unknown>>(config?: ParseArg
  * ```
  */
 export declare function parseArgsWithDefaults<T = Record<string, unknown>>(config?: ParseArgsConfig): ParsedArgs<T>;
-/**
- * Common parseArgs configuration for Socket registry scripts.
- */
-export declare const commonParseArgsConfig: ParseArgsConfig;
-/**
- * Extract positional arguments from process.argv.
- * Useful for commands that accept file paths or other positional parameters.
- *
- * @example
- * ```typescript
- * // process.argv = ["node", "script.js", "src", "lib", "--verbose"]
- * getPositionalArgs()  // ["src", "lib"]
- * ```
- */
-export declare function getPositionalArgs(startIndex?: number): string[];
-/**
- * Check if a specific flag is present in argv.
- *
- * @example
- * ```typescript
- * hasFlag('verbose')  // true if --verbose is in process.argv
- * hasFlag('force', ['--force', '--quiet'])  // true
- * ```
- */
-export declare function hasFlag(flag: string, argv?: string[]): boolean;
 export {};

package/dist/argv/parse.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -38,6 +39,38 @@ __export(parse_exports, {
 module.exports = __toCommonJS(parse_exports);
 var import_node_process = __toESM(require("node:process"));
 var import_yargs_parser = __toESM(require("../external/yargs-parser"));
+const commonParseArgsConfig = {
+  options: {
+    force: {
+      type: "boolean",
+      short: "f",
+      default: false
+    },
+    quiet: {
+      type: "boolean",
+      short: "q",
+      default: false
+    }
+  },
+  strict: false
+};
+function getPositionalArgs(startIndex = 2) {
+  const args = import_node_process.default.argv.slice(startIndex);
+  const positionals = [];
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg.startsWith("-")) {
+      break;
+    }
+    positionals.push(arg);
+    i++;
+  }
+  return positionals;
+}
+function hasFlag(flag, argv = import_node_process.default.argv) {
+  return argv.includes(`--${flag}`);
+}
 function parseArgs(config = {}) {
   const {
     allowNegative = false,
@@ -127,38 +160,6 @@ function parseArgsWithDefaults(config = {}) {
     ...config
   });
 }
-const commonParseArgsConfig = {
-  options: {
-    force: {
-      type: "boolean",
-      short: "f",
-      default: false
-    },
-    quiet: {
-      type: "boolean",
-      short: "q",
-      default: false
-    }
-  },
-  strict: false
-};
-function getPositionalArgs(startIndex = 2) {
-  const args = import_node_process.default.argv.slice(startIndex);
-  const positionals = [];
-  let i = 0;
-  while (i < args.length) {
-    const arg = args[i];
-    if (arg.startsWith("-")) {
-      break;
-    }
-    positionals.push(arg);
-    i++;
-  }
-  return positionals;
-}
-function hasFlag(flag, argv = import_node_process.default.argv) {
-  return argv.includes(`--${flag}`);
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   commonParseArgsConfig,

package/dist/arrays.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @fileoverview Array utility functions for formatting lists and collections.
+ * Provides conjunction and disjunction formatters using Intl.ListFormat.
+ */
 /**
  * Split an array into chunks of a specified size.
  *
@@ -27,7 +31,6 @@
  * // Returns: [[1, 2], [3]]
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function arrayChunk<T>(arr: T[] | readonly T[], size?: number | undefined): T[][];
 /**
  * Get unique values from an array.
@@ -59,12 +62,7 @@ export declare function arrayChunk<T>(arr: T[] | readonly T[], size?: number | u
  * // Returns: []
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function arrayUnique<T>(arr: T[] | readonly T[]): T[];
-// IMPORTANT: Do not use destructuring here - use direct assignment instead.
-// tsgo has a bug that incorrectly transpiles destructured exports, resulting in
-// `exports.SomeName = void 0;` which causes runtime errors.
-// See: https://github.com/SocketDev/socket-packageurl-js/issues/3
 /**
  * Alias for native Array.isArray.
  * Determines whether the passed value is an array.
@@ -132,7 +130,6 @@ export declare const isArray: (arg: any) => arg is any[];
  * // Outputs: "You can choose React, Vue, and Angular"
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function joinAnd(arr: string[] | readonly string[]): string;
 /**
  * Join array elements with proper "or" disjunction formatting.
@@ -168,5 +165,4 @@ export declare function joinAnd(arr: string[] | readonly string[]): string;
  * // Outputs: "Choose a package manager: npm, yarn, or pnpm"
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function joinOr(arr: string[] | readonly string[]): string;

package/dist/arrays.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;

package/dist/bin.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @fileoverview Binary path resolution and execution utilities for package managers.
+ * Provides cross-platform bin path lookup, command execution, and path normalization.
+ */
 /**
  * Options for the which function.
  */
@@ -24,14 +28,13 @@ export interface WhichOptions {
  * await execBin('/usr/local/bin/node', ['script.js'], { cwd: '/tmp' })
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function execBin(binPath: string, args?: string[], options?: import('./spawn').SpawnOptions): Promise<{
     cmd: string;
     args: string[] | readonly string[];
     code: number;
-    signal: NodeJS.Signals;
-    stdout: string | Buffer<ArrayBufferLike>;
-    stderr: string | Buffer<ArrayBufferLike>;
+    signal: NodeJS.Signals | null;
+    stdout: string | Buffer;
+    stderr: string | Buffer;
 }>;
 /**
  * Find the real executable for a binary, bypassing shadow bins.
@@ -83,7 +86,6 @@ export declare function findRealYarn(): string;
  * ```
  */
 export declare function isShadowBinPath(dirPath: string | undefined): boolean;
-/*@__NO_SIDE_EFFECTS__*/
 /**
  * Resolve a binary path to the real underlying script file.
  * Handles Windows .cmd wrappers and Unix shell scripts, resolving them to the actual .js files they execute.