@socketsecurity/lib/dist/path.d.ts

Core utilities and infrastructure for Socket.dev security tools

/**
 * Check if a path contains node_modules directory.
 *
 * Detects whether a given path includes a `node_modules` directory segment.
 * This is useful for identifying npm package dependencies and filtering
 * dependency-related paths.
 *
 * The check matches `node_modules` appearing as a complete path segment,
 * ensuring it is either at the start, end, or surrounded by path separators.
 *
 * @param {string | Buffer | URL} pathLike - The path to check
 * @returns {boolean} `true` if the path contains `node_modules`, `false` otherwise
 *
 * @example
 * ```typescript
 * isNodeModules('/project/node_modules/package')    // true
 * isNodeModules('node_modules/package/index.js')    // true
 * isNodeModules('/src/my_node_modules_backup')      // false
 * isNodeModules('/project/src/index.js')            // false
 * ```
 */
/*@__NO_SIDE_EFFECTS__*/
export declare function isNodeModules(pathLike: string | Buffer | URL): boolean;
/**
 * Check if a path is absolute.
 *
 * An absolute path is one that specifies a location from the root of the file system.
 * This function handles both POSIX and Windows path formats.
 *
 * POSIX absolute paths:
 * - Start with forward slash '/'
 * - Examples: '/home/user', '/usr/bin/node'
 *
 * Windows absolute paths (3 types):
 * 1. Drive-letter paths: Start with drive letter + colon + separator
 *    - Format: [A-Za-z]:[\\/]
 *    - Examples: 'C:\Windows', 'D:/data', 'c:\Program Files'
 *    - Reference: https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#file-and-directory-names
 *
 * 2. UNC paths: Start with double backslash (handled by backslash check)
 *    - Format: \\server\share
 *    - Examples: '\\server\share\file', '\\?\C:\path'
 *    - Reference: https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#unc-names
 *
 * 3. Device paths: Start with backslash
 *    - Examples: '\Windows', '\\.\device'
 *    - Note: Single backslash paths are relative to current drive
 *
 * @param {string | Buffer | URL} pathLike - The path to check
 * @returns {boolean} `true` if the path is absolute, `false` otherwise
 *
 * @example
 * ```typescript
 * // POSIX paths
 * isAbsolute('/home/user')           // true
 * isAbsolute('/usr/bin/node')        // true
 *
 * // Windows paths
 * isAbsolute('C:\\Windows')          // true
 * isAbsolute('D:/data')              // true
 * isAbsolute('\\\\server\\share')    // true
 *
 * // Relative paths
 * isAbsolute('../relative')          // false
 * isAbsolute('relative/path')        // false
 * isAbsolute('.')                    // false
 * ```
 */
/*@__NO_SIDE_EFFECTS__*/
export declare function isAbsolute(pathLike: string | Buffer | URL): boolean;
/**
 * Check if a value is a valid file path (absolute or relative).
 *
 * Determines whether a given value represents a valid file system path.
 * This function distinguishes between file paths and other string formats
 * like package names, URLs, or bare module specifiers.
 *
 * Valid paths include:
 * - Absolute paths (e.g., `/usr/bin`, `C:\Windows`)
 * - Relative paths with separators (e.g., `./src`, `../lib`)
 * - Special relative paths (`.`, `..`)
 * - Paths starting with `@` that have subpaths (e.g., `@scope/name/file`)
 *
 * Not considered paths:
 * - URLs with protocols (e.g., `http://`, `file://`, `git:`)
 * - Bare package names (e.g., `lodash`, `react`)
 * - Scoped package names without subpaths (e.g., `@scope/name`)
 *
 * @param {string | Buffer | URL} pathLike - The value to check
 * @returns {boolean} `true` if the value is a valid file path, `false` otherwise
 *
 * @example
 * ```typescript
 * // Valid paths
 * isPath('/absolute/path')           // true
 * isPath('./relative/path')          // true
 * isPath('../parent/dir')            // true
 * isPath('.')                        // true
 * isPath('..')                       // true
 * isPath('@scope/name/subpath')      // true
 * isPath('C:\\Windows')              // true (Windows)
 *
 * // Not paths
 * isPath('lodash')                   // false - bare package name
 * isPath('@scope/package')           // false - scoped package name
 * isPath('http://example.com')       // false - URL
 * isPath('file://path')              // false - file URL
 * isPath('')                         // false - empty string
 * ```
 */
/*@__NO_SIDE_EFFECTS__*/
export declare function isPath(pathLike: string | Buffer | URL): boolean;
/**
 * Check if a path is relative.
 *
 * Determines whether a given path is relative (i.e., not absolute). A path
 * is considered relative if it does not specify a location from the root of
 * the file system.
 *
 * Relative paths include:
 * - Paths starting with `.` or `..` (e.g., `./src`, `../lib`)
 * - Paths without leading separators (e.g., `src/file.js`)
 * - Empty strings (treated as relative)
 *
 * @param {string | Buffer | URL} pathLike - The path to check
 * @returns {boolean} `true` if the path is relative, `false` if absolute
 *
 * @example
 * ```typescript
 * // Relative paths
 * isRelative('./src/index.js')       // true
 * isRelative('../lib/util.js')       // true
 * isRelative('src/file.js')          // true
 * isRelative('')                     // true
 *
 * // Absolute paths
 * isRelative('/home/user')           // false
 * isRelative('C:\\Windows')          // false (Windows)
 * isRelative('\\\\server\\share')    // false (Windows UNC)
 * ```
 */
/*@__NO_SIDE_EFFECTS__*/
export declare function isRelative(pathLike: string | Buffer | URL): boolean;
/**
 * Normalize a path by converting backslashes to forward slashes and collapsing segments.
 *
 * This function performs several normalization operations:
 * - Converts all backslashes (`\`) to forward slashes (`/`)
 * - Collapses repeated slashes into single slashes
 * - Resolves `.` (current directory) segments
 * - Resolves `..` (parent directory) segments
 * - Preserves UNC path prefixes (`//server/share`)
 * - Preserves Windows namespace prefixes (`//./`, `//?/`)
 * - Returns `.` for empty or collapsed paths
 *
 * Special handling:
 * - UNC paths: Maintains double leading slashes for `//server/share` format
 * - Windows namespaces: Preserves `//./` and `//?/` prefixes
 * - Leading `..` segments: Preserved in relative paths without prefix
 * - Trailing components: Properly handled when resolving `..`
 *
 * @param {string | Buffer | URL} pathLike - The path to normalize
 * @returns {string} The normalized path with forward slashes and collapsed segments
 *
 * @example
 * ```typescript
 * // Basic normalization
 * normalizePath('foo/bar//baz')              // 'foo/bar/baz'
 * normalizePath('foo/./bar')                 // 'foo/bar'
 * normalizePath('foo/bar/../baz')            // 'foo/baz'
 *
 * // Windows paths
 * normalizePath('C:\\Users\\username\\file.txt') // 'C:/Users/username/file.txt'
 * normalizePath('foo\\bar\\baz')                 // 'foo/bar/baz'
 *
 * // UNC paths
 * normalizePath('\\\\server\\share\\file')   // '//server/share/file'
 *
 * // Edge cases
 * normalizePath('')                          // '.'
 * normalizePath('.')                         // '.'
 * normalizePath('..')                        // '..'
 * normalizePath('///foo///bar///')           // '/foo/bar'
 * normalizePath('foo/../..')                 // '..'
 * ```
 */
/*@__NO_SIDE_EFFECTS__*/
export declare function normalizePath(pathLike: string | Buffer | URL): string;
/**
 * Convert a path-like value to a string.
 *
 * Converts various path-like types (string, Buffer, URL) into a normalized
 * string representation. This function handles different input formats and
 * provides consistent string output for path operations.
 *
 * Supported input types:
 * - `string`: Returned as-is
 * - `Buffer`: Decoded as UTF-8 string
 * - `URL`: Converted using `fileURLToPath()`, with fallback for malformed URLs
 * - `null` / `undefined`: Returns empty string
 *
 * URL handling:
 * - Valid file URLs are converted via `url.fileURLToPath()`
 * - Malformed URLs fall back to pathname extraction with decoding
 * - Windows drive letters in URLs are handled specially
 * - Percent-encoded characters are decoded (e.g., `%20` becomes space)
 *
 * @param {string | Buffer | URL | null | undefined} pathLike - The path-like value to convert
 * @returns {string} The string representation of the path, or empty string for null/undefined
 *
 * @example
 * ```typescript
 * // String input
 * pathLikeToString('/home/user')                        // '/home/user'
 *
 * // Buffer input
 * pathLikeToString(Buffer.from('/tmp/file'))            // '/tmp/file'
 *
 * // URL input
 * pathLikeToString(new URL('file:///home/user'))        // '/home/user'
 * pathLikeToString(new URL('file:///C:/Windows'))       // 'C:/Windows' (Windows)
 *
 * // Null/undefined input
 * pathLikeToString(null)                                // ''
 * pathLikeToString(undefined)                           // ''
 *
 * // Percent-encoded URLs
 * pathLikeToString(new URL('file:///path%20with%20spaces'))  // '/path with spaces'
 * ```
 */
/*@__NO_SIDE_EFFECTS__*/
export declare function pathLikeToString(pathLike: string | Buffer | URL | null | undefined): string;
/**
 * Split a path into an array of segments.
 *
 * Divides a path into individual components by splitting on path separators
 * (both forward slashes and backslashes). This is useful for path traversal,
 * analysis, and manipulation.
 *
 * The function handles:
 * - Forward slashes (`/`) on all platforms
 * - Backslashes (`\`) on Windows
 * - Mixed separators in a single path
 * - Empty paths (returns empty array)
 *
 * Note: The resulting array may contain empty strings if the path has leading,
 * trailing, or consecutive separators (e.g., `/foo//bar/` becomes `['', 'foo', '', 'bar', '']`).
 *
 * @param {string | Buffer | URL} pathLike - The path to split
 * @returns {string[]} Array of path segments, or empty array for empty paths
 *
 * @example
 * ```typescript
 * // POSIX paths
 * splitPath('/home/user/file.txt')      // ['', 'home', 'user', 'file.txt']
 * splitPath('src/lib/util.js')          // ['src', 'lib', 'util.js']
 *
 * // Windows paths
 * splitPath('C:\\Users\\John')          // ['C:', 'Users', 'John']
 * splitPath('folder\\file.txt')         // ['folder', 'file.txt']
 *
 * // Mixed separators
 * splitPath('path/to\\file')            // ['path', 'to', 'file']
 *
 * // Edge cases
 * splitPath('')                         // []
 * splitPath('/')                        // ['', '']
 * splitPath('/foo//bar/')               // ['', 'foo', '', 'bar', '']
 * ```
 */
/*@__NO_SIDE_EFFECTS__*/
export declare function splitPath(pathLike: string | Buffer | URL): string[];
/**
 * Remove leading ./ or ../ from a path.
 *
 * Strips the `./` or `.\` prefix from relative paths. This is useful for
 * normalizing paths when the current directory reference is implicit or
 * unwanted.
 *
 * Note: This function only removes a single leading `./` or `.\`. It does
 * not remove `../` prefixes or process the rest of the path.
 *
 * @param {string | Buffer | URL} pathLike - The path to process
 * @returns {string} The path without leading `./` or `.\`, or unchanged if no such prefix
 *
 * @example
 * ```typescript
 * // Remove ./ prefix
 * trimLeadingDotSlash('./src/index.js')     // 'src/index.js'
 * trimLeadingDotSlash('.\\src\\file.txt')   // 'src\\file.txt'
 *
 * // Preserve ../ prefix
 * trimLeadingDotSlash('../lib/util.js')     // '../lib/util.js'
 *
 * // No change for other paths
 * trimLeadingDotSlash('/absolute/path')     // '/absolute/path'
 * trimLeadingDotSlash('relative/path')      // 'relative/path'
 * trimLeadingDotSlash('.')                  // '.'
 * ```
 */
/*@__NO_SIDE_EFFECTS__*/
export declare function trimLeadingDotSlash(pathLike: string | Buffer | URL): string;
/**
 * Get the relative path from one path to another.
 *
 * Computes the relative path from `from` to `to` and normalizes the result.
 * This is a convenience wrapper around the `relative()` function that adds
 * path normalization (converting separators and collapsing segments).
 *
 * The function:
 * 1. Calculates the relative path using `relative()`
 * 2. Normalizes the result using `normalizePath()`
 * 3. Preserves empty strings (same path) without converting to `.`
 *
 * @param {string} from - The source path (starting point)
 * @param {string} to - The destination path (target)
 * @returns {string} The normalized relative path from `from` to `to`, or empty string if paths are identical
 *
 * @example
 * ```typescript
 * // Basic usage
 * relativeResolve('/foo/bar', '/foo/baz')         // '../baz'
 * relativeResolve('/foo/bar/baz', '/foo')         // '../..'
 * relativeResolve('/foo', '/foo/bar')             // 'bar'
 *
 * // Same paths
 * relativeResolve('/foo/bar', '/foo/bar')         // ''
 *
 * // Windows paths (normalized)
 * relativeResolve('C:\\foo\\bar', 'C:\\foo\\baz') // '../baz'
 *
 * // With normalization
 * relativeResolve('/foo/./bar', '/foo/baz')       // '../baz'
 * relativeResolve('/foo/bar/../baz', '/foo/qux')  // '../qux'
 * ```
 */
/*@__NO_SIDE_EFFECTS__*/
export declare function relativeResolve(from: string, to: string): string;