# 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