@decocms/parity 0.8.0 → 0.9.0

package/AGENTS.md

@@ -29,6 +29,16 @@ Do **not** run parity for:
 | "is the new site missing cache?"             | `parity cache --cand ... --pages 30`                               |
 | "I want an LLM prompt with all the issues"   | `parity prompt <runId>` (writes Markdown to stdout)                |
 | "explain this specific issue"                | `parity explain <runId> <issueId>` (needs `ANTHROPIC_API_KEY`)     |
+| "does THIS single site actually work?"       | `parity e2e --url ... --flows ...` (no comparison — pre-launch / partner audit) |
+| "exercise search / cart / login on a site"   | `parity e2e --url ... --flows=search,cart-interactions,login`      |
+
+### `parity run` vs `parity e2e` — decision tree
+
+- Have two URLs (prod source-of-truth + candidate)? → `parity run` (regression detection)
+- Have ONE URL and want to validate it works end-to-end? → `parity e2e` (functional validation)
+- Have ONE URL and only need absolute checks (vitals/console/SEO)? → `parity audit` (lighter, no flows)
+
+`parity e2e` reuses the same flows + checks as `parity run`, just in single-site mode (checks adapt with absolute criteria when one side is empty).
 
 ## Reading the JSON output
 
@@ -41,8 +51,11 @@ Do **not** run parity for:
   issues: Issue[],          // all raw issues from every check
   checks: CheckResult[],    // one per check; .data has structured details
   visualDiff: {
-    pagesChecked, pagesWithDiffs, pagesPassed,
-    results: VisualDiffPage[]   // per page: prod/cand screenshots, sections, LLM diffs
+    pagesChecked, pagesWithDiffs, pagesPassed, pagesFailed,
+    parityOk: boolean,         // ⭐ binary signal — see below
+    pagesFromCache: number,    // how many verdicts came from cross-run cache
+    llmCallsUsed: number,
+    results: VisualDiffPage[]  // per page: prod/cand screenshots, sections, LLM diffs, cachedAt?
   },
   flowCaptures: FlowCapture[]   // per-flow page captures with vitals + network
 }
@@ -52,11 +65,22 @@ To programmatically decide if a migration is ready:
 
 ```ts
 const run = JSON.parse(fs.readFileSync(`${runDir}/report.json`));
+
+// Binary signal — most agent loops want this.
+if (run.visualDiff?.parityOk === false) {
+  // at least one page is rendering wrong; surface to user
+  const broken = run.visualDiff.results.filter(p => p.verdict !== "pass");
+  // each entry has pageKey, viewport, pctDiff, differences, sectionsOnlyInProd
+}
+
+// Issue-level gating (independent of visual parity)
 if (run.verdict.critical === 0 && run.verdict.high === 0) {
   // ship it
 }
 ```
 
+`visualDiff.parityOk` is `true` iff every page in `results` has `verdict === "pass"`. The check itself accounts for the budget-cap edge case: pages where the LLM was skipped AND pctDiff was meaningfully high are surfaced as `"diffs"` rather than silently falling through to `"pass"`. Trust this flag for "is parity OK?" automation.
+
 ## Driving fixes from the output
 
 The most useful flow for an AI agent is:
@@ -82,11 +106,36 @@ The CLI never fails just because the LLM is unavailable. Issues will still be re
 
 ## Cost-conscious usage
 
-A `--preset full` run with visual diff ≈ 6-12 Claude calls × ~$0.01-0.02 each. Cheap, but in tight loops:
+A `--preset full` run with visual diff ≈ 6-24 Claude calls × ~$0.01-0.02 each. Cheap, but in tight loops:
 
 - Use `--preset smoke` first (no LLM, ~30s) to validate the URLs respond
 - Use `--no-visual-diff` if you only care about functional checks
 - Use `parity journey` (no aggregation step) for the tightest CI loop
+- **The cross-run cache** (`parity-output/cache/verdicts.json`) automatically skips the LLM call on pages whose screenshots haven't changed since the last verdict. Re-runs after a partial fix typically only spend LLM calls on the pages that actually changed.
+
+## Picking which pages to verify
+
+Default behavior: `parity run` discovers a representative sample from prod's sitemap (1 home + a few PLPs + a few PDPs, capped by `--visual-pages`).
+
+When you need deterministic coverage (e.g. you know `/account` and `/checkout` are the routes at risk), bypass discovery:
+
+```bash
+# explicit list — useful when an agent loop knows which routes matter
+parity run --prod ... --cand ... --pages "/,/account,/p/known-product,/categoria/calcas"
+
+# read paths from a file (one per line; # for comments)
+parity run --prod ... --cand ... --pages-file ./targets.txt
+```
+
+These flags override sitemap sampling entirely. Every listed path gets captured + compared, no cap from `--visual-pages`.
+
+## Cache flags
+
+- Default: cache is **on**. Persists at `<output>/cache/verdicts.json` between runs.
+- `--no-cache` — ignore existing cache entries; force fresh LLM judgment on every page.
+- `--clear-cache` — wipe the cache file before the run starts (use after a prompt change or when verdicts feel stale).
+
+The cache key is `sha256(prod_screenshot_bytes + cand_screenshot_bytes + LLM_PROMPT_VERSION)`. Any byte change in either screenshot invalidates the entry naturally. The `LLM_PROMPT_VERSION` constant (in `src/llm/visual-semantic-diff.ts`) bumps the entire cache atomically when the prompt or tool schema changes — no need to wipe by hand.
 
 Hard caps already in place:
 

package/CHANGELOG.md

@@ -5,7 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
-## [0.5.1](https://github.com/decocms/parity/compare/v0.5.0...v0.5.1) (2026-05-27)
+## [0.9.0](https://github.com/decocms/parity/compare/v0.8.1...v0.9.0) (2026-05-29)
+
+### Added
+
+* **e2e command:** new `parity e2e --url=<URL>` for single-site functional validation. Runs all functional flows (homepage, plp, pdp, purchase-journey, search, cart-interactions, optionally login) plus all checks in single-site mode. Use for pre-launch / partner-site verification when there's no prod baseline to compare against.
+* **search flow:** new `flowSearch` (6 steps: visit-home → open-search → type-and-autocomplete → submit-results → search-no-results → search-empty-state). Resolves the search term inteligentemente via cascade (rc.search.terms → cache → LLM suggest → PT-BR fallbacks). Generates a deterministic unicode `no-results` term per run to exercise the empty-state UI without false matches.
+* **cart-interactions flow:** new `flowCartInteractions` (7 steps: seed-cart → read-baseline → increment-qty → decrement-qty → apply-invalid-coupon → remove-item → verify-empty-state). Seeds via PJ-style navigation (home → PLP → PDP → add → minicart) then exercises each cart interaction with before/after qty+price validation.
+* **login flow:** new `flowLogin` (5 steps, gated by `rc.login.enabled` + `PARITY_LOGIN_EMAIL` / `PARITY_LOGIN_PASSWORD` env vars). Validates invalid-credential error + valid-credential redirect + account area access. Credentials never read from `.parityrc.json` (env vars only).
+* **10 new checks:** `search-presence`, `search-autocomplete`, `search-results`, `search-no-results`, `cart-interactions-flow`, `not-found-parity`, `cookie-cep-modal-cls`, `pdp-gallery-related`, `footer-links-health`, `login-flow`. All adapt to comparative (`parity run`) vs single-site (`parity e2e`) mode.
+* **universal `findElement(page, ctx, { key, intent, budget })` helper:** unifies the override → learned → defaults → LLM-recovery cascade behind one call. Replaces ~80 lines of boilerplate across the new flows and is now the recommended pattern for any new selector-driven step.
+* **21 new selector keys:** `searchTrigger`, `searchInput`, `searchSuggestions`, `cartItemRow`, `cartQuantityIncrement`/`Decrement`, `cartRemoveItem`, `cartCouponInput`/`Submit`, `cartTotalPrice`, `pdpGalleryThumbnail`/`Main`, `pdpRelatedShelf`, `loginTrigger`/`EmailInput`/`PasswordInput`/`Submit`/`ErrorMessage`, `accountMenuTrigger`. Defaults cover VTEX/Shopify/Deco patterns; LLM discovery extended to suggest them when missing.
+* **`StepCapture` validations:** `searchValidation` (term/mode/resultCount/suggestionCount/hasEmptyState), `cartItemValidation` (action/before/after/succeeded), `loginValidation` (stage/errorMessage).
+* **`ParityRc` blocks:** `search.terms` / `search.noResultsTerm`, `login.enabled`, `footer.maxLinks` / `followExternal`, `notFound.testUrl`.
+* **preset `full`:** now includes `search,cart-interactions` alongside `purchase-journey`.
+
+### Fixed
+
+* **cache-coverage false positives:** assets with `cache-control: public, max-age=N≥60s` are no longer flagged as "MISS opportunities" just because `fromCache=false` (which is always the case on a cold Playwright session). New `cacheable` decision state recognizes properly-configured cache headers. On Miess this dropped flagged opportunities from 323 → 0 — the assets had 1-year `max-age` headers and weren't actually misconfigured.
+* **http-status-parity in single-site mode:** the check no longer flags every captured page as "missing in prod" when `parity e2e` runs with an empty prod slot by convention. Returns `skipped` when prod is empty and cand has content.
+* **audit-seo noindex exceptions:** `/search`, `/buscapagina` (VTEX legacy), `/s` (VTEX Intelligent Search), `/account`, `/checkout`, `/cart`, `/login`, `/404` and friends no longer trigger `noindex` high-severity issues — those routes SHOULD be noindex by SEO best practice.
+* **search-no-results severity scaling:** unicode term returning 1-10 products is now `medium` "fuzzy fallback" rather than `critical` "matches everything"; only >10 products without empty state remains critical. Matches real VTEX Intelligent Search behavior on stores like Miess.
+* **search empty-state detection:** waits for SPA hydration (`networkidle` + 800ms) before checking; combines `innerText` + captured HTML + proximity heuristic so VTEX Intelligent Search empty states are reliably detected.
+* **cache-coverage wording in single-site mode:** says `"no site"` instead of `"em cand"` when running without a prod baseline.
+* **e2e flow `runId` propagation:** `FlowContext.runId` is now plumbed from `e2e.ts` / `run.ts` so the deterministic no-results unicode term uses the actual run id (was previously taking the literal string `"screenshots"` from `outDir.split("/").pop()`).
 
 ### Fixed
 

package/README.md

@@ -22,6 +22,16 @@ Built originally for Fresh → TanStack Start migrations of Deco storefronts, bu
 | Lazy section presence         | Deco `/deco/render` and `/_loader/*` routes responding                 |
 | SEO deep audit                | robots.txt, sitemap, noindex regressions                               |
 | Cache coverage                | Cache hit rate, opportunities to cache                                 |
+| **Search presence**           | Search input reachable from home in both                               |
+| **Search autocomplete**       | Typing reveals suggestions; cand keeps parity with prod                |
+| **Search results**            | Same keyword returns comparable product counts                         |
+| **Search no-results**         | Unicode garbage term shows empty state, doesn't match products         |
+| **Cart interactions**         | Increment / decrement / coupon / remove all behave in cand             |
+| **404 parity**                | Invalid URL returns 404 (no catch-all 200 in cand)                     |
+| **Cookie/CEP modal CLS**      | Modals don't introduce layout shifts >0.1 in cand                      |
+| **PDP gallery + related**     | Image gallery + "Related products" shelf still render                  |
+| **Footer links health**       | Institutional links (privacy, contact, etc.) aren't broken in cand     |
+| **Login flow** _(opt-in)_     | Valid credentials log in; invalid ones show a clear error              |
 
 All results are aggregated (optionally via Claude) and ranked by severity. Each issue includes screenshots, reproduction, and a suggested fix.
 
@@ -62,6 +72,7 @@ Individual flags always override the preset.
 | ------------------ | ----------------------------------------------------------------------------- |
 | `parity run`       | Full comparison run between two URLs                                          |
 | `parity audit`     | **Single-site** absolute audit (no prod×cand). Console + Vitals + SEO + Imgs  |
+| `parity e2e`       | **Single-site** functional end-to-end: all flows + all checks. ONE URL.       |
 | `parity journey`   | CI-friendly: only the purchase journey, with JUnit / GitHub annotations       |
 | `parity vitals`    | Crawl N pages, compare Web Vitals prod vs cand                                |
 | `parity cache`     | CDN cache analysis, opportunities, request categorization                     |
@@ -128,6 +139,27 @@ If `ANTHROPIC_API_KEY` is set, the LLM is invoked automatically and prints a one
 
 The same flags are available individually on `parity section`: `--heatmap`, `--css-source`, `--prompt`, `--llm-summary`. Use those when you only need one signal; `parity fix` is the "do everything" shortcut.
 
+## `parity e2e` — single-site functional run
+
+The `audit` command runs absolute checks (vitals, console, network, images, SEO) — useful but doesn't exercise interactions. `parity e2e` runs **all the functional flows** (homepage, plp, pdp, purchase-journey, search, cart-interactions, optionally login) against a single URL plus all parity checks in single-site mode.
+
+```bash
+# Quick e2e for a single site (no comparison, ~3-5min)
+parity e2e --url https://www.example.com
+
+# Pick specific flows
+parity e2e --url https://www.example.com --flows=search,cart-interactions
+
+# Override LLM-discovered search term
+parity e2e --url https://www.example.com --search-terms="camisa,promocao"
+
+# With login (credentials via env or flags)
+PARITY_LOGIN_EMAIL=test@example.com PARITY_LOGIN_PASSWORD=*** \
+  parity e2e --url https://www.example.com --flows=login
+```
+
+**Use `parity e2e` when** you want to validate "does this site actually work end-to-end?" — pre-launch, post-deploy, partner sites. **Use `parity run` when** you need to detect *regressions* between two versions (prod vs migration candidate).
+
 ## Configuration (optional)
 
 `.parityrc.json` at the project root — selector overrides and run defaults:
@@ -142,11 +174,26 @@ The same flags are available individually on `parity section`: `--heatmap`, `--c
     "minicartTrigger": "[data-minicart-trigger]",
     "cepInputPdp": "input[name='shipping-zipcode']",
     "cepInputCart": "input[name='cart-zipcode']",
-    "checkoutButton": "a:has-text('Finalizar compra')"
-  }
+    "checkoutButton": "a:has-text('Finalizar compra')",
+    "searchInput": "input[type='search']",
+    "cartCouponInput": "input[name*='coupon']"
+  },
+  "search": {
+    "terms": ["camisa", "promocao"]
+  },
+  "footer": {
+    "maxLinks": 20,
+    "followExternal": false
+  },
+  "notFound": {
+    "testUrl": "/this-page-definitely-does-not-exist"
+  },
+  "login": { "enabled": true }
 }
 ```
 
+> **Credentials are NEVER read from `.parityrc.json`.** Set `PARITY_LOGIN_EMAIL` and `PARITY_LOGIN_PASSWORD` as environment variables (`.parityrc.json` is for non-secret config only).
+
 `.parityignore` — noise suppression:
 
 ```json