import { Tree } from '../../vfs';

/**
 * Walk entry representing a file or directory.
 */
interface WalkEntry {
    /** Entry basename */
    name: string;
    /** Full path */
    path: string;
    /** Relative path from start */
    relativePath: string;
    /** Is a file */
    isFile: boolean;
    /** Is a directory */
    isDirectory: boolean;
    /** Is a symbolic link */
    isSymlink: boolean;
    /** Depth from start directory */
    depth: number;
}
/**
 * Configuration for directory traversal behavior.
 */
interface WalkOptions {
    /** Maximum depth (-1 for unlimited) */
    maxDepth?: number;
    /** Include hidden files (dotfiles) */
    includeHidden?: boolean;
    /** Glob patterns to ignore */
    ignorePatterns?: string[];
    /** Respect .gitignore */
    respectGitignore?: boolean;
}
/**
 * Visitor function signature.
 */
type WalkVisitorResult = void | 'skip' | 'stop';
/**
 * Walk visitor function.
 */
type WalkVisitor = (entry: WalkEntry) => WalkVisitorResult;
/**
 * Traverses a directory tree synchronously, calling a visitor function
 * for each file and directory encountered. Supports depth limiting,
 * hidden file filtering, and gitignore pattern matching.
 *
 * @param startPath - Root directory to begin traversal
 * @param visitor - Callback function invoked for each file system entry
 * @param options - Configuration for traversal behavior
 *
 * @example Walking a directory tree
 * ```typescript
 * import { walkDirectory } from '@hyperfrontend/project-scope'
 *
 * const tsFiles: string[] = []
 * walkDirectory('./src', (entry) => {
 *   if (entry.isFile && entry.name.endsWith('.ts')) {
 *     tsFiles.push(entry.relativePath)
 *   }
 * }, { maxDepth: 5, respectGitignore: true })
 * ```
 */
declare function walkDirectory(startPath: string, visitor: WalkVisitor, options?: WalkOptions): void;
/**
 * Traverses a virtual file system tree, calling a visitor function
 * for each file and directory. Operates on in-memory tree structure
 * without disk I/O.
 *
 * @param tree - In-memory virtual file system representation
 * @param startPath - Root path within the tree to begin traversal
 * @param visitor - Callback function invoked for each tree entry
 * @param options - Configuration for traversal behavior
 *
 * @example Walking a virtual tree
 * ```typescript
 * import { createTree, walkTree } from '@hyperfrontend/project-scope'
 *
 * const tree = createTree('/workspace')
 * walkTree(tree, 'src', (entry) => {
 *   if (entry.isDirectory) {
 *     console.log('Dir:', entry.relativePath)
 *     return 'skip' // Don't recurse into this directory
 *   }
 * })
 * ```
 */
declare function walkTree(tree: Tree, startPath: string, visitor: WalkVisitor, options?: WalkOptions): void;

/**
 * Options for file and directory search operations.
 */
interface FindOptions extends WalkOptions {
    /** Return absolute paths */
    absolutePaths?: boolean;
    /** Maximum results to return */
    maxResults?: number;
}
/**
 * Searches a directory tree for files matching one or more glob patterns,
 * returning relative or absolute paths based on options.
 *
 * @param startPath - Root directory to begin the search
 * @param patterns - Glob patterns (e.g., '*.ts', '**\/*.json') to filter files
 * @param options - Configuration for search behavior
 * @returns List of relative file paths that match the patterns
 *
 * @example Finding files by pattern
 * ```typescript
 * import { findFiles } from '@hyperfrontend/project-scope'
 *
 * // Find all TypeScript files
 * const tsFiles = findFiles('./src', '\*\*\/*.ts')
 *
 * // Find multiple file types
 * const configFiles = findFiles('./', ['\*.json', '\*.yaml', '\*.yml'])
 *
 * // Limit results and get absolute paths
 * const first10 = findFiles('./src', '\*\*\/*.ts', {
 *   maxResults: 10,
 *   absolutePaths: true
 * })
 * ```
 */
declare function findFiles(startPath: string, patterns: string | string[], options?: FindOptions): string[];
/**
 * Searches a virtual file system tree for files matching glob patterns,
 * useful for analyzing project structure without disk I/O.
 *
 * @param tree - In-memory virtual file system representation
 * @param patterns - Glob patterns (e.g., '*.ts', '**\/*.json') to filter files
 * @param options - Configuration for search behavior
 * @returns List of virtual file paths that match the patterns
 *
 * @example Finding files in a virtual tree
 * ```typescript
 * import { createTree, findFilesInTree } from '@hyperfrontend/project-scope'
 *
 * const tree = createTree('/workspace')
 * const tsFiles = findFilesInTree(tree, '**\/*.ts', { maxDepth: 3 })
 * // => ['src/index.ts', 'src/utils/helpers.ts']
 * ```
 */
declare function findFilesInTree(tree: Tree, patterns: string | string[], options?: FindOptions): string[];
/**
 * Searches a directory tree for directories matching one or more glob patterns,
 * returning relative or absolute paths based on options.
 *
 * @param startPath - Root directory to begin the search
 * @param patterns - Glob patterns to filter directories (supports wildcards)
 * @param options - Configuration for search behavior
 * @returns List of relative directory paths that match the patterns
 *
 * @example Finding directories by pattern
 * ```typescript
 * import { findDirectories } from '@hyperfrontend/project-scope'
 *
 * const componentDirs = findDirectories('./src', 'components')
 * // => ['features/auth/components', 'features/dashboard/components']
 * ```
 */
declare function findDirectories(startPath: string, patterns: string | string[], options?: FindOptions): string[];

export { findDirectories, findFiles, findFilesInTree, walkDirectory, walkTree };
export type { FindOptions, WalkEntry, WalkOptions, WalkVisitor, WalkVisitorResult };