@vijaypjavvadi/bdd2pw 4.0.1 → 4.0.2

package/CHANGELOG.md

@@ -9,6 +9,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 _Nothing yet._
 
+## [4.0.2] — 2026-07-24
+
+### Documentation-only patch — README refresh to match the actual v4.0.x feature set
+
+The npm storefront (`https://www.npmjs.com/package/@vijaypjavvadi/bdd2pw`)
+was still describing bdd2pw "as of v3.8.1" three major/minor versions
+later. Anyone landing on the page was reading a description that omitted
+data-driven scaffolds, the three v4.0.1 hallucination-rejection gates,
+the OpenAI + Gemini providers, and the 8-app reproducible benchmark
+harness. That's a versioning-hygiene issue — the code shipped, the
+storefront didn't catch up.
+
+### Changed
+
+- **README** — "What `bdd2pw` is and isn't (as of v3.8.1)" → "(as of v4.0.2)".
+- **README** — LLM fallback bullet rewritten to name all three providers
+  by name (Anthropic Claude Sonnet 4.6, OpenAI gpt-4o-mini, Google
+  Gemini 2.5 Flash) and describe the fail-closed governance semantics
+  explicitly.
+- **README** — New bullet documenting the three v4.0.1 hallucination
+  rejection gates (invented-helper, structured pomCall, bare field call)
+  and the 19 unit tests locking behaviour.
+- **README** — New bullet documenting v4.0.0 data-driven scaffolds
+  (`--data`, `--gen-data`, `--schema`, `--seed`).
+- **README** — New bullet documenting the 8-app reproducible benchmark
+  harness (`bench/runner.ts`) that accompanies the SoftwareX manuscript.
+- **README** — "Validated end-to-end against real public sites" list
+  expanded from 2 apps to the full 8-app benchmark set.
+
+### No code changes
+
+Patch release. No changes under `src/`, `dist/`, `templates/`, `bin`, or
+public API. `npm i @vijaypjavvadi/bdd2pw@4.0.2` is byte-identical to
+`@4.0.1` at runtime — only `README.md`, `CHANGELOG.md`, and `package.json`
+version differ.
+
+### Why patch and not minor
+
+SemVer patch is correct here: no new user-facing capability, no bug fix
+in shipped code, only documentation. Bumping to 4.1 would falsely signal
+new features to CI systems that pin ranges like `^4.0.0`.
+
 ## [4.0.1] — 2026-06-29
 
 ### Fixed — LLM hallucinated POM methods land as TODO instead of broken code

package/README.md

@@ -25,20 +25,23 @@ Most teams writing BDD test cases (via Cucumber `.feature` files, possibly autho
 
 Point it at a `.feature` file and a URL. It parses the Gherkin, scans the live page with Chromium, picks the most stable locator for every interactive element, matches each step to a POM method call, and emits a runnable Playwright TypeScript repo — including `playwright.config.ts`, `pages/login.page.ts`, `tests/login.spec.ts`, and a `BDD_REVIEW.md` listing anything a human still needs to look at.
 
-## What `bdd2pw` is and isn't (as of v3.8.1)
+## What `bdd2pw` is and isn't (as of v4.0.2)
 
-`bdd2pw` is a **deterministic scaffolder with an optional governed LLM fallback**. The output is honest about its limits:
+`bdd2pw` is a **deterministic scaffolder with an optional governed LLM fallback across three providers**. The output is honest about its limits:
 
-- **Specific `.feature` files** — quoted credentials, concrete assertion targets, standard verb forms — convert to **runnable specs with zero hand-edits**. Validated end-to-end against real public sites (`practicetestautomation.com`, `owasp-juice-shop`): every scenario green.
-- **Vague `.feature` files** — "Enter valid username and password and click login button" with no quoted values — get partial coverage. Unmatched steps either route to the LLM fallback (when an Anthropic / OpenAI key is configured) or land as `// TODO` comments + warnings in `BDD_REVIEW.md`.
+- **Specific `.feature` files** — quoted credentials, concrete assertion targets, standard verb forms — convert to **runnable specs with zero hand-edits**. Validated end-to-end against 8 public benchmark applications (`practicetestautomation.com`, `owasp-juice-shop`, SauceDemo, the-internet, OpenCart, Magento, Conduit, Reqres): 8/8 compilation across deterministic and LLM-governed modes.
+- **Vague `.feature` files** — "Enter valid username and password and click login button" with no quoted values — get partial coverage. Unmatched steps either route to the LLM fallback (when an Anthropic / OpenAI / Gemini key is configured) or land as `// TODO` comments + warnings in `BDD_REVIEW.md`.
 - **200+ deterministic rules**, organised across three layers:
   - **API rules** (v3.0+) — `page.request.*` patterns for GET / POST / PUT / DELETE / PATCH, body / header / status assertions.
   - **Visibility rules** (v3.1+) — `<noun> is visible / displayed / shown / appears` intercepts before URL-slug heuristics, so prose like "the user's name or profile indicator is visible in the UI" never gets slugified into a URL regex.
   - **UI + URL rules** (v1.x lineage, refined through v3.7.1) — 30+ rules covering first-person, third-person, no-subject Cucumber dialects + compound input steps.
 - **7 opt-in domain rule packs** (v3.4 + v3.8) — banking, healthcare, insurance, retail, gov, education, telecom. Each adds ~20 industry-specific patterns. Activated via `domains: ["banking"]`; empty by default for byte-stable existing behaviour.
-- **LLM fallback is batched per scenario** (v3.5) — one Anthropic / OpenAI / Gemini call per scenario instead of one per unmatched step. ~75% cost reduction on unmatched-heavy scaffolds. Every prompt goes through the `ai-governance` sidecar's `/sanitize` endpoint (fail-closed).
+- **Three-provider LLM fallback, batched per scenario** (v3.5 + v3.11 + v3.12) — one Anthropic Claude Sonnet 4.6, OpenAI gpt-4o-mini, or Google Gemini 2.5 Flash call per scenario instead of one per unmatched step. ~75% cost reduction on unmatched-heavy scaffolds. Every prompt goes through the `ai-governance` sidecar's `/sanitize` endpoint (fail-closed on 4xx/5xx/timeout — the run terminates rather than emit ungoverned code).
+- **Three hallucination-rejection gates on LLM output** (v4.0.1) — invented-helper detection, structured-pomCall guard, and bare-field-call trap. Bindings the LLM emits that would compile-fail land as `// TODO` comments with `BDD_REVIEW.md` entries instead of broken code. Locked by 19 dedicated unit tests.
+- **Data-driven scaffolds** (v4.0.0) — `--data <path>` injects CSV / JSON / XLSX rows into every Scenario Outline's `Examples:` table; `--gen-data --schema <path> --rows N` generates synthetic rows via Faker + optional per-column LLM calls (`llm:auto insurance claim description`); seeded (`--seed 42`) for reproducibility.
 - **`updatePom` is append-only by construction.** Re-scanning a page that already has a Page Object adds new locators only. Hand-edited method bodies, custom helper methods, custom imports are all preserved byte-identical.
 - **`--merge` mode** (v3.2) preserves `// bdd2pw:user-block id="..."` sections across regenerations so iterative locator tuning doesn't lose work.
+- **Reproducible benchmark harness** (v4.0.0) — `bench/runner.ts` scaffolds all 8 benchmark apps in three modes (deterministic-only, LLM-blocked, LLM-governed) with per-app sha256 verification. Public artifact accompanying the SoftwareX manuscript.
 
 > **The pitch.** Run `bdd2pw scaffold` and you get a Playwright TS repo where `npx playwright test` runs against the real site. For specific fixtures, all green. For vague ones, the 60-90% you'd otherwise hand-write is done; you finish the rest — or you let the governed LLM finish them.
 
@@ -394,7 +397,9 @@ Each release is shaped to be self-contained, ship in ~2 weeks, and keep `domains
 
 If you use `@vijaypjavvadi/bdd2pw` in academic work, please cite:
 
-> Javvadi, V. P. (2026). *@vijaypjavvadi/bdd2pw: Live-DOM Page Object Scaffolding from Gherkin Specifications via the Microsoft Playwright MCP* (Version 3.8.1) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.20450278
+> Javvadi, V. P. (2026). *@vijaypjavvadi/bdd2pw: Live-DOM Page Object Scaffolding from Gherkin Specifications via the Microsoft Playwright MCP* (Version 4.0.1) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.21050268
+
+(v4.0.2 is a documentation-only patch on top of the v4.0.1 artifact; cite v4.0.1 for reproducibility.)
 
 A machine-readable [`CITATION.cff`](CITATION.cff) file is included in the repository root.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vijaypjavvadi/bdd2pw",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "description": "Scaffold runnable Playwright TypeScript tests from Gherkin .feature files. Detects existing Page Objects, scans live pages via Microsoft Playwright MCP, emits POMs + specs, ready for execution. CLI + HTTP service. Optional governed LLM fallback (Anthropic / OpenAI / Gemini).",
   "bin": {
     "bdd2pw": "dist/cli.js"