Merge pull request #56 from jrjohnson/diffier-diffs

Various Report Improvements

Author: jrjohnson

bin/visual-differ.ts

@@ -91,7 +91,9 @@ program
           console.log('❌ Visual differences detected.');
         }
 
-        console.log(`\n📄 Report generated: ${resolvedOutput}/index.html\n`);
+        console.log(`\n📄 Reports generated:`);
+        console.log(`  HTML: ${resolvedOutput}/index.html`);
+        console.log(`  Markdown: ${resolvedOutput}/report.md\n`);
 
         process.exit(result.exitCode);
       } catch (error) {

lib/constants.ts

@@ -17,7 +17,17 @@ export const CANDIDATE_SUFFIX = '-candidate.png';
  */
 export const DIFF_SUFFIX = '-diff.png';
 
+/**
+ * Subdirectory within the output directory where diff images are stored
+ */
+export const IMAGES_DIR = 'images';
+
 /**
  * Name of the generated HTML report file
  */
 export const REPORT_FILENAME = 'index.html';
+
+/**
+ * Name of the generated Markdown report file
+ */
+export const MARKDOWN_REPORT_FILENAME = 'report.md';

lib/markdown-report-generator.ts

@@ -0,0 +1,107 @@
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+import { MARKDOWN_REPORT_FILENAME } from './constants.js';
+import type { ComparisonResult } from './image-comparer.js';
+import type { ScannedFile } from './file-scanner.js';
+
+// Generates a markdown report and writes it to the output directory
+export function generateMarkdownReport(
+  comparisonResults: ComparisonResult[],
+  baselineOnly: ScannedFile[],
+  candidateOnly: ScannedFile[],
+  outputDir: string,
+): void {
+  const markdown = generateMarkdown(comparisonResults, baselineOnly, candidateOnly);
+  writeFileSync(join(outputDir, MARKDOWN_REPORT_FILENAME), markdown);
+}
+
+// Builds the full markdown string from comparison data
+function generateMarkdown(
+  comparisonResults: ComparisonResult[],
+  baselineOnly: ScannedFile[],
+  candidateOnly: ScannedFile[],
+): string {
+  const withDifferences = comparisonResults.filter((r) => r.hasDifference);
+  const withoutDifferences = comparisonResults.filter((r) => !r.hasDifference);
+
+  const totalImages = comparisonResults.length + baselineOnly.length + candidateOnly.length;
+  const diffCount = withDifferences.length;
+  const removedCount = baselineOnly.length;
+  const addedCount = candidateOnly.length;
+  const identicalCount = withoutDifferences.length;
+
+  const hasFailed = diffCount > 0 || removedCount > 0;
+  const statusEmoji = hasFailed ? '❌' : '✅';
+  const statusText = hasFailed ? 'FAILED' : 'PASSED';
+
+  const lines: string[] = [];
+
+  // Status header
+  lines.push(`# ${statusEmoji} Visual Diff Report — ${statusText}`);
+  lines.push('');
+
+  // Summary line
+  const parts: string[] = [];
+  if (diffCount > 0) parts.push(`**${diffCount}** different`);
+  if (removedCount > 0) parts.push(`**${removedCount}** removed`);
+  if (addedCount > 0) parts.push(`**${addedCount}** added`);
+  if (identicalCount > 0) parts.push(`**${identicalCount}** identical`);
+  lines.push(`**${totalImages}** images compared: ${parts.join(' · ')}`);
+  lines.push('');
+
+  // Details section with all file lists
+  const hasDetails =
+    withDifferences.length > 0 || removedCount > 0 || addedCount > 0 || identicalCount > 0;
+
+  if (hasDetails) {
+    lines.push('<details>');
+    lines.push('<summary>Details</summary>');
+    lines.push('');
+
+    if (withDifferences.length > 0) {
+      lines.push(`### Differences (${diffCount})`);
+      lines.push('');
+      lines.push('| File | Diff % | Notes |');
+      lines.push('|------|--------|-------|');
+      for (const result of withDifferences) {
+        const notes = result.dimensionMismatch
+          ? `⚠️ Dimension mismatch (${result.dimensionMismatch.baseline} → ${result.dimensionMismatch.candidate})`
+          : '';
+        lines.push(`| ${result.pair.name} | ${result.diffPercentage.toFixed(2)}% | ${notes} |`);
+      }
+      lines.push('');
+    }
+
+    if (removedCount > 0) {
+      lines.push(`### Removed Files (${removedCount})`);
+      lines.push('');
+      for (const file of baselineOnly) {
+        lines.push(`- \`${file.name}\``);
+      }
+      lines.push('');
+    }
+
+    if (addedCount > 0) {
+      lines.push(`### Added Files (${addedCount})`);
+      lines.push('');
+      for (const file of candidateOnly) {
+        lines.push(`- \`${file.name}\``);
+      }
+      lines.push('');
+    }
+
+    if (identicalCount > 0) {
+      lines.push(`### Identical Files (${identicalCount})`);
+      lines.push('');
+      for (const result of withoutDifferences) {
+        lines.push(`- \`${result.pair.name}\``);
+      }
+      lines.push('');
+    }
+
+    lines.push('</details>');
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}

lib/report-generator.ts

@@ -2,7 +2,7 @@ import { readFileSync, writeFileSync } from 'fs';
 import { join, basename, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import Handlebars from 'handlebars';
-import { REPORT_FILENAME } from './constants.js';
+import { IMAGES_DIR, REPORT_FILENAME } from './constants.js';
 import type { ComparisonResult } from './image-comparer.js';
 import type { ScannedFile } from './file-scanner.js';
 
@@ -67,9 +67,9 @@ function generateHTML(
       name: result.pair.name,
       dimensionMismatch: result.dimensionMismatch,
       diffPercentage: result.diffPercentage.toFixed(2),
-      baselineImage: basename(result.pair.baselinePath),
-      diffImage: basename(result.pair.diffPath),
-      candidateImage: basename(result.pair.candidatePath),
+      baselineImage: `${IMAGES_DIR}/${basename(result.pair.baselinePath)}`,
+      diffImage: `${IMAGES_DIR}/${basename(result.pair.diffPath)}`,
+      candidateImage: `${IMAGES_DIR}/${basename(result.pair.candidatePath)}`,
     })),
     withoutDifferences: withoutDifferences.map((result) => ({
       name: result.pair.name,

lib/visual-differ.ts

@@ -1,10 +1,13 @@
-import { writeFileSync } from 'fs';
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
 import { PNG } from 'pngjs';
 import { scanAndMatchFiles } from './file-scanner.js';
 import { PngFilePair } from './png-file-pair.js';
 import { compareImages } from './image-comparer.js';
 import { calculateExitCode } from './exit-code-calculator.js';
 import { generateReport } from './report-generator.js';
+import { generateMarkdownReport } from './markdown-report-generator.js';
+import { IMAGES_DIR } from './constants.js';
 import type { ComparisonResult } from './image-comparer.js';
 
 /**
@@ -44,13 +47,17 @@ export function compareDirectories(
   // Scan and match files
   const fileMatches = scanAndMatchFiles(baselineDir, candidateDir);
 
+  // Create images subdirectory for diff output
+  const imagesDir = join(outputDir, IMAGES_DIR);
+  mkdirSync(imagesDir, { recursive: true });
+
   // Load and compare matched PNG pairs
   const comparisonResults: ComparisonResult[] = fileMatches.matched.map((matched) => {
     const pngPair = new PngFilePair(
       matched.name,
       { name: matched.name, path: matched.baselinePath },
       { name: matched.name, path: matched.candidatePath },
-      outputDir,
+      imagesDir,
     );
 
     // Handle dimension mismatch - write PNGs and treat as 100% different
@@ -76,8 +83,14 @@ export function compareDirectories(
   // Calculate exit code
   const exitCode = calculateExitCode(comparisonResults, fileMatches.baselineOnly);
 
-  // Generate report
+  // Generate reports
   generateReport(comparisonResults, fileMatches.baselineOnly, fileMatches.candidateOnly, outputDir);
+  generateMarkdownReport(
+    comparisonResults,
+    fileMatches.baselineOnly,
+    fileMatches.candidateOnly,
+    outputDir,
+  );
 
   // Return summary
   const withDifferences = comparisonResults.filter((r) => r.hasDifference).length;