@socketsecurity/lib 5.15.0 → 5.17.0

package/dist/external/tar-fs.js

@@ -547,9 +547,9 @@ var require_text_decoder = __commonJS({
   }
 });
 
-// node_modules/.pnpm/streamx@2.23.0/node_modules/streamx/index.js
+// node_modules/.pnpm/streamx@2.25.0/node_modules/streamx/index.js
 var require_streamx = __commonJS({
-  "node_modules/.pnpm/streamx@2.23.0/node_modules/streamx/index.js"(exports2, module2) {
+  "node_modules/.pnpm/streamx@2.25.0/node_modules/streamx/index.js"(exports2, module2) {
     var { EventEmitter } = require_default();
     var STREAM_DESTROYED = new Error("Stream was destroyed");
     var PREMATURE_CLOSE = new Error("Premature close");
@@ -660,6 +660,9 @@ var require_streamx = __commonJS({
         this.afterWrite = afterWrite.bind(this);
         this.afterUpdateNextTick = updateWriteNT.bind(this);
       }
+      get ending() {
+        return (this.stream._duplexState & WRITE_FINISHING) !== 0;
+      }
       get ended() {
         return (this.stream._duplexState & WRITE_DONE) !== 0;
       }
@@ -761,6 +764,9 @@ var require_streamx = __commonJS({
         this.afterRead = afterRead.bind(this);
         this.afterUpdateNextTick = updateReadNT.bind(this);
       }
+      get ending() {
+        return (this.stream._duplexState & READ_ENDING) !== 0;
+      }
       get ended() {
         return (this.stream._duplexState & READ_DONE) !== 0;
       }
@@ -825,7 +831,8 @@ var require_streamx = __commonJS({
         const stream = this.stream;
         if ((stream._duplexState & READ_STATUS) === READ_QUEUED) {
           const data = this.shift();
-          if (this.pipeTo !== null && this.pipeTo.write(data) === false) stream._duplexState &= READ_PIPE_NOT_DRAINED;
+          if (this.pipeTo !== null && this.pipeTo.write(data) === false)
+            stream._duplexState &= READ_PIPE_NOT_DRAINED;
           if ((stream._duplexState & READ_EMIT_DATA) !== 0) stream.emit("data", data);
           return data;
         }
@@ -839,7 +846,8 @@ var require_streamx = __commonJS({
         const stream = this.stream;
         while ((stream._duplexState & READ_STATUS) === READ_QUEUED && (stream._duplexState & READ_FLOWING) !== 0) {
           const data = this.shift();
-          if (this.pipeTo !== null && this.pipeTo.write(data) === false) stream._duplexState &= READ_PIPE_NOT_DRAINED;
+          if (this.pipeTo !== null && this.pipeTo.write(data) === false)
+            stream._duplexState &= READ_PIPE_NOT_DRAINED;
           if ((stream._duplexState & READ_EMIT_DATA) !== 0) stream.emit("data", data);
         }
       }
@@ -1001,7 +1009,8 @@ var require_streamx = __commonJS({
     function afterRead(err) {
       if (err) this.stream.destroy(err);
       this.stream._duplexState &= READ_NOT_ACTIVE;
-      if (this.readAhead === false && (this.stream._duplexState & READ_RESUMED) === 0) this.stream._duplexState &= READ_NO_READ_AHEAD;
+      if (this.readAhead === false && (this.stream._duplexState & READ_RESUMED) === 0)
+        this.stream._duplexState &= READ_NO_READ_AHEAD;
       this.updateCallback();
     }
     __name(afterRead, "afterRead");
@@ -1265,7 +1274,8 @@ var require_streamx = __commonJS({
         function ondata(data) {
           if (promiseReject === null) return;
           if (error) promiseReject(error);
-          else if (data === null && (stream._duplexState & READ_DONE) === 0) promiseReject(STREAM_DESTROYED);
+          else if (data === null && (stream._duplexState & READ_DONE) === 0)
+            promiseReject(STREAM_DESTROYED);
           else promiseResolve({ value: data, done: data === null });
           promiseReject = promiseResolve = null;
         }
@@ -1512,10 +1522,18 @@ var require_streamx = __commonJS({
       return typeof stream._duplexState === "number" && isStream(stream);
     }
     __name(isStreamx, "isStreamx");
+    function isEnding(stream) {
+      return !!stream._readableState && stream._readableState.ending;
+    }
+    __name(isEnding, "isEnding");
     function isEnded(stream) {
       return !!stream._readableState && stream._readableState.ended;
     }
     __name(isEnded, "isEnded");
+    function isFinishing(stream) {
+      return !!stream._writableState && stream._writableState.ending;
+    }
+    __name(isFinishing, "isFinishing");
     function isFinished(stream) {
       return !!stream._writableState && stream._writableState.ended;
     }
@@ -1530,7 +1548,7 @@ var require_streamx = __commonJS({
     }
     __name(isReadStreamx, "isReadStreamx");
     function isDisturbed(stream) {
-      return (stream._duplexState & OPENING) !== OPENING || (stream._duplexState & ACTIVE_OR_TICKING) !== 0;
+      return (stream._duplexState & OPENING) !== OPENING || (stream._duplexState & DESTROYING) === DESTROYING || (stream._duplexState & ACTIVE_OR_TICKING) !== 0;
     }
     __name(isDisturbed, "isDisturbed");
     function isTypedArray(data) {
@@ -1557,7 +1575,9 @@ var require_streamx = __commonJS({
       pipelinePromise,
       isStream,
       isStreamx,
+      isEnding,
       isEnded,
+      isFinishing,
       isFinished,
       isDisturbed,
       getStreamError,

package/dist/fs.d.ts

@@ -283,6 +283,12 @@ export declare function findUpSync(name: string | string[] | readonly string[],
  * Called automatically by the paths/rewire module when paths are overridden in tests.
  *
  * @internal Used for test rewiring
+ *
+ * @example
+ * ```typescript
+ * invalidatePathCache()
+ * // Cached allowed directories are now cleared
+ * ```
  */
 export declare function invalidatePathCache(): void;
 /**
@@ -382,6 +388,13 @@ export declare function normalizeEncoding(enc: BufferEncoding | string | null |
  *
  * @param enc - Encoding to normalize
  * @returns Normalized encoding string, defaults to 'utf8' for unknown encodings
+ *
+ * @example
+ * ```typescript
+ * normalizeEncodingSlow('ucs2')    // 'utf16le'
+ * normalizeEncodingSlow('LATIN1')  // 'latin1'
+ * normalizeEncodingSlow('binary')  // 'latin1'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function normalizeEncodingSlow(enc: string): BufferEncoding;

package/dist/functions.d.ts

@@ -7,21 +7,51 @@ export type AsyncFunction<TArgs extends unknown[], TResult> = (...args: TArgs) =
 export type AnyFunction = (...args: unknown[]) => unknown;
 /**
  * A no-op function that does nothing.
+ *
+ * @example
+ * ```typescript
+ * const callback = noop
+ * callback()  // does nothing
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function noop(): void;
 /**
  * Create a function that only executes once.
+ *
+ * @example
+ * ```typescript
+ * const init = once(() => Math.random())
+ * init()  // 0.456 (random value)
+ * init()  // 0.456 (same value, not recalculated)
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function once<T extends AnyFunction>(fn: T): T;
 /**
  * Wrap an async function to silently catch and ignore errors.
+ *
+ * @example
+ * ```typescript
+ * const safeFetch = silentWrapAsync(async (url: string) => {
+ *   const res = await fetch(url)
+ *   return res.json()
+ * })
+ * await safeFetch('https://example.com')  // result or undefined on error
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function silentWrapAsync<TArgs extends unknown[], TResult>(fn: AsyncFunction<TArgs, TResult>): (...args: TArgs) => Promise<TResult | undefined>;
 /**
  * Execute a function with tail call optimization via trampoline.
+ *
+ * @example
+ * ```typescript
+ * const factorial = trampoline((n: number, acc = 1): any =>
+ *   n <= 1 ? acc : () => factorial(n - 1, n * acc)
+ * )
+ * factorial(5)  // 120
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function trampoline<T extends AnyFunction>(fn: T): T;

package/dist/globs.d.ts

@@ -32,11 +32,26 @@ export type { Pattern, FastGlobOptions };
 export declare const defaultIgnore: readonly string[];
 /**
  * Create a stream of license file paths matching glob patterns.
+ *
+ * @example
+ * ```typescript
+ * const stream = globStreamLicenses('/tmp/my-package')
+ * for await (const licensePath of stream) {
+ *   console.log(licensePath)
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function globStreamLicenses(dirname: string, options?: GlobOptions): NodeJS.ReadableStream;
 /**
  * Get a cached glob matcher function.
+ *
+ * @example
+ * ```typescript
+ * const isMatch = getGlobMatcher('*.ts')
+ * isMatch('index.ts')  // true
+ * isMatch('index.js')  // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getGlobMatcher(glob: Pattern | Pattern[], options?: {
@@ -47,12 +62,24 @@ export declare function getGlobMatcher(glob: Pattern | Pattern[], options?: {
 /**
  * Asynchronously find files matching glob patterns.
  * Wrapper around fast-glob.
+ *
+ * @example
+ * ```typescript
+ * const files = await glob('src/*.ts', { cwd: '/tmp/project' })
+ * console.log(files) // ['src/index.ts', 'src/utils.ts']
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function glob(patterns: Pattern | Pattern[], options?: FastGlobOptions): Promise<string[]>;
 /**
  * Synchronously find files matching glob patterns.
  * Wrapper around fast-glob.sync.
+ *
+ * @example
+ * ```typescript
+ * const files = globSync('*.json', { cwd: '/tmp/project' })
+ * console.log(files) // ['package.json', 'tsconfig.json']
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function globSync(patterns: Pattern | Pattern[], options?: FastGlobOptions): string[];

package/dist/http-request.d.ts

@@ -429,6 +429,13 @@ export interface HttpResponse {
  * `httpRequest()` (e.g., multipart form-data uploads via `http.request()`,
  * or responses from third-party HTTP libraries) and need to convert it
  * into the standard HttpResponse interface.
+ *
+ * @example
+ * ```typescript
+ * const raw = await makeRawRequest('https://example.com/api')
+ * const response = await readIncomingResponse(raw)
+ * console.log(response.status, response.body.toString('utf8'))
+ * ```
  */
 export declare function readIncomingResponse(msg: IncomingResponse): Promise<HttpResponse>;
 /**
@@ -772,6 +779,15 @@ export declare function fetchChecksums(url: string, options?: FetchChecksumsOpti
 /**
  * Build an enriched error message based on the error code.
  * Generic guidance (no product-specific branding).
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await fetch('https://api.example.com')
+ * } catch (err) {
+ *   console.error(enrichErrorMessage('https://api.example.com', 'GET', err))
+ * }
+ * ```
  */
 export declare function enrichErrorMessage(url: string, method: string, error: NodeJS.ErrnoException): string;
 /**

package/dist/json/format.d.ts

@@ -69,6 +69,12 @@ export declare function extractFormatting(json: string): JsonFormatting;
  * Get default formatting for JSON files.
  *
  * @returns Default formatting (2 spaces, LF line endings)
+ *
+ * @example
+ * ```typescript
+ * const fmt = getDefaultFormatting()
+ * // { indent: 2, newline: '\n' }
+ * ```
  */
 export declare function getDefaultFormatting(): JsonFormatting;
 /**
@@ -109,6 +115,12 @@ export declare function stringifyWithFormatting(content: Record<string, unknown>
  *
  * @param content - Content object with potential symbol properties
  * @returns Object with symbols removed
+ *
+ * @example
+ * ```typescript
+ * const obj = { key: "value", [Symbol.for("indent")]: 2 }
+ * stripFormattingSymbols(obj)  // { key: "value" }
+ * ```
  */
 export declare function stripFormattingSymbols(content: Record<string | symbol, unknown>): Record<string, unknown>;
 /**
@@ -116,6 +128,12 @@ export declare function stripFormattingSymbols(content: Record<string | symbol,
  *
  * @param content - Content object with Symbol.for('indent') and Symbol.for('newline')
  * @returns Formatting metadata, or defaults if symbols not present
+ *
+ * @example
+ * ```typescript
+ * const content = { [Symbol.for("indent")]: 4, [Symbol.for("newline")]: "\r\n" }
+ * getFormattingFromContent(content)  // { indent: 4, newline: "\r\n" }
+ * ```
  */
 export declare function getFormattingFromContent(content: Record<string | symbol, unknown>): JsonFormatting;
 /**

package/dist/memoization.d.ts

@@ -79,6 +79,11 @@ export declare function Memoize(options?: MemoizeOptions<unknown[], unknown>): (
 /**
  * Clear all memoization caches.
  * Useful for testing or when you need to force recomputation.
+ *
+ * @example
+ * ```typescript
+ * clearAllMemoizationCaches()
+ * ```
  */
 export declare function clearAllMemoizationCaches(): void;
 /**

package/dist/packages/edit.d.ts

@@ -83,21 +83,49 @@ export interface EditablePackageJsonInstance {
 }
 /**
  * Get the EditablePackageJson class for package.json manipulation.
+ *
+ * @example
+ * ```typescript
+ * const EditablePackageJson = getEditablePackageJsonClass()
+ * const pkg = await EditablePackageJson.load('/tmp/my-project')
+ * console.log(pkg.content.name)
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getEditablePackageJsonClass(): EditablePackageJsonConstructor;
 /**
  * Convert a package.json object to an editable instance.
+ *
+ * @example
+ * ```typescript
+ * const editable = pkgJsonToEditable({ name: 'my-pkg', version: '1.0.0' })
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function pkgJsonToEditable(pkgJson: PackageJson, options?: EditablePackageJsonOptions): unknown;
 /**
  * Convert package.json to editable instance with file persistence.
+ *
+ * @example
+ * ```typescript
+ * const editable = await toEditablePackageJson(
+ *   { name: 'my-pkg', version: '1.0.0' },
+ *   { path: '/tmp/my-project' }
+ * )
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function toEditablePackageJson(pkgJson: PackageJson, options?: EditablePackageJsonOptions): Promise<unknown>;
 /**
  * Convert package.json to editable instance with file persistence synchronously.
+ *
+ * @example
+ * ```typescript
+ * const editable = toEditablePackageJsonSync(
+ *   { name: 'my-pkg', version: '1.0.0' },
+ *   { path: '/tmp/my-project' }
+ * )
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function toEditablePackageJsonSync(pkgJson: PackageJson, options?: EditablePackageJsonOptions): unknown;

package/dist/packages/exports.d.ts

@@ -1,30 +1,70 @@
 /**
  * Find types definition for a specific subpath in package exports.
+ *
+ * @example
+ * ```typescript
+ * const exports = { '.': { types: './dist/index.d.ts', import: './dist/index.js' } }
+ * const types = findTypesForSubpath(exports, './dist/index.js')
+ * // types === './dist/index.d.ts'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function findTypesForSubpath(entryExports: unknown, subpath: string): string | undefined;
 /**
  * Get subpaths from package exports.
+ *
+ * @example
+ * ```typescript
+ * const exports = { '.': './index.js', './utils': './utils.js' }
+ * getSubpaths(exports) // ['.', './utils']
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSubpaths(entryExports: unknown): string[];
 /**
  * Get file paths from package exports.
+ *
+ * @example
+ * ```typescript
+ * const exports = { '.': './dist/index.js', './utils': './dist/utils.js' }
+ * getExportFilePaths(exports) // ['./dist/index.js', './dist/utils.js']
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getExportFilePaths(entryExports: unknown): string[];
 /**
  * Check if package exports use conditional patterns (e.g., import/require).
+ *
+ * @example
+ * ```typescript
+ * isConditionalExports({ import: './index.mjs', require: './index.cjs' }) // true
+ * isConditionalExports({ '.': './index.js' })                            // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isConditionalExports(entryExports: unknown): boolean;
 /**
  * Check if package exports use subpath patterns (keys starting with '.').
+ *
+ * @example
+ * ```typescript
+ * isSubpathExports({ '.': './index.js', './utils': './utils.js' }) // true
+ * isSubpathExports({ import: './index.mjs' })                     // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isSubpathExports(entryExports: unknown): boolean;
 /**
  * Normalize package.json exports field to canonical format.
+ *
+ * @example
+ * ```typescript
+ * resolvePackageJsonEntryExports('./index.js')
+ * // { '.': './index.js' }
+ *
+ * resolvePackageJsonEntryExports({ '.': './index.js' })
+ * // { '.': './index.js' }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function resolvePackageJsonEntryExports(entryExports: unknown): unknown;

package/dist/packages/licenses.d.ts

@@ -28,41 +28,100 @@ export interface LicenseVisitor {
 }
 /**
  * Collect licenses that are incompatible (copyleft).
+ *
+ * @example
+ * ```typescript
+ * const nodes = [{ license: 'MIT' }, { license: 'GPL-3.0' }]
+ * const incompatible = collectIncompatibleLicenses(nodes)
+ * // incompatible contains only the GPL-3.0 node
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function collectIncompatibleLicenses(licenseNodes: LicenseNode[]): LicenseNode[];
 /**
  * Collect warnings from license nodes.
+ *
+ * @example
+ * ```typescript
+ * const nodes = [{ license: 'UNLICENSED' }]
+ * collectLicenseWarnings(nodes) // ['Package is unlicensed']
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function collectLicenseWarnings(licenseNodes: LicenseNode[]): string[];
 /**
  * Create an AST node from a raw node.
+ *
+ * @example
+ * ```typescript
+ * const raw = { license: 'MIT' }
+ * const node = createAstNode(raw)
+ * // node.type === 'License'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function createAstNode(rawNode: SpdxAstNode): InternalAstNode;
 /**
  * Create a binary operation AST node.
+ *
+ * @example
+ * ```typescript
+ * const raw = {
+ *   left: { license: 'MIT' },
+ *   conjunction: 'OR' as const,
+ *   right: { license: 'Apache-2.0' }
+ * }
+ * const node = createBinaryOperationNode(raw)
+ * // node.type === 'BinaryOperation'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function createBinaryOperationNode(rawNodeParam: SpdxBinaryOperationNode): InternalBinaryOperationNode;
 /**
  * Create a license AST node.
+ *
+ * @example
+ * ```typescript
+ * const node = createLicenseNode({ license: 'MIT' })
+ * // node.type === 'License' && node.license === 'MIT'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function createLicenseNode(rawNode: SpdxLicenseNode): InternalLicenseNode;
 /**
  * Parse an SPDX license expression into an AST.
+ *
+ * @example
+ * ```typescript
+ * const ast = parseSpdxExp('MIT OR Apache-2.0')
+ * // ast is a BinaryOperation node with MIT and Apache-2.0 leaves
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function parseSpdxExp(spdxExp: string): SpdxAstNode | undefined;
 /**
  * Parse package license field into structured license nodes.
+ *
+ * @example
+ * ```typescript
+ * const nodes = resolvePackageLicenses('MIT', '/tmp/my-project')
+ * // [{ license: 'MIT' }]
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function resolvePackageLicenses(licenseFieldValue: string, where: string): LicenseNode[];
 /**
  * Traverse SPDX license AST and invoke visitor callbacks for each node.
+ *
+ * @example
+ * ```typescript
+ * const ast = parseSpdxExp('MIT OR Apache-2.0')
+ * const licenses: string[] = []
+ * if (ast) {
+ *   visitLicenses(ast, { License(node) { licenses.push(node.license) } })
+ * }
+ * // licenses === ['MIT', 'Apache-2.0']
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function visitLicenses(ast: SpdxAstNode, visitor: LicenseVisitor): void;

package/dist/packages/manifest.d.ts

@@ -1,16 +1,34 @@
 import type { PackageJson, PacoteOptions } from '../packages';
 /**
  * Create a package.json object for a Socket registry package.
+ *
+ * @example
+ * ```typescript
+ * const pkgJson = createPackageJson('is-number', 'packages/npm/is-number', {
+ *   version: '1.0.0',
+ *   description: 'Check if a value is a number'
+ * })
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function createPackageJson(sockRegPkgName: string, directory: string, options?: PackageJson | undefined): PackageJson;
 /**
  * Fetch the manifest for a package.
+ *
+ * @example
+ * ```typescript
+ * const manifest = await fetchPackageManifest('lodash@4.17.21')
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function fetchPackageManifest(pkgNameOrId: string, options?: PacoteOptions): Promise<unknown>;
 /**
  * Fetch the packument (package document) for a package.
+ *
+ * @example
+ * ```typescript
+ * const packument = await fetchPackagePackument('lodash')
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function fetchPackagePackument(pkgNameOrId: string, options?: PacoteOptions): Promise<unknown>;

package/dist/packages/normalize.d.ts

@@ -1,21 +1,43 @@
 import type { NormalizeOptions, PackageJson } from '../packages';
 /**
  * Normalize a package.json object with standard npm package normalization.
+ *
+ * @example
+ * ```typescript
+ * const pkgJson = { name: 'my-pkg', version: '1.0.0' }
+ * const normalized = normalizePackageJson(pkgJson)
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function normalizePackageJson(pkgJson: PackageJson, options?: NormalizeOptions): PackageJson;
 /**
  * Extract escaped scope from a Socket registry package name.
+ *
+ * @example
+ * ```typescript
+ * resolveEscapedScope('babel__core') // 'babel__'
+ * resolveEscapedScope('lodash')      // undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function resolveEscapedScope(sockRegPkgName: string): string | undefined;
 /**
  * Resolve original package name from Socket registry package name.
+ *
+ * @example
+ * ```typescript
+ * resolveOriginalPackageName('@socketregistry/is-number') // 'is-number'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function resolveOriginalPackageName(sockRegPkgName: string): string;
 /**
  * Convert escaped scope to standard npm scope format.
+ *
+ * @example
+ * ```typescript
+ * unescapeScope('babel__') // '@babel'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function unescapeScope(escapedScope: string): string;