feat: Phase 3 report generation & CLI integration

docs/cli-reference.md

@@ -0,0 +1,120 @@
+# CLI Reference
+
+## Commands
+
+### validate
+
+Validate measurements against a corpus.
+
+```bash
+bun run scripts/cli.ts validate [options]
+```
+
+**Options**
+
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--corpus` | `all` \| `english` \| `rtl` \| `cjk` \| `complex` \| `mixed` | `english` | Which test corpus to validate |
+| `--report` | `csv` \| `markdown` \| `html` \| `json` \| `console` | `console` | Output format |
+| `--output` | path | stdout | File to write the report |
+| `--language` | BCP-47 code | (all) | Filter by language (e.g. `en`, `ar`) |
+| `--severity` | `pass` \| `warning` \| `error` \| `critical` | (all) | Filter by severity |
+| `--font` | pattern | (all) | Filter by font pattern |
+| `--verbose` | — | false | Show detailed output and summary to stderr |
+| `--no-color` | — | false | Disable colored output |
+
+**Examples**
+
+```bash
+# Validate English corpus (default)
+bun run scripts/cli.ts validate
+
+# Validate all and export as CSV
+bun run scripts/cli.ts validate --corpus=all --report=csv --output=all.csv
+
+# Show only Arabic warnings
+bun run scripts/cli.ts validate --language=ar --severity=warning
+
+# Export as JSON for piping
+bun run scripts/cli.ts validate --report=json | jq '.[] | select(.overallSeverity=="critical")'
+```
+
+---
+
+### report
+
+Generate a report from existing saved results.
+
+```bash
+bun run scripts/cli.ts report --input=results.json [options]
+```
+
+**Options**
+
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--input` | path | *(required)* | Path to JSON results file |
+| `--format` | `csv` \| `markdown` \| `html` \| `json` \| `console` | `console` | Output format |
+| `--output` | path | stdout | File to write the report |
+| `--language` | BCP-47 code | (all) | Filter by language |
+| `--severity` | `pass` \| `warning` \| `error` \| `critical` | (all) | Filter by severity |
+
+**Example**
+
+```bash
+bun run scripts/cli.ts report --input=results.json --format=html --output=report.html
+```
+
+---
+
+### help
+
+Show top-level help text.
+
+```bash
+bun run scripts/cli.ts help
+```
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | All measurements passed |
+| `1` | Warnings or errors detected |
+| `2` | Critical issues detected |
+| `3` | Invalid arguments |
+| `4` | File I/O or parsing error |
+
+---
+
+## Environment Variables
+
+These variables are reserved for future use and are not yet implemented.
+
+| Variable | Description |
+|----------|-------------|
+| `MEASUREMENT_VALIDATOR_DEBUG=1` | Enable debug logging |
+| `MEASUREMENT_VALIDATOR_COLORS=false` | Disable colored output |
+| `MEASUREMENT_VALIDATOR_TIMEOUT=30000` | Timeout in milliseconds |
+
+---
+
+## npm Script Shortcut
+
+Add the following to `package.json` to expose a shorter `validator` alias:
+
+```json
+{
+  "scripts": {
+    "validator": "bun run scripts/cli.ts"
+  }
+}
+```
+
+Then use:
+
+```bash
+npm run validator validate --corpus=all --report=csv --output=all.csv
+```

docs/reports.md

@@ -0,0 +1,117 @@
+# Report Generation Guide
+
+## Overview
+
+The measurement validator can generate reports in multiple formats from
+validation results.  Use the CLI to validate a corpus and export the output
+in the format that fits your workflow.
+
+## CLI Usage
+
+### Basic validation (console output)
+
+```bash
+bun run scripts/cli.ts validate
+```
+
+### Generate CSV report
+
+```bash
+bun run validator validate --report=csv --output=results.csv
+```
+
+### Generate HTML report
+
+```bash
+bun run validator validate --report=html --output=report.html
+```
+
+### Filter by language
+
+```bash
+bun run validator validate --language=ar --report=markdown
+```
+
+### Filter by severity
+
+```bash
+bun run validator validate --severity=critical --report=json
+```
+
+## Report Formats
+
+### CSV
+
+- Excel-compatible (UTF-8 with BOM by default)
+- Tab-delimited option available (`--separator=\t`)
+- Quotes and newlines inside fields are correctly escaped
+- Includes: Sample, Text, Font, MaxWidth, PretextWidth, DOMWidth, Delta,
+  ErrorPercent, Severity, RootCause, Confidence, Language, Timestamp
+
+### Markdown
+
+- GitHub Flavored Markdown
+- Copy-pasteable to issues and pull requests
+- Grouped by language (default) or flat
+- Severity summary at the top with emoji indicators
+
+### HTML
+
+- Self-contained single file — no external dependencies
+- In-page filter controls (language, severity)
+- Summary statistics cards
+- By-language breakdown table
+- Print-friendly styling
+
+### JSON
+
+- Machine-readable
+- Complete data, all fields preserved
+- Pipe to `jq` or other tools
+
+## Examples
+
+### Export all measurements as CSV
+
+```bash
+bun run validator validate --corpus=all --report=csv --output=all.csv
+```
+
+### Get summary of RTL divergences
+
+```bash
+bun run validator validate --language=ar --severity=error --report=markdown
+```
+
+### Analyze CJK measurements
+
+```bash
+bun run validator validate --language=zh --report=html --output=zh.html
+bun run validator validate --language=ja --report=html --output=ja.html
+bun run validator validate --language=ko --report=html --output=ko.html
+```
+
+## Programmatic Usage
+
+```typescript
+import {
+  ReportFormatter,
+  type MeasurementResult,
+} from './src/measurement-validator/index.ts'
+
+const results: MeasurementResult[] = [] // from your validation run
+
+const formatter = new ReportFormatter(results)
+
+// Generate different formats
+const csv  = formatter.toCSV({ encoding: 'utf-8-bom' })
+const md   = formatter.toMarkdown({ groupByLanguage: true })
+const html = formatter.toHTML({ includeCharts: false })
+const json = formatter.toJSON()
+
+// Apply filters before formatting
+const arabicWarnings = formatter
+  .filterByLanguage('ar')
+  .filterBySeverity('warning')
+  .toMarkdown()
+```

package.json

@@ -65,6 +65,7 @@
     "probe-check": "bun run scripts/probe-check.ts",
     "probe-check:safari": "PROBE_CHECK_BROWSER=safari bun run scripts/probe-check.ts",
     "status-dashboard": "bun run scripts/status-dashboard.ts",
+    "validator": "bun run scripts/cli.ts",
     "site:build": "rm -rf site && bun run scripts/build-demo-site.ts",
     "start": "HOST=${HOST:-127.0.0.1}; PORT=3000; pids=$(lsof -tiTCP:$PORT -sTCP:LISTEN 2>/dev/null); if [ -n \"$pids\" ]; then echo \"Freeing port $PORT: terminating $pids\"; kill $pids 2>/dev/null || true; sleep 1; pids=$(lsof -tiTCP:$PORT -sTCP:LISTEN 2>/dev/null); if [ -n \"$pids\" ]; then echo \"Port $PORT still busy: killing $pids\"; kill -9 $pids 2>/dev/null || true; fi; fi; bun pages/*.html pages/demos/*.html pages/demos/*/index.html --host=$HOST:$PORT",
     "start:lan": "HOST=0.0.0.0 bun run start",

scripts/cli.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env bun
+/**
+ * Measurement Validator CLI
+ *
+ * Usage:
+ *   bun run scripts/cli.ts validate [options]
+ *   bun run scripts/cli.ts report   [options]
+ *   bun run scripts/cli.ts help
+ */
+
+import { runValidation } from './validate-command.ts'
+import { generateReport } from './report-command.ts'
+
+const USAGE = `
+Measurement Validator CLI
+
+USAGE
+  bun run scripts/cli.ts <command> [options]
+
+COMMANDS
+  validate    Validate measurements against a corpus
+  report      Generate a report from saved results
+  help        Show this help text
+
+Run "bun run scripts/cli.ts <command> --help" for command-specific options.
+`.trim()
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2)
+  const command = args[0]
+
+  if (command === undefined || command === 'help' || command === '--help' || command === '-h') {
+    console.log(USAGE)
+    process.exit(0)
+  }
+
+  if (command === 'validate') {
+    await runValidation(args.slice(1))
+    return
+  }
+
+  if (command === 'report') {
+    await generateReport(args.slice(1))
+    return
+  }
+
+  console.error(`Unknown command: ${command}`)
+  console.error('Run "bun run scripts/cli.ts help" for usage.')
+  process.exit(3)
+}
+
+await main()