@vijaypjavvadi/bdd2pw 1.1.7 → 2.0.0

package/dist/llm/types.d.ts

@@ -0,0 +1,143 @@
+/**
+ * LLM fallback types — v2.0.
+ *
+ * The LLM is invoked ONLY when bdd2pw's deterministic rule table
+ * (`src/transformers/stepMatcher.ts`) fails to match a step. The LLM's
+ * job is to produce a single `StepBinding` matching the existing IR
+ * shape. This is identical to what a hand-written rule would produce, so
+ * downstream emitters don't need to know an LLM was involved.
+ *
+ * Every LLM-generated binding is also appended to
+ * `<repo>/artefacts/candidate-rules.jsonl` so a separate offline pipeline
+ * can review and propose new deterministic rules. Auto-writing rules
+ * back into `stepMatcher.ts` is deferred to v2.1+ (see docs/SCOPE.md).
+ */
+import type { PageObjectIR, StepIR, StepBinding } from "../types";
+export interface LLMClientOptions {
+    /** Provider identifier — "anthropic" in v2.0; OpenAI/Gemini in v2.1+. */
+    provider: "anthropic";
+    /** Anthropic model. Default: claude-sonnet-4-6. */
+    model?: string;
+    /** API key. Resolved from env var (ANTHROPIC_API_KEY) when omitted. */
+    apiKey?: string;
+    /**
+     * ai-governance sidecar base URL — default http://localhost:4900.
+     * EVERY prompt is POSTed to `${governanceUrl}/sanitize` before being
+     * sent to the provider. If the sidecar is unreachable, generation fails
+     * (fail-closed) — we don't leak unsanitised payloads.
+     */
+    governanceUrl?: string;
+    /** Max LLM calls per scaffold(). Default 50. */
+    maxCalls?: number;
+    /** Cache database path. Default <repo>/.bdd2pw/llm-cache.sqlite. */
+    cachePath?: string;
+    /**
+     * Disable governance sanitisation. NOT for production — only useful in
+     * unit tests where the sidecar isn't running and the test prompts
+     * contain no real user data.
+     */
+    skipGovernance?: boolean;
+    /**
+     * Optional logger callback (defaults to no-op). Useful in tests to
+     * capture prompts/responses without polluting stdout.
+     */
+    log?: (event: LLMLogEvent) => void;
+}
+export type LLMLogEvent = {
+    kind: "cache_hit";
+    key: string;
+} | {
+    kind: "cache_miss";
+    key: string;
+} | {
+    kind: "sanitise_start";
+    bytes: number;
+} | {
+    kind: "sanitise_done";
+    bytes: number;
+    findings: number;
+} | {
+    kind: "provider_call_start";
+    model: string;
+    promptBytes: number;
+} | {
+    kind: "provider_call_done";
+    model: string;
+    latencyMs: number;
+    inputTokens: number;
+    outputTokens: number;
+} | {
+    kind: "binding_parsed";
+    binding: StepBinding;
+} | {
+    kind: "error";
+    phase: string;
+    message: string;
+};
+/** Input to the step-binding generator. */
+export interface GenerateBindingInput {
+    /** The Gherkin step that didn't match any rule. */
+    step: StepIR;
+    /** The current Page Object — fields, methods, class name. */
+    pom: PageObjectIR;
+    /** camelCase variable name used in the spec (e.g. `loginPage`). */
+    pageVar: string;
+    /** URL the scaffold targets — gives the LLM additional context. */
+    url?: string;
+    /** Stable scaffold-run identifier. Logged into candidate-rules.jsonl. */
+    scaffoldId: string;
+}
+/** Result of an LLM-generation attempt. */
+export interface GenerateBindingResult {
+    /** When generation succeeds. */
+    binding?: StepBinding;
+    /** When generation fails — soft-fail, caller falls back to TODO warning. */
+    error?: string;
+    /** True if the binding came from cache (no provider call made). */
+    fromCache: boolean;
+    /** Provider model name (for audit). */
+    model?: string;
+    /** Total latency including governance + provider + parsing, ms. */
+    latencyMs?: number;
+}
+/**
+ * Pluggable LLM client. v2.0 ships AnthropicLLMClient (provider=anthropic)
+ * and MockLLMClient (for tests). v2.1 adds OpenAI/Gemini.
+ */
+export interface LLMClient {
+    /** Generate a StepBinding for an unmatched step. */
+    generateBinding(input: GenerateBindingInput): Promise<GenerateBindingResult>;
+    /** Have we hit the max-calls budget for this scaffold? */
+    budgetExhausted(): boolean;
+    /** Calls made so far. */
+    callsMade(): number;
+    /** Close any underlying resources (cache db handle, etc.). */
+    close?(): Promise<void>;
+}
+/**
+ * Single line written to artefacts/candidate-rules.jsonl. The offline
+ * review pipeline ingests these to propose new deterministic rules.
+ */
+export interface CandidateRuleEntry {
+    /** ISO-8601 timestamp of when the LLM produced this binding. */
+    ts: string;
+    /** Stable scaffold-run identifier. */
+    scaffoldId: string;
+    /** Original Gherkin step text — input to any future regex. */
+    stepText: string;
+    /** Step keyword (Given/When/Then/And/But) — for context. */
+    stepKeyword: string;
+    /** The binding the LLM produced. */
+    binding: StepBinding;
+    /** POM signature — class name + field names + method names. */
+    pomSignature: {
+        className: string;
+        fieldNames: string[];
+        methodNames: string[];
+    };
+    /** LLM provider + model. */
+    provider: string;
+    model: string;
+    /** Whether this binding came from cache (LLM not actually called). */
+    fromCache: boolean;
+}

package/dist/llm/types.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * LLM fallback types — v2.0.
+ *
+ * The LLM is invoked ONLY when bdd2pw's deterministic rule table
+ * (`src/transformers/stepMatcher.ts`) fails to match a step. The LLM's
+ * job is to produce a single `StepBinding` matching the existing IR
+ * shape. This is identical to what a hand-written rule would produce, so
+ * downstream emitters don't need to know an LLM was involved.
+ *
+ * Every LLM-generated binding is also appended to
+ * `<repo>/artefacts/candidate-rules.jsonl` so a separate offline pipeline
+ * can review and propose new deterministic rules. Auto-writing rules
+ * back into `stepMatcher.ts` is deferred to v2.1+ (see docs/SCOPE.md).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/llm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/llm/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG"}

package/dist/types.d.ts

@@ -125,6 +125,38 @@ export interface ScaffoldOptions {
      * offline runs.
      */
     snapshotFile?: string;
+    /**
+     * LLM fallback (v2.0+) — when a Gherkin step doesn't match any
+     * deterministic rule, defer to an LLM to produce the binding. Off by
+     * default. Every successful binding is appended to
+     * `<repo>/artefacts/candidate-rules.jsonl` for offline review (v2.0)
+     * or auto-rule-write (v2.1+, deferred).
+     *
+     * - `provider`: "anthropic" (only provider in v2.0). v2.1+ will add
+     *   "openai" and "gemini". The legacy `llm` flag in scaffold options
+     *   already accepts these strings; pass it through.
+     * - `model`: override the default model. Default for Anthropic is
+     *   claude-sonnet-4-6.
+     * - `apiKey`: API key for the provider. Defaults to
+     *   `process.env.ANTHROPIC_API_KEY` when omitted.
+     * - `governanceUrl`: ai-governance sidecar URL. Default
+     *   http://localhost:4900. The sidecar's /sanitize endpoint scrubs
+     *   every prompt before it leaves the perimeter (fail-closed).
+     * - `maxCalls`: max LLM calls per scaffold. Default 50.
+     * - `cachePath`: SQLite cache file. Default
+     *   `<repo>/.bdd2pw/llm-cache.sqlite`. Pass ":memory:" for tests.
+     * - `skipGovernance`: ONLY for tests. When true, prompts skip the
+     *   sidecar. Production runs MUST keep this off.
+     */
+    llmConfig?: {
+        provider: "anthropic";
+        model?: string;
+        apiKey?: string;
+        governanceUrl?: string;
+        maxCalls?: number;
+        cachePath?: string;
+        skipGovernance?: boolean;
+    };
     /**
      * Enable self-healing locator integration (v1.1+).
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vijaypjavvadi/bdd2pw",
-  "version": "1.1.7",
+  "version": "2.0.0",
   "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"