@hyperfrontend/project-scope 0.2.0 → 0.2.2

package/project/traversal/index.d.ts

@@ -1,3 +1,165 @@
-export * from './walk';
-export * from './search';
-//# sourceMappingURL=index.d.ts.map
+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 };

package/project/traversal/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/project-scope/src/project/traversal/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAA;AACtB,cAAc,UAAU,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/project-scope/src/project/traversal/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAC3C,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAA;AACpF,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AACtE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA"}