diff --git a/README.md b/README.md index 81fda7a..41f740f 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,18 @@ formwatch monitor forms.yml formwatch report --html ``` +![formwatch HTML report](docs/images/html-report.png) + +
+More screenshots and diagrams + +![formwatch test in the terminal](docs/images/terminal-test.png) +![formwatch monitor over the demo site](docs/images/terminal-monitor.png) +![Check pipeline](docs/images/diagram-pipeline.svg) + +More in [docs/diagrams.md](docs/diagrams.md). +
+ See [CHANGELOG.md](CHANGELOG.md) for what's shipped so far, and [docs/adr/0001-formwatch-architecture.md](docs/adr/0001-formwatch-architecture.md) for why it's built the way it is. diff --git a/docs/diagrams.md b/docs/diagrams.md new file mode 100644 index 0000000..f5d84e6 --- /dev/null +++ b/docs/diagrams.md @@ -0,0 +1,88 @@ +# formwatch diagrams + +Rendered copies live in [`docs/images/`](images/). Background for these +diagrams: [ADR-0001](adr/0001-formwatch-architecture.md) (architecture) and +[ADR-0002](adr/0002-enterprise-hardening.md) (authorized-use hardening). + +## Check pipeline + +From a form registry to the places results end up. + +![formwatch pipeline](images/diagram-pipeline.svg) + +```mermaid +flowchart LR + subgraph IN["Input"] + URL["formwatch test <url>"] + YML["forms.yml
(one or more, globs ok)"] + CFG["formwatch.yml
options · proxy · limits"] + end + + subgraph RUN["runner (tokio)"] + SHARD["shard + max-concurrent
per-host rate limiter"] + CHROME["headless Chrome
via chromiumoxide (CDP)"] + end + + subgraph CHECKS["checks — one CheckResult each (Pass · Warn · Fail)"] + direction TB + C1["Flow · Submission wizard · required docs ·
validation errors · input persistence"] + C2["Accessibility · axe-core injected ·
zoom · link text · duplicate names"] + C3["Mobile · 375px emulation · tap targets ·
autofill hints · input types · bot wall"] + C8["Custom checks (--checks-dir) ·
LLM wording review, opt-in, PII redacted"] + end + + subgraph STATE[".formwatch/"] + HIST["history/<form>/<ts>.json
diffs · flakiness"] + BASE["baseline.json
accepted findings"] + AUDIT["audit log (JSONL)"] + end + + subgraph OUT["Outputs"] + TERM["terminal table"] + HTML["report --html
with failure screenshots"] + CI["JUnit · SARIF · JSON"] + PROM["serve: /metrics · /api/forms"] + HOOK["webhook
Slack / generic JSON"] + GHA["GitHub Action
code scanning · PR gate"] + end + + URL --> SHARD + YML --> SHARD + CFG --> SHARD + SHARD --> CHROME --> CHECKS + CHECKS --> HIST + BASE -. "only new or worse findings fail" .-> CHECKS + CHECKS --> AUDIT + CHECKS --> TERM + HIST --> HTML + HIST --> CI + HIST --> PROM + HIST -- "regression vs previous run" --> HOOK + CI --> GHA +``` + +## One `formwatch test` run + +```mermaid +sequenceDiagram + autonumber + actor U as User / CI + participant F as formwatch + participant C as Chrome (CDP) + participant S as Target form + participant H as .formwatch/history + + U->>F: formwatch test https://city.gov/apply + F->>F: load config · check authorized-use flags + F->>C: launch headless (cached build or fetch) + C->>S: navigate + loop each check category + F->>C: evaluate JS / emulate device / dispatch input + C-->>F: DOM facts, axe-core violations + F->>F: CheckResult (Pass · Warn · Fail) + screenshot on non-Pass + end + Note over F,S: Real POST only with --submit --accept-terms + F->>H: write run JSON + F->>H: read previous run → diff / flaky + F-->>U: table · exit code (--fail-on fail|warn) +``` diff --git a/docs/images/diagram-pipeline.png b/docs/images/diagram-pipeline.png new file mode 100644 index 0000000..6c3c440 Binary files /dev/null and b/docs/images/diagram-pipeline.png differ diff --git a/docs/images/diagram-pipeline.svg b/docs/images/diagram-pipeline.svg new file mode 100644 index 0000000..c9bdde3 --- /dev/null +++ b/docs/images/diagram-pipeline.svg @@ -0,0 +1,99 @@ +

Outputs

.formwatch/

checks — one CheckResult each (Pass · Warn · Fail)

runner (tokio)

Input

only new or worse findings fail

regression vs previous run

formwatch test <url>

forms.yml
(one or more, globs ok)

formwatch.yml
options · proxy · limits

shard + max-concurrent
per-host rate limiter

headless Chrome
via chromiumoxide (CDP)

Flow · Submission wizard · required docs ·
validation errors · input persistence

Accessibility · axe-core injected ·
zoom · link text · duplicate names

Mobile · 375px emulation · tap targets ·
autofill hints · input types · bot wall

Custom checks (--checks-dir) ·
LLM wording review, opt-in, PII redacted

history/<form>/<ts>.json
diffs · flakiness

baseline.json
accepted findings

audit log (JSONL)

terminal table

report --html
with failure screenshots

JUnit · SARIF · JSON

serve: /metrics · /api/forms

webhook
Slack / generic JSON

GitHub Action
code scanning · PR gate

 \ No newline at end of file diff --git a/docs/images/diagram-test-sequence.png b/docs/images/diagram-test-sequence.png new file mode 100644 index 0000000..a4c15e9 Binary files /dev/null and b/docs/images/diagram-test-sequence.png differ diff --git a/docs/images/diagram-test-sequence.svg b/docs/images/diagram-test-sequence.svg new file mode 100644 index 0000000..263905d --- /dev/null +++ b/docs/images/diagram-test-sequence.svg @@ -0,0 +1,99 @@ +.formwatch/historyTarget formChrome (CDP)formwatch.formwatch/historyTarget formChrome (CDP)formwatchloop[each check category]Real POST only with --submit --accept-termsUser / CIformwatch test https://city.gov/apply1load config · check authorized-use flags2launch headless (cached build or fetch)3navigate4evaluate JS / emulate device / dispatch input5DOM facts, axe-core violations6CheckResult (Pass · Warn · Fail) + screenshot on non-Pass7write run JSON8read previous run → diff / flaky9table · exit code (--fail-on fail|warn)10User / CI \ No newline at end of file diff --git a/docs/images/html-report.png b/docs/images/html-report.png new file mode 100644 index 0000000..e1dd027 Binary files /dev/null and b/docs/images/html-report.png differ diff --git a/docs/images/terminal-monitor.png b/docs/images/terminal-monitor.png new file mode 100644 index 0000000..3495d9c Binary files /dev/null and b/docs/images/terminal-monitor.png differ diff --git a/docs/images/terminal-test.png b/docs/images/terminal-test.png new file mode 100644 index 0000000..0ce4046 Binary files /dev/null and b/docs/images/terminal-test.png differ