codescoop 1.0.0

package/src/utils/validation.js

@@ -0,0 +1,278 @@
+/**
+ * Validation Utilities
+ * Handles edge cases and input validation
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Validate HTML file
+ * @param {string} filePath - Path to HTML file
+ * @returns {Object} Validation result
+ */
+function validateHTMLFile(filePath) {
+    const errors = [];
+    const warnings = [];
+
+    // Check if file exists
+    if (!fs.existsSync(filePath)) {
+        errors.push(`File not found: ${filePath}`);
+        return { valid: false, errors, warnings };
+    }
+
+    // Check file extension
+    const ext = path.extname(filePath).toLowerCase();
+    if (!['.html', '.htm', '.xhtml', '.php', '.ejs', '.hbs', '.pug'].includes(ext)) {
+        warnings.push(`File extension "${ext}" is not a typical HTML extension. Proceeding anyway.`);
+    }
+
+    // Try to read file
+    let content;
+    try {
+        content = fs.readFileSync(filePath, 'utf-8');
+    } catch (error) {
+        if (error.code === 'EACCES') {
+            errors.push(`Permission denied: Cannot read ${filePath}`);
+        } else if (error.code === 'EISDIR') {
+            errors.push(`Path is a directory, not a file: ${filePath}`);
+        } else {
+            errors.push(`Cannot read file: ${error.message}`);
+        }
+        return { valid: false, errors, warnings };
+    }
+
+    // Check if file is empty
+    if (!content || content.trim().length === 0) {
+        errors.push('File is empty');
+        return { valid: false, errors, warnings };
+    }
+
+    // Check if file looks like HTML (has at least some HTML-like content)
+    if (!/<[a-z][\s\S]*>/i.test(content)) {
+        warnings.push('File does not appear to contain HTML tags');
+    }
+
+    // Check if it might be a binary file (has null bytes)
+    if (content.includes('\0')) {
+        errors.push('File appears to be binary, not text');
+        return { valid: false, errors, warnings };
+    }
+
+    // Check file size (warn if very large)
+    const stats = fs.statSync(filePath);
+    const sizeInMB = stats.size / (1024 * 1024);
+    if (sizeInMB > 10) {
+        warnings.push(`Large file (${sizeInMB.toFixed(2)} MB). Analysis may be slow.`);
+    }
+
+    return { valid: true, errors, warnings, content, sizeInMB };
+}
+
+/**
+ * Validate output path
+ * @param {string} outputPath - Path to output file
+ * @returns {Object} Validation result
+ */
+function validateOutputPath(outputPath) {
+    const errors = [];
+    const warnings = [];
+
+    if (!outputPath) {
+        return { valid: true, errors, warnings }; // Will use default
+    }
+
+    const dir = path.dirname(outputPath);
+
+    // Check if directory exists
+    if (!fs.existsSync(dir)) {
+        try {
+            fs.mkdirSync(dir, { recursive: true });
+        } catch (error) {
+            errors.push(`Cannot create output directory: ${error.message}`);
+            return { valid: false, errors, warnings };
+        }
+    }
+
+    // Check if path is a directory
+    if (fs.existsSync(outputPath) && fs.statSync(outputPath).isDirectory()) {
+        errors.push(`Output path is a directory: ${outputPath}. Please specify a file name.`);
+        return { valid: false, errors, warnings };
+    }
+
+    // Check if file already exists
+    if (fs.existsSync(outputPath)) {
+        warnings.push(`Output file already exists and will be overwritten: ${outputPath}`);
+    }
+
+    // Check write permission
+    try {
+        fs.accessSync(dir, fs.constants.W_OK);
+    } catch (error) {
+        errors.push(`Cannot write to directory: ${dir}`);
+        return { valid: false, errors, warnings };
+    }
+
+    return { valid: true, errors, warnings };
+}
+
+/**
+ * Validate project directory
+ * @param {string} dirPath - Path to project directory
+ * @returns {Object} Validation result
+ */
+function validateProjectDir(dirPath) {
+    const errors = [];
+    const warnings = [];
+
+    // Check if directory exists
+    if (!fs.existsSync(dirPath)) {
+        errors.push(`Directory not found: ${dirPath}`);
+        return { valid: false, errors, warnings };
+    }
+
+    // Check if it's actually a directory
+    if (!fs.statSync(dirPath).isDirectory()) {
+        errors.push(`Path is not a directory: ${dirPath}`);
+        return { valid: false, errors, warnings };
+    }
+
+    // Check read permission
+    try {
+        fs.accessSync(dirPath, fs.constants.R_OK);
+    } catch (error) {
+        errors.push(`Cannot read directory: ${dirPath}`);
+        return { valid: false, errors, warnings };
+    }
+
+    // Count files to give user an idea
+    try {
+        const entries = fs.readdirSync(dirPath);
+        if (entries.length === 0) {
+            warnings.push('Directory is empty');
+        }
+    } catch (error) {
+        warnings.push(`Could not read directory contents: ${error.message}`);
+    }
+
+    return { valid: true, errors, warnings };
+}
+
+/**
+ * Safe file read with encoding detection
+ * @param {string} filePath - Path to file
+ * @returns {Object} Result with content or error
+ */
+function safeReadFile(filePath) {
+    try {
+        // Try UTF-8 first
+        let content = fs.readFileSync(filePath, 'utf-8');
+
+        // Check for BOM and remove if present
+        if (content.charCodeAt(0) === 0xFEFF) {
+            content = content.slice(1);
+        }
+
+        // Check if content looks corrupted (many replacement characters)
+        const replacementChars = (content.match(/\uFFFD/g) || []).length;
+        if (replacementChars > content.length * 0.1) {
+            return {
+                success: false,
+                error: 'File encoding issue: Too many invalid characters',
+                encoding: 'unknown'
+            };
+        }
+
+        return { success: true, content, encoding: 'utf-8' };
+    } catch (error) {
+        return {
+            success: false,
+            error: error.message,
+            encoding: null
+        };
+    }
+}
+
+/**
+ * Sanitize selector input
+ * Prevents potential injection or crash-causing input
+ * @param {string} selector - User-provided selector
+ * @returns {Object} Sanitized result
+ */
+function sanitizeSelector(selector) {
+    if (!selector || typeof selector !== 'string') {
+        return { valid: false, error: 'Selector must be a non-empty string' };
+    }
+
+    const trimmed = selector.trim();
+
+    // Max length check
+    if (trimmed.length > 1000) {
+        return { valid: false, error: 'Selector is too long (max 1000 characters)' };
+    }
+
+    // Check for potentially problematic patterns
+    const dangerousPatterns = [
+        /javascript:/i,
+        /<script/i,
+        /on\w+=/i,
+    ];
+
+    for (const pattern of dangerousPatterns) {
+        if (pattern.test(trimmed)) {
+            return { valid: false, error: 'Selector contains invalid patterns' };
+        }
+    }
+
+    return { valid: true, selector: trimmed };
+}
+
+/**
+ * Check if a path is safe (no directory traversal attacks)
+ * @param {string} basePath - Base directory
+ * @param {string} targetPath - Target path to validate
+ * @returns {boolean} True if safe
+ */
+function isPathSafe(basePath, targetPath) {
+    const resolvedBase = path.resolve(basePath);
+    const resolvedTarget = path.resolve(basePath, targetPath);
+
+    return resolvedTarget.startsWith(resolvedBase);
+}
+
+/**
+ * Format error message for user display
+ * @param {Error} error - Error object
+ * @param {boolean} verbose - Show stack trace
+ * @returns {string} Formatted message
+ */
+function formatError(error, verbose = false) {
+    let message = error.message || 'Unknown error occurred';
+
+    // Add helpful context for common errors
+    if (error.code === 'ENOENT') {
+        message = `File or directory not found: ${error.path || 'unknown'}`;
+    } else if (error.code === 'EACCES') {
+        message = `Permission denied: ${error.path || 'unknown'}`;
+    } else if (error.code === 'EMFILE') {
+        message = 'Too many files open. Try closing some applications.';
+    } else if (error.code === 'ENOSPC') {
+        message = 'Disk is full. Free up some space.';
+    }
+
+    if (verbose && error.stack) {
+        message += `\n\nStack trace:\n${error.stack}`;
+    }
+
+    return message;
+}
+
+module.exports = {
+    validateHTMLFile,
+    validateOutputPath,
+    validateProjectDir,
+    safeReadFile,
+    sanitizeSelector,
+    isPathSafe,
+    formatError
+};

package/src/utils/variable-extractor.js

@@ -0,0 +1,271 @@
+/**
+ * Variable Extractor Module
+ * Extracts CSS custom properties and SCSS variables definitions
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Extract all CSS custom property usages from CSS content
+ * @param {string} content - CSS/SCSS content
+ * @returns {Set<string>} Set of variable names used
+ */
+function extractCSSVariableUsages(content) {
+    const usages = new Set();
+
+    // Match var(--variable-name) patterns
+    const varRegex = /var\(\s*(--[a-zA-Z0-9_-]+)\s*(?:,\s*[^)]+)?\)/g;
+    let match;
+    while ((match = varRegex.exec(content)) !== null) {
+        usages.add(match[1]);
+    }
+
+    return usages;
+}
+
+/**
+ * Extract all SCSS variable usages from SCSS content
+ * @param {string} content - SCSS content
+ * @returns {Set<string>} Set of variable names used
+ */
+function extractSCSSVariableUsages(content) {
+    const usages = new Set();
+
+    // Match $variable-name patterns (but not in definitions)
+    // This regex looks for $ followed by variable name that's NOT at the start of a definition
+    const scssVarRegex = /(?<!^\s*)\$([a-zA-Z_][a-zA-Z0-9_-]*)/gm;
+    let match;
+    while ((match = scssVarRegex.exec(content)) !== null) {
+        usages.add('$' + match[1]);
+    }
+
+    return usages;
+}
+
+/**
+ * Find CSS custom property definitions in content
+ * @param {string} content - CSS/SCSS content
+ * @param {Set<string>} variableNames - Variables to find
+ * @returns {Object} Map of variable name to definition
+ */
+function findCSSVariableDefinitions(content, variableNames) {
+    const definitions = {};
+
+    for (const varName of variableNames) {
+        // Look for --variable-name: value; pattern
+        const escapedName = varName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const defRegex = new RegExp(`(${escapedName})\\s*:\\s*([^;]+);`, 'gm');
+
+        let match;
+        while ((match = defRegex.exec(content)) !== null) {
+            // Get some context around the match
+            const lineStart = content.lastIndexOf('\n', match.index) + 1;
+            const lineEnd = content.indexOf('\n', match.index + match[0].length);
+            const line = content.substring(lineStart, lineEnd > -1 ? lineEnd : undefined).trim();
+
+            // Try to find the selector/context
+            const beforeMatch = content.substring(Math.max(0, match.index - 200), match.index);
+            const selectorMatch = beforeMatch.match(/([^{}]+)\s*\{[^{}]*$/);
+            const selector = selectorMatch ? selectorMatch[1].trim().split('\n').pop().trim() : ':root';
+
+            if (!definitions[varName]) {
+                definitions[varName] = [];
+            }
+
+            definitions[varName].push({
+                value: match[2].trim(),
+                context: selector,
+                fullLine: line
+            });
+        }
+    }
+
+    return definitions;
+}
+
+/**
+ * Find SCSS variable definitions in content
+ * @param {string} content - SCSS content
+ * @param {Set<string>} variableNames - Variables to find (with $ prefix)
+ * @returns {Object} Map of variable name to definition
+ */
+function findSCSSVariableDefinitions(content, variableNames) {
+    const definitions = {};
+
+    for (const varName of variableNames) {
+        // Look for $variable-name: value; pattern at the start of a line
+        const escapedName = varName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const defRegex = new RegExp(`^\\s*(${escapedName})\\s*:\\s*([^;]+);`, 'gm');
+
+        let match;
+        while ((match = defRegex.exec(content)) !== null) {
+            const line = match[0].trim();
+
+            if (!definitions[varName]) {
+                definitions[varName] = [];
+            }
+
+            definitions[varName].push({
+                value: match[2].trim(),
+                context: 'global',
+                fullLine: line
+            });
+        }
+    }
+
+    return definitions;
+}
+
+/**
+ * Extract variables from matched CSS rules and find their definitions
+ * @param {Array} cssMatches - Array of CSS match objects with content
+ * @param {Array} projectFiles - Array of CSS/SCSS file paths
+ * @param {string} projectDir - Project directory
+ * @returns {Object} Variable definitions found
+ */
+async function extractVariablesFromMatches(cssMatches, projectFiles, projectDir) {
+    // Collect all variable usages from matched rules
+    const cssVarsUsed = new Set();
+    const scssVarsUsed = new Set();
+
+    for (const match of cssMatches) {
+        const content = match.content || '';
+
+        // Extract CSS custom property usages
+        const cssUsages = extractCSSVariableUsages(content);
+        cssUsages.forEach(v => cssVarsUsed.add(v));
+
+        // Extract SCSS variable usages
+        const scssUsages = extractSCSSVariableUsages(content);
+        scssUsages.forEach(v => scssVarsUsed.add(v));
+    }
+
+    if (cssVarsUsed.size === 0 && scssVarsUsed.size === 0) {
+        return { cssVariables: {}, scssVariables: {}, usedVariables: [] };
+    }
+
+    // Search project files for definitions
+    const allCSSDefinitions = {};
+    const allSCSSDefinitions = {};
+
+    const cssFiles = projectFiles.filter(f =>
+        f.endsWith('.css') || f.endsWith('.scss') || f.endsWith('.sass')
+    );
+
+    for (const filePath of cssFiles) {
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            const relPath = path.relative(projectDir, filePath);
+
+            // Find CSS variable definitions
+            if (cssVarsUsed.size > 0) {
+                const defs = findCSSVariableDefinitions(content, cssVarsUsed);
+                for (const [varName, defList] of Object.entries(defs)) {
+                    if (!allCSSDefinitions[varName]) {
+                        allCSSDefinitions[varName] = [];
+                    }
+                    defList.forEach(def => {
+                        allCSSDefinitions[varName].push({
+                            ...def,
+                            file: relPath
+                        });
+                    });
+                }
+            }
+
+            // Find SCSS variable definitions
+            if (scssVarsUsed.size > 0 && (filePath.endsWith('.scss') || filePath.endsWith('.sass'))) {
+                const defs = findSCSSVariableDefinitions(content, scssVarsUsed);
+                for (const [varName, defList] of Object.entries(defs)) {
+                    if (!allSCSSDefinitions[varName]) {
+                        allSCSSDefinitions[varName] = [];
+                    }
+                    defList.forEach(def => {
+                        allSCSSDefinitions[varName].push({
+                            ...def,
+                            file: relPath
+                        });
+                    });
+                }
+            }
+        } catch (error) {
+            // Skip files that can't be read
+        }
+    }
+
+    // Find undefined variables (used but not found)
+    const undefinedCSSVars = [...cssVarsUsed].filter(v => !allCSSDefinitions[v]);
+    const undefinedSCSSVars = [...scssVarsUsed].filter(v => !allSCSSDefinitions[v]);
+
+    return {
+        cssVariables: allCSSDefinitions,
+        scssVariables: allSCSSDefinitions,
+        undefinedCSSVariables: undefinedCSSVars,
+        undefinedSCSSVariables: undefinedSCSSVars,
+        usedVariables: [...cssVarsUsed, ...scssVarsUsed]
+    };
+}
+
+/**
+ * Format variable definitions as markdown
+ * @param {Object} variableData - Variable data from extractVariablesFromMatches
+ * @returns {string} Markdown content
+ */
+function formatVariablesAsMarkdown(variableData) {
+    const { cssVariables, scssVariables, undefinedCSSVariables, undefinedSCSSVariables } = variableData;
+
+    let content = '';
+
+    // CSS Variables
+    const cssVarNames = Object.keys(cssVariables);
+    if (cssVarNames.length > 0) {
+        content += `### CSS Custom Properties Used\n\n`;
+        content += `| Variable | Value | Context | File |\n`;
+        content += `|----------|-------|---------|------|\n`;
+
+        for (const varName of cssVarNames) {
+            const defs = cssVariables[varName];
+            // Show first definition (usually :root)
+            const def = defs[0];
+            const shortValue = def.value.length > 40 ? def.value.substring(0, 37) + '...' : def.value;
+            content += `| \`${varName}\` | \`${shortValue}\` | ${def.context} | \`${def.file}\` |\n`;
+        }
+        content += '\n';
+    }
+
+    // SCSS Variables
+    const scssVarNames = Object.keys(scssVariables);
+    if (scssVarNames.length > 0) {
+        content += `### SCSS Variables Used\n\n`;
+        content += `\`\`\`scss\n`;
+        for (const varName of scssVarNames) {
+            const defs = scssVariables[varName];
+            const def = defs[0];
+            content += `${varName}: ${def.value};\n`;
+        }
+        content += `\`\`\`\n\n`;
+    }
+
+    // Undefined variables warning
+    const allUndefined = [...(undefinedCSSVariables || []), ...(undefinedSCSSVariables || [])];
+    if (allUndefined.length > 0) {
+        content += `### ⚠️ Undefined Variables\n\n`;
+        content += `The following variables are used but their definitions were not found:\n\n`;
+        allUndefined.forEach(v => {
+            content += `- \`${v}\`\n`;
+        });
+        content += `\n> These may be defined in a file not scanned, or loaded via a CSS framework.\n\n`;
+    }
+
+    return content;
+}
+
+module.exports = {
+    extractCSSVariableUsages,
+    extractSCSSVariableUsages,
+    findCSSVariableDefinitions,
+    findSCSSVariableDefinitions,
+    extractVariablesFromMatches,
+    formatVariablesAsMarkdown
+};