@vijaypjavvadi/bdd2pw 3.0.0 → 3.2.0

package/dist/parser/jsonScenarioParser.d.ts

@@ -0,0 +1,55 @@
+/**
+ * v3.2.0 — TestForge handoff Issue 8. Accept structured JSON scenarios
+ * in addition to .feature files.
+ *
+ * Input shape (TestForge's TCG output):
+ *
+ *   {
+ *     "name": "Login with valid credentials",
+ *     "kind": "ui",
+ *     "heuristic": "happy path",
+ *     "preconditions": ["user is registered"],
+ *     "actions": ["navigate to login page", "fill username", ...],
+ *     "expected": ["dashboard is visible"],
+ *     "data": { "username": "student", "password": "Password123" }
+ *   }
+ *
+ * Either a single object or an array of objects is accepted at the
+ * top level. The converter synthesises Gherkin steps:
+ *
+ *   - preconditions → `Given <text>`
+ *   - actions       → `When <text>` (first), `And <text>` (rest)
+ *   - expected      → `Then <text>` (first), `And <text>` (rest)
+ *
+ * `data` is appended to each action step that contains a templating
+ * placeholder like `<username>`; otherwise it's surfaced as a Gherkin
+ * doc-string attached to the first action step.
+ *
+ * The synthesised FeatureIR is identical in shape to what
+ * gherkinParser produces, so downstream code (stepMatcher, emitTestFile)
+ * treats both paths uniformly.
+ */
+import type { FeatureIR } from "../types";
+export interface JsonScenario {
+    name: string;
+    kind?: "ui" | "api" | "mixed" | string;
+    heuristic?: string;
+    preconditions?: string[];
+    actions?: string[];
+    expected?: string[];
+    data?: Record<string, string | number | boolean>;
+    /** Optional explicit tags. If omitted, derived from `kind`. */
+    tags?: string[];
+}
+/** Detect whether a file path is a JSON-scenario input. */
+export declare function isJsonScenarioFile(file: string): boolean;
+/**
+ * Read a JSON scenarios file and convert it to a FeatureIR. The
+ * feature name is derived from the file basename (matching gherkin
+ * convention: `login.feature` → "login"). Each top-level scenario in
+ * the JSON becomes a ScenarioIR.
+ *
+ * Returns a fully-formed FeatureIR — sourceFile points at the JSON
+ * file so the rest of the pipeline can reference the input correctly.
+ */
+export declare function parseJsonScenarios(filePath: string): Promise<FeatureIR>;

package/dist/parser/jsonScenarioParser.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * v3.2.0 — TestForge handoff Issue 8. Accept structured JSON scenarios
+ * in addition to .feature files.
+ *
+ * Input shape (TestForge's TCG output):
+ *
+ *   {
+ *     "name": "Login with valid credentials",
+ *     "kind": "ui",
+ *     "heuristic": "happy path",
+ *     "preconditions": ["user is registered"],
+ *     "actions": ["navigate to login page", "fill username", ...],
+ *     "expected": ["dashboard is visible"],
+ *     "data": { "username": "student", "password": "Password123" }
+ *   }
+ *
+ * Either a single object or an array of objects is accepted at the
+ * top level. The converter synthesises Gherkin steps:
+ *
+ *   - preconditions → `Given <text>`
+ *   - actions       → `When <text>` (first), `And <text>` (rest)
+ *   - expected      → `Then <text>` (first), `And <text>` (rest)
+ *
+ * `data` is appended to each action step that contains a templating
+ * placeholder like `<username>`; otherwise it's surfaced as a Gherkin
+ * doc-string attached to the first action step.
+ *
+ * The synthesised FeatureIR is identical in shape to what
+ * gherkinParser produces, so downstream code (stepMatcher, emitTestFile)
+ * treats both paths uniformly.
+ */
+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.isJsonScenarioFile = isJsonScenarioFile;
+exports.parseJsonScenarios = parseJsonScenarios;
+const fs = __importStar(require("fs-extra"));
+const path = __importStar(require("path"));
+/** Detect whether a file path is a JSON-scenario input. */
+function isJsonScenarioFile(file) {
+    return /\.json$/i.test(file);
+}
+/**
+ * Read a JSON scenarios file and convert it to a FeatureIR. The
+ * feature name is derived from the file basename (matching gherkin
+ * convention: `login.feature` → "login"). Each top-level scenario in
+ * the JSON becomes a ScenarioIR.
+ *
+ * Returns a fully-formed FeatureIR — sourceFile points at the JSON
+ * file so the rest of the pipeline can reference the input correctly.
+ */
+async function parseJsonScenarios(filePath) {
+    const raw = await fs.readFile(filePath, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`JSON scenarios file ${filePath} is not valid JSON: ${err.message}`);
+    }
+    const list = Array.isArray(parsed)
+        ? parsed
+        : [parsed];
+    const scenarios = list.map(jsonScenarioToScenarioIR);
+    const featureName = path.basename(filePath, path.extname(filePath));
+    return {
+        name: featureName,
+        description: undefined,
+        background: undefined,
+        scenarios,
+        tags: [],
+        sourceFile: filePath,
+    };
+}
+/**
+ * Convert one JSON scenario object to a ScenarioIR. The action/expected
+ * arrays are flattened into a Gherkin step list following standard BDD
+ * convention: first step in each group gets the strong keyword
+ * (Given/When/Then), subsequent steps get `And`.
+ */
+function jsonScenarioToScenarioIR(s) {
+    if (!s || typeof s !== "object" || typeof s.name !== "string") {
+        throw new Error(`Each JSON scenario must have a string "name" field. Received: ${JSON.stringify(s)}`);
+    }
+    const steps = [];
+    for (let i = 0; i < (s.preconditions?.length ?? 0); i++) {
+        steps.push({
+            keyword: i === 0 ? "Given" : "And",
+            text: s.preconditions[i],
+        });
+    }
+    for (let i = 0; i < (s.actions?.length ?? 0); i++) {
+        const text = applyDataTemplating(s.actions[i], s.data);
+        steps.push({
+            keyword: i === 0 ? "When" : "And",
+            text,
+        });
+    }
+    for (let i = 0; i < (s.expected?.length ?? 0); i++) {
+        steps.push({
+            keyword: i === 0 ? "Then" : "And",
+            text: applyDataTemplating(s.expected[i], s.data),
+        });
+    }
+    // Tag derivation: explicit `tags` wins; otherwise derive from `kind`
+    // so `kind: "api"` produces `@api` automatically. Same for ui/mixed.
+    const tags = s.tags ?? deriveTagsFromKind(s.kind);
+    return {
+        name: s.name,
+        steps,
+        tags,
+        examples: undefined,
+    };
+}
+function deriveTagsFromKind(kind) {
+    if (!kind)
+        return [];
+    if (kind === "mixed")
+        return ["@ui", "@api"];
+    return [`@${kind}`];
+}
+/**
+ * Replace `<placeholder>` tokens in a step text with values from the
+ * scenario's `data` object. Leaves the step alone when no placeholders
+ * are present. Same convention as Cucumber's Scenario Outline.
+ */
+function applyDataTemplating(text, data) {
+    if (!data)
+        return text;
+    return text.replace(/<([a-zA-Z_][\w]*)>/g, (full, key) => {
+        if (Object.prototype.hasOwnProperty.call(data, key)) {
+            return String(data[key]);
+        }
+        return full; // leave unreplaced placeholders intact
+    });
+}
+//# sourceMappingURL=jsonScenarioParser.js.map

package/dist/parser/jsonScenarioParser.js.map

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

package/dist/repo/projectScaffolder.d.ts

@@ -26,6 +26,12 @@ export interface ScaffoldProjectOptions {
     projectName?: string;
     /** When true, also write lib/heal.ts and patch tsconfig paths. */
     selfHealing?: boolean;
+    /**
+     * v3.2.0 — pin emitted devDependency versions when set to `exact`.
+     * Default `caret` matches existing behavior. See TestForge handoff
+     * Issue 9 and pw-emit v1.3.0.
+     */
+    dependencyStrategy?: "caret" | "exact";
 }
 export interface ScaffoldProjectResult {
     filesWritten: string[];

package/dist/repo/projectScaffolder.js

@@ -63,6 +63,7 @@ async function scaffoldProject(opts) {
         templatesDir: opts.templatesDir,
         baseUrl: opts.baseUrl,
         projectName: opts.projectName,
+        dependencyStrategy: opts.dependencyStrategy,
     });
     const filesWritten = [...result.filesWritten];
     const warnings = [...result.warnings];

package/dist/repo/projectScaffolder.js.map

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

package/dist/reports/metaSidecar.d.ts

@@ -0,0 +1,60 @@
+/**
+ * v3.2.0 — TestForge handoff Issue 10. Emit a `<spec-stem>.spec.meta.json`
+ * file alongside each generated `.spec.ts` describing every step's
+ * semantic intent. Lets downstream tooling (visual regression, defect
+ * analysis, self-healing pipelines) consume bdd2pw's understanding
+ * without re-parsing the TypeScript output.
+ *
+ * Sidecar shape (stable across patch versions):
+ *
+ *   {
+ *     "version": "<bdd2pw version>",
+ *     "source": "<.feature path relative to repo>",
+ *     "scenarios": [
+ *       {
+ *         "name": "Login with valid credentials",
+ *         "tags": ["@positive"],
+ *         "steps": [
+ *           { "id": "0001", "keyword": "Given", "text": "...",
+ *             "intent": "navigation", "locator": "page",
+ *             "assertion": "goto" },
+ *           ...
+ *         ]
+ *       }
+ *     ]
+ *   }
+ *
+ * `intent` is one of: navigation | interaction | assertion | api |
+ * compound | todo. Inferred from the binding shape (pomCall vs
+ * assertion vs customBody vs warning). When the binding carries
+ * `apiContext`, intent is `api` regardless of which sub-field is set.
+ */
+import type { StepBinding } from "../types";
+export interface MetaSidecarStep {
+    id: string;
+    keyword: string;
+    text: string;
+    intent: "navigation" | "interaction" | "assertion" | "api" | "compound" | "todo";
+    /** Resolved locator string when the binding has one. */
+    locator?: string;
+    /** Matcher name or method name when the binding has one. */
+    assertion?: string;
+}
+export interface MetaSidecarScenario {
+    name: string;
+    tags?: string[];
+    steps: MetaSidecarStep[];
+}
+export interface MetaSidecar {
+    version: string;
+    source: string;
+    scenarios: MetaSidecarScenario[];
+}
+/**
+ * Convert a list of bindings (one scenario's worth) into the meta
+ * sidecar's `steps` array. IDs are zero-padded 4 digits, sequential
+ * in source order — same convention as the optional step boundary
+ * markers (v3.1.0 Issue 5), so post-processors can correlate the
+ * sidecar to the in-source markers when both features are enabled.
+ */
+export declare function bindingsToMetaSteps(bindings: StepBinding[]): MetaSidecarStep[];

package/dist/reports/metaSidecar.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * v3.2.0 — TestForge handoff Issue 10. Emit a `<spec-stem>.spec.meta.json`
+ * file alongside each generated `.spec.ts` describing every step's
+ * semantic intent. Lets downstream tooling (visual regression, defect
+ * analysis, self-healing pipelines) consume bdd2pw's understanding
+ * without re-parsing the TypeScript output.
+ *
+ * Sidecar shape (stable across patch versions):
+ *
+ *   {
+ *     "version": "<bdd2pw version>",
+ *     "source": "<.feature path relative to repo>",
+ *     "scenarios": [
+ *       {
+ *         "name": "Login with valid credentials",
+ *         "tags": ["@positive"],
+ *         "steps": [
+ *           { "id": "0001", "keyword": "Given", "text": "...",
+ *             "intent": "navigation", "locator": "page",
+ *             "assertion": "goto" },
+ *           ...
+ *         ]
+ *       }
+ *     ]
+ *   }
+ *
+ * `intent` is one of: navigation | interaction | assertion | api |
+ * compound | todo. Inferred from the binding shape (pomCall vs
+ * assertion vs customBody vs warning). When the binding carries
+ * `apiContext`, intent is `api` regardless of which sub-field is set.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bindingsToMetaSteps = bindingsToMetaSteps;
+/**
+ * Classify a step binding's intent. Order of checks matters:
+ *   1. apiContext flag → "api" (overrides every other shape since API
+ *      bindings often carry customBody + assertion together).
+ *   2. warning-only → "todo".
+ *   3. pomCall with method "goto" → "navigation".
+ *   4. pomCall otherwise → "interaction".
+ *   5. assertion → "assertion".
+ *   6. customBody → "compound".
+ *   7. fallback → "todo".
+ */
+function classifyIntent(b) {
+    if (b.apiContext)
+        return "api";
+    if (!b.pomCall && !b.assertion && !b.customBody && b.warning)
+        return "todo";
+    if (b.pomCall) {
+        return b.pomCall.method === "goto" ? "navigation" : "interaction";
+    }
+    if (b.assertion)
+        return "assertion";
+    if (b.customBody)
+        return "compound";
+    return "todo";
+}
+/**
+ * Convert a list of bindings (one scenario's worth) into the meta
+ * sidecar's `steps` array. IDs are zero-padded 4 digits, sequential
+ * in source order — same convention as the optional step boundary
+ * markers (v3.1.0 Issue 5), so post-processors can correlate the
+ * sidecar to the in-source markers when both features are enabled.
+ */
+function bindingsToMetaSteps(bindings) {
+    return bindings.map((b, idx) => {
+        const step = {
+            id: String(idx + 1).padStart(4, "0"),
+            keyword: b.step.keyword,
+            text: b.step.text,
+            intent: classifyIntent(b),
+        };
+        if (b.pomCall) {
+            step.locator = `${b.pomCall.page}.${b.pomCall.method}`;
+            step.assertion = b.pomCall.method;
+        }
+        else if (b.assertion) {
+            step.locator = b.assertion.locator;
+            step.assertion = b.assertion.matcher;
+        }
+        return step;
+    });
+}
+//# sourceMappingURL=metaSidecar.js.map

package/dist/reports/metaSidecar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metaSidecar.js","sourceRoot":"","sources":["../../src/reports/metaSidecar.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;;AAwDH,kDAmBC;AAhDD;;;;;;;;;;GAUG;AACH,SAAS,cAAc,CAAC,CAAc;IACpC,IAAI,CAAC,CAAC,UAAU;QAAE,OAAO,KAAK,CAAC;IAC/B,IAAI,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,OAAO;QAAE,OAAO,MAAM,CAAC;IAC5E,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;QACd,OAAO,CAAC,CAAC,OAAO,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,aAAa,CAAC;IACpE,CAAC;IACD,IAAI,CAAC,CAAC,SAAS;QAAE,OAAO,WAAW,CAAC;IACpC,IAAI,CAAC,CAAC,UAAU;QAAE,OAAO,UAAU,CAAC;IACpC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,mBAAmB,CACjC,QAAuB;IAEvB,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE;QAC7B,MAAM,IAAI,GAAoB;YAC5B,EAAE,EAAE,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC;YACpC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO;YACvB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI;YACjB,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;SAC1B,CAAC;QACF,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;YACd,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YACvD,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;QACpC,CAAC;aAAM,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC;YACvB,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC;YACnC,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC;QACvC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/reports/specMerge.d.ts

@@ -0,0 +1,60 @@
+/**
+ * v3.2.0 — TestForge handoff Issue 7. Preserve user-edited blocks
+ * across regeneration.
+ *
+ * Two artefacts make this work:
+ *
+ *   1. **A generated-header marker.** Every spec emitted with `merge`
+ *      enabled gets a leading
+ *      `// bdd2pw:generated v=<version> source=<feature>` comment, so a
+ *      future run can recognise its own output.
+ *
+ *   2. **User-block markers.** Anywhere in the spec, the user can wrap
+ *      hand-edited code in:
+ *
+ *          // bdd2pw:user-block id="custom-locator"
+ *          await this.special = page.locator("[data-thing]");
+ *          // bdd2pw:end-user-block
+ *
+ *      During regeneration, blocks with the same `id` are spliced back
+ *      into the new output. Blocks whose id is absent from the new
+ *      output are appended at end of file under a clearly-labelled
+ *      "stale user blocks" section so nothing is lost silently.
+ *
+ * The merge is conservative — it never touches the LINES INSIDE
+ * user blocks; everything else is fresh output.
+ *
+ * Why id-keyed splicing instead of line-based diff? Line numbers
+ * shift every time the input feature changes. Id-keyed markers
+ * survive arbitrary reordering and renaming.
+ */
+/** Detect whether a previously-emitted spec was produced with merge on. */
+export declare function isMergeAnnotated(existing: string): boolean;
+/** Extract every user-block in `existing`, keyed by id. */
+export declare function extractUserBlocks(existing: string): Map<string, string>;
+/**
+ * Splice preserved user blocks into a freshly-rendered spec.
+ *
+ *   - `next` is the new bdd2pw output (no user blocks yet).
+ *   - `preserved` is the id → block-text map extracted from the
+ *     PREVIOUS spec via `extractUserBlocks`.
+ *
+ * For each preserved block: if `next` contains a placeholder line
+ * `// bdd2pw:user-block id="<id>"` ... `// bdd2pw:end-user-block`
+ * (which bdd2pw never emits by itself — see note below), replace it.
+ * Otherwise append the block under a "stale user blocks" footer so
+ * the user can salvage / delete it on their own.
+ *
+ * Note: bdd2pw doesn't insert empty user-block placeholders by
+ * default — users opt in by editing a generated spec and adding the
+ * markers themselves. So in practice the splice path here is
+ * usually the "append at end" branch, which is intentional — once
+ * a user edits a spec under merge, the markers they added live
+ * forever inside the spec until they remove them.
+ */
+export declare function mergeUserBlocks(next: string, preserved: Map<string, string>): string;
+/**
+ * Prepend the generated header to a fresh spec so future merges can
+ * detect that the file is bdd2pw-managed.
+ */
+export declare function prependGeneratedHeader(contents: string, version: string, source: string): string;

package/dist/reports/specMerge.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * v3.2.0 — TestForge handoff Issue 7. Preserve user-edited blocks
+ * across regeneration.
+ *
+ * Two artefacts make this work:
+ *
+ *   1. **A generated-header marker.** Every spec emitted with `merge`
+ *      enabled gets a leading
+ *      `// bdd2pw:generated v=<version> source=<feature>` comment, so a
+ *      future run can recognise its own output.
+ *
+ *   2. **User-block markers.** Anywhere in the spec, the user can wrap
+ *      hand-edited code in:
+ *
+ *          // bdd2pw:user-block id="custom-locator"
+ *          await this.special = page.locator("[data-thing]");
+ *          // bdd2pw:end-user-block
+ *
+ *      During regeneration, blocks with the same `id` are spliced back
+ *      into the new output. Blocks whose id is absent from the new
+ *      output are appended at end of file under a clearly-labelled
+ *      "stale user blocks" section so nothing is lost silently.
+ *
+ * The merge is conservative — it never touches the LINES INSIDE
+ * user blocks; everything else is fresh output.
+ *
+ * Why id-keyed splicing instead of line-based diff? Line numbers
+ * shift every time the input feature changes. Id-keyed markers
+ * survive arbitrary reordering and renaming.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isMergeAnnotated = isMergeAnnotated;
+exports.extractUserBlocks = extractUserBlocks;
+exports.mergeUserBlocks = mergeUserBlocks;
+exports.prependGeneratedHeader = prependGeneratedHeader;
+/** Match a user-block open marker plus capture its id and body. */
+const USER_BLOCK_RE = /\/\/\s*bdd2pw:user-block\s+id\s*=\s*"([^"]+)"[ \t]*\r?\n([\s\S]*?)\/\/\s*bdd2pw:end-user-block/g;
+/** Header comment we emit at the top of merge-enabled specs. */
+function generatedHeader(version, source) {
+    return `// bdd2pw:generated v=${version} source=${source}`;
+}
+/** Detect whether a previously-emitted spec was produced with merge on. */
+function isMergeAnnotated(existing) {
+    return /^\/\/\s*bdd2pw:generated\s/.test(existing.trimStart());
+}
+/** Extract every user-block in `existing`, keyed by id. */
+function extractUserBlocks(existing) {
+    const out = new Map();
+    const re = new RegExp(USER_BLOCK_RE.source, "g");
+    let m;
+    while ((m = re.exec(existing)) !== null) {
+        const id = m[1];
+        const body = m[2];
+        // Stash the WHOLE block including markers so the splice keeps
+        // them in the output. (If we only captured `body`, a subsequent
+        // regen would lose the markers and the next regen wouldn't see
+        // the block.)
+        const full = m[0];
+        out.set(id, full);
+    }
+    return out;
+}
+/**
+ * Splice preserved user blocks into a freshly-rendered spec.
+ *
+ *   - `next` is the new bdd2pw output (no user blocks yet).
+ *   - `preserved` is the id → block-text map extracted from the
+ *     PREVIOUS spec via `extractUserBlocks`.
+ *
+ * For each preserved block: if `next` contains a placeholder line
+ * `// bdd2pw:user-block id="<id>"` ... `// bdd2pw:end-user-block`
+ * (which bdd2pw never emits by itself — see note below), replace it.
+ * Otherwise append the block under a "stale user blocks" footer so
+ * the user can salvage / delete it on their own.
+ *
+ * Note: bdd2pw doesn't insert empty user-block placeholders by
+ * default — users opt in by editing a generated spec and adding the
+ * markers themselves. So in practice the splice path here is
+ * usually the "append at end" branch, which is intentional — once
+ * a user edits a spec under merge, the markers they added live
+ * forever inside the spec until they remove them.
+ */
+function mergeUserBlocks(next, preserved) {
+    if (preserved.size === 0)
+        return next;
+    // For each preserved id, replace any matching open/close marker in
+    // `next`, otherwise queue for append.
+    let merged = next;
+    const stale = [];
+    for (const [id, block] of preserved.entries()) {
+        const placeholder = new RegExp(`\\/\\/\\s*bdd2pw:user-block\\s+id\\s*=\\s*"${escapeForRegex(id)}"[ \\t]*\\r?\\n[\\s\\S]*?\\/\\/\\s*bdd2pw:end-user-block`, "g");
+        if (placeholder.test(merged)) {
+            merged = merged.replace(placeholder, block);
+        }
+        else {
+            stale.push({ id, block });
+        }
+    }
+    if (stale.length === 0)
+        return merged;
+    const footer = [
+        "",
+        "// ── bdd2pw:stale-user-blocks ──────────────────────────────",
+        "// The following user-block sections existed in the previous",
+        "// generated spec but no matching id was found in the freshly-",
+        "// generated output. They're preserved here so you don't lose",
+        "// them. Move them inline (or delete them) and the next merge",
+        "// will pick up the change.",
+        ...stale.map((s) => s.block),
+        "// ── bdd2pw:end-stale-user-blocks ──────────────────────────",
+        "",
+    ].join("\n");
+    return merged + footer;
+}
+/**
+ * Prepend the generated header to a fresh spec so future merges can
+ * detect that the file is bdd2pw-managed.
+ */
+function prependGeneratedHeader(contents, version, source) {
+    const header = generatedHeader(version, source);
+    // Idempotent: if the contents already start with our header, don't
+    // duplicate it.
+    if (isMergeAnnotated(contents))
+        return contents;
+    return `${header}\n${contents}`;
+}
+function escapeForRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//# sourceMappingURL=specMerge.js.map

package/dist/reports/specMerge.js.map

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

package/dist/transformers/stepMatcher.js

@@ -22,6 +22,7 @@ const naming_1 = require("../utils/naming");
 const stepNormalizer_1 = require("./stepNormalizer");
 const stepNormalizer_2 = require("./stepNormalizer");
 const apiRules_1 = require("./apiRules");
+const visibilityRules_1 = require("./visibilityRules");
 /**
  * Match every step in every scenario to a POM call / assertion / TODO.
  * Background steps are also threaded through if the orchestrator passes
@@ -85,6 +86,14 @@ const RULES = [
     // at the top guarantees deterministic interception before any UI rule
     // accidentally chews on an API-ish phrase. See src/transformers/apiRules.ts.
     ...apiRules_1.API_RULES,
+    // v3.1.0 — visibility rules go SECOND. TestForge handoff Issue 1:
+    // steps like "the user's name or profile indicator is visible in the
+    // UI" were falling through to the URL-slug rules and producing
+    // always-failing `toHaveURL(/.../)` assertions. These rules intercept
+    // anything matching "<noun> is visible/displayed/shown/appears" and
+    // either resolve a POM locator or land a clean TODO — never a URL
+    // regex. See src/transformers/visibilityRules.ts.
+    ...visibilityRules_1.VISIBILITY_RULES,
     // 1. Navigation: "I am on the login page" / "I navigate to /foo"
     {
         pattern: new RegExp(`^(?:${SUBJ} )?(?:am on|navigate to|navigates? to|open|opens?|visit|visits?|go to|goes? to|am at|is at) (?:the )?(?:.+?\\s+)?["']?([^"']+?)["']?(?: page)?$`, "i"),