@sdods/core 0.3.2 → 0.5.2

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

package/dist/load-module.js

@@ -0,0 +1,70 @@
+import { pathToFileURL } from 'node:url';
+/**
+ * Import a TypeScript module that belongs to a project (`steps/auth.ts` and friends) from outside
+ * the Playwright runner.
+ *
+ * `sdods run` loads project files through Playwright's TS loader, which transpiles full
+ * TypeScript, remaps `import './helper.js'` to `helper.ts`, and treats a file as ESM or CommonJS
+ * by its package type. A bare `import()` from a CLI command hands the file to Node's native type
+ * stripping instead, which does none of the remapping — so a helper imported the conventional way
+ * worked under `sdods run` and crashed `sdods auth capture` with "Cannot find module .../helper.js"
+ * (#86). In the workspace the gap was invisible, because bin/sdods.js registers tsx globally.
+ *
+ * tsx gives the same three behaviours as Playwright's loader. Both its ESM and CommonJS hooks are
+ * registered — a project without `"type": "module"` loads `.ts` as CommonJS, and a CommonJS
+ * `require('./helper.js')` only goes through tsx's CJS hook — and removed again once the import
+ * settles, so nothing else in the process is affected. Registrations are reference-counted so
+ * overlapping imports do not unregister each other's hooks mid-load.
+ */
+let active = 0;
+let hooks;
+async function acquire() {
+    active++;
+    hooks ??= (async () => {
+        const [esm, cjs] = await Promise.all([import('tsx/esm/api'), import('tsx/cjs/api')]);
+        const offEsm = esm.register();
+        const offCjs = cjs.register();
+        return async () => {
+            offCjs();
+            await offEsm();
+        };
+    })();
+    try {
+        await hooks;
+    }
+    catch (e) {
+        // Do not leave a rejected registration cached for every later import.
+        if (--active === 0)
+            hooks = undefined;
+        throw e;
+    }
+}
+async function releaseOne() {
+    if (--active > 0 || !hooks)
+        return;
+    const off = hooks;
+    hooks = undefined;
+    await (await off)();
+}
+export async function importProjectModule(file) {
+    await acquire();
+    try {
+        return (await import(pathToFileURL(file).href));
+    }
+    finally {
+        await releaseOne();
+    }
+}
+/**
+ * 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 function namedExport(mod, name) {
+    if (mod[name] !== undefined)
+        return mod[name];
+    const def = mod.default;
+    if (def && typeof def === 'object' && def[name] !== undefined)
+        return def[name];
+    return undefined;
+}
+//# sourceMappingURL=load-module.js.map

package/dist/logger.d.ts

@@ -1,4 +1,5 @@
 export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'step' | 'debug';
+export declare function isSecretKey(name: string): boolean;
 export declare function setLogLevel(level: LogLevel): void;
 export declare function setLogJson(enabled: boolean): void;
 export declare function getLogLevel(): LogLevel;

package/dist/logger.js

@@ -9,7 +9,11 @@ const ORDER = {
 };
 let globalLevel = process.env.SDODS_LOG_LEVEL || 'info';
 let jsonMode = process.env.SDODS_LOG_JSON === '1';
-const SECRET_KEY = /(password|secret|token|apikey|api_key|authorization|cookie)/i;
+/** Key names whose string values are credentials: config fields, header names, log fields. */
+const SECRET_KEY = /(passw(or)?d|secret|token|api[-_]?key|[-_]key$|authorization|cookie|credential)/i;
+export function isSecretKey(name) {
+    return SECRET_KEY.test(name);
+}
 export function setLogLevel(level) {
     globalLevel = level;
 }
@@ -26,9 +30,11 @@ export function redact(value, depth = 0) {
         return value.map((v) => redact(v, depth + 1));
     if (value && typeof value === 'object') {
         const out = {};
+        // Header auth (`{ type: header, name, value }`) keeps its secret under a neutral key.
+        const headerAuth = value.type === 'header';
         for (const [k, v] of Object.entries(value)) {
-            out[k] =
-                SECRET_KEY.test(k) && typeof v === 'string' && v.length > 0 ? '***' : redact(v, depth + 1);
+            const secret = SECRET_KEY.test(k) || (headerAuth && k === 'value');
+            out[k] = secret && typeof v === 'string' && v.length > 0 ? '***' : redact(v, depth + 1);
         }
         return out;
     }

package/dist/steps/a11y.steps.js

@@ -3,7 +3,7 @@ import { expect } from '@playwright/test';
 import { attachmentNames, scenarioFiles } from '@sdods/contracts';
 import './params.js';
 import { Then } from '../fixtures/test.js';
-import { render } from '../api/template.js';
+import { renderStrict } from '../api/template.js';
 import { SdodsError } from '../errors.js';
 import { Logger } from '../logger.js';
 /**
@@ -449,7 +449,7 @@ Then('the page should have no accessibility violations', async ({ page, scenario
  * an empty context happily and reports zero violations, which is indistinguishable from a pass.
  */
 Then('the page should have no accessibility violations within {string}', async ({ page, scenario, apiContext, env, $bddContext, $testInfo }, selector) => {
-    const sel = render(selector, ...scopesOf(apiContext, env));
+    const sel = renderStrict(selector, ...scopesOf(apiContext, env));
     await requireRegion(page, sel);
     const results = await runAxe(page, { include: sel });
     attachA11y({ scenario, testInfo: $testInfo, stepIndex: $bddContext.stepIndex }, results);
@@ -462,7 +462,7 @@ Then('the page should have no accessibility violations within {string}', async (
  * nothing — "or worse than banana" would otherwise be the greenest step in the suite.
  */
 Then('the page should have no accessibility violations of impact {string} or worse', async ({ page, scenario, apiContext, env, $bddContext, $testInfo }, level) => {
-    const floor = parseImpactFloor(render(level, ...scopesOf(apiContext, env)));
+    const floor = parseImpactFloor(renderStrict(level, ...scopesOf(apiContext, env)));
     const results = await runAxe(page, {});
     attachA11y({ scenario, testInfo: $testInfo, stepIndex: $bddContext.stepIndex }, results);
     assertAxeChecked(results, `on ${page.url()}`);
@@ -472,8 +472,8 @@ Then('the page should have no accessibility violations of impact {string} or wor
 /** PROVES a region carries no violation at or above a severity — the scoped form of the above. */
 Then('the page should have no accessibility violations of impact {string} or worse within {string}', async ({ page, scenario, apiContext, env, $bddContext, $testInfo }, level, selector) => {
     const scopes = scopesOf(apiContext, env);
-    const floor = parseImpactFloor(render(level, ...scopes));
-    const sel = render(selector, ...scopes);
+    const floor = parseImpactFloor(renderStrict(level, ...scopes));
+    const sel = renderStrict(selector, ...scopes);
     await requireRegion(page, sel);
     const results = await runAxe(page, { include: sel });
     attachA11y({ scenario, testInfo: $testInfo, stepIndex: $bddContext.stepIndex }, results);
@@ -489,7 +489,7 @@ Then('the page should have no accessibility violations of impact {string} or wor
  * step fails on either, because a rule that never ran cannot have passed.
  */
 Then('the page should have no accessibility violations of rule {string}', async ({ page, scenario, apiContext, env, $bddContext, $testInfo }, ruleId) => {
-    const rule = render(ruleId, ...scopesOf(apiContext, env));
+    const rule = renderStrict(ruleId, ...scopesOf(apiContext, env));
     const results = await runAxe(page, { rules: [rule] });
     attachA11y({ scenario, testInfo: $testInfo, stepIndex: $bddContext.stepIndex }, results);
     const bucket = assertRuleRan(results, rule, `on ${page.url()}`);
@@ -510,7 +510,7 @@ Then('the page should have no colour-contrast violations', async ({ page, scenar
 });
 /** PROVES one region's text meets AA contrast — for auditing a themed component in isolation. */
 Then('the page should have no colour-contrast violations within {string}', async ({ page, scenario, apiContext, env, $bddContext, $testInfo }, selector) => {
-    const sel = render(selector, ...scopesOf(apiContext, env));
+    const sel = renderStrict(selector, ...scopesOf(apiContext, env));
     await requireRegion(page, sel);
     const results = await runAxe(page, { include: sel, rules: ['color-contrast'] });
     attachA11y({ scenario, testInfo: $testInfo, stepIndex: $bddContext.stepIndex }, results);
@@ -556,7 +556,7 @@ Then('every image on the page should carry an alt attribute', async ({ page }) =
 });
 /** PROVES every image inside one region declares its alt intent — the scoped form of the above. */
 Then('every image within {string} should carry an alt attribute', async ({ page, apiContext, env }, selector) => {
-    const sel = render(selector, ...scopesOf(apiContext, env));
+    const sel = renderStrict(selector, ...scopesOf(apiContext, env));
     const gathered = await page.evaluate(gatherImages, sel);
     const images = assertGathered(assertRegion(gathered, sel), 'img elements', `within "${sel}"`);
     const missing = imagesWithoutAlt(images);
@@ -571,7 +571,7 @@ Then('every image within {string} should carry an alt attribute', async ({ page,
  * itself — axe sees a non-empty name and passes it.
  */
 Then('every icon-only control within {string} should expose an accessible name', async ({ page, apiContext, env }, selector) => {
-    const sel = render(selector, ...scopesOf(apiContext, env));
+    const sel = renderStrict(selector, ...scopesOf(apiContext, env));
     const gathered = await page.evaluate(gatherControls, sel);
     const controls = assertRegion(gathered, sel);
     const iconOnly = assertGathered(iconOnlyControls(controls), 'icon-only controls', `within "${sel}" (${controls.length} control(s) there render text)`);
@@ -588,7 +588,7 @@ Then('every icon-only control within {string} should expose an accessible name',
  * enter keyboard modality and never blurs between elements.
  */
 Then('every focusable element within {string} should show a visible focus indicator', async ({ page, apiContext, env }, selector) => {
-    const sel = render(selector, ...scopesOf(apiContext, env));
+    const sel = renderStrict(selector, ...scopesOf(apiContext, env));
     await page.keyboard.press('Tab');
     const gathered = await page.evaluate(gatherFocusIndicators, sel);
     const focusables = assertGathered(assertRegion(gathered, sel), 'focusable elements', `within "${sel}"`);