@sdods/core 0.3.2 → 0.5.1

package/dist/heal/healer.js

@@ -3,7 +3,7 @@ import { expect } from '@playwright/test';
 import { attachmentNames, scenarioFiles } from '@sdods/contracts';
 import { Logger } from '../logger.js';
 import { SdodsError } from '../errors.js';
-import { buildCandidates } from './strategies.js';
+import { buildCandidates, disambiguationCandidates, rolesFor } from './strategies.js';
 /** Locator wrapper: every action goes through the healer. */
 export class HealedLocator {
     healer;
@@ -83,54 +83,100 @@ export class Healer {
     async expectText(primary, ctx, text) {
         await expect(await this.resolve(primary, ctx, 'assert')).toContainText(text);
     }
+    /**
+     * The first of `locators`, in preference order, that matches anything. Waits up to
+     * primaryTimeoutMs for the LAST one to attach — callers list the loosest locator last, a
+     * superset of the others — so an element that renders a moment late is still judged by the
+     * most precise locator. When nothing matches, the most precise one is returned for resolve()
+     * to wait on and heal from.
+     */
+    async prefer(...locators) {
+        const loosest = locators[locators.length - 1];
+        await loosest
+            .first()
+            .waitFor({ state: 'attached', timeout: this.deps.config.primaryTimeoutMs })
+            .catch(() => undefined);
+        for (const locator of locators)
+            if ((await locator.count()) > 0)
+                return locator;
+        return locators[0];
+    }
     /**
      * Wait briefly for the primary locator; on failure probe all candidates in parallel,
-     * score them and pick the best above minScore. Records a HealEvent either way.
+     * score them and pick the best above minScore. A primary that is visible but matches several
+     * elements is healed too, for actions that have a role to prefer. Records a HealEvent whenever
+     * it heals.
      */
     async resolve(primary, ctx, action) {
         const cfg = this.deps.config;
+        const healable = cfg.enabled && cfg.actions.includes(action);
         try {
             await primary.first().waitFor({ state: 'visible', timeout: cfg.primaryTimeoutMs });
-            return primary;
         }
         catch (primaryError) {
-            if (!cfg.enabled || !cfg.actions.includes(action))
+            if (!healable)
                 throw primaryError;
             const page = primary.page();
-            const t0 = Date.now();
             const candidates = buildCandidates(page, ctx);
             if (candidates.length === 0)
                 throw primaryError;
-            const probes = await Promise.all(candidates.map((c) => this.probe(c, cfg.probeTimeoutMs, action)));
-            const ranked = probes.sort((a, b) => b.score - a.score);
-            const best = ranked[0];
-            const event = {
-                fingerprint: this.deps.scenario?.fingerprint ?? '',
-                runId: this.deps.runId ?? '',
-                stepIndex: this.deps.stepIndex?.() ?? 0,
-                action,
-                description: ctx.description,
-                pageUrl: page.url(),
-                originalSelector: String(primary),
-                context: { ...ctx, name: ctx.name instanceof RegExp ? ctx.name.toString() : ctx.name },
-                strategyUsed: best && best.score >= cfg.minScore ? best.strategy : null,
-                healedSelector: best && best.score >= cfg.minScore ? best.selector : null,
-                candidates: ranked.map(({ locator: _l, baseScore: _b, ...rest }) => rest),
-                succeeded: Boolean(best && best.score >= cfg.minScore),
-                durationMs: Date.now() - t0,
-                at: new Date().toISOString(),
-            };
-            this.record(event);
-            if (!event.succeeded || !best) {
-                throw new SdodsError('HEAL_FAILED', `Could not locate "${ctx.description}" (${String(primary)}) and no healing candidate scored ≥ ${cfg.minScore}.`, {
-                    hint: `Probed: ${ranked.map((p) => `${p.strategy}=${p.score.toFixed(2)}`).join(', ') || 'none'}. Add role/name/testId/label to the heal context or fix the locator.`,
-                    details: { candidates: event.candidates },
-                    cause: primaryError,
-                });
-            }
-            this.log.warn(`healed "${ctx.description}": ${String(primary)} → ${best.selector} via ${best.strategy} (score ${best.score.toFixed(2)}, ${event.durationMs} ms). Update the page object.`);
-            return best.locator.first();
+            // The role filter goes first: a primary whose FIRST match is hidden (a collapsed toggle
+            // ahead of the field) never becomes visible, yet narrows to the visible element that fits.
+            return this.heal(primary, ctx, action, [...disambiguationCandidates(page, primary, ctx, action), ...candidates], { cause: primaryError });
+        }
+        // Visible is not enough. A primary matching several elements makes the action throw a
+        // strict-mode violation after resolve() has returned, where healing never sees it. Assertions
+        // and hovers have no role to prefer, and their callers take .first() when they mean "any of
+        // them", so only role-bound actions are disambiguated.
+        if (!healable || rolesFor(action).length === 0)
+            return primary;
+        const matched = await primary.count();
+        if (matched <= 1)
+            return primary;
+        const page = primary.page();
+        return this.heal(primary, ctx, action, [...disambiguationCandidates(page, primary, ctx, action), ...buildCandidates(page, ctx)], { matched });
+    }
+    async heal(primary, ctx, action, candidates, why) {
+        const cfg = this.deps.config;
+        const page = primary.page();
+        const t0 = Date.now();
+        const probes = await Promise.all(candidates.map((c) => this.probe(c, cfg.probeTimeoutMs, action)));
+        const ranked = probes.sort((a, b) => b.score - a.score);
+        // Healing an ambiguity onto another ambiguous locator would only move the strict-mode
+        // violation, so that heal accepts a unique candidate only.
+        const ambiguous = why.matched !== undefined;
+        const best = ranked.find((p) => p.score >= cfg.minScore && (!ambiguous || p.count === 1));
+        const event = {
+            fingerprint: this.deps.scenario?.fingerprint ?? '',
+            runId: this.deps.runId ?? '',
+            stepIndex: this.deps.stepIndex?.() ?? 0,
+            action,
+            description: ctx.description,
+            pageUrl: page.url(),
+            originalSelector: String(primary),
+            context: { ...ctx, name: ctx.name instanceof RegExp ? ctx.name.toString() : ctx.name },
+            strategyUsed: best ? best.strategy : null,
+            healedSelector: best ? best.selector : null,
+            candidates: ranked.map(({ locator: _l, baseScore: _b, ...rest }) => rest),
+            succeeded: Boolean(best),
+            durationMs: Date.now() - t0,
+            at: new Date().toISOString(),
+        };
+        this.record(event);
+        const probed = ranked.map((p) => `${p.strategy}=${p.score.toFixed(2)}`).join(', ') || 'none';
+        if (!best) {
+            throw new SdodsError('HEAL_FAILED', ambiguous
+                ? `"${ctx.description}" (${String(primary)}) matched ${why.matched} elements and no healing candidate narrowed it to one that fits "${action}" with a score ≥ ${cfg.minScore}.`
+                : `Could not locate "${ctx.description}" (${String(primary)}) and no healing candidate scored ≥ ${cfg.minScore}.`, {
+                hint: ambiguous
+                    ? `Probed: ${probed}. Make the locator specific to one element: an exact name or label, a role, or a test id.`
+                    : `Probed: ${probed}. Add role/name/testId/label to the heal context or fix the locator.`,
+                details: { candidates: event.candidates },
+                cause: why.cause,
+            });
         }
+        this.log.warn(`healed "${ctx.description}": ${String(primary)}${ambiguous ? ` (matched ${why.matched})` : ''} → ${best.selector} via ${best.strategy} (score ${best.score.toFixed(2)}, ${event.durationMs} ms). Update the page object.`);
+        return best.locator.first();
     }
     async probe(c, timeoutMs, action) {
         const t0 = Date.now();

package/dist/heal/strategies.d.ts

@@ -1,5 +1,15 @@
-import type { Page } from '@playwright/test';
-import type { HealContext, HealProbe } from './types.js';
+import type { Locator, Page } from '@playwright/test';
+import type { AriaRole, HealAction, HealContext, HealProbe } from './types.js';
+export declare function rolesFor(action: HealAction): AriaRole[];
+/** `locator` narrowed to elements whose role fits `action`; `locator` itself when none is defined. */
+export declare function withActionRole(page: Page, locator: Locator, action: HealAction): Locator;
+/**
+ * Candidates for a primary locator that matched several elements: the primary narrowed to the
+ * roles that fit the action (and the context's own role, when it names one), as a single union.
+ * A union keeps a genuine tie ambiguous — an input and a select both labelled "Country" still
+ * count 2 for a fill — rather than letting role order break it silently.
+ */
+export declare function disambiguationCandidates(page: Page, primary: Locator, ctx: HealContext, action: HealAction): Omit<HealProbe, 'score' | 'count' | 'visible' | 'enabled' | 'ms'>[];
 /** Build candidate locators from the context, ordered by base score (higher = more semantic). */
 export declare function buildCandidates(page: Page, ctx: HealContext): Omit<HealProbe, 'score' | 'count' | 'visible' | 'enabled' | 'ms'>[];
 //# sourceMappingURL=strategies.d.ts.map

package/dist/heal/strategies.js

@@ -1,3 +1,45 @@
+/**
+ * The roles an element must have for an action to make sense on it. `assert` and `hover` apply to
+ * anything, so they have none. A contenteditable editor has no role at all, which is why callers
+ * treat a role filter as a preference, never as the only way to reach an element.
+ */
+const ACTION_ROLES = {
+    fill: ['textbox', 'searchbox', 'combobox', 'spinbutton'],
+    select: ['combobox', 'listbox'],
+    check: ['checkbox', 'radio', 'switch'],
+    click: ['button', 'link', 'menuitem', 'tab', 'option', 'checkbox', 'radio', 'switch'],
+    assert: [],
+    hover: [],
+};
+export function rolesFor(action) {
+    return ACTION_ROLES[action];
+}
+/** `locator` narrowed to elements whose role fits `action`; `locator` itself when none is defined. */
+export function withActionRole(page, locator, action) {
+    const roles = rolesFor(action);
+    if (roles.length === 0)
+        return locator;
+    return locator.and(roles.map((r) => page.getByRole(r)).reduce((union, next) => union.or(next)));
+}
+/**
+ * Candidates for a primary locator that matched several elements: the primary narrowed to the
+ * roles that fit the action (and the context's own role, when it names one), as a single union.
+ * A union keeps a genuine tie ambiguous — an input and a select both labelled "Country" still
+ * count 2 for a fill — rather than letting role order break it silently.
+ */
+export function disambiguationCandidates(page, primary, ctx, action) {
+    const roles = [...new Set([...(ctx.role ? [ctx.role] : []), ...rolesFor(action)])];
+    if (roles.length === 0)
+        return [];
+    return [
+        {
+            strategy: 'role-filter',
+            selector: `${String(primary)}.and(${roles.map((r) => `getByRole('${r}')`).join('.or(')}${')'.repeat(roles.length - 1)})`,
+            locator: primary.and(roles.map((r) => page.getByRole(r)).reduce((union, next) => union.or(next))),
+            baseScore: 1.0,
+        },
+    ];
+}
 /** Build candidate locators from the context, ordered by base score (higher = more semantic). */
 export function buildCandidates(page, ctx) {
     const out = [];

package/dist/lint/index.d.ts

@@ -20,6 +20,7 @@ export declare function detectUndefinedSteps(project: ProjectConfig & {
     message: string;
     file?: string;
     line?: number;
+    rule?: string;
 }>>;
 export declare function formatFindings(result: LintResult): string;
 //# sourceMappingURL=index.d.ts.map

package/dist/lint/index.js

@@ -1,9 +1,10 @@
 import { readdirSync, statSync, existsSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { join, relative, resolve } from 'node:path';
 import { execa } from 'execa';
 import { BROWSERS_FOR_SKIP, KNOWN_VALUE_TAGS, LAYER_TAGS, RUNNER_SPECIAL_TAGS, VALUE_TAG, taxonomyFromProject, } from '../config/tags.js';
 import { moduleForFeature } from '../config/workspace.js';
 import { parseFeatureFile, scenariosOf } from './gherkin.js';
+import { checkStepAmbiguity } from './steps.js';
 export * from './gherkin.js';
 export function listFeatureFiles(root) {
     const out = [];
@@ -30,8 +31,10 @@ export async function lintProject(opts) {
     const errors = [];
     const warnings = [];
     const rel = (f) => relative(project.root, f).replace(/\\/g, '/');
+    const parsedFeatures = [];
     for (const file of files) {
         const parsed = parseFeatureFile(file);
+        parsedFeatures.push(parsed);
         for (const e of parsed.errors)
             errors.push({
                 severity: 'error',
@@ -213,16 +216,25 @@ export async function lintProject(opts) {
                 seen.set(key, sc.line);
         }
     }
+    // A phrasing matched by two definitions stops bddgen generating anything (#60).
+    const ambiguity = await checkStepAmbiguity({ project, features: parsedFeatures });
+    errors.push(...ambiguity.errors);
+    warnings.push(...ambiguity.warnings);
     if (opts.undefinedSteps && opts.repoRoot) {
         const found = await detectUndefinedSteps(project, opts.repoRoot);
-        for (const f of found)
+        for (const f of found) {
+            const rule = f.rule ?? 'steps/undefined';
+            // The static check above usually saw this ambiguity already; do not report it twice.
+            if (errors.some((e) => e.rule === rule && e.file === f.file && e.line === f.line))
+                continue;
             errors.push({
                 severity: 'error',
-                rule: 'steps/undefined',
+                rule,
                 message: f.message,
                 file: f.file ?? '',
                 line: f.line,
             });
+        }
     }
     return { errors, warnings, filesChecked: files.length };
 }
@@ -266,6 +278,35 @@ export async function detectUndefinedSteps(project, repoRoot) {
                 .slice(0, 10)
                 .join(' | '),
         });
+    // bddgen stops at the first ambiguous step. This parser only knew the missing-step block, so an
+    // ambiguity (#60) — or any other generation failure — came back as "no findings".
+    const ambiguous = /^Step: (.+?) # (.+\.feature):(\d+)(?::\d+)?$/;
+    for (let i = 0; i < lines.length; i++) {
+        const s = ambiguous.exec(lines[i].trim());
+        if (!s || !/Multiple definitions matched/.test(lines[i - 1] ?? ''))
+            continue;
+        const variants = [];
+        for (let j = i + 1; j < lines.length && lines[j].trim().startsWith('- '); j++)
+            variants.push(lines[j].trim().slice(2));
+        out.push({
+            rule: 'steps/ambiguous',
+            message: `Multiple definitions matched "${s[1]}": ${variants.join('; ')}`,
+            file: relative(project.root, resolve(repoRoot, s[2])).replace(/\\/g, '/'),
+            line: Number(s[3]),
+        });
+    }
+    if (!out.length) {
+        const tail = text
+            .split('\n')
+            .map((l) => l.trim())
+            .filter(Boolean)
+            .slice(-5)
+            .join(' | ');
+        out.push({
+            rule: 'steps/bddgen',
+            message: `bddgen failed to generate specs (exit ${result.exitCode}): ${tail || '(no output)'}`,
+        });
+    }
     return out;
 }
 export function formatFindings(result) {

package/dist/lint/steps.d.ts

@@ -0,0 +1,13 @@
+import type { LintFinding, ProjectConfig } from '@sdods/contracts';
+import type { ParsedFeature } from './gherkin.js';
+export interface AmbiguityCheckOptions {
+    project: ProjectConfig & {
+        root: string;
+    };
+    features: ParsedFeature[];
+}
+export declare function checkStepAmbiguity(opts: AmbiguityCheckOptions): Promise<{
+    errors: LintFinding[];
+    warnings: LintFinding[];
+}>;
+//# sourceMappingURL=steps.d.ts.map

package/dist/lint/steps.js

@@ -0,0 +1,333 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, join, relative } from 'node:path';
+import { CucumberExpression, ParameterType, ParameterTypeRegistry, RegularExpression, } from '@cucumber/cucumber-expressions';
+import { parseTagExpr } from '../config/tags.js';
+import { coreStepNames, coreStepsDir, coreStepsPatterns } from '../steps/glob.js';
+/**
+ * Ambiguous step definitions (#60).
+ *
+ * playwright-bdd refuses to generate specs when one scenario step matches more than one definition
+ * ("Multiple definitions matched scenario step"), and the core step libraries share one namespace
+ * with a project's own steps — so a phrasing a project wrote before a library shipped the same
+ * text breaks the whole suite at `sdods run`, while lint used to say "no findings".
+ *
+ * Definitions are read statically (no step file is executed, so lint stays fast and side-effect
+ * free) from exactly the files the runner hands bddgen: the core libraries minus
+ * `steps.core.exclude`, plus the project's `steps/**` and `pages/**`. They are matched against
+ * pickle step text (outline rows expanded) with the same Cucumber expression engine and the same
+ * rules bddgen uses: keywords are ignored, tag-scoped definitions are filtered by the scenario's
+ * tags, and `@skip` / `@fixme` scenarios are not matched. A pattern that is not a literal, or that
+ * names a parameter type lint cannot see, is left out rather than guessed at: this check must
+ * never fail a suite that bddgen would generate.
+ */
+const STEP_FNS = new Set(['Given', 'When', 'Then', 'Step']);
+function walk(dir, out) {
+    if (!existsSync(dir))
+        return;
+    for (const name of readdirSync(dir).sort()) {
+        if (name === 'node_modules')
+            continue;
+        const p = join(dir, name);
+        if (statSync(p).isDirectory())
+            walk(p, out);
+        else if (name.endsWith('.ts') && !name.endsWith('.d.ts'))
+            out.push(p);
+    }
+}
+function literalRegExp(text) {
+    const m = /^\/(.*)\/([a-z]*)$/s.exec(text);
+    if (!m)
+        return undefined;
+    try {
+        return new RegExp(m[1], m[2]);
+    }
+    catch {
+        return undefined;
+    }
+}
+function extract(ts, file, library) {
+    const steps = [];
+    const params = [];
+    const text = readFileSync(file, 'utf8');
+    const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, file.endsWith('.js') ? ts.ScriptKind.JS : ts.ScriptKind.TS);
+    const stringOf = (n) => {
+        if (!n)
+            return undefined;
+        if (ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n))
+            return n.text;
+        if (ts.isRegularExpressionLiteral(n))
+            return literalRegExp(n.text);
+        return undefined;
+    };
+    const visit = (node) => {
+        if (ts.isCallExpression(node)) {
+            const callee = node.expression;
+            const name = ts.isIdentifier(callee)
+                ? callee.text
+                : ts.isPropertyAccessExpression(callee)
+                    ? callee.name.text
+                    : undefined;
+            if (name && STEP_FNS.has(name) && node.arguments.length) {
+                const pattern = stringOf(node.arguments[0]);
+                if (pattern !== undefined) {
+                    const def = {
+                        pattern,
+                        file,
+                        line: sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1,
+                        library,
+                    };
+                    const opts = node.arguments[1];
+                    if (opts && ts.isObjectLiteralExpression(opts)) {
+                        for (const prop of opts.properties) {
+                            if (ts.isPropertyAssignment(prop) &&
+                                (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)) &&
+                                prop.name.text === 'tags') {
+                                const tags = stringOf(prop.initializer);
+                                def.tags = typeof tags === 'string' ? tags : null;
+                            }
+                            else if (ts.isShorthandPropertyAssignment(prop) && prop.name.text === 'tags') {
+                                def.tags = null;
+                            }
+                        }
+                    }
+                    steps.push(def);
+                }
+            }
+            else if (name === 'defineParameterType' && node.arguments[0]) {
+                const arg = node.arguments[0];
+                if (ts.isObjectLiteralExpression(arg)) {
+                    let pname;
+                    const regexps = [];
+                    for (const prop of arg.properties) {
+                        if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name))
+                            continue;
+                        if (prop.name.text === 'name') {
+                            const v = stringOf(prop.initializer);
+                            if (typeof v === 'string')
+                                pname = v;
+                        }
+                        else if (prop.name.text === 'regexp') {
+                            const init = prop.initializer;
+                            const items = ts.isArrayLiteralExpression(init) ? [...init.elements] : [init];
+                            for (const item of items) {
+                                const v = stringOf(item);
+                                if (v !== undefined)
+                                    regexps.push(v);
+                            }
+                        }
+                    }
+                    if (pname && regexps.length)
+                        params.push({ name: pname, regexps });
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return { steps, params };
+}
+/** Gherkin step id → line, across backgrounds, scenarios and rules. */
+function stepLines(doc) {
+    const lines = new Map();
+    const children = (list) => {
+        for (const c of list) {
+            const block = c.background ?? c.scenario;
+            for (const s of block?.steps ?? [])
+                lines.set(s.id, s.location.line);
+            if (c.rule)
+                children(c.rule.children);
+        }
+    };
+    if (doc.feature)
+        children(doc.feature.children);
+    return lines;
+}
+export async function checkStepAmbiguity(opts) {
+    const { project, features } = opts;
+    const errors = [];
+    const warnings = [];
+    const rel = (f) => relative(project.root, f).replace(/\\/g, '/');
+    const exclude = project.steps?.core?.exclude ?? [];
+    try {
+        coreStepsPatterns(exclude);
+    }
+    catch (e) {
+        errors.push({
+            severity: 'error',
+            rule: 'steps/core-exclude',
+            message: `${e.message} ${e.hint ?? ''}`.trim(),
+            file: 'sdods.project.yaml',
+        });
+    }
+    const { ts } = await import('ts-morph');
+    const dir = coreStepsDir();
+    const coreFile = (name) => [`${name}.ts`, `${name}.js`].map((f) => join(dir, f)).find((f) => existsSync(f));
+    const defs = [];
+    const paramDefs = [];
+    const add = (file, library) => {
+        if (!file)
+            return;
+        const r = extract(ts, file, library);
+        defs.push(...r.steps);
+        paramDefs.push(...r.params);
+    };
+    add(coreFile('params'));
+    for (const lib of coreStepNames()) {
+        if (!exclude.includes(lib))
+            add(coreFile(`${lib}.steps`), lib);
+    }
+    const projectFiles = [];
+    walk(join(project.root, 'steps'), projectFiles);
+    walk(join(project.root, 'pages'), projectFiles);
+    for (const f of projectFiles)
+        add(f);
+    const registry = new ParameterTypeRegistry();
+    for (const p of paramDefs) {
+        try {
+            registry.defineParameterType(new ParameterType(p.name, p.regexps, null, (s) => s, false, false));
+        }
+        catch {
+            /* already defined (a project re-declaring a core type) — the first one wins */
+        }
+    }
+    const usable = defs.filter((d) => {
+        try {
+            d.expression =
+                typeof d.pattern === 'string'
+                    ? new CucumberExpression(d.pattern, registry)
+                    : new RegularExpression(d.pattern, registry);
+            return true;
+        }
+        catch {
+            return false; // e.g. a parameter type defined dynamically — never guess
+        }
+    });
+    const tagExpr = new Map();
+    for (const d of usable) {
+        if (typeof d.tags === 'string' && !tagExpr.has(d.tags)) {
+            try {
+                tagExpr.set(d.tags, parseTagExpr(d.tags));
+            }
+            catch {
+                d.tags = null;
+            }
+        }
+    }
+    const describe = (d) => d.library ? `${basename(d.file)}:${d.line}` : `${rel(d.file)}:${d.line}`;
+    const originOf = (d) => (d.library ? `core library "${d.library}"` : rel(d.file));
+    // text → definitions matching it by text alone (tags applied per scenario below)
+    const byText = new Map();
+    const matching = (text) => {
+        let hit = byText.get(text);
+        if (!hit) {
+            hit = usable.filter((d) => d.expression.match(text) !== null);
+            byText.set(text, hit);
+        }
+        return hit;
+    };
+    const groups = new Map();
+    const usedAmbiguous = new Set();
+    for (const feature of features) {
+        if (feature.errors.length)
+            continue;
+        const lines = stepLines(feature.document);
+        for (const pickle of feature.pickles) {
+            const tags = pickle.tags.map((t) => t.name);
+            if (tags.includes('@skip') || tags.includes('@fixme'))
+                continue;
+            for (const step of pickle.steps) {
+                let matched = matching(step.text);
+                if (matched.length < 2)
+                    continue;
+                if (tags.length) {
+                    const tagged = matched.filter((d) => typeof d.tags === 'string' && tagExpr.get(d.tags).evaluate(tags));
+                    matched = tagged.length ? tagged : matched.filter((d) => d.tags === undefined);
+                }
+                // A tag option lint cannot read might be what separates them: say nothing.
+                if (matched.length < 2 || matched.some((d) => d.tags === null))
+                    continue;
+                const origins = [...new Set(matched.map(originOf))].sort();
+                const key = origins.join('');
+                let g = groups.get(key);
+                if (!g) {
+                    g = {
+                        defs: [],
+                        origins,
+                        libraries: [...new Set(matched.flatMap((d) => (d.library ? [d.library] : [])))].sort(),
+                        occurrences: new Map(),
+                    };
+                    groups.set(key, g);
+                }
+                const line = lines.get(step.astNodeIds[0]) ?? 0;
+                const loc = `${rel(feature.file)}:${line}`;
+                if (!g.occurrences.has(loc))
+                    g.occurrences.set(loc, { file: rel(feature.file), line, text: step.text, defs: matched });
+                for (const d of matched)
+                    usedAmbiguous.add(d);
+            }
+        }
+    }
+    const excludeHint = (libraries) => libraries.length
+        ? ` Rename or remove the project definition, or drop the library with steps.core.exclude: [${libraries.join(', ')}] in sdods.project.yaml.`
+        : ' Remove or reword one of the definitions.';
+    for (const g of groups.values()) {
+        const occ = [...g.occurrences.values()];
+        const first = occ[0];
+        const examples = occ
+            .slice(0, 3)
+            .map((o) => `"${o.text}" (${o.file}:${o.line}) → ${o.defs.map(describe).join(', ')}`)
+            .join('; ');
+        const more = occ.length > 3 ? `; and ${occ.length - 3} more` : '';
+        const where = g.origins.length === 1
+            ? `more than one definition in ${g.origins[0]}`
+            : `definitions in both ${g.origins.join(' and ')}`;
+        errors.push({
+            severity: 'error',
+            rule: 'steps/ambiguous',
+            message: `${occ.length} step(s) match ${where}; bddgen fails with "Multiple definitions matched scenario step". ` +
+                `${examples}${more}.${excludeHint(g.libraries)}`,
+            file: first.file,
+            line: first.line,
+        });
+    }
+    // The same phrasing defined twice with a project file involved, not used by any feature yet.
+    const dupes = new Map();
+    for (const d of usable) {
+        if (d.tags !== undefined)
+            continue;
+        const key = typeof d.pattern === 'string' ? `s:${d.pattern}` : `r:${d.pattern.source}`;
+        dupes.set(key, [...(dupes.get(key) ?? []), d]);
+    }
+    const dupGroups = new Map();
+    for (const set of dupes.values()) {
+        if (set.length < 2 || set.every((d) => d.library) || set.some((d) => usedAmbiguous.has(d)))
+            continue;
+        const origins = [...new Set(set.map(originOf))].sort();
+        const key = origins.join('');
+        const g = dupGroups.get(key) ?? {
+            origins,
+            libraries: [...new Set(set.flatMap((d) => (d.library ? [d.library] : [])))].sort(),
+            sets: [],
+        };
+        g.sets.push(set);
+        dupGroups.set(key, g);
+    }
+    for (const g of dupGroups.values()) {
+        const firstProject = g.sets[0].find((d) => !d.library);
+        const examples = g.sets
+            .slice(0, 3)
+            .map((set) => `"${String(set[0].pattern)}" at ${set.map(describe).join(', ')}`)
+            .join('; ');
+        const more = g.sets.length > 3 ? `; and ${g.sets.length - 3} more` : '';
+        warnings.push({
+            severity: 'warning',
+            rule: 'steps/duplicate',
+            message: `${g.sets.length} phrasing(s) defined in ${g.origins.join(' and ')}; the first feature to use one will fail generation. ` +
+                `${examples}${more}.${excludeHint(g.libraries)}`,
+            file: rel(firstProject.file),
+            line: firstProject.line,
+        });
+    }
+    return { errors, warnings };
+}
+//# sourceMappingURL=steps.js.map

package/dist/load-module.d.ts

@@ -0,0 +1,7 @@
+export declare function importProjectModule<T = Record<string, unknown>>(file: string): Promise<T>;
+/**
+ * A named export from a module loaded by {@link importProjectModule}. A CommonJS-format file (no
+ * `"type": "module"` in the project) arrives with its exports under `default`.
+ */
+export declare function namedExport<T>(mod: Record<string, unknown>, name: string): T | undefined;
+//# sourceMappingURL=load-module.d.ts.map