website-evaluator/spec/report.md

Report Spec (WE-R)

Overview

Assembles all collected data into a single Markdown file optimised for Claude to read. Findings are phrased in a pre-interpreted tone: each issue explains what it means and what to do about it, not just that a value is absent or wrong.

Responsibilities

• Accept LighthouseResult[] and DomData as inputs
• Produce a single Markdown string
• Apply severity grading to Lighthouse scores
• Categorise findings as Critical (must fix) / Warning (should fix) / Info
• Write the report in the defined section order
• Deduplicate findings that appear in both desktop and mobile audits

Delegates to: nothing (pure function, no I/O)

Dependencies

Read lighthouse.md for LighthouseResult shape. Read dom-analysis.md for DomData shape.

Data Model

Score grading

Score	Grade	Colour label
90–100	A	Good
75–89	B	Needs improvement
50–74	C	Poor
0–49	F	Critical

Severity rules

• Critical (must fix): Lighthouse finding with score === 0 in any preset
• Warning (should fix): Lighthouse finding with 0 < score < 0.9 in any preset; or DOM issues (missing description, heading skips, missing alt)
• Info: Minor or informational items

Requirements

WE-R-1: The report begins with a level-1 heading: # Website Evaluation: {hostname}. Hostname is extracted from the URL (no scheme, no path).

WE-R-2: A generation line follows: _Generated: {ISO date} · Audited: {full URL}_

WE-R-3: Section order (all sections always present, even if empty):

1. Lighthouse Scores (desktop + mobile tables)
2. Core Web Vitals (desktop + mobile tables)
3. Critical Issues
4. Warnings
5. Info
6. Page Structure
7. Screenshots reference
8. Raw Data reference

WE-R-4: Lighthouse score tables have columns: Category | Desktop | Mobile | Desktop Grade | Mobile Grade. Why: Side-by-side makes it easy to spot mobile regressions.

WE-R-5: Core Web Vitals tables have columns: Metric | Desktop | Mobile | Status. Status is the worst of the two presets for that metric (e.g., if desktop is "good" but mobile is "needs-improvement", show "needs-improvement").

WE-R-6: Each finding is rendered as a Markdown checkbox list item:

- [ ] **{title}** — {pre-interpreted explanation with fix guidance}

The title comes from audit.title. The explanation is built from audit.description (stripped of Markdown links) plus any savings estimate.

WE-R-7: If the same audit ID appears as a finding in both desktop and mobile results, it appears once in the report (not duplicated). The severity is the worst across both presets.

WE-R-8: DOM issues (missing meta description, heading skips, missing alt text, missing noopener) are included in the Warnings section with pre-interpreted phrasing. Exact phrasing:

• Missing meta description: "Meta description missing — search engines will auto-generate one, often poorly. Add a 155-char summary."
• Heading skip: "Heading hierarchy skips {skip} — this confuses screen readers and weakens document structure."
• Missing alt: "{n} image(s) lack alt text — WCAG 1.1.1 violation (Level A); screen readers will skip them entirely."
• Missing noopener: "{n} link(s) open in a new tab without rel=\"noopener\" — the opened page can access window.opener."

WE-R-9: Page Structure section lists:

• Title (value + char count + assessment: "good" if 30–65 chars, "too short" / "too long" otherwise)
• Meta description (value or "missing")
• Canonical (value or "not set")
• Heading counts per level (e.g., "H1×1, H2×4, H3×7")
• Images (total, missing alt count)
• Links (total, external, new-tab-no-opener count)
• Structured data (types detected or "none")
• Open Graph (present/absent)

WE-R-10: Screenshots section contains Markdown image references:

![Desktop view](screenshots/desktop.png)
![Mobile view](screenshots/mobile.png)

WE-R-11: If all Critical, Warning, and Info sections are empty, replace each with _None detected._.

WE-R-12: The function signature is:

assembleReport(url, lighthouseResults, domData) → string

It is a pure function — no file I/O, no side effects.

Scenarios

Scenario: Score table format

Given: Desktop performance 87, mobile performance 62 When: Report is assembled Then: Score table shows desktop 87 (B), mobile 62 (C) in the same row

Scenario: Finding deduplication

Given: meta-description audit fails (score 0) in both desktop and mobile results When: Report is assembled Then: The meta-description finding appears exactly once in Critical Issues

Scenario: Empty sections

Given: All Lighthouse audits pass (score ≥ 0.9), no DOM issues When: Report is assembled Then: Critical Issues, Warnings, and Info sections each contain _None detected._

Scenario: Title assessment

Given: Page title is 14 chars ("Example Domain") When: Page Structure section is built Then: Title line shows "Example Domain" (14 chars — too short)