/**
 * Entry metadata for a directory listing.
 */
interface DirectoryEntry {
    /** Entry basename */
    name: string;
    /** Full path */
    path: string;
    /** Is a file */
    isFile: boolean;
    /** Is a directory */
    isDirectory: boolean;
    /** Is a symbolic link */
    isSymlink: boolean;
    /** Directory depth (for recursive listings) */
    depth?: number;
}
/**
 * Options for recursive directory listing.
 */
interface RecursiveOptions {
    /** Maximum depth (-1 or Infinity for unlimited) */
    maxDepth?: number;
    /** Include hidden files (dotfiles) */
    includeHidden?: boolean;
    /** Follow symbolic links into directories */
    followSymlinks?: boolean;
}
/**
 * List immediate contents of a directory.
 *
 * @param dirPath - Absolute or relative path to the directory
 * @returns Array of entries with metadata for each file/directory
 * @throws {Error} If directory doesn't exist or isn't a directory
 *
 * @example Listing directory contents
 * ```typescript
 * import { readDirectory } from '@hyperfrontend/project-scope'
 *
 * const entries = readDirectory('./src')
 * for (const entry of entries) {
 *   console.log(entry.name, entry.isFile ? 'file' : 'directory')
 * }
 * ```
 */
declare function readDirectory(dirPath: string): DirectoryEntry[];
/**
 * List directory contents recursively with depth tracking.
 *
 * @param dirPath - Root directory path to start traversal
 * @param options - Configuration for depth limit, hidden files, and symlinks
 * @returns Flat array of all entries found during traversal
 *
 * @example Recursive directory listing with options
 * ```typescript
 * import { readDirectoryRecursive } from '@hyperfrontend/project-scope'
 *
 * // List all files up to 3 levels deep
 * const entries = readDirectoryRecursive('./src', { maxDepth: 3 })
 *
 * // Include hidden files
 * const allEntries = readDirectoryRecursive('./project', { includeHidden: true })
 * ```
 */
declare function readDirectoryRecursive(dirPath: string, options?: RecursiveOptions): DirectoryEntry[];
/**
 * Options for {@link createDirectory}.
 */
interface CreateDirectoryOptions {
    /** Create parent directories if missing (default: true) */
    recursive?: boolean;
}
/**
 * Create a directory, optionally creating parent directories.
 *
 * @param dirPath - Path where the directory should be created
 * @param options - Creation options
 * @param options.recursive - Create parent directories if missing (default: true)
 *
 * @example Creating directories
 * ```typescript
 * // Create nested directories
 * createDirectory('./output/reports/2024')
 *
 * // Create single directory without parents
 * createDirectory('./logs', { recursive: false })
 * ```
 */
declare function createDirectory(dirPath: string, options?: CreateDirectoryOptions): void;
/**
 * Options for {@link removeDirectory}.
 */
interface RemoveDirectoryOptions {
    /** Delete directory contents recursively */
    recursive?: boolean;
    /** Ignore errors if directory doesn't exist */
    force?: boolean;
}
/**
 * Delete a directory from the filesystem.
 *
 * @param dirPath - Path to the directory to remove
 * @param options - Removal configuration
 * @param options.recursive - Delete directory contents recursively
 * @param options.force - Ignore errors if directory doesn't exist
 *
 * @example Removing directories
 * ```typescript
 * // Remove directory and all contents
 * removeDirectory('./temp', { recursive: true })
 *
 * // Safe removal (no error if missing)
 * removeDirectory('./cache', { recursive: true, force: true })
 * ```
 */
declare function removeDirectory(dirPath: string, options?: RemoveDirectoryOptions): void;

/**
 * Error codes for file system operations.
 */
type FileSystemErrorCode = 'FS_NOT_FOUND' | 'FS_READ_ERROR' | 'FS_WRITE_ERROR' | 'FS_PARSE_ERROR' | 'FS_NOT_A_DIRECTORY';
/**
 * File system error with code and context.
 */
interface FileSystemErrorContext {
    /** Absolute or relative path where the error occurred */
    path: string;
    /** The filesystem operation that failed */
    operation: 'read' | 'write' | 'stat' | 'readdir';
    /** Original error that caused the failure */
    cause?: unknown;
}
/**
 * Create a file system error with code and context.
 *
 * @param message - The error message describing what went wrong
 * @param code - The category code for this type of filesystem failure
 * @param context - Additional context including path, operation, and cause
 * @returns A configured Error object with code and context properties
 *
 * @example Creating a file system error
 * ```typescript
 * throw createFileSystemError(
 *   'Cannot read file',
 *   'FS_READ_ERROR',
 *   { path: './missing.txt', operation: 'read' }
 * )
 * ```
 */
declare function createFileSystemError(message: string, code: FileSystemErrorCode, context: FileSystemErrorContext): Error;
/**
 * Read file contents as string.
 *
 * @param filePath - Path to file
 * @param encoding - File encoding (default: utf-8)
 * @returns File contents as string
 * @throws {Error} If file doesn't exist or can't be read
 *
 * @example Reading file contents
 * ```typescript
 * import { readFileContent } from '@hyperfrontend/project-scope'
 *
 * const content = readFileContent('./package.json')
 * console.log(content) // JSON string
 * ```
 */
declare function readFileContent(filePath: string, encoding?: BufferEncoding): string;
/**
 * Read file contents as Buffer.
 *
 * @param filePath - Path to file
 * @returns File contents as Buffer
 * @throws {Error} If file doesn't exist or can't be read
 *
 * @example Reading file as buffer
 * ```typescript
 * const buffer = readFileBuffer('./image.png')
 * console.log(buffer.length) // File size in bytes
 * ```
 */
declare function readFileBuffer(filePath: string): Buffer;
/**
 * Read file if exists, return null otherwise.
 *
 * @param filePath - Path to file
 * @param encoding - File encoding (default: utf-8)
 * @returns File contents or null if file doesn't exist
 *
 * @example Reading file if it exists
 * ```typescript
 * const content = readFileIfExists('./optional-config.json')
 * if (content) {
 *   // File existed, use content
 * }
 * ```
 */
declare function readFileIfExists(filePath: string, encoding?: BufferEncoding): string | null;
/**
 * Options for reading a JSON file.
 */
interface ReadJsonFileOptions<T> {
    /** Default value to return if the file is not found */
    default?: T;
}
/**
 * Read and parse JSON file.
 *
 * @param filePath - Path to JSON file
 * @param options - Parse options
 * @param options.default - Default value if file not found (if not provided, throws on missing file)
 * @returns Parsed JSON object
 * @throws {Error} If file doesn't exist (when no default provided) or contains invalid JSON
 *
 * @example Reading JSON file
 * ```typescript
 * import { readJsonFile } from '@hyperfrontend/project-scope'
 *
 * // Read with type inference
 * interface Config { port: number }
 * const config = readJsonFile<Config>('./config.json')
 *
 * // Read with default fallback
 * const settings = readJsonFile('./settings.json', { default: {} })
 * ```
 */
declare function readJsonFile<T>(filePath: string, options?: ReadJsonFileOptions<T>): T;
/**
 * Read and parse JSON file if exists, return null otherwise.
 *
 * @param filePath - Path to JSON file
 * @returns Parsed JSON object or null if file doesn't exist or is invalid
 *
 * @example Reading JSON file if it exists
 * ```typescript
 * interface UserSettings { theme: string }
 * const settings = readJsonFileIfExists<UserSettings>('./user-settings.json')
 * const theme = settings?.theme ?? 'default'
 * ```
 */
declare function readJsonFileIfExists<T>(filePath: string): T | null;

/**
 * File statistics.
 */
interface FileStats {
    /** Is a file */
    isFile: boolean;
    /** Is a directory */
    isDirectory: boolean;
    /** Is a symbolic link */
    isSymlink: boolean;
    /** File size in bytes */
    size: number;
    /** Creation time */
    created: Date;
    /** Modification time */
    modified: Date;
    /** Last access time */
    accessed: Date;
    /** File mode/permissions */
    mode: number;
}
/**
 * Get file stats with error handling.
 *
 * @param filePath - Path to file
 * @param followSymlinks - Whether to follow symlinks (default: true)
 * @returns File stats or null if path doesn't exist
 *
 * @example Getting file statistics
 * ```typescript
 * const stats = getFileStat('./package.json')
 * if (stats) {
 *   console.log(`Size: ${stats.size} bytes`)
 *   console.log(`Modified: ${stats.modified}`)
 * }
 * ```
 */
declare function getFileStat(filePath: string, followSymlinks?: boolean): FileStats | null;
/**
 * Check if path is a file.
 *
 * @param filePath - Path to check
 * @returns True if path is a file
 *
 * @example Checking if path is a file
 * ```typescript
 * if (isFile('./package.json')) {
 *   // Path exists and is a regular file
 * }
 * ```
 */
declare function isFile(filePath: string): boolean;
/**
 * Check if path is a directory.
 *
 * @param dirPath - Path to check
 * @returns True if path is a directory
 *
 * @example Checking if path is a directory
 * ```typescript
 * if (isDirectory('./src')) {
 *   // Path exists and is a directory
 * }
 * ```
 */
declare function isDirectory(dirPath: string): boolean;
/**
 * Check if path is a symbolic link.
 *
 * @param linkPath - Path to check
 * @returns True if path is a symlink
 *
 * @example Checking if path is a symlink
 * ```typescript
 * if (isSymlink('./node_modules/.bin/tsc')) {
 *   // Path is a symbolic link
 * }
 * ```
 */
declare function isSymlink(linkPath: string): boolean;
/**
 * Check if path exists.
 *
 * @param filePath - Path to check
 * @returns True if path exists
 *
 * @example Checking if path exists
 * ```typescript
 * if (exists('./config.json')) {
 *   const config = readJsonFile('./config.json')
 * }
 * ```
 */
declare function exists(filePath: string): boolean;

/**
 * Options for write operations.
 */
interface WriteFileOptions {
    /** File encoding */
    encoding?: BufferEncoding;
    /** File mode/permissions */
    mode?: number;
}
/**
 * Options for JSON write operations.
 */
interface WriteJsonOptions extends WriteFileOptions {
    /** Indentation spaces (default: 2) */
    indent?: number;
}
/**
 * Ensure directory exists, create recursively if not.
 *
 * @param dirPath - Directory path to ensure exists
 *
 * @example Ensuring directory exists
 * ```typescript
 * ensureDir('./output/reports')
 * // Directory now exists (created if missing)
 * ```
 */
declare function ensureDir(dirPath: string): void;
/**
 * Write string content to file.
 * Creates parent directories if needed.
 *
 * @param filePath - Absolute or relative path to the target file
 * @param content - String content to write to the file
 * @param options - Optional write configuration (encoding, mode)
 * @throws {Error} If write fails
 *
 * @example Writing text content to file
 * ```typescript
 * import { writeFileContent } from '@hyperfrontend/project-scope'
 *
 * // Write a simple text file
 * writeFileContent('./output/data.txt', 'Hello, World!')
 *
 * // Write with custom encoding
 * writeFileContent('./output/data.txt', 'Content', { encoding: 'utf-8' })
 * ```
 */
declare function writeFileContent(filePath: string, content: string, options?: WriteFileOptions): void;
/**
 * Write Buffer to file.
 * Creates parent directories if needed.
 *
 * @param filePath - Absolute or relative path to the target file
 * @param content - Buffer containing binary data to write
 * @param options - Optional write configuration (mode)
 * @throws {Error} If write fails
 *
 * @example Writing binary buffer to file
 * ```typescript
 * const imageBuffer = Buffer.from([0x89, 0x50, 0x4e, 0x47])
 * writeFileBuffer('./output/image.png', imageBuffer)
 * ```
 */
declare function writeFileBuffer(filePath: string, content: Buffer, options?: WriteFileOptions): void;
/**
 * Write JSON data to file with formatting.
 * Creates parent directories if needed.
 *
 * @param filePath - Absolute or relative path to the target JSON file
 * @param data - Object or value to serialize as JSON
 * @param options - Optional write configuration (indent, encoding, mode)
 * @throws {Error} If write fails
 *
 * @example Writing JSON data to file
 * ```typescript
 * import { writeJsonFile } from '@hyperfrontend/project-scope'
 *
 * // Write object to JSON file
 * writeJsonFile('./config.json', { port: 3000, debug: true })
 *
 * // Write with custom indentation
 * writeJsonFile('./config.json', data, { indent: 4 })
 * ```
 */
declare function writeJsonFile<T>(filePath: string, data: T, options?: WriteJsonOptions): void;

/**
 * Generic upward directory traversal.
 * Name avoids similarity to fs.readdir/fs.readdirSync.
 *
 * @param startPath - Starting directory
 * @param predicate - Function to test each directory
 * @returns First matching directory or null
 *
 * @example Finding directory containing README
 * ```typescript
 * // Find first directory containing a README
 * const readmeDir = traverseUpward('./src/utils', (dir) =>
 *   existsSync(join(dir, 'README.md'))
 * )
 * // => '/project' or null
 * ```
 */
declare function traverseUpward(startPath: string, predicate: (dirPath: string) => boolean): string | null;
/**
 * Find directory containing any of the specified marker files.
 *
 * @param startPath - Starting directory
 * @param markers - Array of marker file names to search for
 * @returns First directory containing any marker, or null
 *
 * @example Finding project root by marker files
 * ```typescript
 * // Find project root by looking for common marker files
 * const projectRoot = locateByMarkers('./src/components', [
 *   'package.json',
 *   'nx.json',
 *   'tsconfig.base.json'
 * ])
 * // => '/workspace/my-project'
 * ```
 */
declare function locateByMarkers(startPath: string, markers: readonly string[]): string | null;
/**
 * Find directory where predicate returns true, starting from given path.
 *
 * @param startPath - Starting directory
 * @param test - Function to test if directory matches criteria
 * @returns Matching directory path or null
 *
 * @example Finding directory with specific config
 * ```typescript
 * // Find directory with a specific config
 * const configDir = findUpwardWhere('./deep/nested/path', (dir) =>
 *   existsSync(join(dir, '.eslintrc.js'))
 * )
 * ```
 */
declare function findUpwardWhere(startPath: string, test: (dirPath: string) => boolean): string | null;

export { createDirectory, createFileSystemError, ensureDir, exists, findUpwardWhere, getFileStat, isDirectory, isFile, isSymlink, locateByMarkers, readDirectory, readDirectoryRecursive, readFileBuffer, readFileContent, readFileIfExists, readJsonFile, readJsonFileIfExists, removeDirectory, traverseUpward, writeFileBuffer, writeFileContent, writeJsonFile };
export type { DirectoryEntry, FileStats, FileSystemErrorCode, FileSystemErrorContext, ReadJsonFileOptions, RecursiveOptions, WriteFileOptions, WriteJsonOptions };