filemayor 2.0.0

package/core/scanner.js

@@ -0,0 +1,436 @@
+#!/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) {
+        // Validate the path
+        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}"`);
+        }
+
+        // Verify it's actually a directory
+        try {
+            const stat = fs.statSync(validation.resolved);
+            if (!stat.isDirectory()) {
+                throw new Error(`Not a directory: "${validation.resolved}"`);
+            }
+        } catch (err) {
+            if (err.code === 'ENOENT') {
+                throw new Error(`Directory not found: "${validation.resolved}"`);
+            }
+            throw err;
+        }
+
+        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 }
+        };
+    }
+
+    /**
+     * Internal recursive scan implementation
+     */
+    _scanRecursive(dir, rootPath, depth, results) {
+        // Check abort signal
+        if (this._aborted || this.options.abortSignal?.aborted) {
+            this._aborted = true;
+            return;
+        }
+
+        // Depth limit
+        if (depth > this.options.maxDepth) return;
+
+        this.stats.dirsScanned++;
+
+        // Progress callback
+        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) {
+            const errorInfo = {
+                path: dir,
+                code: err.code,
+                message: err.message,
+                depth
+            };
+            this.stats.errors.push(errorInfo);
+            if (this.options.onError) {
+                this.options.onError(errorInfo);
+            }
+            return;
+        }
+
+        for (const item of items) {
+            if (this._aborted) return;
+
+            const fullPath = path.join(dir, item.name);
+
+            // ─── Filtering ────────────────────────────────
+
+            // Skip hidden files/dirs
+            if (!this.options.includeHidden && item.name.startsWith('.')) {
+                this.stats.skipped++;
+                continue;
+            }
+
+            // Skip ignored directories
+            if (item.isDirectory() && this.options.ignore.includes(item.name)) {
+                this.stats.skipped++;
+                continue;
+            }
+
+            // Skip by glob patterns
+            if (this.options.ignorePatterns.length > 0) {
+                const shouldSkip = this.options.ignorePatterns.some(p => matchGlob(p, item.name));
+                if (shouldSkip) {
+                    this.stats.skipped++;
+                    continue;
+                }
+            }
+
+            // Handle symlinks
+            if (item.isSymbolicLink && item.isSymbolicLink() && !this.options.followSymlinks) {
+                this.stats.skipped++;
+                continue;
+            }
+
+            // ─── Process Entry ────────────────────────────
+
+            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,
+                    depth
+                });
+                continue;
+            }
+
+            if (stats.isFile()) {
+                // Apply file filters
+                if (this._shouldIncludeFile(fullPath, stats)) {
+                    const fileInfo = buildFileInfo(fullPath, stats, rootPath);
+                    results.push(fileInfo);
+                    this.stats.filesFound++;
+                    this.stats.totalSize += stats.size;
+
+                    // Track category counts
+                    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) {
+                    const dirInfo = buildFileInfo(fullPath, stats, rootPath);
+                    results.push(dirInfo);
+                }
+                this._scanRecursive(fullPath, rootPath, depth + 1, results);
+            }
+        }
+    }
+
+    /**
+     * 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
+};