codescoop 1.0.0

package/src/utils/specificity-calculator.js

@@ -0,0 +1,251 @@
+/**
+ * CSS Specificity Calculator
+ * Uses the battle-tested 'specificity' npm library to calculate specificity
+ * and predict which CSS rules will actually render
+ */
+
+const { calculate } = require('specificity');
+
+/**
+ * Calculate specificity for a CSS selector using the npm library
+ * Returns [inline, ids, classes, elements] tuple
+ * @param {string} selector - CSS selector
+ * @returns {number[]} Specificity tuple [inline, ids, classes, elements]
+ */
+function calculateSpecificity(selector) {
+    if (!selector || typeof selector !== 'string') {
+        return [0, 0, 0, 0];
+    }
+
+    try {
+        const result = calculate(selector);
+        if (result) {
+            // Library returns { A: ids, B: classes, C: elements }
+            // We add inline (0) as the first element for consistency
+            return [0, result.A || 0, result.B || 0, result.C || 0];
+        }
+    } catch (error) {
+        // If the library can't parse it, return zeroes
+        // console.warn(`Could not calculate specificity for "${selector}": ${error.message}`);
+    }
+
+    return [0, 0, 0, 0];
+}
+
+/**
+ * Compare two specificity tuples
+ * @param {number[]} a - First specificity
+ * @param {number[]} b - Second specificity
+ * @returns {number} -1 if a < b, 0 if equal, 1 if a > b
+ */
+function compareSpecificity(a, b) {
+    for (let i = 0; i < 4; i++) {
+        if (a[i] > b[i]) return 1;
+        if (a[i] < b[i]) return -1;
+    }
+    return 0;
+}
+
+/**
+ * Format specificity as readable string
+ * @param {number[]} spec - Specificity tuple
+ * @returns {string} Formatted string like "(0,1,2,3)"
+ */
+function formatSpecificity(spec) {
+    return `(${spec.join(',')})`;
+}
+
+/**
+ * Check if a CSS value has !important
+ * @param {string} value - CSS property value
+ * @returns {boolean}
+ */
+function hasImportant(value) {
+    return typeof value === 'string' && value.includes('!important');
+}
+
+/**
+ * Analyze CSS rules and predict which ones will render
+ * @param {Array} cssResults - CSS analysis results from the tool
+ * @param {Object} linkedFiles - Information about linked CSS files
+ * @returns {Object} Conflict analysis with winners/losers
+ */
+function analyzeConflicts(cssResults, linkedFiles = { css: [] }) {
+    // Group rules by property
+    const propertyRules = {};
+
+    // Track file order (later = higher priority for same specificity)
+    const fileOrder = {};
+    linkedFiles.css.forEach((file, index) => {
+        fileOrder[file] = index;
+    });
+
+    let globalOrder = 0;
+
+    for (const result of cssResults) {
+        const filePath = result.filePath || result.file;
+        const fileOrderValue = fileOrder[filePath] ?? 999;
+
+        for (const match of result.matches || []) {
+            const selector = match.selector || '';
+            const specificity = calculateSpecificity(selector);
+            const content = match.content || '';
+
+            // Parse properties from content
+            const properties = parseProperties(content);
+
+            for (const [prop, value] of Object.entries(properties)) {
+                if (!propertyRules[prop]) {
+                    propertyRules[prop] = [];
+                }
+
+                propertyRules[prop].push({
+                    selector,
+                    specificity,
+                    value,
+                    hasImportant: hasImportant(value),
+                    file: filePath,
+                    fileOrder: fileOrderValue,
+                    globalOrder: globalOrder++,
+                    startLine: match.startLine,
+                    endLine: match.endLine
+                });
+            }
+        }
+    }
+
+    // Determine winner for each property
+    const conflicts = {};
+
+    for (const [prop, rules] of Object.entries(propertyRules)) {
+        if (rules.length <= 1) {
+            continue; // No conflict
+        }
+
+        // Sort by priority: !important > specificity > file order > declaration order
+        const sorted = [...rules].sort((a, b) => {
+            // !important always wins
+            if (a.hasImportant && !b.hasImportant) return 1;
+            if (!a.hasImportant && b.hasImportant) return -1;
+
+            // Compare specificity
+            const specCompare = compareSpecificity(a.specificity, b.specificity);
+            if (specCompare !== 0) return specCompare;
+
+            // Same specificity: later file wins
+            if (a.fileOrder !== b.fileOrder) return a.fileOrder - b.fileOrder;
+
+            // Same file: later declaration wins
+            return a.globalOrder - b.globalOrder;
+        });
+
+        const winner = sorted[sorted.length - 1];
+        const losers = sorted.slice(0, -1);
+
+        conflicts[prop] = {
+            winner,
+            losers,
+            hasConflict: losers.length > 0
+        };
+    }
+
+    return conflicts;
+}
+
+/**
+ * Parse CSS properties from a rule content
+ * @param {string} content - CSS rule content
+ * @returns {Object} Property-value pairs
+ */
+function parseProperties(content) {
+    const properties = {};
+
+    // Remove selector and braces if present
+    let body = content;
+    const braceMatch = content.match(/\{([^}]+)\}/);
+    if (braceMatch) {
+        body = braceMatch[1];
+    }
+
+    // Split by semicolons and parse
+    const declarations = body.split(';');
+    for (const decl of declarations) {
+        const colonIndex = decl.indexOf(':');
+        if (colonIndex > 0) {
+            const prop = decl.substring(0, colonIndex).trim();
+            const value = decl.substring(colonIndex + 1).trim();
+            if (prop && value) {
+                properties[prop] = value;
+            }
+        }
+    }
+
+    return properties;
+}
+
+/**
+ * Format conflict analysis as markdown
+ * @param {Object} conflicts - Conflict analysis from analyzeConflicts
+ * @returns {string} Markdown formatted output
+ */
+function formatConflictsMarkdown(conflicts) {
+    const conflictingProps = Object.entries(conflicts).filter(([_, data]) => data.hasConflict);
+
+    if (conflictingProps.length === 0) {
+        return '';
+    }
+
+    let md = `\n---\n\n## ⚔️ CSS Conflicts Detected\n\n`;
+    md += `> Multiple CSS rules are competing for the same properties. Here's what will actually render:\n`;
+    md += `> *Note: Rules are sorted by specificity. If equal, the browser uses the rule loaded last.*\n\n`;
+
+    for (const [prop, data] of conflictingProps) {
+        const { winner, losers } = data;
+
+        md += `### \`${prop}\`\n\n`;
+        md += `| Status | File | Selector | Value | Specificity |\n`;
+        md += `|--------|------|----------|-------|-------------|\n`;
+
+        // Show winner first
+        md += `| ✅ **Winner** | \`${getFileName(winner.file)}\` | \`${winner.selector}\` | \`${truncateValue(winner.value)}\` | ${formatSpecificity(winner.specificity)}${winner.hasImportant ? ' **!important**' : ''} |\n`;
+
+        // Show losers
+        for (const loser of losers.reverse()) {
+            md += `| ❌ Overridden | \`${getFileName(loser.file)}\` | \`${loser.selector}\` | \`${truncateValue(loser.value)}\` | ${formatSpecificity(loser.specificity)}${loser.hasImportant ? ' !important' : ''} |\n`;
+        }
+
+        md += '\n';
+    }
+
+    md += `**${conflictingProps.length}** property conflict(s) detected.\n`;
+
+    return md;
+}
+
+/**
+ * Truncate long CSS values for display
+ */
+function truncateValue(value) {
+    if (!value) return '';
+    if (value.length > 40) {
+        return value.substring(0, 37) + '...';
+    }
+    return value;
+}
+
+/**
+ * Get just the filename from a path
+ */
+function getFileName(filePath) {
+    if (!filePath) return 'unknown';
+    const parts = filePath.replace(/\\/g, '/').split('/');
+    return parts[parts.length - 1];
+}
+
+module.exports = {
+    calculateSpecificity,
+    compareSpecificity,
+    formatSpecificity,
+    analyzeConflicts,
+    formatConflictsMarkdown
+};

package/src/utils/template-parser.js

@@ -0,0 +1,260 @@
+/**
+ * Template Parser Module
+ * Parses PHP, Blade, Twig, and other template files by stripping server-side code
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Supported template types and their patterns
+ */
+const TEMPLATE_PATTERNS = {
+    php: {
+        extensions: ['.php', '.phtml', '.inc'],
+        // Match <?php ... ?> and <?= ... ?> and <? ... ?>
+        patterns: [
+            /<\?php[\s\S]*?\?>/gi,
+            /<\?=[\s\S]*?\?>/gi,
+            /<\?(?!xml)[\s\S]*?\?>/gi
+        ],
+        // PHP echo shortcuts to preserve (convert to placeholders)
+        echoPatterns: [
+            { regex: /<\?=\s*\$([a-zA-Z_][a-zA-Z0-9_]*)\s*\?>/g, placeholder: '{{$1}}' },
+            { regex: /<\?php\s+echo\s+\$([a-zA-Z_][a-zA-Z0-9_]*)\s*;\s*\?>/g, placeholder: '{{$1}}' }
+        ]
+    },
+    blade: {
+        extensions: ['.blade.php'],
+        // Blade directives
+        patterns: [
+            /@(if|else|elseif|endif|foreach|endforeach|for|endfor|while|endwhile|switch|case|break|default|endswitch|unless|endunless|isset|endisset|empty|endempty|auth|endauth|guest|endguest|hasSection|yield|section|endsection|show|parent|include|extends|component|endcomponent|slot|endslot|push|endpush|stack|prepend|endprepend|php|endphp|verbatim|endverbatim|error|enderror|once|endonce|env|endenv|production|endproduction|props|aware|class|disabled|readonly|required|checked|selected)\b[^@]*/gi,
+            /\{\{--[\s\S]*?--\}\}/g, // Blade comments
+            /\{\!\![\s\S]*?\!\!\}/g, // Unescaped output
+        ],
+        // Preserve Blade echo as placeholders
+        echoPatterns: [
+            { regex: /\{\{\s*\$([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g, placeholder: '{{$1}}' }
+        ]
+    },
+    twig: {
+        extensions: ['.twig', '.html.twig'],
+        patterns: [
+            /\{%[\s\S]*?%\}/g, // Twig tags
+            /\{#[\s\S]*?#\}/g, // Twig comments
+        ],
+        echoPatterns: [
+            { regex: /\{\{\s*([a-zA-Z_][a-zA-Z0-9_.]*)\s*\}\}/g, placeholder: '{{$1}}' }
+        ]
+    },
+    ejs: {
+        extensions: ['.ejs'],
+        patterns: [
+            /<%[\s\S]*?%>/g, // EJS tags
+            /<%#[\s\S]*?%>/g, // EJS comments
+        ],
+        echoPatterns: [
+            { regex: /<%=\s*([a-zA-Z_][a-zA-Z0-9_.]*)\s*%>/g, placeholder: '{{$1}}' }
+        ]
+    },
+    erb: {
+        extensions: ['.erb', '.html.erb'],
+        patterns: [
+            /<%[\s\S]*?%>/g,
+            /<%#[\s\S]*?%>/g,
+        ],
+        echoPatterns: [
+            { regex: /<%=\s*@?([a-zA-Z_][a-zA-Z0-9_.]*)\s*%>/g, placeholder: '{{$1}}' }
+        ]
+    },
+    handlebars: {
+        extensions: ['.hbs', '.handlebars'],
+        patterns: [
+            /\{\{#[\s\S]*?\}\}/g, // Block helpers
+            /\{\{\/[\s\S]*?\}\}/g, // Close blocks
+            /\{\{!--[\s\S]*?--\}\}/g, // Comments
+            /\{\{![\s\S]*?\}\}/g, // Inline comments
+        ],
+        echoPatterns: [
+            { regex: /\{\{\s*([a-zA-Z_][a-zA-Z0-9_.]*)\s*\}\}/g, placeholder: '{{$1}}' }
+        ]
+    },
+    jsp: {
+        extensions: ['.jsp', '.jspf'],
+        patterns: [
+            /<%@[\s\S]*?%>/g, // Directives
+            /<%![\s\S]*?%>/g, // Declarations
+            /<%[\s\S]*?%>/g, // Scriptlets
+            /<%--[\s\S]*?--%>/g, // Comments
+        ],
+        echoPatterns: [
+            { regex: /\$\{([a-zA-Z_][a-zA-Z0-9_.]*)\}/g, placeholder: '{{$1}}' }
+        ]
+    },
+    asp: {
+        extensions: ['.asp', '.aspx', '.cshtml', '.vbhtml'],
+        patterns: [
+            /<%[\s\S]*?%>/g,
+            /@\{[\s\S]*?\}/g, // Razor code blocks
+            /@[\w]+\([^)]*\)/g, // Razor helpers
+        ],
+        echoPatterns: [
+            { regex: /@([a-zA-Z_][a-zA-Z0-9_.]*)/g, placeholder: '{{$1}}' }
+        ]
+    }
+};
+
+/**
+ * Detect template type from file extension
+ * @param {string} filePath - Path to template file
+ * @returns {string|null} Template type or null
+ */
+function detectTemplateType(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    const basename = path.basename(filePath).toLowerCase();
+
+    // Check for compound extensions first (like .blade.php)
+    for (const [type, config] of Object.entries(TEMPLATE_PATTERNS)) {
+        for (const extension of config.extensions) {
+            if (basename.endsWith(extension)) {
+                return type;
+            }
+        }
+    }
+
+    // Check simple extension
+    for (const [type, config] of Object.entries(TEMPLATE_PATTERNS)) {
+        if (config.extensions.includes(ext)) {
+            return type;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Check if file is a template file
+ * @param {string} filePath - Path to check
+ * @returns {boolean}
+ */
+function isTemplateFile(filePath) {
+    return detectTemplateType(filePath) !== null;
+}
+
+/**
+ * Parse template file and extract HTML
+ * @param {string} filePath - Path to template file
+ * @param {Object} options - Parse options
+ * @returns {Object} Parsed result with HTML and metadata
+ */
+function parseTemplateFile(filePath, options = {}) {
+    const {
+        preserveEchos = true,
+        preserveComments = false
+    } = options;
+
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return parseTemplateContent(content, filePath, { preserveEchos, preserveComments });
+}
+
+/**
+ * Parse template content and extract HTML
+ * @param {string} content - Template content
+ * @param {string} filePath - Original file path (for type detection)
+ * @param {Object} options - Parse options
+ * @returns {Object} Parsed result
+ */
+function parseTemplateContent(content, filePath, options = {}) {
+    const {
+        preserveEchos = true,
+        preserveComments = false
+    } = options;
+
+    const templateType = detectTemplateType(filePath);
+    if (!templateType) {
+        // Not a template, return as-is
+        return {
+            html: content,
+            templateType: null,
+            dynamicClasses: [],
+            warnings: []
+        };
+    }
+
+    const config = TEMPLATE_PATTERNS[templateType];
+    let html = content;
+    const dynamicClasses = [];
+    const warnings = [];
+
+    // First, extract potential dynamic class patterns
+    const classPatterns = [
+        /class\s*=\s*["'][^"']*<\?[\s\S]*?\?>[^"']*["']/g,
+        /class\s*=\s*["'][^"']*\{\{[\s\S]*?\}\}[^"']*["']/g,
+        /class\s*=\s*["'][^"']*<%[\s\S]*?%>[^"']*["']/g,
+        /:class\s*=\s*["']\{[\s\S]*?\}["']/g, // Vue-like
+        /className\s*=\s*\{[\s\S]*?\}/g, // React-like in templates
+    ];
+
+    for (const pattern of classPatterns) {
+        const matches = content.match(pattern);
+        if (matches) {
+            matches.forEach(m => {
+                dynamicClasses.push({
+                    original: m,
+                    warning: 'Dynamic class detected - may not be fully extracted'
+                });
+            });
+        }
+    }
+
+    if (dynamicClasses.length > 0) {
+        warnings.push(`Found ${dynamicClasses.length} dynamic class attribute(s) - these may contain additional classes at runtime`);
+    }
+
+    // Preserve echo patterns as placeholders if requested
+    if (preserveEchos && config.echoPatterns) {
+        for (const echo of config.echoPatterns) {
+            html = html.replace(echo.regex, echo.placeholder);
+        }
+    }
+
+    // Remove server-side code patterns
+    for (const pattern of config.patterns) {
+        html = html.replace(pattern, '');
+    }
+
+    // Clean up excess whitespace but preserve structure
+    html = html
+        .replace(/^\s*[\r\n]/gm, '\n') // Remove blank lines
+        .replace(/\n{3,}/g, '\n\n') // Max 2 newlines
+        .trim();
+
+    return {
+        html,
+        templateType,
+        originalContent: content,
+        dynamicClasses,
+        warnings
+    };
+}
+
+/**
+ * Get list of supported template extensions
+ * @returns {string[]}
+ */
+function getSupportedExtensions() {
+    const extensions = [];
+    for (const config of Object.values(TEMPLATE_PATTERNS)) {
+        extensions.push(...config.extensions);
+    }
+    return [...new Set(extensions)];
+}
+
+module.exports = {
+    TEMPLATE_PATTERNS,
+    detectTemplateType,
+    isTemplateFile,
+    parseTemplateFile,
+    parseTemplateContent,
+    getSupportedExtensions
+};

package/src/utils/url-fetcher.js

@@ -0,0 +1,123 @@
+/**
+ * URL Fetcher Module
+ * Fetches rendered HTML from live URLs for WordPress/Magento/dynamic sites
+ */
+
+const https = require('https');
+const http = require('http');
+
+/**
+ * Fetch HTML content from a URL
+ * @param {string} url - URL to fetch
+ * @param {Object} options - Fetch options
+ * @returns {Promise<{html: string, url: string, statusCode: number}>}
+ */
+async function fetchURL(url, options = {}) {
+    const {
+        timeout = 30000,
+        userAgent = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+        followRedirects = true,
+        maxRedirects = 5
+    } = options;
+
+    return new Promise((resolve, reject) => {
+        const parsedUrl = new URL(url);
+        const protocol = parsedUrl.protocol === 'https:' ? https : http;
+
+        const requestOptions = {
+            hostname: parsedUrl.hostname,
+            port: parsedUrl.port || (parsedUrl.protocol === 'https:' ? 443 : 80),
+            path: parsedUrl.pathname + parsedUrl.search,
+            method: 'GET',
+            headers: {
+                'User-Agent': userAgent,
+                'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+                'Accept-Language': 'en-US,en;q=0.5',
+                'Accept-Encoding': 'identity',
+                'Connection': 'keep-alive'
+            },
+            timeout
+        };
+
+        const req = protocol.request(requestOptions, (res) => {
+            // Handle redirects
+            if (followRedirects && [301, 302, 303, 307, 308].includes(res.statusCode)) {
+                if (maxRedirects <= 0) {
+                    reject(new Error('Too many redirects'));
+                    return;
+                }
+                const redirectUrl = res.headers.location;
+                if (!redirectUrl) {
+                    reject(new Error('Redirect without location header'));
+                    return;
+                }
+                // Resolve relative URLs
+                const absoluteUrl = redirectUrl.startsWith('http')
+                    ? redirectUrl
+                    : new URL(redirectUrl, url).toString();
+
+                fetchURL(absoluteUrl, { ...options, maxRedirects: maxRedirects - 1 })
+                    .then(resolve)
+                    .catch(reject);
+                return;
+            }
+
+            let data = '';
+            res.setEncoding('utf8');
+
+            res.on('data', (chunk) => {
+                data += chunk;
+            });
+
+            res.on('end', () => {
+                resolve({
+                    html: data,
+                    url: url,
+                    statusCode: res.statusCode,
+                    contentType: res.headers['content-type'] || ''
+                });
+            });
+        });
+
+        req.on('error', (error) => {
+            reject(new Error(`Failed to fetch URL: ${error.message}`));
+        });
+
+        req.on('timeout', () => {
+            req.destroy();
+            reject(new Error(`Request timeout after ${timeout}ms`));
+        });
+
+        req.end();
+    });
+}
+
+/**
+ * Check if input is a URL
+ * @param {string} input - Input string
+ * @returns {boolean}
+ */
+function isURL(input) {
+    try {
+        const url = new URL(input);
+        return url.protocol === 'http:' || url.protocol === 'https:';
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Extract base URL for relative path resolution
+ * @param {string} url - Full URL
+ * @returns {string} Base URL
+ */
+function getBaseURL(url) {
+    const parsed = new URL(url);
+    return `${parsed.protocol}//${parsed.host}`;
+}
+
+module.exports = {
+    fetchURL,
+    isURL,
+    getBaseURL
+};