# violation-watch-feed (vwf)

Surfaces **Clean Water Act permit violations upstream of a given river point**
as an **Atom feed** and a **live map**. Data: USGS NLDI (river network) +
EPA ECHO (facilities, Detailed Facility Reports).

Built for [owockibot.xyz](https://owockibot.xyz) bounty **#479** by ARION
(autonomous agent, human-supervised).

## Usage

```bash
node vwf.js --lat 39.7392 --lng -104.9903 --out ./out
```

No dependencies — Node >= 18 with global `fetch`.

| flag | default | meaning |
|---|---|---|
| `--lat`, `--lng` | (required) | query point on/near a river |
| `--distance-km` | 25 | upstream main-stem walk length |
| `--corridor-km` | 3 | max off-path distance for a facility to count as "upstream" |
| `--sample-km` | 5 | spacing of ECHO radius queries along the path |
| `--radius-km` | 4 | radius of each ECHO facility query |
| `--max-dfr` | 40 | cap on per-facility detail lookups |
| `--out` | — | directory for `violations.json`, `feed.atom`, `map.html` |

## How it works

1. **Snap** the point to the nearest NHDPlus flowline (`/comid/position`).
2. **Walk upstream** main-stem (`/navigation/UM/flowlines`) to `distance-km`,
   building an ordered km-axis along the reach.
3. **Harvest candidates**: ECHO `get_facilities` radius queries are placed
   every `sample-km` along the path; each returns a `QueryID` whose full
   result is pulled via `get_download` CSV (includes `FacLat`/`FacLong`).
4. **Corridor filter**: each facility is projected onto the path; only those
   within `corridor-km` are kept, sorted by upstream distance.
5. **Violation status**: for each candidate (up to `max-dfr`), the ECHO
   Detailed Facility Report (`get_dfr`) yields `CurrentSNC` and `QtrsInNC`
   from `ComplianceSummary.Source` (statute CWA) plus formal-action counts.
   Facilities sharing a `RegistryID` are deduplicated (same site can hold
   several permits).
6. **Emit**:
   - `feed.atom` — one `<entry>` per violator (SNC or ≥1 quarter in
     noncompliance), linked to its ECHO DFR page.
   - `map.html` — Leaflet map: query marker, dashed corridor polyline,
     red = SNC, orange = quarters-in-NC, gray = checked-and-clean.
   - `violations.json` — the same data machine-readable.

## Example

`examples/south-platte/` was generated from the South Platte River through
downtown Denver (`39.7392,-104.9903`, 20 km upstream, 3 km corridor): 1,239
facilities inside the corridor, first 30 checked, 2 violators surfaced
(a 12-quarter noncompliant site and a 5-quarter site).

## Notes & limits

- `max-dfr` bounds ECHO detail calls; dense urban corridors can contain
  thousands of permits. Facilities are checked nearest-first.
- "Upstream" is main-stem (`UM` navigation), not all tributaries (`UT`).
- ECHO compliance values reflect the service's `CurrentAsOf` date.