design-clone 2.1.0 → 3.0.0

package/src/verification/generate-audit-report-sections.js

@@ -0,0 +1,158 @@
+/**
+ * Audit Report Section Generators
+ *
+ * Pure functions for generating markdown table and section content
+ * extracted from generate-audit-report.js to keep each file under 200 lines.
+ */
+
+import path from 'path';
+import { generateCSSFixes } from './generate-audit-report-css-fixes.js';
+
+// Re-export so callers only need this one module
+export { generateCSSFixes };
+
+// Status icons
+export const STATUS_ICONS = {
+  pass: '✅',
+  warn: '⚠️',
+  fail: '❌',
+  info: 'ℹ️'
+};
+
+/**
+ * Calculate component status from verification result
+ * @param {Object|null} result
+ * @returns {{status: string, icon: string, label: string}}
+ */
+export function getComponentStatus(result) {
+  if (!result) return { status: 'skip', icon: STATUS_ICONS.info, label: 'Not tested' };
+  const { summary } = result;
+  if (!summary) return { status: 'skip', icon: STATUS_ICONS.info, label: 'No data' };
+  if (summary.failed > 0) return { status: 'fail', icon: STATUS_ICONS.fail, label: `${summary.failed} failed` };
+  if (summary.warnings?.length > 0) return { status: 'warn', icon: STATUS_ICONS.warn, label: `${summary.warnings.length} warnings` };
+  return { status: 'pass', icon: STATUS_ICONS.pass, label: 'Passed' };
+}
+
+/**
+ * Generate summary table markdown
+ * @param {Object} results - Map of component name to result
+ * @returns {string}
+ */
+export function generateSummaryTable(results) {
+  let table = `| Component | Status | Tests | Details |\n|-----------|--------|-------|----------|\n`;
+  for (const [component, result] of Object.entries(results)) {
+    const status = getComponentStatus(result);
+    const tests = result?.summary ? `${result.summary.passed}/${result.summary.totalTests}` : '-';
+    const label = component.charAt(0).toUpperCase() + component.slice(1);
+    table += `| ${label} | ${status.icon} ${status.label} | ${tests} | ${result?.url || '-'} |\n`;
+  }
+  return table;
+}
+
+/**
+ * Generate responsive viewport breakdown table
+ * @param {Object} results
+ * @returns {string}
+ */
+export function generateViewportTable(results) {
+  const viewports = ['mobile', 'tablet', 'desktop'];
+  const components = Object.keys(results).filter(c => results[c]?.viewports);
+  if (components.length === 0) return '';
+
+  let table = `| Component | Mobile | Tablet | Desktop |\n|-----------|--------|--------|----------|\n`;
+  for (const component of components) {
+    const result = results[component];
+    const row = [component.charAt(0).toUpperCase() + component.slice(1)];
+    for (const vp of viewports) {
+      const vpResult = result.viewports?.[vp];
+      if (vpResult) {
+        const icon = vpResult.failed > 0 ? STATUS_ICONS.fail
+          : vpResult.warnings?.length > 0 ? STATUS_ICONS.warn
+          : STATUS_ICONS.pass;
+        row.push(`${icon} ${vpResult.passed}/${vpResult.tests?.length || 0}`);
+      } else {
+        row.push('-');
+      }
+    }
+    table += `| ${row.join(' | ')} |\n`;
+  }
+  return table;
+}
+
+/**
+ * Generate a markdown section for a single component
+ * @param {string} component
+ * @param {Object|null} result
+ * @returns {string}
+ */
+export function generateComponentSection(component, result) {
+  const label = component.charAt(0).toUpperCase() + component.slice(1);
+  if (!result) return `### ${label}\n\n${STATUS_ICONS.info} Not tested\n\n---\n\n`;
+
+  const status = getComponentStatus(result);
+  let section = `### ${label} ${status.icon}\n\n`;
+
+  if (component === 'slider' && result.sliderLibrary) {
+    section += `**Library:** ${result.sliderLibrary}\n\n`;
+  }
+
+  if (result.viewports) {
+    for (const [viewport, vpResult] of Object.entries(result.viewports)) {
+      const vpLabel = viewport.charAt(0).toUpperCase() + viewport.slice(1);
+      section += `#### ${vpLabel} (${vpResult.dimensions?.width}x${vpResult.dimensions?.height})\n\n`;
+
+      if (vpResult.tests?.length > 0) {
+        for (const test of vpResult.tests) {
+          const icon = test.passed ? STATUS_ICONS.pass : STATUS_ICONS.fail;
+          section += `- ${icon} **${test.name}**`;
+          if (test.selector) section += ` - \`${test.selector}\``;
+          if (test.count !== undefined) section += ` (${test.count} found)`;
+          if (test.note) section += ` - ${test.note}`;
+          if (test.error) section += ` - ⚠️ ${test.error}`;
+          section += '\n';
+        }
+      }
+
+      if (vpResult.warnings?.length > 0) {
+        section += '\n**Warnings:**\n';
+        for (const warning of vpResult.warnings) {
+          section += `- ${STATUS_ICONS.warn} ${warning}\n`;
+        }
+      }
+      section += '\n';
+    }
+  }
+
+  if (result.screenshots?.length > 0) {
+    section += `#### Screenshots\n\n| Viewport | Screenshot |\n|----------|------------|\n`;
+    for (const screenshot of result.screenshots) {
+      const name = path.basename(screenshot);
+      const viewport = name.replace(/^[a-z]+-test-/, '').replace('.png', '');
+      section += `| ${viewport} | [${name}](${screenshot}) |\n`;
+    }
+    section += '\n';
+  }
+
+  section += '---\n\n';
+  return section;
+}
+
+/**
+ * Generate the full markdown audit report string
+ * @param {Object} results
+ * @param {string|undefined} url
+ * @returns {string}
+ */
+export function generateMarkdownReport(results, url) {
+  const timestamp = new Date().toISOString();
+  let report = `# Component Audit Report\n\n**Generated:** ${timestamp}\n**URL:** ${url || 'N/A'}\n\n`;
+  report += `## Summary\n\n${generateSummaryTable(results)}\n`;
+  report += `## Responsive Breakdown\n\n${generateViewportTable(results)}\n`;
+  report += `## Component Details\n\n`;
+  for (const [component, result] of Object.entries(results)) {
+    report += generateComponentSection(component, result);
+  }
+  report += generateCSSFixes(results);
+  report += `---\n\n*Report generated by design-clone verification suite*\n`;
+  return report;
+}

package/src/verification/generate-audit-report.js

@@ -20,7 +20,8 @@
 
 import fs from 'fs/promises';
 import path from 'path';
-import { parseArgs, outputJSON, outputError } from '../utils/browser.js';
+import { parseArgs, outputJSON, outputError } from '../utils/helpers.js';
+import { generateMarkdownReport } from './generate-audit-report-sections.js';
 
 // Component types and their result files
 const COMPONENT_FILES = {
@@ -31,16 +32,10 @@ const COMPONENT_FILES = {
   layout: 'layout-results.json'
 };
 
-// Status icons
-const STATUS_ICONS = {
-  pass: '✅',
-  warn: '⚠️',
-  fail: '❌',
-  info: 'ℹ️'
-};
-
 /**
  * Load verification results from directory
+ * @param {string} dir
+ * @returns {Promise<Object>} Map of component name to parsed result or null
  */
 async function loadVerificationResults(dir) {
   const results = {};
@@ -61,264 +56,6 @@ async function loadVerificationResults(dir) {
   return results;
 }
 
-/**
- * Calculate component status
- */
-function getComponentStatus(result) {
-  if (!result) return { status: 'skip', icon: STATUS_ICONS.info, label: 'Not tested' };
-
-  const { summary } = result;
-  if (!summary) return { status: 'skip', icon: STATUS_ICONS.info, label: 'No data' };
-
-  if (summary.failed > 0) {
-    return { status: 'fail', icon: STATUS_ICONS.fail, label: `${summary.failed} failed` };
-  }
-  if (summary.warnings?.length > 0) {
-    return { status: 'warn', icon: STATUS_ICONS.warn, label: `${summary.warnings.length} warnings` };
-  }
-  return { status: 'pass', icon: STATUS_ICONS.pass, label: 'Passed' };
-}
-
-/**
- * Generate summary table
- */
-function generateSummaryTable(results) {
-  let table = `| Component | Status | Tests | Details |
-|-----------|--------|-------|---------|
-`;
-
-  for (const [component, result] of Object.entries(results)) {
-    const status = getComponentStatus(result);
-    const tests = result?.summary
-      ? `${result.summary.passed}/${result.summary.totalTests}`
-      : '-';
-    table += `| ${component.charAt(0).toUpperCase() + component.slice(1)} | ${status.icon} ${status.label} | ${tests} | ${result?.url || '-'} |\n`;
-  }
-
-  return table;
-}
-
-/**
- * Generate viewport breakdown table
- */
-function generateViewportTable(results) {
-  const viewports = ['mobile', 'tablet', 'desktop'];
-  const components = Object.keys(results).filter(c => results[c]?.viewports);
-
-  if (components.length === 0) return '';
-
-  let table = `| Component | Mobile | Tablet | Desktop |
-|-----------|--------|--------|---------|
-`;
-
-  for (const component of components) {
-    const result = results[component];
-    const row = [component.charAt(0).toUpperCase() + component.slice(1)];
-
-    for (const vp of viewports) {
-      const vpResult = result.viewports?.[vp];
-      if (vpResult) {
-        const icon = vpResult.failed > 0 ? STATUS_ICONS.fail
-          : vpResult.warnings?.length > 0 ? STATUS_ICONS.warn
-          : STATUS_ICONS.pass;
-        row.push(`${icon} ${vpResult.passed}/${vpResult.tests?.length || 0}`);
-      } else {
-        row.push('-');
-      }
-    }
-
-    table += `| ${row.join(' | ')} |\n`;
-  }
-
-  return table;
-}
-
-/**
- * Generate component section
- */
-function generateComponentSection(component, result) {
-  if (!result) {
-    return `### ${component.charAt(0).toUpperCase() + component.slice(1)}
-
-${STATUS_ICONS.info} Not tested
-
----
-
-`;
-  }
-
-  const status = getComponentStatus(result);
-  let section = `### ${component.charAt(0).toUpperCase() + component.slice(1)} ${status.icon}
-
-`;
-
-  // Add component-specific info
-  if (component === 'slider' && result.sliderLibrary) {
-    section += `**Library:** ${result.sliderLibrary}\n\n`;
-  }
-
-  // Test results by viewport
-  if (result.viewports) {
-    for (const [viewport, vpResult] of Object.entries(result.viewports)) {
-      section += `#### ${viewport.charAt(0).toUpperCase() + viewport.slice(1)} (${vpResult.dimensions?.width}x${vpResult.dimensions?.height})\n\n`;
-
-      // List tests
-      if (vpResult.tests?.length > 0) {
-        for (const test of vpResult.tests) {
-          const icon = test.passed ? STATUS_ICONS.pass : STATUS_ICONS.fail;
-          section += `- ${icon} **${test.name}**`;
-          if (test.selector) section += ` - \`${test.selector}\``;
-          if (test.count !== undefined) section += ` (${test.count} found)`;
-          if (test.note) section += ` - ${test.note}`;
-          if (test.error) section += ` - ⚠️ ${test.error}`;
-          section += '\n';
-        }
-      }
-
-      // Warnings
-      if (vpResult.warnings?.length > 0) {
-        section += '\n**Warnings:**\n';
-        for (const warning of vpResult.warnings) {
-          section += `- ${STATUS_ICONS.warn} ${warning}\n`;
-        }
-      }
-
-      section += '\n';
-    }
-  }
-
-  // Screenshots
-  if (result.screenshots?.length > 0) {
-    section += `#### Screenshots\n\n`;
-    section += `| Viewport | Screenshot |\n|----------|------------|\n`;
-    for (const screenshot of result.screenshots) {
-      const name = path.basename(screenshot);
-      const viewport = name.replace(/^[a-z]+-test-/, '').replace('.png', '');
-      section += `| ${viewport} | [${name}](${screenshot}) |\n`;
-    }
-    section += '\n';
-  }
-
-  section += '---\n\n';
-  return section;
-}
-
-/**
- * Generate CSS fixes section
- */
-function generateCSSFixes(results) {
-  const fixes = [];
-
-  // Collect issues that might need CSS fixes
-  for (const [component, result] of Object.entries(results)) {
-    if (!result?.viewports) continue;
-
-    for (const [viewport, vpResult] of Object.entries(result.viewports)) {
-      // Check for layout issues
-      if (component === 'header' && vpResult.headerHeight) {
-        // Height consistency check already done in verify-header
-      }
-
-      if (component === 'footer') {
-        const positionTest = vpResult.tests?.find(t => t.name === 'Footer at page bottom');
-        if (positionTest && !positionTest.passed) {
-          fixes.push({
-            component,
-            viewport,
-            issue: 'Footer not at page bottom',
-            suggestion: `/* Ensure footer sticks to bottom */
-footer {
-  margin-top: auto;
-}
-body {
-  min-height: 100vh;
-  display: flex;
-  flex-direction: column;
-}`
-          });
-        }
-      }
-
-      // Check warnings
-      if (vpResult.warnings) {
-        for (const warning of vpResult.warnings) {
-          if (warning.includes('z-index')) {
-            fixes.push({
-              component,
-              viewport,
-              issue: warning,
-              suggestion: `/* Increase header z-index */
-header, .header, [role="banner"] {
-  z-index: 1000;
-}`
-            });
-          }
-        }
-      }
-    }
-  }
-
-  if (fixes.length === 0) return '';
-
-  let section = `## Suggested CSS Fixes
-
-`;
-
-  for (const fix of fixes) {
-    section += `### ${fix.component} (${fix.viewport})
-
-**Issue:** ${fix.issue}
-
-\`\`\`css
-${fix.suggestion}
-\`\`\`
-
-`;
-  }
-
-  return section;
-}
-
-/**
- * Generate full markdown report
- */
-function generateMarkdownReport(results, url) {
-  const timestamp = new Date().toISOString();
-
-  let report = `# Component Audit Report
-
-**Generated:** ${timestamp}
-**URL:** ${url || 'N/A'}
-
-## Summary
-
-${generateSummaryTable(results)}
-
-## Responsive Breakdown
-
-${generateViewportTable(results)}
-
-## Component Details
-
-`;
-
-  // Add each component section
-  for (const [component, result] of Object.entries(results)) {
-    report += generateComponentSection(component, result);
-  }
-
-  // Add CSS fixes if any
-  report += generateCSSFixes(results);
-
-  // Footer
-  report += `---
-
-*Report generated by design-clone verification suite*
-`;
-
-  return report;
-}
-
 /**
  * Main function
  */
@@ -336,24 +73,17 @@ async function generateAuditReport() {
   try {
     if (verbose) console.error(`\n📊 Generating audit report from ${args.dir}\n`);
 
-    // Load all verification results
     const results = await loadVerificationResults(args.dir);
-
-    // Get URL from first available result
     const url = Object.values(results).find(r => r?.url)?.url;
 
-    // Count loaded components
     const loadedCount = Object.values(results).filter(r => r !== null).length;
     if (verbose) console.error(`  Loaded ${loadedCount}/${Object.keys(COMPONENT_FILES).length} component results`);
 
-    // Generate report
     const report = generateMarkdownReport(results, url);
 
-    // Write report
     await fs.writeFile(outputPath, report, 'utf-8');
     if (verbose) console.error(`  ✓ Report written to ${outputPath}`);
 
-    // Calculate overall stats
     let totalTests = 0, totalPassed = 0, totalFailed = 0, totalWarnings = 0;
     for (const result of Object.values(results)) {
       if (result?.summary) {
@@ -368,13 +98,7 @@ async function generateAuditReport() {
       success: totalFailed === 0,
       reportPath: outputPath,
       url,
-      summary: {
-        components: loadedCount,
-        totalTests,
-        passed: totalPassed,
-        failed: totalFailed,
-        warnings: totalWarnings
-      }
+      summary: { components: loadedCount, totalTests, passed: totalPassed, failed: totalFailed, warnings: totalWarnings }
     };
 
     if (verbose) {

package/src/verification/quality-scorer.js

@@ -0,0 +1,92 @@
+/**
+ * Output Quality Scorer
+ *
+ * Scores the quality of a design clone capture on 5 metrics (0-100 scale).
+ * Auto-runs for clone-px mode, opt-in for basic clone.
+ */
+
+import fs from 'fs/promises';
+
+const WEIGHTS = {
+  cssCoverage: 0.30,
+  assetCompleteness: 0.25,
+  responsiveFidelity: 0.20,
+  htmlSemantics: 0.15,
+  accessibility: 0.10
+};
+
+const SEMANTIC_TAGS = new Set([
+  'header', 'footer', 'nav', 'main', 'article', 'section', 'aside', 'figure', 'figcaption'
+]);
+
+function scoreCssCoverage(extraction) {
+  if (!extraction?.css || !extraction?.filtered) return 0;
+  const reduction = parseInt(extraction.filtered.reduction) || 0;
+  const kept = 100 - reduction;
+  if (kept >= 80) return 100;
+  if (kept >= 50) return 80;
+  return 60;
+}
+
+function scoreAssetCompleteness(stats) {
+  if (!stats || stats.total === 0) return 100;
+  const ratio = stats.downloaded / stats.total;
+  return Math.round(ratio * 100);
+}
+
+function scoreResponsiveFidelity(screenshots) {
+  if (!screenshots) return 0;
+  const count = Array.isArray(screenshots) ? screenshots.length : 0;
+  if (count >= 3) return 100;
+  if (count >= 2) return 70;
+  return 40;
+}
+
+function scoreHtmlSemantics(htmlContent) {
+  if (!htmlContent) return 0;
+  let found = 0;
+  for (const tag of SEMANTIC_TAGS) {
+    if (htmlContent.includes(`<${tag}`)) found++;
+  }
+  return Math.min(100, Math.round((found / SEMANTIC_TAGS.size) * 100));
+}
+
+function scoreAccessibility(htmlContent) {
+  if (!htmlContent) return 0;
+  let score = 0;
+  const imgCount = (htmlContent.match(/<img/g) || []).length;
+  const altCount = (htmlContent.match(/<img[^>]+alt=/g) || []).length;
+  if (imgCount === 0) score += 50;
+  else score += Math.round((altCount / imgCount) * 50);
+  if (htmlContent.includes('<h1')) score += 25;
+  if (/<html[^>]+lang=/.test(htmlContent)) score += 25;
+  return Math.min(100, score);
+}
+
+/**
+ * Score the quality of a design clone capture
+ * @param {{ extraction: Object, screenshots: Array, assetStats: Object, outputDir: string }} params
+ * @returns {Promise<{overall: number, metrics: Object, weights: Object, maxScore: number}>}
+ */
+export async function scoreCapture({ extraction, screenshots, assetStats, outputDir }) {
+  let htmlContent = '';
+  if (extraction?.html?.path) {
+    try { htmlContent = await fs.readFile(extraction.html.path, 'utf-8'); } catch { /* ok */ }
+  }
+
+  const metrics = {
+    cssCoverage: scoreCssCoverage(extraction),
+    assetCompleteness: scoreAssetCompleteness(assetStats),
+    responsiveFidelity: scoreResponsiveFidelity(screenshots),
+    htmlSemantics: scoreHtmlSemantics(htmlContent),
+    accessibility: scoreAccessibility(htmlContent)
+  };
+
+  const overall = Math.round(
+    Object.entries(WEIGHTS).reduce(
+      (sum, [key, weight]) => sum + (metrics[key] * weight), 0
+    )
+  );
+
+  return { overall, metrics, weights: WEIGHTS, maxScore: 100 };
+}

package/src/verification/verify-footer-checks.js

@@ -0,0 +1,103 @@
+/**
+ * Footer Viewport Checks
+ *
+ * Orchestrates all per-viewport footer checks using helpers.
+ * Separated from verify-footer-helpers.js to keep each file under 200 lines.
+ */
+
+import {
+  FOOTER_SELECTORS,
+  findElement,
+  countElements,
+  countVisibleElements,
+  checkFooterPosition,
+  checkCopyright
+} from './verify-footer-helpers.js';
+
+/**
+ * Test footer at a specific viewport — runs all footer checks
+ * @param {import('playwright').Page} page
+ * @param {string} viewportName
+ * @param {Object} VIEWPORTS - Viewport map
+ * @param {boolean} verbose
+ * @returns {Promise<Object>} Viewport result object
+ */
+export async function testFooterViewport(page, viewportName, VIEWPORTS, verbose = false) {
+  const viewport = VIEWPORTS[viewportName];
+  await page.setViewportSize(viewport);
+  await new Promise(r => setTimeout(r, 500));
+  await page.evaluate(() => { window.scrollTo(0, document.body.scrollHeight); });
+  await new Promise(r => setTimeout(r, 300));
+
+  const result = { viewport: viewportName, dimensions: viewport, tests: [], passed: 0, failed: 0, warnings: [] };
+  if (verbose) console.error(`\n📱 Testing ${viewportName} (${viewport.width}x${viewport.height})...`);
+
+  const footerResult = await findElement(page, FOOTER_SELECTORS.container);
+  if (!footerResult) {
+    result.tests.push({ name: 'Footer container exists', passed: false, error: 'No footer container found' });
+    result.failed++;
+    if (verbose) console.error(`  ✗ Footer not found`);
+    return result;
+  }
+
+  result.tests.push({ name: 'Footer container exists', passed: true, selector: footerResult.selector });
+  result.passed++;
+  if (verbose) console.error(`  ✓ Footer found: ${footerResult.selector}`);
+
+  const positionInfo = await checkFooterPosition(page, footerResult.selector);
+  if (positionInfo) {
+    if (positionInfo.isAtBottom) {
+      result.tests.push({ name: 'Footer at page bottom', passed: true, y: positionInfo.y, pageHeight: positionInfo.pageHeight });
+      result.passed++;
+      if (verbose) console.error(`  ✓ Footer at bottom (y: ${Math.round(positionInfo.y)})`);
+    } else {
+      result.tests.push({ name: 'Footer at page bottom', passed: false, y: positionInfo.y, footerBottom: positionInfo.footerBottom, pageHeight: positionInfo.pageHeight, error: 'Footer not at page bottom' });
+      result.failed++;
+      if (verbose) console.error(`  ✗ Footer not at bottom (gap: ${positionInfo.pageHeight - positionInfo.footerBottom}px)`);
+    }
+    result.footerDimensions = { height: positionInfo.height, width: positionInfo.width, backgroundColor: positionInfo.backgroundColor, color: positionInfo.color };
+  }
+
+  if (viewportName !== 'mobile') {
+    const columns = await countElements(page, FOOTER_SELECTORS.columns);
+    if (columns.count >= 1) {
+      result.tests.push({ name: 'Multi-column layout', passed: true, count: columns.count, selector: columns.selector, note: columns.count === 1 ? 'Single column layout' : undefined });
+      result.passed++;
+      if (verbose) console.error(`  ✓ ${columns.count} column(s) found`);
+    } else {
+      result.warnings.push('No clear column structure detected');
+      if (verbose) console.error(`  ⚠ No column structure detected`);
+    }
+  }
+
+  const links = await countVisibleElements(page, FOOTER_SELECTORS.links);
+  if (links.count >= 1) {
+    result.tests.push({ name: 'Footer links present', passed: true, count: links.count, selector: links.selector });
+    result.passed++;
+    if (verbose) console.error(`  ✓ ${links.count} links found`);
+  } else {
+    result.warnings.push('No links found in footer');
+    if (verbose) console.error(`  ⚠ No links found`);
+  }
+
+  const copyrightInfo = await checkCopyright(page);
+  if (copyrightInfo && (copyrightInfo.hasCopyright || copyrightInfo.hasYear)) {
+    result.tests.push({ name: 'Copyright text present', passed: true, hasCopyright: copyrightInfo.hasCopyright, hasCurrentYear: copyrightInfo.hasCurrentYear });
+    result.passed++;
+    if (verbose) console.error(`  ✓ Copyright found (current year: ${copyrightInfo.hasCurrentYear})`);
+  } else {
+    result.warnings.push('No copyright text found');
+    if (verbose) console.error(`  ⚠ No copyright text`);
+  }
+
+  const socialIcons = await countVisibleElements(page, FOOTER_SELECTORS.socialIcons);
+  if (socialIcons.count > 0) {
+    result.tests.push({ name: 'Social icons present', passed: true, count: socialIcons.count });
+    result.passed++;
+    if (verbose) console.error(`  ✓ ${socialIcons.count} social icons found`);
+  } else {
+    if (verbose) console.error(`  ℹ No social icons found`);
+  }
+
+  return result;
+}