@decocms/parity 0.35.13 → 0.35.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -56,7 +56,7 @@ Do **not** fake single-site with `parity run --prod X --cand X` — it runs ever
56
56
  // A FAIL from high findings keeps status "fail" but the score stays the formula — "91 · FAIL" is valid;
57
57
  // read status for the gate, score for progress. It's a progress meter: it RISES as issues get fixed.
58
58
  previousRun?: { id, timestamp, score, scoreDelta }, // trend vs last comparable run (same hosts + scoreVersion)
59
- topIssues: Issue[], // LLM-ranked, deduplicated; usually 5-10 items
59
+ topIssues: Issue[], // one per root cause (issue group), by severity then pages hit; ≤10, real ids + evidence
60
60
  issues: Issue[], // all raw issues from every check
61
61
  checks: CheckResult[], // one per check; .data has structured details
62
62
  visualDiff: {
@@ -102,9 +102,9 @@ The visual module runs on the `parity heatmap` engine — deterministic, no LLM.
102
102
  The most useful flow for an AI agent is:
103
103
 
104
104
  1. Run `parity run --preset full` → wait → read `report.json`
105
- 2. For each `topIssue` with severity ≥ high, open the file(s) referenced in `suggestedFix`
105
+ 2. For each `topIssue` with severity ≥ high, open its `evidence[]` and follow `suggestedFix` when the check set one; `parity explain <runId> <issueId>` for an LLM deep-dive on one issue
106
106
  3. For visual diffs: read `visualDiff.results[].findings` (element + property + px) and `.sectionsOnlyInProd` — the latter are Deco sections present in prod's DOM but missing in cand. Most likely cause: not registered in `src/setup.ts → registerSections()`.
107
- 4. For console errors: read `issues[].evidence[]` for HAR paths; the failed request is usually the root cause.
107
+ 4. For console errors: read `issues[].details` and the matching `flowCaptures[].network` rows; the failed request is usually the root cause. (HARs are not recorded by default — `PARITY_HAR=1` writes `har/<viewport>-<side>.har` for a human to open.)
108
108
  5. Re-run `parity journey` (cheaper) after each fix to confirm.
109
109
 
110
110
  **Important:** prod is the source of truth. Never modify prod-side code to make tests pass — always fix cand.
@@ -113,11 +113,11 @@ The most useful flow for an AI agent is:
113
113
 
114
114
  If neither `ANTHROPIC_API_KEY` nor `OPENROUTER_API_KEY` is set:
115
115
 
116
- - `topIssues` will fall back to deterministic severity-sorted merge (still useful)
116
+ - `topIssues` is unaffected — it is ranked deterministically from the issue groups, never by an LLM
117
117
  - the visual module is unaffected — it never used an LLM (heatmap engine)
118
118
  - Selector discovery is skipped; defaults from `.parityrc.json` or platform heuristics kick in
119
119
 
120
- The CLI never fails just because the LLM is unavailable. Issues will still be reported, just less polished.
120
+ The CLI never fails just because the LLM is unavailable.
121
121
 
122
122
  ## Cost-conscious usage
123
123
 
@@ -125,7 +125,7 @@ The visual module costs no LLM calls. In tight loops:
125
125
 
126
126
  - Use `--preset smoke` first (no LLM, ~30s) to validate the URLs respond
127
127
  - Use `--no-visual-diff` if you only care about functional checks
128
- - Use `parity journey` (no aggregation step) for the tightest CI loop
128
+ - Use `parity journey` (one flow, no visual pass) for the tightest CI loop
129
129
  - Use `parity heatmap` on the one page you just fixed instead of a whole run
130
130
 
131
131
  ## Picking which pages to verify
package/README.md CHANGED
@@ -73,7 +73,7 @@ Three providers, auto-detected in this order — **none required** if you have t
73
73
  2. `OPENROUTER_API_KEY` — OpenRouter
74
74
  3. **Local `claude` CLI** — uses [`@anthropic-ai/claude-agent-sdk`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk); goes through your existing Claude plan. No env vars needed
75
75
 
76
- Force with `--llm <anthropic|openrouter|claude-code|none|auto>`. Override per-feature with `--llm-model visual-diff=claude-opus-5,explain=claude-opus-5`, or flatten everything to one tier with `--llm-tier-default <haiku|sonnet|opus>`. Default tiers: **Sonnet** for selector discovery / recovery / matching / vision / aggregation (the structural-reasoning calls), **Haiku** for short copy-list classification (`search-terms`), **Opus** for `explain`. Cost-conscious? Try `--llm-tier-default haiku` and bump features back to Sonnet selectively if you hit selector misses.
76
+ Force with `--llm <anthropic|openrouter|claude-code|none|auto>`. Override per-feature with `--llm-model visual-diff=claude-opus-5,explain=claude-opus-5`, or flatten everything to one tier with `--llm-tier-default <haiku|sonnet|opus>`. Default tiers: **Sonnet** for selector discovery / recovery / matching / vision (the structural-reasoning calls), **Haiku** for short copy-list classification (`search-terms`), **Opus** for `explain`. Cost-conscious? Try `--llm-tier-default haiku` and bump features back to Sonnet selectively if you hit selector misses.
77
77
 
78
78
  Without any provider, the CLI still runs and outputs raw check results.
79
79
 
@@ -81,11 +81,12 @@ Without any provider, the CLI still runs and outputs raw check results.
81
81
 
82
82
  ```
83
83
  ./parity-output/runs/<runId>/
84
- ├── report.html # links to screenshots/ by relative path — keep the two together
85
84
  ├── report.json # structured output for agents / CI / tooling
85
+ ├── report.html # only with --html/--open, or rendered later by `parity report <runId>`;
86
+ │ # links to screenshots/ by relative path — keep the two together
86
87
  ├── screenshots/ # per-page, per-viewport, per-side; includes pixelmatch heatmaps
87
- ├── har/ # Playwright HARs (one per viewport/side)
88
- └── traces/ # Playwright traces — drag into trace.playwright.dev
88
+ ├── har/ # Playwright HARs, one per viewport/side — only with PARITY_HAR=1
89
+ └── traces/ # Playwright traces (drag into trace.playwright.dev) — only with PARITY_TRACE=1
89
90
  ```
90
91
 
91
92
  ## Presets