@vijaypjavvadi/bdd2pw 1.1.7 → 2.0.0

package/dist/llm/governanceClient.d.ts

@@ -1,24 +1,44 @@
 /**
- * Routes every LLM call through the `ai-governance` sidecar (default :8004).
- * No direct calls to provider SDKs — providers are plugins inside the sidecar.
+ * Wrapper for the ai-governance sidecar's `/sanitize` endpoint.
  *
- * Phase 4 work item.
+ * Per `E:\EB1A_Research\ai-governance\service\app.py`:
+ *
+ *   POST /sanitize
+ *     body: { kind: "code", content: string }
+ *     200:  { kind: "code", sanitised: string, findings: [] }
+ *
+ * v2.0 (this file): we send the LLM PROMPT (the user-message content
+ * built in `prompt.ts`) as kind="code" — `code` re-uses the log-rule
+ * scrubber to redact secrets that might leak via test data in the
+ * .feature file.
+ *
+ * v1.x note: the original Phase 4 stub here imagined a unified
+ * "callViaGovernance" RPC that the sidecar would proxy to providers.
+ * That's NOT the actual sidecar API — the sidecar is a sanitiser, not
+ * an LLM proxy. bdd2pw owns the provider call; the sidecar just scrubs
+ * the payload first.
+ *
+ * Fail-closed: if the sidecar is unreachable or returns a non-2xx, we
+ * REFUSE to call the LLM. Better to degrade to TODO than leak unsanitised
+ * payloads. The caller can pass `skipGovernance: true` for unit tests
+ * (NOT for production).
  */
+export interface SanitiseResult {
+    sanitised: string;
+    findings: Array<Record<string, unknown>>;
+}
+export declare class GovernanceUnreachableError extends Error {
+    constructor(url: string, cause?: unknown);
+}
+/** Legacy alias kept for backwards-compat with any external imports. */
 export declare class GovernanceError extends Error {
     readonly cause?: unknown | undefined;
     constructor(message: string, cause?: unknown | undefined);
 }
-export interface GovernanceCallInput {
-    provider: "anthropic" | "openai" | "gemini";
-    model?: string;
-    prompt: string;
-    context?: Record<string, unknown>;
-    governanceUrl?: string;
-}
-export interface GovernanceCallResult {
-    text: string;
-    redactions: number;
-    provider: string;
-    model: string;
+export declare class GovernanceClient {
+    private baseUrl;
+    constructor(baseUrl: string);
+    sanitiseCode(content: string): Promise<SanitiseResult>;
+    /** Probe `/health` — used at startup to fail-fast before the first scaffold. */
+    health(): Promise<boolean>;
 }
-export declare function callViaGovernance(_input: GovernanceCallInput): Promise<GovernanceCallResult>;

package/dist/llm/governanceClient.js

@@ -1,13 +1,43 @@
 "use strict";
 /**
- * Routes every LLM call through the `ai-governance` sidecar (default :8004).
- * No direct calls to provider SDKs — providers are plugins inside the sidecar.
+ * Wrapper for the ai-governance sidecar's `/sanitize` endpoint.
  *
- * Phase 4 work item.
+ * Per `E:\EB1A_Research\ai-governance\service\app.py`:
+ *
+ *   POST /sanitize
+ *     body: { kind: "code", content: string }
+ *     200:  { kind: "code", sanitised: string, findings: [] }
+ *
+ * v2.0 (this file): we send the LLM PROMPT (the user-message content
+ * built in `prompt.ts`) as kind="code" — `code` re-uses the log-rule
+ * scrubber to redact secrets that might leak via test data in the
+ * .feature file.
+ *
+ * v1.x note: the original Phase 4 stub here imagined a unified
+ * "callViaGovernance" RPC that the sidecar would proxy to providers.
+ * That's NOT the actual sidecar API — the sidecar is a sanitiser, not
+ * an LLM proxy. bdd2pw owns the provider call; the sidecar just scrubs
+ * the payload first.
+ *
+ * Fail-closed: if the sidecar is unreachable or returns a non-2xx, we
+ * REFUSE to call the LLM. Better to degrade to TODO than leak unsanitised
+ * payloads. The caller can pass `skipGovernance: true` for unit tests
+ * (NOT for production).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GovernanceError = void 0;
-exports.callViaGovernance = callViaGovernance;
+exports.GovernanceClient = exports.GovernanceError = exports.GovernanceUnreachableError = void 0;
+const undici_1 = require("undici");
+class GovernanceUnreachableError extends Error {
+    constructor(url, cause) {
+        super(`ai-governance sidecar unreachable at ${url}. Start it with: ` +
+            `'uvicorn service.app:app --port 4900' from the ai-governance repo, ` +
+            `or pass --skip-governance for non-production runs (NOT recommended). ` +
+            (cause instanceof Error ? `Underlying error: ${cause.message}` : ""));
+        this.name = "GovernanceUnreachableError";
+    }
+}
+exports.GovernanceUnreachableError = GovernanceUnreachableError;
+/** Legacy alias kept for backwards-compat with any external imports. */
 class GovernanceError extends Error {
     constructor(message, cause) {
         super(message);
@@ -16,7 +46,43 @@ class GovernanceError extends Error {
     }
 }
 exports.GovernanceError = GovernanceError;
-async function callViaGovernance(_input) {
-    throw new GovernanceError("callViaGovernance() — Phase 4");
+class GovernanceClient {
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+    }
+    async sanitiseCode(content) {
+        const url = `${this.baseUrl}/sanitize`;
+        let res;
+        try {
+            res = await (0, undici_1.request)(url, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ kind: "code", content }),
+            });
+        }
+        catch (err) {
+            throw new GovernanceUnreachableError(url, err);
+        }
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+            const body = await res.body.text().catch(() => "(no body)");
+            throw new Error(`ai-governance /sanitize returned ${res.statusCode}: ${body.slice(0, 200)}`);
+        }
+        const json = (await res.body.json());
+        return {
+            sanitised: json.sanitised ?? content,
+            findings: json.findings ?? [],
+        };
+    }
+    /** Probe `/health` — used at startup to fail-fast before the first scaffold. */
+    async health() {
+        try {
+            const res = await (0, undici_1.request)(`${this.baseUrl}/health`);
+            return res.statusCode === 200;
+        }
+        catch {
+            return false;
+        }
+    }
 }
+exports.GovernanceClient = GovernanceClient;
 //# sourceMappingURL=governanceClient.js.map

package/dist/llm/governanceClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"governanceClient.js","sourceRoot":"","sources":["../../src/llm/governanceClient.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAwBH,8CAIC;AA1BD,MAAa,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAe,EAAkB,KAAe;QAC1D,KAAK,CAAC,OAAO,CAAC,CAAC;QAD4B,UAAK,GAAL,KAAK,CAAU;QAE1D,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AALD,0CAKC;AAiBM,KAAK,UAAU,iBAAiB,CACrC,MAA2B;IAE3B,MAAM,IAAI,eAAe,CAAC,+BAA+B,CAAC,CAAC;AAC7D,CAAC"}
+{"version":3,"file":"governanceClient.js","sourceRoot":"","sources":["../../src/llm/governanceClient.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;;;AAEH,mCAAiC;AAOjC,MAAa,0BAA2B,SAAQ,KAAK;IACnD,YAAY,GAAW,EAAE,KAAe;QACtC,KAAK,CACH,wCAAwC,GAAG,mBAAmB;YAC5D,qEAAqE;YACrE,uEAAuE;YACvE,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,qBAAqB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CACvE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAVD,gEAUC;AAED,wEAAwE;AACxE,MAAa,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAe,EAAkB,KAAe;QAC1D,KAAK,CAAC,OAAO,CAAC,CAAC;QAD4B,UAAK,GAAL,KAAK,CAAU;QAE1D,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AALD,0CAKC;AAED,MAAa,gBAAgB;IAE3B,YAAY,OAAe;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,OAAe;QAChC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,WAAW,CAAC;QACvC,IAAI,GAAG,CAAC;QACR,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,IAAA,gBAAO,EAAC,GAAG,EAAE;gBACvB,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;aAChD,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,0BAA0B,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACjD,CAAC;QACD,IAAI,GAAG,CAAC,UAAU,GAAG,GAAG,IAAI,GAAG,CAAC,UAAU,IAAI,GAAG,EAAE,CAAC;YAClD,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,CAAC;YAC5D,MAAM,IAAI,KAAK,CACb,oCAAoC,GAAG,CAAC,UAAU,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAC5E,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAGlC,CAAC;QACF,OAAO;YACL,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,OAAO;YACpC,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,EAAE;SAC9B,CAAC;IACJ,CAAC;IAED,gFAAgF;IAChF,KAAK,CAAC,MAAM;QACV,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAA,gBAAO,EAAC,GAAG,IAAI,CAAC,OAAO,SAAS,CAAC,CAAC;YACpD,OAAO,GAAG,CAAC,UAAU,KAAK,GAAG,CAAC;QAChC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF;AA3CD,4CA2CC"}

package/dist/llm/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Public API of the LLM module — v2.0.
+ *
+ *   import { createLLMClient, matchStepWithLLM, CandidateRulesWriter }
+ *     from "./llm";
+ *
+ * The bdd2pw orchestrator (src/index.ts) only needs to import these
+ * three names. Everything else is internal.
+ */
+import type { LLMClient, LLMClientOptions } from "./types";
+export { AnthropicLLMClient } from "./anthropicClient";
+export { CandidateRulesWriter } from "./candidateRules";
+export { GovernanceClient, GovernanceUnreachableError } from "./governanceClient";
+export { matchStepWithLLM, matchStepsWithLLM, type MatchStepWithLLMContext, } from "./llmStepMatcher";
+export type { CandidateRuleEntry, GenerateBindingInput, GenerateBindingResult, LLMClient, LLMClientOptions, LLMLogEvent, } from "./types";
+/**
+ * Construct the right LLMClient for the given options. Today the only
+ * provider is "anthropic"; the factory exists so v2.1 (OpenAI/Gemini)
+ * can plug in without touching callers.
+ *
+ * `repoRoot` is used to derive the default cache path:
+ *   `<repoRoot>/.bdd2pw/llm-cache.sqlite`.
+ *
+ * Returns undefined when LLM is disabled (no provider configured) — so
+ * callers can pass the result straight into matchStepWithLLM's `llm`
+ * field without an explicit null-check.
+ */
+export declare function createLLMClient(opts: LLMClientOptions | undefined, repoRoot: string): LLMClient | undefined;

package/dist/llm/index.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * Public API of the LLM module — v2.0.
+ *
+ *   import { createLLMClient, matchStepWithLLM, CandidateRulesWriter }
+ *     from "./llm";
+ *
+ * The bdd2pw orchestrator (src/index.ts) only needs to import these
+ * three names. Everything else is internal.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchStepsWithLLM = exports.matchStepWithLLM = exports.GovernanceUnreachableError = exports.GovernanceClient = exports.CandidateRulesWriter = exports.AnthropicLLMClient = void 0;
+exports.createLLMClient = createLLMClient;
+const path = __importStar(require("path"));
+const anthropicClient_1 = require("./anthropicClient");
+var anthropicClient_2 = require("./anthropicClient");
+Object.defineProperty(exports, "AnthropicLLMClient", { enumerable: true, get: function () { return anthropicClient_2.AnthropicLLMClient; } });
+var candidateRules_1 = require("./candidateRules");
+Object.defineProperty(exports, "CandidateRulesWriter", { enumerable: true, get: function () { return candidateRules_1.CandidateRulesWriter; } });
+var governanceClient_1 = require("./governanceClient");
+Object.defineProperty(exports, "GovernanceClient", { enumerable: true, get: function () { return governanceClient_1.GovernanceClient; } });
+Object.defineProperty(exports, "GovernanceUnreachableError", { enumerable: true, get: function () { return governanceClient_1.GovernanceUnreachableError; } });
+var llmStepMatcher_1 = require("./llmStepMatcher");
+Object.defineProperty(exports, "matchStepWithLLM", { enumerable: true, get: function () { return llmStepMatcher_1.matchStepWithLLM; } });
+Object.defineProperty(exports, "matchStepsWithLLM", { enumerable: true, get: function () { return llmStepMatcher_1.matchStepsWithLLM; } });
+/**
+ * Construct the right LLMClient for the given options. Today the only
+ * provider is "anthropic"; the factory exists so v2.1 (OpenAI/Gemini)
+ * can plug in without touching callers.
+ *
+ * `repoRoot` is used to derive the default cache path:
+ *   `<repoRoot>/.bdd2pw/llm-cache.sqlite`.
+ *
+ * Returns undefined when LLM is disabled (no provider configured) — so
+ * callers can pass the result straight into matchStepWithLLM's `llm`
+ * field without an explicit null-check.
+ */
+function createLLMClient(opts, repoRoot) {
+    if (!opts || !opts.provider)
+        return undefined;
+    const cachePathDefault = path.join(repoRoot, ".bdd2pw", "llm-cache.sqlite");
+    switch (opts.provider) {
+        case "anthropic":
+            return new anthropicClient_1.AnthropicLLMClient(opts, cachePathDefault);
+        default:
+            // v2.1 will add openai / gemini.
+            return undefined;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/llm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCH,0CAiBC;AAlDD,2CAA6B;AAC7B,uDAAuD;AAGvD,qDAAuD;AAA9C,qHAAA,kBAAkB,OAAA;AAC3B,mDAAwD;AAA/C,sHAAA,oBAAoB,OAAA;AAC7B,uDAAkF;AAAzE,oHAAA,gBAAgB,OAAA;AAAE,8HAAA,0BAA0B,OAAA;AACrD,mDAI0B;AAHxB,kHAAA,gBAAgB,OAAA;AAChB,mHAAA,iBAAiB,OAAA;AAYnB;;;;;;;;;;;GAWG;AACH,SAAgB,eAAe,CAC7B,IAAkC,EAClC,QAAgB;IAEhB,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC9C,MAAM,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAChC,QAAQ,EACR,SAAS,EACT,kBAAkB,CACnB,CAAC;IACF,QAAQ,IAAI,CAAC,QAAQ,EAAE,CAAC;QACtB,KAAK,WAAW;YACd,OAAO,IAAI,oCAAkB,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;QACxD;YACE,iCAAiC;YACjC,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC"}

package/dist/llm/llmStepMatcher.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Async overlay over the deterministic stepMatcher — when the rule table
+ * fails to match a step AND an LLM client is provided, fall back to the
+ * LLM. Every successful LLM-generated binding is appended to
+ * `<repo>/artefacts/candidate-rules.jsonl` for offline review.
+ *
+ * Why a wrapper, not modifying matchStep:
+ *   - Keeps the rule-based matcher pure-sync, so unit tests stay fast.
+ *   - LLM fallback is opt-in and orthogonal — easier to reason about
+ *     and to disable in CI where determinism matters.
+ *   - The wrapper is the natural integration point for the candidate-
+ *     rules JSONL writer; the deterministic matcher doesn't need to
+ *     know that pipeline exists.
+ */
+import type { PageObjectIR, StepBinding, StepIR } from "../types";
+import { CandidateRulesWriter } from "./candidateRules";
+import type { LLMClient } from "./types";
+export interface MatchStepWithLLMContext {
+    /** When provided AND the rule matcher returns a warning, ask the LLM. */
+    llm?: LLMClient;
+    /** Where to log every successful LLM binding for offline review. */
+    candidates?: CandidateRulesWriter;
+    /** Stable scaffold-run identifier — written into each candidate row. */
+    scaffoldId: string;
+    /** Target URL — passed to LLM for additional context. */
+    url?: string;
+}
+export declare function matchStepWithLLM(step: StepIR, pom: PageObjectIR, pageVar: string, ctx: MatchStepWithLLMContext): Promise<StepBinding>;
+/**
+ * Convenience: match a list of steps with LLM overlay, sequentially. We
+ * deliberately don't parallelise — the cache means repeated step text
+ * within a feature returns instantly, but parallel calls would all miss
+ * the cache and pay for the same step twice.
+ */
+export declare function matchStepsWithLLM(steps: StepIR[], pom: PageObjectIR, pageVar: string, ctx: MatchStepWithLLMContext): Promise<StepBinding[]>;

package/dist/llm/llmStepMatcher.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Async overlay over the deterministic stepMatcher — when the rule table
+ * fails to match a step AND an LLM client is provided, fall back to the
+ * LLM. Every successful LLM-generated binding is appended to
+ * `<repo>/artefacts/candidate-rules.jsonl` for offline review.
+ *
+ * Why a wrapper, not modifying matchStep:
+ *   - Keeps the rule-based matcher pure-sync, so unit tests stay fast.
+ *   - LLM fallback is opt-in and orthogonal — easier to reason about
+ *     and to disable in CI where determinism matters.
+ *   - The wrapper is the natural integration point for the candidate-
+ *     rules JSONL writer; the deterministic matcher doesn't need to
+ *     know that pipeline exists.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchStepWithLLM = matchStepWithLLM;
+exports.matchStepsWithLLM = matchStepsWithLLM;
+const stepMatcher_1 = require("../transformers/stepMatcher");
+async function matchStepWithLLM(step, pom, pageVar, ctx) {
+    // 1) Always try rule-based first.
+    const ruleBased = (0, stepMatcher_1.matchStep)(step, pom, pageVar);
+    // 2) If the rule matcher produced a real binding (no warning), use it.
+    if (!ruleBased.warning)
+        return ruleBased;
+    // 3) No LLM client → return the warning binding (TODO behaviour).
+    if (!ctx.llm)
+        return ruleBased;
+    // 4) Budget exhausted → return the warning binding (caller already
+    //    notified at startup; this just keeps scaffolding moving).
+    if (ctx.llm.budgetExhausted())
+        return ruleBased;
+    // 5) Try the LLM. Soft-fail back to rule-based on any error.
+    try {
+        const result = await ctx.llm.generateBinding({
+            step,
+            pom,
+            pageVar,
+            url: ctx.url,
+            scaffoldId: ctx.scaffoldId,
+        });
+        if (!result.binding) {
+            // Annotate the warning with the LLM error so BDD_REVIEW shows why
+            // the LLM didn't help. The step still falls through to TODO.
+            return {
+                ...ruleBased,
+                warning: result.error
+                    ? `${ruleBased.warning} (LLM fallback also failed: ${result.error})`
+                    : ruleBased.warning,
+            };
+        }
+        // Append to candidate-rules.jsonl for offline review. Best-effort.
+        if (ctx.candidates) {
+            await ctx.candidates.append({
+                ts: new Date().toISOString(),
+                scaffoldId: ctx.scaffoldId,
+                stepText: step.text,
+                stepKeyword: step.keyword,
+                binding: result.binding,
+                pomSignature: {
+                    className: pom.className,
+                    fieldNames: pom.fields.map((f) => f.fieldName),
+                    methodNames: pom.methods.map((m) => m.name),
+                },
+                provider: "anthropic",
+                model: result.model ?? "(unknown)",
+                fromCache: result.fromCache,
+            });
+        }
+        return result.binding;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ...ruleBased,
+            warning: `${ruleBased.warning} (LLM fallback threw: ${message})`,
+        };
+    }
+}
+/**
+ * Convenience: match a list of steps with LLM overlay, sequentially. We
+ * deliberately don't parallelise — the cache means repeated step text
+ * within a feature returns instantly, but parallel calls would all miss
+ * the cache and pay for the same step twice.
+ */
+async function matchStepsWithLLM(steps, pom, pageVar, ctx) {
+    const out = [];
+    for (const step of steps) {
+        out.push(await matchStepWithLLM(step, pom, pageVar, ctx));
+    }
+    return out;
+}
+//# sourceMappingURL=llmStepMatcher.js.map

package/dist/llm/llmStepMatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llmStepMatcher.js","sourceRoot":"","sources":["../../src/llm/llmStepMatcher.ts"],"names":[],"mappings":"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"}

package/dist/llm/prompt.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Build the Anthropic prompt used to generate a `StepBinding` from an
+ * unmatched Gherkin step.
+ *
+ * Design principles:
+ *
+ *   1. **JSON-only output.** The model is instructed to return ONE JSON
+ *      object matching the StepBinding type — no prose, no Markdown
+ *      fences. We then JSON.parse it; malformed output triggers a soft-fail.
+ *
+ *   2. **Specific not creative.** Show the model the existing rule
+ *      taxonomy (briefly) so it tries to match the same shapes our
+ *      deterministic rules produce. Otherwise the LLM invents novel
+ *      locator chains that drift from the rest of the codebase.
+ *
+ *   3. **POM-aware.** Every prompt includes the current POM's field and
+ *      method names. The LLM should prefer existing fields over
+ *      synthesising raw locators.
+ *
+ *   4. **Temperature 0** (set at call site) — same input → same output,
+ *      paired with caching for true determinism.
+ */
+import type { GenerateBindingInput } from "./types";
+/** System prompt — shared across all generations. */
+export declare const SYSTEM_PROMPT = "You are a deterministic step-binding generator for bdd2pw, a Gherkin \u2192 Playwright TypeScript scaffolder.\n\nbdd2pw normally maps each Gherkin step to one of 30+ deterministic regex rules. When no rule matches, you produce the binding instead.\n\nYour output MUST be a single JSON object matching this TypeScript type:\n\ninterface StepBinding {\n  step: { keyword: \"Given\"|\"When\"|\"Then\"|\"And\"|\"But\"; text: string };\n  pomCall?: { page: string; method: string; args: string[] };  // for actions\n  assertion?: { locator: string; matcher: string; expected?: string };  // for assertions\n  customBody?: string;  // pre-rendered TS for compound steps\n  warning?: string;  // populated only if you genuinely cannot map the step\n}\n\nRules:\n- Output exactly ONE JSON object. No prose, no Markdown, no backticks.\n- Echo the step in the \"step\" field unchanged.\n- Choose ONE of: pomCall, assertion, customBody. Never two.\n- Prefer existing POM fields over synthesizing locators. Only use page.locator(...) / page.getByText(...) / page.getByRole(...) when no POM field matches.\n- For assertions, set \"matcher\" to one of: toBeVisible, toBeHidden, toContainText, toHaveText, toHaveURL, toHaveAttribute, not.toBeVisible, not.toHaveURL.\n- For toContainText/toHaveText, \"expected\" must be a JS-quoted string like \"\\\"X\\\"\".\n- For toHaveURL, \"expected\" should be: new RegExp(\"...\") (a JS expression as a STRING).\n- For toHaveAttribute, \"expected\" should be: \"name\", \"value\" (two args, as a single string).\n- Always end synthesised locators with .first() to avoid Playwright strict-mode violations when text appears in multiple elements.\n- If the step has no quoted value AND no resolvable POM field, set \"warning\" to a clear single-sentence explanation of what's ambiguous and emit no pomCall/assertion. The user will hand-edit the spec.";
+/**
+ * Build the user-side message for one step. Includes:
+ *   - The step keyword + text.
+ *   - The POM IR (className, field names with their locator API+args, methods).
+ *   - The target URL (gives the model context about what page).
+ *   - The pageVar variable name to use in pomCall.page.
+ */
+export declare function buildUserPrompt(input: GenerateBindingInput): string;
+/**
+ * Cache key — stable across runs given identical inputs. Determinism plus
+ * cost control: the same step text + POM signature returns the same binding
+ * forever (until the user explicitly clears the cache or upgrades bdd2pw).
+ */
+export declare function cacheKey(input: GenerateBindingInput, model: string): string;

package/dist/llm/prompt.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * Build the Anthropic prompt used to generate a `StepBinding` from an
+ * unmatched Gherkin step.
+ *
+ * Design principles:
+ *
+ *   1. **JSON-only output.** The model is instructed to return ONE JSON
+ *      object matching the StepBinding type — no prose, no Markdown
+ *      fences. We then JSON.parse it; malformed output triggers a soft-fail.
+ *
+ *   2. **Specific not creative.** Show the model the existing rule
+ *      taxonomy (briefly) so it tries to match the same shapes our
+ *      deterministic rules produce. Otherwise the LLM invents novel
+ *      locator chains that drift from the rest of the codebase.
+ *
+ *   3. **POM-aware.** Every prompt includes the current POM's field and
+ *      method names. The LLM should prefer existing fields over
+ *      synthesising raw locators.
+ *
+ *   4. **Temperature 0** (set at call site) — same input → same output,
+ *      paired with caching for true determinism.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SYSTEM_PROMPT = void 0;
+exports.buildUserPrompt = buildUserPrompt;
+exports.cacheKey = cacheKey;
+/** System prompt — shared across all generations. */
+exports.SYSTEM_PROMPT = `You are a deterministic step-binding generator for bdd2pw, a Gherkin → Playwright TypeScript scaffolder.
+
+bdd2pw normally maps each Gherkin step to one of 30+ deterministic regex rules. When no rule matches, you produce the binding instead.
+
+Your output MUST be a single JSON object matching this TypeScript type:
+
+interface StepBinding {
+  step: { keyword: "Given"|"When"|"Then"|"And"|"But"; text: string };
+  pomCall?: { page: string; method: string; args: string[] };  // for actions
+  assertion?: { locator: string; matcher: string; expected?: string };  // for assertions
+  customBody?: string;  // pre-rendered TS for compound steps
+  warning?: string;  // populated only if you genuinely cannot map the step
+}
+
+Rules:
+- Output exactly ONE JSON object. No prose, no Markdown, no backticks.
+- Echo the step in the "step" field unchanged.
+- Choose ONE of: pomCall, assertion, customBody. Never two.
+- Prefer existing POM fields over synthesizing locators. Only use page.locator(...) / page.getByText(...) / page.getByRole(...) when no POM field matches.
+- For assertions, set "matcher" to one of: toBeVisible, toBeHidden, toContainText, toHaveText, toHaveURL, toHaveAttribute, not.toBeVisible, not.toHaveURL.
+- For toContainText/toHaveText, "expected" must be a JS-quoted string like "\\"X\\"".
+- For toHaveURL, "expected" should be: new RegExp("...") (a JS expression as a STRING).
+- For toHaveAttribute, "expected" should be: "name", "value" (two args, as a single string).
+- Always end synthesised locators with .first() to avoid Playwright strict-mode violations when text appears in multiple elements.
+- If the step has no quoted value AND no resolvable POM field, set "warning" to a clear single-sentence explanation of what's ambiguous and emit no pomCall/assertion. The user will hand-edit the spec.`;
+/**
+ * Build the user-side message for one step. Includes:
+ *   - The step keyword + text.
+ *   - The POM IR (className, field names with their locator API+args, methods).
+ *   - The target URL (gives the model context about what page).
+ *   - The pageVar variable name to use in pomCall.page.
+ */
+function buildUserPrompt(input) {
+    const { step, pom, pageVar, url } = input;
+    const fieldsBlock = pom.fields.length
+        ? pom.fields
+            .map((f) => `  - ${f.fieldName}: ${pageVar}.${f.fieldName} (page.${f.api}(${f.args}))`)
+            .join("\n")
+        : "  (no fields discovered yet)";
+    const methodsBlock = pom.methods.length
+        ? pom.methods
+            .map((m) => `  - ${m.name}(${m.params.map((p) => `${p.name}: ${p.type}`).join(", ")})`)
+            .join("\n")
+        : "  (no methods)";
+    const stepArg = step.argument
+        ? typeof step.argument === "string"
+            ? `\nDoc string:\n${step.argument}`
+            : `\nData table:\n${JSON.stringify(step.argument)}`
+        : "";
+    return `Step that didn't match any rule:
+  ${step.keyword} ${step.text}${stepArg}
+
+POM context:
+  className: ${pom.className}
+  pageVar: ${pageVar}
+  url: ${url ?? "(none)"}
+
+POM fields:
+${fieldsBlock}
+
+POM methods:
+${methodsBlock}
+
+Return the JSON binding now.`;
+}
+/**
+ * Cache key — stable across runs given identical inputs. Determinism plus
+ * cost control: the same step text + POM signature returns the same binding
+ * forever (until the user explicitly clears the cache or upgrades bdd2pw).
+ */
+function cacheKey(input, model) {
+    const fieldNames = input.pom.fields.map((f) => f.fieldName).sort().join(",");
+    const methodNames = input.pom.methods.map((m) => m.name).sort().join(",");
+    // Include the model so a model upgrade invalidates old cache entries.
+    return [
+        "v2",
+        model,
+        input.step.keyword,
+        input.step.text,
+        input.pom.className,
+        fieldNames,
+        methodNames,
+    ].join("|");
+}
+//# sourceMappingURL=prompt.js.map

package/dist/llm/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/llm/prompt.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;AAsCH,0CA0CC;AAOD,4BAaC;AAhGD,qDAAqD;AACxC,QAAA,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;yMAwB4K,CAAC;AAE1M;;;;;;GAMG;AACH,SAAgB,eAAe,CAAC,KAA2B;IACzD,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC;IAE1C,MAAM,WAAW,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM;QACnC,CAAC,CAAC,GAAG,CAAC,MAAM;aACP,GAAG,CACF,CAAC,CAAC,EAAE,EAAE,CACJ,OAAO,CAAC,CAAC,SAAS,KAAK,OAAO,IAAI,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,IAAI,CAC7E;aACA,IAAI,CAAC,IAAI,CAAC;QACf,CAAC,CAAC,8BAA8B,CAAC;IAEnC,MAAM,YAAY,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM;QACrC,CAAC,CAAC,GAAG,CAAC,OAAO;aACR,GAAG,CACF,CAAC,CAAC,EAAE,EAAE,CACJ,OAAO,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC7E;aACA,IAAI,CAAC,IAAI,CAAC;QACf,CAAC,CAAC,gBAAgB,CAAC;IAErB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ;QAC3B,CAAC,CAAC,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ;YACjC,CAAC,CAAC,kBAAkB,IAAI,CAAC,QAAQ,EAAE;YACnC,CAAC,CAAC,kBAAkB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE;QACrD,CAAC,CAAC,EAAE,CAAC;IAEP,OAAO;IACL,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,GAAG,OAAO;;;eAGxB,GAAG,CAAC,SAAS;aACf,OAAO;SACX,GAAG,IAAI,QAAQ;;;EAGtB,WAAW;;;EAGX,YAAY;;6BAEe,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AACH,SAAgB,QAAQ,CAAC,KAA2B,EAAE,KAAa;IACjE,MAAM,UAAU,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7E,MAAM,WAAW,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1E,sEAAsE;IACtE,OAAO;QACL,IAAI;QACJ,KAAK;QACL,KAAK,CAAC,IAAI,CAAC,OAAO;QAClB,KAAK,CAAC,IAAI,CAAC,IAAI;QACf,KAAK,CAAC,GAAG,CAAC,SAAS;QACnB,UAAU;QACV,WAAW;KACZ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC"}