filemayor 3.6.0 → 4.0.5

package/core/scanner.js

@@ -1,466 +1,466 @@
-#!/usr/bin/env node
-
-/**
- * ═══════════════════════════════════════════════════════════════════
- * FILEMAYOR CORE — SCANNER
- * Recursive directory scanner with configurable depth, filters,
- * glob patterns, and category detection. Enterprise-grade.
- * ═══════════════════════════════════════════════════════════════════
- */
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const { categorize } = require('./categories');
-const { validatePath, isDirSafe, canRead } = require('./security');
-
-// ─── Default Configuration ────────────────────────────────────────
-const DEFAULT_SCAN_OPTIONS = {
-    maxDepth: 20,               // Max recursion depth
-    followSymlinks: false,      // Follow symbolic links
-    includeHidden: false,       // Include dot files/dirs
-    includeDirectories: false,  // Include directories in results
-    extensions: null,           // Filter by extensions (null = all)
-    excludeExtensions: null,    // Exclude specific extensions
-    ignore: [                   // Directories to skip
-        'node_modules', '.git', '__pycache__', '.venv',
-        'venv', '.idea', '.vscode', 'dist', 'build',
-        '.svn', '.hg', 'bower_components', '.terraform',
-        '.next', '.nuxt', '.cache', 'coverage'
-    ],
-    ignorePatterns: [],         // Glob-like name patterns to skip
-    minSize: 0,                 // Minimum file size in bytes
-    maxSize: Infinity,          // Maximum file size in bytes
-    modifiedAfter: null,        // Only files modified after this date
-    modifiedBefore: null,       // Only files modified before this date
-    onProgress: null,           // Progress callback
-    onError: null,              // Error callback
-    abortSignal: null,          // AbortController signal for cancellation
-};
-
-// ─── Glob Pattern Matching ────────────────────────────────────────
-
-/**
- * Simple glob matcher (supports * and ? wildcards)
- * @param {string} pattern - Glob pattern
- * @param {string} str - String to test
- * @returns {boolean}
- */
-function matchGlob(pattern, str) {
-    const regex = pattern
-        .replace(/[.+^${}()|[\]\\]/g, '\\$&') // Escape regex special chars
-        .replace(/\*/g, '.*')                    // * → .*
-        .replace(/\?/g, '.');                    // ? → .
-    return new RegExp(`^${regex}$`, 'i').test(str);
-}
-
-// ─── File Info Construction ───────────────────────────────────────
-
-/**
- * Build a structured FileInfo object from a filesystem entry
- * @param {string} fullPath - Absolute file path
- * @param {fs.Stats} stats - File stats
- * @param {string} rootPath - Original scan root for relative path
- * @returns {Object} Structured file info
- */
-function buildFileInfo(fullPath, stats, rootPath) {
-    const ext = path.extname(fullPath).toLowerCase();
-    const name = path.basename(fullPath);
-    const relativePath = path.relative(rootPath, fullPath);
-    const category = categorize(ext);
-    const dir = path.dirname(fullPath);
-
-    return {
-        name,
-        path: fullPath,
-        relativePath,
-        directory: dir,
-        ext,
-        category,
-        size: stats.size,
-        sizeHuman: formatBytes(stats.size),
-        modified: stats.mtime,
-        created: stats.birthtime,
-        accessed: stats.atime,
-        isFile: stats.isFile(),
-        isDirectory: stats.isDirectory(),
-        isSymlink: stats.isSymbolicLink ? stats.isSymbolicLink() : false,
-        permissions: {
-            readable: true, // We got stats, so it's readable
-            mode: stats.mode
-        }
-    };
-}
-
-/**
- * Format bytes to human-readable string
- * @param {number} bytes
- * @returns {string}
- */
-function formatBytes(bytes) {
-    if (bytes === 0) return '0 B';
-    const units = ['B', 'KB', 'MB', 'GB', 'TB', 'PB'];
-    const i = Math.floor(Math.log(bytes) / Math.log(1024));
-    const value = (bytes / Math.pow(1024, i)).toFixed(i > 0 ? 1 : 0);
-    return `${value} ${units[i]}`;
-}
-
-// ─── Scanner Class ────────────────────────────────────────────────
-
-class Scanner {
-    constructor(options = {}) {
-        this.options = { ...DEFAULT_SCAN_OPTIONS, ...options };
-        this.stats = {
-            filesFound: 0,
-            dirsScanned: 0,
-            totalSize: 0,
-            errors: [],
-            skipped: 0,
-            startTime: null,
-            endTime: null,
-            categories: {}
-        };
-        this._aborted = false;
-    }
-
-    /**
-     * Scan a directory and return all matching files
-     * @param {string} dirPath - Directory to scan
-     * @returns {{ files: Object[], stats: Object }}
-     */
-    scan(dirPath) {
-        const validation = this._validate(dirPath);
-        this.stats.startTime = Date.now();
-        const files = [];
-
-        this._scanRecursive(validation.resolved, validation.resolved, 0, files);
-
-        this.stats.endTime = Date.now();
-        this.stats.duration = this.stats.endTime - this.stats.startTime;
-        this.stats.durationHuman = this._formatDuration(this.stats.duration);
-
-        return {
-            root: validation.resolved,
-            files,
-            stats: { ...this.stats }
-        };
-    }
-
-    /**
-     * Asynchronous scan for higher performance and non-blocking operation
-     * @param {string} dirPath 
-     */
-    async scanAsync(dirPath) {
-        const validation = this._validate(dirPath);
-        this.stats.startTime = Date.now();
-        const files = [];
-
-        await this._scanRecursiveAsync(validation.resolved, validation.resolved, 0, files);
-
-        this.stats.endTime = Date.now();
-        this.stats.duration = this.stats.endTime - this.stats.startTime;
-        this.stats.durationHuman = this._formatDuration(this.stats.duration);
-
-        return {
-            root: validation.resolved,
-            files,
-            stats: { ...this.stats }
-        };
-    }
-
-    /**
-     * Shared validation logic
-     */
-    _validate(dirPath) {
-        const validation = validatePath(dirPath);
-        if (!validation.valid) throw new Error(`Invalid path: ${validation.error}`);
-
-        const safeCheck = isDirSafe(validation.resolved);
-        if (!safeCheck.safe) throw new Error(`Unsafe directory: ${safeCheck.reason}`);
-
-        if (!canRead(validation.resolved)) {
-            throw new Error(`Permission denied: cannot read "${validation.resolved}"`);
-        }
-
-        return validation;
-    }
-
-    /**
-     * Internal recursive scan implementation
-     */
-    _scanRecursive(dir, rootPath, depth, results) {
-        if (this._aborted || this.options.abortSignal?.aborted) {
-            this._aborted = true;
-            return;
-        }
-
-        if (depth > this.options.maxDepth) return;
-        this.stats.dirsScanned++;
-
-        if (this.options.onProgress) {
-            this.options.onProgress({
-                phase: 'scanning',
-                currentDir: dir,
-                filesFound: this.stats.filesFound,
-                dirsScanned: this.stats.dirsScanned,
-                depth
-            });
-        }
-
-        let items;
-        try {
-            items = fs.readdirSync(dir, { withFileTypes: true });
-        } catch (err) {
-            this.stats.errors.push({ path: dir, code: err.code, message: err.message });
-            if (this.options.onError) this.options.onError({ path: dir, error: err.message });
-            return;
-        }
-
-        for (const item of items) {
-            if (this._aborted) return;
-            const fullPath = path.join(dir, item.name);
-
-            if (!this.options.includeHidden && item.name.startsWith('.')) {
-                this.stats.skipped++;
-                continue;
-            }
-
-            if (item.isDirectory() && this.options.ignore.includes(item.name)) {
-                this.stats.skipped++;
-                continue;
-            }
-
-            if (this.options.ignorePatterns.length > 0) {
-                const shouldSkip = this.options.ignorePatterns.some(p => matchGlob(p, item.name));
-                if (shouldSkip) {
-                    this.stats.skipped++;
-                    continue;
-                }
-            }
-
-            if (item.isSymbolicLink && item.isSymbolicLink() && !this.options.followSymlinks) {
-                this.stats.skipped++;
-                continue;
-            }
-
-            let stats;
-            try {
-                stats = this.options.followSymlinks ? fs.statSync(fullPath) : fs.lstatSync(fullPath);
-            } catch (err) {
-                this.stats.errors.push({ path: fullPath, code: err.code, message: err.message });
-                continue;
-            }
-
-            if (stats.isFile()) {
-                if (this._shouldIncludeFile(fullPath, stats)) {
-                    const fileInfo = buildFileInfo(fullPath, stats, rootPath);
-                    results.push(fileInfo);
-                    this.stats.filesFound++;
-                    this.stats.totalSize += stats.size;
-                    const cat = fileInfo.category;
-                    this.stats.categories[cat] = (this.stats.categories[cat] || 0) + 1;
-                } else {
-                    this.stats.skipped++;
-                }
-            } else if (stats.isDirectory()) {
-                if (this.options.includeDirectories) {
-                    results.push(buildFileInfo(fullPath, stats, rootPath));
-                }
-                this._scanRecursive(fullPath, rootPath, depth + 1, results);
-            }
-        }
-    }
-
-    /**
-     * Async recursive scan using promises
-     */
-    async _scanRecursiveAsync(dir, rootPath, depth, results) {
-        if (this._aborted || this.options.abortSignal?.aborted) {
-            this._aborted = true;
-            return;
-        }
-
-        if (depth > this.options.maxDepth) return;
-        this.stats.dirsScanned++;
-
-        let items;
-        try {
-            items = await fs.promises.readdir(dir, { withFileTypes: true });
-        } catch (err) {
-            this.stats.errors.push({ path: dir, code: err.code, message: err.message });
-            return;
-        }
-
-        const promises = items.map(async (item) => {
-            if (this._aborted) return;
-            const fullPath = path.join(dir, item.name);
-
-            // Filtering
-            if (!this.options.includeHidden && item.name.startsWith('.')) return;
-            if (item.isDirectory() && this.options.ignore.includes(item.name)) return;
-
-            let stats;
-            try {
-                stats = await fs.promises.lstat(fullPath);
-            } catch (err) { return; }
-
-            if (stats.isFile()) {
-                if (this._shouldIncludeFile(fullPath, stats)) {
-                    const fileInfo = buildFileInfo(fullPath, stats, rootPath);
-                    results.push(fileInfo);
-                    this.stats.filesFound++;
-                    this.stats.totalSize += stats.size;
-                    const cat = fileInfo.category;
-                    this.stats.categories[cat] = (this.stats.categories[cat] || 0) + 1;
-                }
-            } else if (stats.isDirectory()) {
-                await this._scanRecursiveAsync(fullPath, rootPath, depth + 1, results);
-            }
-        });
-
-        await Promise.all(promises);
-    }
-
-    /**
-     * Check if a file passes all configured filters
-     */
-    _shouldIncludeFile(filePath, stats) {
-        const ext = path.extname(filePath).toLowerCase();
-
-        // Extension whitelist
-        if (this.options.extensions) {
-            const normalizedExts = this.options.extensions.map(e =>
-                e.startsWith('.') ? e.toLowerCase() : `.${e.toLowerCase()}`
-            );
-            if (!normalizedExts.includes(ext)) return false;
-        }
-
-        // Extension blacklist
-        if (this.options.excludeExtensions) {
-            const normalizedExcludes = this.options.excludeExtensions.map(e =>
-                e.startsWith('.') ? e.toLowerCase() : `.${e.toLowerCase()}`
-            );
-            if (normalizedExcludes.includes(ext)) return false;
-        }
-
-        // Size filters
-        if (stats.size < this.options.minSize) return false;
-        if (stats.size > this.options.maxSize) return false;
-
-        // Date filters
-        if (this.options.modifiedAfter) {
-            const threshold = new Date(this.options.modifiedAfter).getTime();
-            if (stats.mtime.getTime() < threshold) return false;
-        }
-        if (this.options.modifiedBefore) {
-            const threshold = new Date(this.options.modifiedBefore).getTime();
-            if (stats.mtime.getTime() > threshold) return false;
-        }
-
-        return true;
-    }
-
-    /**
-     * Abort the current scan
-     */
-    abort() {
-        this._aborted = true;
-    }
-
-    /**
-     * Format milliseconds to human-readable duration
-     */
-    _formatDuration(ms) {
-        if (ms < 1000) return `${ms}ms`;
-        if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
-        const mins = Math.floor(ms / 60000);
-        const secs = ((ms % 60000) / 1000).toFixed(0);
-        return `${mins}m ${secs}s`;
-    }
-}
-
-// ─── Convenience Functions ────────────────────────────────────────
-
-/**
- * Quick scan a directory with default options
- * @param {string} dirPath - Directory to scan
- * @param {Object} options - Scan options
- * @returns {{ files: Object[], stats: Object }}
- */
-function scan(dirPath, options = {}) {
-    const scanner = new Scanner(options);
-    return scanner.scan(dirPath);
-}
-
-/**
- * Quick scan and group results by category
- * @param {string} dirPath - Directory to scan
- * @param {Object} options - Scan options
- * @returns {{ categories: Object, stats: Object }}
- */
-function scanByCategory(dirPath, options = {}) {
-    const result = scan(dirPath, options);
-    const grouped = {};
-
-    for (const file of result.files) {
-        if (!grouped[file.category]) {
-            grouped[file.category] = {
-                files: [],
-                count: 0,
-                totalSize: 0
-            };
-        }
-        grouped[file.category].files.push(file);
-        grouped[file.category].count++;
-        grouped[file.category].totalSize += file.size;
-    }
-
-    // Sort each category's files by name
-    for (const cat of Object.values(grouped)) {
-        cat.files.sort((a, b) => a.name.localeCompare(b.name));
-        cat.totalSizeHuman = formatBytes(cat.totalSize);
-    }
-
-    return {
-        root: result.root,
-        categories: grouped,
-        stats: result.stats
-    };
-}
-
-/**
- * Quick scan and get a size summary
- * @param {string} dirPath - Directory to scan
- * @param {Object} options - Scan options
- * @returns {{ totalSize: number, totalSizeHuman: string, fileCount: number, largestFiles: Object[] }}
- */
-function scanSummary(dirPath, options = {}) {
-    const result = scan(dirPath, options);
-
-    // Sort by size descending
-    const sorted = [...result.files].sort((a, b) => b.size - a.size);
-
-    return {
-        root: result.root,
-        totalSize: result.stats.totalSize,
-        totalSizeHuman: formatBytes(result.stats.totalSize),
-        fileCount: result.stats.filesFound,
-        dirCount: result.stats.dirsScanned,
-        largestFiles: sorted.slice(0, 20),
-        categories: result.stats.categories,
-        duration: result.stats.durationHuman,
-        errors: result.stats.errors
-    };
-}
-
-module.exports = {
-    Scanner,
-    scan,
-    scanByCategory,
-    scanSummary,
-    buildFileInfo,
-    formatBytes,
-    matchGlob,
-    DEFAULT_SCAN_OPTIONS
-};
+#!/usr/bin/env node
+
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR CORE — SCANNER
+ * Recursive directory scanner with configurable depth, filters,
+ * glob patterns, and category detection. Enterprise-grade.
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { categorize } = require('./categories');
+const { validatePath, isDirSafe, canRead } = require('./security');
+
+// ─── Default Configuration ────────────────────────────────────────
+const DEFAULT_SCAN_OPTIONS = {
+    maxDepth: 20,               // Max recursion depth
+    followSymlinks: false,      // Follow symbolic links
+    includeHidden: false,       // Include dot files/dirs
+    includeDirectories: false,  // Include directories in results
+    extensions: null,           // Filter by extensions (null = all)
+    excludeExtensions: null,    // Exclude specific extensions
+    ignore: [                   // Directories to skip
+        'node_modules', '.git', '__pycache__', '.venv',
+        'venv', '.idea', '.vscode', 'dist', 'build',
+        '.svn', '.hg', 'bower_components', '.terraform',
+        '.next', '.nuxt', '.cache', 'coverage'
+    ],
+    ignorePatterns: [],         // Glob-like name patterns to skip
+    minSize: 0,                 // Minimum file size in bytes
+    maxSize: Infinity,          // Maximum file size in bytes
+    modifiedAfter: null,        // Only files modified after this date
+    modifiedBefore: null,       // Only files modified before this date
+    onProgress: null,           // Progress callback
+    onError: null,              // Error callback
+    abortSignal: null,          // AbortController signal for cancellation
+};
+
+// ─── Glob Pattern Matching ────────────────────────────────────────
+
+/**
+ * Simple glob matcher (supports * and ? wildcards)
+ * @param {string} pattern - Glob pattern
+ * @param {string} str - String to test
+ * @returns {boolean}
+ */
+function matchGlob(pattern, str) {
+    const regex = pattern
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&') // Escape regex special chars
+        .replace(/\*/g, '.*')                    // * → .*
+        .replace(/\?/g, '.');                    // ? → .
+    return new RegExp(`^${regex}$`, 'i').test(str);
+}
+
+// ─── File Info Construction ───────────────────────────────────────
+
+/**
+ * Build a structured FileInfo object from a filesystem entry
+ * @param {string} fullPath - Absolute file path
+ * @param {fs.Stats} stats - File stats
+ * @param {string} rootPath - Original scan root for relative path
+ * @returns {Object} Structured file info
+ */
+function buildFileInfo(fullPath, stats, rootPath) {
+    const ext = path.extname(fullPath).toLowerCase();
+    const name = path.basename(fullPath);
+    const relativePath = path.relative(rootPath, fullPath);
+    const category = categorize(ext);
+    const dir = path.dirname(fullPath);
+
+    return {
+        name,
+        path: fullPath,
+        relativePath,
+        directory: dir,
+        ext,
+        category,
+        size: stats.size,
+        sizeHuman: formatBytes(stats.size),
+        modified: stats.mtime,
+        created: stats.birthtime,
+        accessed: stats.atime,
+        isFile: stats.isFile(),
+        isDirectory: stats.isDirectory(),
+        isSymlink: stats.isSymbolicLink ? stats.isSymbolicLink() : false,
+        permissions: {
+            readable: true, // We got stats, so it's readable
+            mode: stats.mode
+        }
+    };
+}
+
+/**
+ * Format bytes to human-readable string
+ * @param {number} bytes
+ * @returns {string}
+ */
+function formatBytes(bytes) {
+    if (bytes === 0) return '0 B';
+    const units = ['B', 'KB', 'MB', 'GB', 'TB', 'PB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(1024));
+    const value = (bytes / Math.pow(1024, i)).toFixed(i > 0 ? 1 : 0);
+    return `${value} ${units[i]}`;
+}
+
+// ─── Scanner Class ────────────────────────────────────────────────
+
+class Scanner {
+    constructor(options = {}) {
+        this.options = { ...DEFAULT_SCAN_OPTIONS, ...options };
+        this.stats = {
+            filesFound: 0,
+            dirsScanned: 0,
+            totalSize: 0,
+            errors: [],
+            skipped: 0,
+            startTime: null,
+            endTime: null,
+            categories: {}
+        };
+        this._aborted = false;
+    }
+
+    /**
+     * Scan a directory and return all matching files
+     * @param {string} dirPath - Directory to scan
+     * @returns {{ files: Object[], stats: Object }}
+     */
+    scan(dirPath) {
+        const validation = this._validate(dirPath);
+        this.stats.startTime = Date.now();
+        const files = [];
+
+        this._scanRecursive(validation.resolved, validation.resolved, 0, files);
+
+        this.stats.endTime = Date.now();
+        this.stats.duration = this.stats.endTime - this.stats.startTime;
+        this.stats.durationHuman = this._formatDuration(this.stats.duration);
+
+        return {
+            root: validation.resolved,
+            files,
+            stats: { ...this.stats }
+        };
+    }
+
+    /**
+     * Asynchronous scan for higher performance and non-blocking operation
+     * @param {string} dirPath 
+     */
+    async scanAsync(dirPath) {
+        const validation = this._validate(dirPath);
+        this.stats.startTime = Date.now();
+        const files = [];
+
+        await this._scanRecursiveAsync(validation.resolved, validation.resolved, 0, files);
+
+        this.stats.endTime = Date.now();
+        this.stats.duration = this.stats.endTime - this.stats.startTime;
+        this.stats.durationHuman = this._formatDuration(this.stats.duration);
+
+        return {
+            root: validation.resolved,
+            files,
+            stats: { ...this.stats }
+        };
+    }
+
+    /**
+     * Shared validation logic
+     */
+    _validate(dirPath) {
+        const validation = validatePath(dirPath);
+        if (!validation.valid) throw new Error(`Invalid path: ${validation.error}`);
+
+        const safeCheck = isDirSafe(validation.resolved);
+        if (!safeCheck.safe) throw new Error(`Unsafe directory: ${safeCheck.reason}`);
+
+        if (!canRead(validation.resolved)) {
+            throw new Error(`Permission denied: cannot read "${validation.resolved}"`);
+        }
+
+        return validation;
+    }
+
+    /**
+     * Internal recursive scan implementation
+     */
+    _scanRecursive(dir, rootPath, depth, results) {
+        if (this._aborted || this.options.abortSignal?.aborted) {
+            this._aborted = true;
+            return;
+        }
+
+        if (depth > this.options.maxDepth) return;
+        this.stats.dirsScanned++;
+
+        if (this.options.onProgress) {
+            this.options.onProgress({
+                phase: 'scanning',
+                currentDir: dir,
+                filesFound: this.stats.filesFound,
+                dirsScanned: this.stats.dirsScanned,
+                depth
+            });
+        }
+
+        let items;
+        try {
+            items = fs.readdirSync(dir, { withFileTypes: true });
+        } catch (err) {
+            this.stats.errors.push({ path: dir, code: err.code, message: err.message });
+            if (this.options.onError) this.options.onError({ path: dir, error: err.message });
+            return;
+        }
+
+        for (const item of items) {
+            if (this._aborted) return;
+            const fullPath = path.join(dir, item.name);
+
+            if (!this.options.includeHidden && item.name.startsWith('.')) {
+                this.stats.skipped++;
+                continue;
+            }
+
+            if (item.isDirectory() && this.options.ignore.includes(item.name)) {
+                this.stats.skipped++;
+                continue;
+            }
+
+            if (this.options.ignorePatterns.length > 0) {
+                const shouldSkip = this.options.ignorePatterns.some(p => matchGlob(p, item.name));
+                if (shouldSkip) {
+                    this.stats.skipped++;
+                    continue;
+                }
+            }
+
+            if (item.isSymbolicLink && item.isSymbolicLink() && !this.options.followSymlinks) {
+                this.stats.skipped++;
+                continue;
+            }
+
+            let stats;
+            try {
+                stats = this.options.followSymlinks ? fs.statSync(fullPath) : fs.lstatSync(fullPath);
+            } catch (err) {
+                this.stats.errors.push({ path: fullPath, code: err.code, message: err.message });
+                continue;
+            }
+
+            if (stats.isFile()) {
+                if (this._shouldIncludeFile(fullPath, stats)) {
+                    const fileInfo = buildFileInfo(fullPath, stats, rootPath);
+                    results.push(fileInfo);
+                    this.stats.filesFound++;
+                    this.stats.totalSize += stats.size;
+                    const cat = fileInfo.category;
+                    this.stats.categories[cat] = (this.stats.categories[cat] || 0) + 1;
+                } else {
+                    this.stats.skipped++;
+                }
+            } else if (stats.isDirectory()) {
+                if (this.options.includeDirectories) {
+                    results.push(buildFileInfo(fullPath, stats, rootPath));
+                }
+                this._scanRecursive(fullPath, rootPath, depth + 1, results);
+            }
+        }
+    }
+
+    /**
+     * Async recursive scan using promises
+     */
+    async _scanRecursiveAsync(dir, rootPath, depth, results) {
+        if (this._aborted || this.options.abortSignal?.aborted) {
+            this._aborted = true;
+            return;
+        }
+
+        if (depth > this.options.maxDepth) return;
+        this.stats.dirsScanned++;
+
+        let items;
+        try {
+            items = await fs.promises.readdir(dir, { withFileTypes: true });
+        } catch (err) {
+            this.stats.errors.push({ path: dir, code: err.code, message: err.message });
+            return;
+        }
+
+        const promises = items.map(async (item) => {
+            if (this._aborted) return;
+            const fullPath = path.join(dir, item.name);
+
+            // Filtering
+            if (!this.options.includeHidden && item.name.startsWith('.')) return;
+            if (item.isDirectory() && this.options.ignore.includes(item.name)) return;
+
+            let stats;
+            try {
+                stats = await fs.promises.lstat(fullPath);
+            } catch (err) { return; }
+
+            if (stats.isFile()) {
+                if (this._shouldIncludeFile(fullPath, stats)) {
+                    const fileInfo = buildFileInfo(fullPath, stats, rootPath);
+                    results.push(fileInfo);
+                    this.stats.filesFound++;
+                    this.stats.totalSize += stats.size;
+                    const cat = fileInfo.category;
+                    this.stats.categories[cat] = (this.stats.categories[cat] || 0) + 1;
+                }
+            } else if (stats.isDirectory()) {
+                await this._scanRecursiveAsync(fullPath, rootPath, depth + 1, results);
+            }
+        });
+
+        await Promise.all(promises);
+    }
+
+    /**
+     * Check if a file passes all configured filters
+     */
+    _shouldIncludeFile(filePath, stats) {
+        const ext = path.extname(filePath).toLowerCase();
+
+        // Extension whitelist
+        if (this.options.extensions) {
+            const normalizedExts = this.options.extensions.map(e =>
+                e.startsWith('.') ? e.toLowerCase() : `.${e.toLowerCase()}`
+            );
+            if (!normalizedExts.includes(ext)) return false;
+        }
+
+        // Extension blacklist
+        if (this.options.excludeExtensions) {
+            const normalizedExcludes = this.options.excludeExtensions.map(e =>
+                e.startsWith('.') ? e.toLowerCase() : `.${e.toLowerCase()}`
+            );
+            if (normalizedExcludes.includes(ext)) return false;
+        }
+
+        // Size filters
+        if (stats.size < this.options.minSize) return false;
+        if (stats.size > this.options.maxSize) return false;
+
+        // Date filters
+        if (this.options.modifiedAfter) {
+            const threshold = new Date(this.options.modifiedAfter).getTime();
+            if (stats.mtime.getTime() < threshold) return false;
+        }
+        if (this.options.modifiedBefore) {
+            const threshold = new Date(this.options.modifiedBefore).getTime();
+            if (stats.mtime.getTime() > threshold) return false;
+        }
+
+        return true;
+    }
+
+    /**
+     * Abort the current scan
+     */
+    abort() {
+        this._aborted = true;
+    }
+
+    /**
+     * Format milliseconds to human-readable duration
+     */
+    _formatDuration(ms) {
+        if (ms < 1000) return `${ms}ms`;
+        if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+        const mins = Math.floor(ms / 60000);
+        const secs = ((ms % 60000) / 1000).toFixed(0);
+        return `${mins}m ${secs}s`;
+    }
+}
+
+// ─── Convenience Functions ────────────────────────────────────────
+
+/**
+ * Quick scan a directory with default options
+ * @param {string} dirPath - Directory to scan
+ * @param {Object} options - Scan options
+ * @returns {{ files: Object[], stats: Object }}
+ */
+function scan(dirPath, options = {}) {
+    const scanner = new Scanner(options);
+    return scanner.scan(dirPath);
+}
+
+/**
+ * Quick scan and group results by category
+ * @param {string} dirPath - Directory to scan
+ * @param {Object} options - Scan options
+ * @returns {{ categories: Object, stats: Object }}
+ */
+function scanByCategory(dirPath, options = {}) {
+    const result = scan(dirPath, options);
+    const grouped = {};
+
+    for (const file of result.files) {
+        if (!grouped[file.category]) {
+            grouped[file.category] = {
+                files: [],
+                count: 0,
+                totalSize: 0
+            };
+        }
+        grouped[file.category].files.push(file);
+        grouped[file.category].count++;
+        grouped[file.category].totalSize += file.size;
+    }
+
+    // Sort each category's files by name
+    for (const cat of Object.values(grouped)) {
+        cat.files.sort((a, b) => a.name.localeCompare(b.name));
+        cat.totalSizeHuman = formatBytes(cat.totalSize);
+    }
+
+    return {
+        root: result.root,
+        categories: grouped,
+        stats: result.stats
+    };
+}
+
+/**
+ * Quick scan and get a size summary
+ * @param {string} dirPath - Directory to scan
+ * @param {Object} options - Scan options
+ * @returns {{ totalSize: number, totalSizeHuman: string, fileCount: number, largestFiles: Object[] }}
+ */
+function scanSummary(dirPath, options = {}) {
+    const result = scan(dirPath, options);
+
+    // Sort by size descending
+    const sorted = [...result.files].sort((a, b) => b.size - a.size);
+
+    return {
+        root: result.root,
+        totalSize: result.stats.totalSize,
+        totalSizeHuman: formatBytes(result.stats.totalSize),
+        fileCount: result.stats.filesFound,
+        dirCount: result.stats.dirsScanned,
+        largestFiles: sorted.slice(0, 20),
+        categories: result.stats.categories,
+        duration: result.stats.durationHuman,
+        errors: result.stats.errors
+    };
+}
+
+module.exports = {
+    Scanner,
+    scan,
+    scanByCategory,
+    scanSummary,
+    buildFileInfo,
+    formatBytes,
+    matchGlob,
+    DEFAULT_SCAN_OPTIONS
+};