website-evaluator/spec/pipeline.md

Pipeline Spec (WE-P)

Overview

Orchestrates the full evaluation pipeline for a single URL. Accepts a URL, runs screenshot capture, Lighthouse audits, and DOM analysis in sequence, writes all outputs to a configured directory, and exits with a clear success or failure code.

Responsibilities

• Parse and validate input (URL + output directory)
• Execute pipeline stages in order: screenshot → lighthouse → DOM → report
• Write all output files to the configured output directory
• Exit 0 on success, exit 1 on any stage failure (with error to stderr)

Delegates to: screenshot.js, lighthouse.js, dom-analysis.js, report.js

Dependencies

None — this is the root spec. All other specs depend on this one for the I/O contract.

Data Model

Input

CLI: node src/index.js <url>
ENV: TARGET_URL=<url>         (fallback if no CLI arg)
ENV: OUTPUT_DIR=/output       (default: /output)

Output directory layout

$OUTPUT_DIR/
  report.md                  ← primary artifact
  screenshots/
    desktop.png
    mobile.png
  raw/
    lighthouse-desktop.json
    lighthouse-mobile.json
    dom.json

Requirements

WE-P-1: The URL must be provided as the first CLI argument or via TARGET_URL. If neither is present, print usage to stderr and exit 1.

WE-P-2: The URL must start with http:// or https://. If it does not, print an error and exit 1. Why: Lighthouse and Playwright both require a valid HTTP URL. Silent failures with invalid URLs are confusing.

WE-P-3: The output directory (default /output) and its subdirectories (screenshots/, raw/) must be created if they do not exist. Why: The Docker volume mount only creates the parent; subdirs must be explicit.

WE-P-4: Pipeline stages run sequentially in this order:

1. Screenshots + DOM extraction (single Playwright browser session)
2. Lighthouse desktop audit
3. Lighthouse mobile audit
4. Report assembly Why: Lighthouse requires its own Chrome instance. Running screenshots and DOM extraction first in a single Playwright session is more efficient than two sessions.

WE-P-5: Each pipeline stage logs a single progress line to stdout before starting (e.g., "Capturing screenshots...").

WE-P-6: If any stage throws, the error message is printed to stderr and the process exits 1. Partial output files are acceptable — the caller should check exit code, not file presence.

WE-P-7: On success, print the path to report.md and exit 0.

Scenarios

Scenario: Happy path

Given: Valid URL https://example.com and writable /output When: Pipeline completes all stages Then: Exit 0; report.md, screenshots/desktop.png, screenshots/mobile.png, raw/lighthouse-desktop.json, raw/lighthouse-mobile.json, raw/dom.json all exist

Scenario: Missing URL

Given: No CLI arg and TARGET_URL not set When: index.js starts Then: Prints usage to stderr, exits 1

Scenario: Invalid URL scheme

Given: URL file:///etc/passwd When: Validation runs Then: Prints error "URL must start with http:// or https://", exits 1