5.0 KiB
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 === 0in any preset - Warning (should fix): Lighthouse finding with
0 < score < 0.9in 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):
- Lighthouse Scores (desktop + mobile tables)
- Core Web Vitals (desktop + mobile tables)
- Critical Issues
- Warnings
- Info
- Page Structure
- Screenshots reference
- 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 accesswindow.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:
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)