feat: Phase 3 report generation & CLI integration

[Copilot]

Adds production-ready multi-format report export and a CLI for running measurement validation — the core deliverable of Phase 3.

New module: src/measurement-validator/

File	Purpose
types.ts	MeasurementResult, MeasurementSeverity, ReportSummary, LanguageStats
stats.ts	computeSummary(), computeStatsByLanguage() — shared, no circular deps
csv-exporter.ts	RFC 4180, UTF-8 BOM by default, configurable separator
markdown-exporter.ts	GFM with language grouping, severity icons, safe \/| escaping
html-report-generator.ts	Self-contained single-file HTML, summary cards, inline filter controls
json-exporter.ts	Full-fidelity JSON serialization
report-formatter.ts	ReportFormatter — fluent filter/sort/export API

const csv = new ReportFormatter(results)
  .filterByLanguage('ar')
  .filterBySeverity('warning')
  .toCSV({ encoding: 'utf-8-bom' })

CLI (scripts/)

• cli.ts — dispatcher for validate, report, help
• validate-command.ts — load corpus → filter → output; exit codes 0/1/2 by severity
• report-command.ts — read saved JSON → filter → reformat; exit codes 3/4 on bad args/I/O

bun run scripts/cli.ts validate --corpus=all --report=csv --output=all.csv
bun run scripts/cli.ts validate --language=ar --severity=error --report=markdown
bun run scripts/cli.ts report --input=results.json --format=html --output=report.html

Tests (test/)

• report-generators.test.ts — 24 tests: CSV headers/BOM/separators/quoting, Markdown structure/XSS-escaping, HTML validity/filter controls, JSON round-trip
• cli.test.ts — 13 tests: all output formats, language/severity filters, file output, exit codes

Docs (docs/)

• reports.md — usage guide + programmatic API
• cli-reference.md — full option/exit-code reference

Original prompt

Phase 3 (Refined): Report Enhancement & CLI Integration

OBJECTIVE

Implement focused, high-ROI report generation and CLI enhancements. This phase delivers production-ready export formats and user-friendly command-line tools without scope creep.

WHAT WE'RE BUILDING

Scope: 4 Weeks (vs 6 weeks previously)

INCLUDED:

• ✅ CSV Export (machine-readable data)
• ✅ Markdown Export (GitHub-friendly reports)
• ✅ HTML Report (visual summary, simple table)
• ✅ Enhanced CLI (--report, --language, --severity flags)
• ✅ Integration tests for all exporters
• ✅ Complete documentation

DEFERRED to Phase 4:

• ⏸️ GitHub Actions workflow (needs stable Phase 1-3 first)
• ⏸️ Performance tracking system (need baseline data)
• ⏸️ Watch mode & streaming
• ⏸️ Dashboard server
• ⏸️ Pre-commit hooks (causes friction, redundant with CI)

REMOVED:

• ❌ Interactive REPL (low usage, high complexity)
• ❌ Dark mode (unnecessary)
• ❌ Mobile responsiveness (not used on mobile)

FILES TO CREATE (10 files)

Core Modules (src/measurement-validator/)

1. html-report-generator.ts (2 days)

interface HTMLReportOptions {
  title?: string
  includeCharts?: boolean
  includeSummary?: boolean
  resultsPerPage?: number
}

function generateHTMLReport(
  results: MeasurementResult[],
  options?: HTMLReportOptions
): string {
  // Returns complete HTML as string
  // Simple table format, no JavaScript
  // Single-file, self-contained
  // <2 second render time
}

Features:

• Summary statistics (pass rate, severity breakdown)
• Filterable table (language, font, severity)
• Per-line details on click
• Print-friendly styling
• No external dependencies

2. csv-exporter.ts (1 day)

interface CSVExportOptions {
  includeDetails?: boolean
  separator?: ',' | ';' | '\t'
  encoding?: 'utf-8' | 'utf-8-bom'
}

function exportToCSV(
  results: MeasurementResult[],
  options?: CSVExportOptions
): string {
  // Proper CSV format
  // UTF-8 encoding with BOM (Excel compatibility)
  // Escape quotes, newlines
  // Test with Excel, Google Sheets, LibreOffice
}

Format:

Sample,Text,Font,MaxWidth,PretextWidth,DOMWidth,Delta,ErrorPercent,Severity,RootCause,Confidence,Timestamp
en-simple,"Hello world",16px Arial,400,87.5,88.0,0.5,0.6%,exact,-,1.0,2024-04-04T10:15:23Z
ar-simple,"مرحبا",16px Arial,400,95.2,110.5,15.3,16.1%,critical,bidi_shaping,0.85,2024-04-04T10:15:25Z

3. markdown-exporter.ts (1 day)

interface MarkdownExportOptions {
  includeDetails?: boolean
  groupByLanguage?: boolean
  includeCharts?: boolean
}

function exportToMarkdown(
  results: MeasurementResult[],
  options?: MarkdownExportOptions
): string {
  // GitHub Flavored Markdown
  // Summary section
  // Results by language
  // Severity breakdown
  // Copy-pasteable to issues
}

Format:

# Measurement Validator Report

**Generated:** 2024-04-04 10:15:23 UTC

## Summary
- ✅ **1,847 passed** (99.8%)
- ⚠️ **2 warnings** (0.1%)
- ❌ **1 error** (0.1%)
- 🔴 **0 critical** (0.0%)

## Results by Language

### English (900 samples)
| Text | Font | Pretext | DOM | Delta | Severity |
|------|------|---------|-----|-------|----------|
| Hello world | 16px Arial | 87.5px | 88.0px | 0.5px | ✅ |

### Arabic (100 samples)
| Text | Font | Pretext | DOM | Delta | Severity |
|------|------|---------|-----|-------|----------|
| مرحبا | 16px Arial | 95.2px | 110.5px | 15.3px | ❌ |

4. json-exporter.ts (0.5 days)

function exportToJSON(results: MeasurementResult[]): string {
  return JSON.stringify(results, null, 2)
}

5. report-formatter.ts (Enhanced from Phase 1)

class ReportFormatter {
  constructor(results: MeasurementResult[])
  
  toHTML(options?: HTMLReportOptions): string
  toCSV(options?: CSVExportOptions): string
  toMarkdown(options?: MarkdownExportOptions): string
  toJSON(): string
  toConsole(): string
  
  filterByLanguage(language: string): ReportFormatter
  filterBySeverity(severity: MeasurementSeverity): ReportFormatter
  sortByDelta(ascending?: boolean): ReportFormatter
  
  summary(): ReportSummary
  statisticsByLanguage(): Record<string, LanguageStats>
}

CLI Module (scripts/)

6. cli.ts (1 day)

// Command structure:
// npm run validator [command] [options]

// Commands:
// - validate [options]    Validate measurements
// - report [options]      Generate reports
// - help                  Show help

// Example usage:
// npm run validator validate --corpus=all --report=csv
// npm run validator report --input=results.json --format=html
// npm run validator validate --language=ar --severity=warning

Options:

--corpus [all|english|rtl|cjk|complex|mixed]
  Which test corpus to validate. Default: english

--report [csv|markdown|html|json|console]
  Output format. Default: console

--output [path]
  File to write report. Default: stdout

--language [en|ar|zh|ja|ko|th|...]
  Filter by language. Default: none ...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

*This pull request was created from Copilot chat.*
>