/**
 * Parsed path components.
 */
interface ParsedPath {
    /** Root of the path (e.g., "/" or "C:\\") */
    root: string;
    /** Directory name */
    dir: string;
    /** Base name with extension */
    base: string;
    /** File extension including dot */
    ext: string;
    /** File name without extension */
    name: string;
}
/**
 * Split path into segments.
 *
 * @param filePath - Path to split
 * @returns Array of path segments
 *
 * @example Splitting path into segments
 * ```typescript
 * pathSegments('src/components/Button.tsx')
 * // => ['src', 'components', 'Button.tsx']
 * ```
 */
declare function pathSegments(filePath: string): string[];
/**
 * Get basename of path.
 *
 * @param filePath - Path to extract basename from
 * @param ext - Optional extension to strip
 * @returns Basename of path
 *
 * @example Getting basename
 * ```typescript
 * getBasename('src/components/Button.tsx')
 * // => 'Button.tsx'
 *
 * getBasename('src/components/Button.tsx', '.tsx')
 * // => 'Button'
 * ```
 */
declare function getBasename(filePath: string, ext?: string): string;
/**
 * Get directory name of path.
 *
 * @param filePath - Path to extract directory from
 * @returns Directory name
 *
 * @example Getting directory name
 * ```typescript
 * getDirname('src/components/Button.tsx')
 * // => 'src/components'
 * ```
 */
declare function getDirname(filePath: string): string;
/**
 * Get file extension (including dot).
 *
 * @param filePath - Path to extract extension from
 * @returns Extension including dot (e.g., '.ts')
 *
 * @example Getting file extension
 * ```typescript
 * getExtension('src/utils/helpers.ts')
 * // => '.ts'
 *
 * getExtension('package.json')
 * // => '.json'
 * ```
 */
declare function getExtension(filePath: string): string;
/**
 * Get filename without extension.
 *
 * @param filePath - Path to extract name from
 * @returns Filename without extension
 *
 * @example Getting filename without extension
 * ```typescript
 * getFileNameWithoutExtension('src/utils/helpers.ts')
 * // => 'helpers'
 * ```
 */
declare function getFileNameWithoutExtension(filePath: string): string;
/**
 * Parse path into components.
 *
 * @param filePath - Path to parse
 * @returns Parsed path components
 *
 * @example Parsing path components
 * ```typescript
 * const parsed = parsePath('/workspace/src/index.ts')
 * // => { root: '/', dir: '/workspace/src', base: 'index.ts', ext: '.ts', name: 'index' }
 * ```
 */
declare function parsePath(filePath: string): ParsedPath;

/**
 * Reports whether `candidate` resolves to a location inside `root`.
 *
 * The lexical check runs first and rejects `..` traversal and absolute escapes
 * with no filesystem access at all, so a hostile path is never stat-ed. Only a
 * path that is already lexically contained is then resolved through symlinks, so
 * an in-tree link cannot tunnel outside the root — and that realpath touches
 * only paths the caller would legitimately read anyway.
 *
 * @param root - The directory the candidate must stay within.
 * @param candidate - The path to validate (resolved relative to the cwd if not absolute).
 * @returns True when the candidate is the root or contained within it.
 *
 * @example Confining a resolved import target
 * ```typescript
 * isWithinRoot('/project', '/project/src/index.ts') // true
 * isWithinRoot('/project', '/project/../etc/passwd') // false
 * ```
 */
declare function isWithinRoot(root: string, candidate: string): boolean;

/**
 * Join path segments.
 * Uses platform-specific separators (e.g., / or \).
 *
 * @param paths - Path segments to join
 * @returns Joined path
 *
 * @example Joining path segments
 * ```typescript
 * const fullPath = join('src', 'components', 'Button.tsx')
 * // => 'src/components/Button.tsx' (or 'src\\components\\Button.tsx' on Windows)
 * ```
 */
declare function join(...paths: string[]): string;
/**
 * Join path segments using POSIX separators (/).
 * Always uses forward slashes regardless of platform.
 *
 * @param paths - Path segments to join
 * @returns Joined path with forward slashes
 *
 * @example Joining paths with forward slashes
 * ```typescript
 * const configPath = joinPosix('config', 'settings', 'app.json')
 * // => 'config/settings/app.json'
 * ```
 */
declare function joinPosix(...paths: string[]): string;

/**
 * Normalize path separators to forward slashes.
 *
 * @param filePath - Path to normalize
 * @returns Normalized path with forward slashes
 *
 * @example Normalizing path separators
 * ```typescript
 * const path = normalizePath('src\\components\\Button.tsx')
 * // => 'src/components/Button.tsx'
 * ```
 */
declare function normalizePath(filePath: string): string;
/**
 * Convert path separators to forward slashes using POSIX style.
 * Resolves `.` and `..` segments for cross-platform configuration.
 *
 * @param filePath - The input path to convert
 * @returns Path with forward slashes and resolved segments
 *
 * @example Converting to forward slashes
 * ```typescript
 * const path = normalizeToForwardSlashes('./src/../lib/utils')
 * // => 'lib/utils'
 * ```
 */
declare function normalizeToForwardSlashes(filePath: string): string;
/**
 * Convert path to use the operating system's native separator.
 *
 * @param filePath - The input path to convert
 * @returns Path with native separators (backslash on Windows, forward slash elsewhere)
 *
 * @example Converting to native separators
 * ```typescript
 * const path = normalizeToNative('src/components/Button.tsx')
 * // => 'src\\components\\Button.tsx' on Windows
 * // => 'src/components/Button.tsx' on Unix
 * ```
 */
declare function normalizeToNative(filePath: string): string;
/**
 * Strip any trailing forward or back slashes from a path.
 *
 * @param filePath - Path that may have trailing slashes
 * @returns Path with trailing slashes removed
 *
 * @example Removing trailing slashes
 * ```typescript
 * removeTrailingSlash('src/components/')
 * // => 'src/components'
 *
 * removeTrailingSlash('path\\to\\dir\\')
 * // => 'path\\to\\dir'
 * ```
 */
declare function removeTrailingSlash(filePath: string): string;
/**
 * Append a forward slash to the path if not already present.
 *
 * @param filePath - Path to process
 * @returns Path with trailing forward slash
 *
 * @example Ensuring trailing slash
 * ```typescript
 * ensureTrailingSlash('src/components')
 * // => 'src/components/'
 *
 * ensureTrailingSlash('already/has/')
 * // => 'already/has/'
 * ```
 */
declare function ensureTrailingSlash(filePath: string): string;

/**
 * Resolve path segments to an absolute path.
 *
 * @param segments - Path segments to resolve
 * @returns Resolved absolute path with normalized separators
 *
 * @example Resolving to absolute path
 * ```typescript
 * const absPath = resolvePath('src', 'components', 'Button.tsx')
 * // => '/workspace/project/src/components/Button.tsx'
 * ```
 */
declare function resolvePath(...segments: string[]): string;
/**
 * Resolve path relative to workspace root.
 *
 * @param workspaceRoot - Workspace root directory
 * @param segments - Path segments relative to workspace
 * @returns Resolved absolute path with normalized separators
 *
 * @example Resolving from workspace root
 * ```typescript
 * const configPath = resolveFromWorkspace('/workspace', 'config', 'app.json')
 * // => '/workspace/config/app.json'
 * ```
 */
declare function resolveFromWorkspace(workspaceRoot: string, ...segments: string[]): string;
/**
 * Resolve symlinks to real path.
 *
 * @param filePath - Path to resolve
 * @returns Real path or null if path doesn't exist
 *
 * @example Resolving symlinks
 * ```typescript
 * const realPath = resolveRealPath('./node_modules/.bin/tsc')
 * // => '/workspace/node_modules/typescript/bin/tsc'
 * ```
 */
declare function resolveRealPath(filePath: string): string | null;
/**
 * Compute the normalized path from source directory to target.
 *
 * @param from - Source path (base directory)
 * @param to - Target path to reach
 * @returns Relative path from source to target with forward slashes
 *
 * @example Computing relative path
 * ```typescript
 * relativePath('/workspace/src/utils', '/workspace/lib/helpers')
 * // => '../../lib/helpers'
 * ```
 */
declare function relativePath(from: string, to: string): string;
/**
 * Join path segments.
 *
 * @param segments - Path segments to join
 * @returns Joined path with normalized separators
 *
 * @example Joining path segments
 * ```typescript
 * joinPath('src', 'components', 'Button.tsx')
 * // => 'src/components/Button.tsx'
 * ```
 */
declare function joinPath(...segments: string[]): string;
/**
 * Check if path is absolute.
 *
 * @param filePath - Path to check
 * @returns True if path is absolute
 *
 * @example Checking absolute path
 * ```typescript
 * isAbsolute('/workspace/src/index.ts')
 * // => true
 *
 * isAbsolute('./src/index.ts')
 * // => false
 * ```
 */
declare function isAbsolute(filePath: string): boolean;
/**
 * Calculate offset from root (e.g., "../../../").
 *
 * @param filePath - Path to calculate offset for
 * @returns Relative offset path (e.g., "../../")
 *
 * @example Calculating offset from root
 * ```typescript
 * offsetFromRoot('libs/utils/src')
 * // => '../../../'
 *
 * offsetFromRoot('apps')
 * // => '../'
 * ```
 */
declare function offsetFromRoot(filePath: string): string;

export { ensureTrailingSlash, getBasename, getDirname, getExtension, getFileNameWithoutExtension, isAbsolute, isWithinRoot, join, joinPath, joinPosix, normalizePath, normalizeToForwardSlashes, normalizeToNative, offsetFromRoot, parsePath, pathSegments, relativePath, removeTrailingSlash, resolveFromWorkspace, resolvePath, resolveRealPath };
export type { ParsedPath };