@sdods/core 0.7.2 → 0.9.0

package/dist/data/user-pool.js

@@ -1,4 +1,5 @@
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, statSync, unlinkSync, writeSync, } from 'node:fs';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, statSync, unlinkSync, utimesSync, writeFileSync, writeSync, } from 'node:fs';
+import { cpus } from 'node:os';
 import { join } from 'node:path';
 import { SdodsError } from '../errors.js';
 import { Logger } from '../logger.js';
@@ -82,9 +83,46 @@ export class FileLeaseStore {
         return out;
     }
 }
+/** `data.userPool.waitMs` when unset and leases are held per worker. */
+export const DEFAULT_LEASE_WAIT_MS = 30_000;
+const POLL_MS = 500;
+/** A waiter refreshes its ticket every poll; one untouched this long belongs to a waiter that is gone. */
+const TICKET_STALE_MS = 10_000;
+/**
+ * The worker count Playwright will actually use: `--workers` / `SDODS_WORKERS` when set (both land
+ * in `runtime.workers`), else Playwright's own default of half the logical cores.
+ *
+ * Every browser and layer of one `sdods run` shares this pool: the CLI starts ONE `playwright test`
+ * with a `--project` per run target, and Playwright's `workers` caps the whole invocation.
+ */
+export function effectiveWorkers(workers) {
+    return workers ?? Math.max(1, Math.floor(cpus().length / 2));
+}
+/** How long a lease request waits for a free account (see `data.userPool.waitMs`). */
+export function leaseWaitMs(pool) {
+    if (pool.waitMs !== undefined)
+        return pool.waitMs;
+    return pool.leaseScope === 'scenario' ? pool.leaseTtlMs : DEFAULT_LEASE_WAIT_MS;
+}
+/**
+ * With `leaseScope: scenario`, waiting for an account is how one account serialises the scenarios
+ * that need it, so the wait must not count against the scenario's own timeout: a scenario third in
+ * line would otherwise fail having done nothing. The timeout is raised by the longest possible wait
+ * before leasing, then settled to what was actually waited.
+ */
+export function scenarioLeaseClock(pool, testInfo) {
+    const base = testInfo.timeout;
+    if (pool?.leaseScope !== 'scenario' || pool.mode === 'shared' || base <= 0) {
+        return { settle: () => undefined };
+    }
+    const started = Date.now();
+    testInfo.setTimeout(base + leaseWaitMs(pool));
+    return { settle: () => testInfo.setTimeout(base + (Date.now() - started)) };
+}
 /**
  * Pool of accounts from the configured dataset, partitioned by role and capped by env.users.poolSize.
- * Leases are keyed by owner (`runId:shardOffset+parallelIndex`) and released on worker teardown.
+ * Leases are keyed by owner (`runId:shardOffset+parallelIndex`) and released on worker teardown, or
+ * at scenario teardown with `leaseScope: scenario`.
  */
 export class FileUserPool {
     config;
@@ -93,18 +131,28 @@ export class FileUserPool {
     log = new Logger('pool');
     leased = new Map(); // by role
     rows;
-    store;
+    storeInstance;
+    leaseDir;
     constructor(config, data, opts) {
         this.config = config;
         this.data = data;
         this.opts = opts;
-        this.store =
-            opts.store ??
-                new FileLeaseStore(join(config.runtime.artifactsDir, '..', 'leases', config.project.slug, config.env.name));
+        this.leaseDir = join(config.runtime.artifactsDir, '..', 'leases', config.project.slug, config.env.name);
+        this.storeInstance = opts.store;
+    }
+    /**
+     * Created on first use. Every scenario depends on the pool (the scenario-scope release fixture is
+     * automatic), and a project that never leases must not grow a lease directory for it.
+     */
+    get store() {
+        return (this.storeInstance ??= new FileLeaseStore(this.leaseDir));
     }
     static ownerFor(config, parallelIndex) {
         const shard = config.runtime.shard;
-        const offset = shard ? (shard.current - 1) * (config.runtime.workers ?? 1) : 0;
+        // Shards each number their workers from 0, so the offset must span a whole shard's workers.
+        // It used `workers ?? 1`, which let shard 2's worker 0 share an owner with shard 1's worker 1
+        // whenever --workers was left to Playwright's default.
+        const offset = shard ? (shard.current - 1) * effectiveWorkers(config.runtime.workers) : 0;
         return `${config.runtime.runId}:${offset + parallelIndex}`;
     }
     async users() {
@@ -161,42 +209,122 @@ export class FileUserPool {
             return user;
         }
         const ttl = pool.leaseTtlMs;
-        const waitMs = this.opts.waitMs ?? pool.waitMs;
+        const waitMs = this.opts.waitMs ?? leaseWaitMs(pool);
         const started = Date.now();
-        while (true) {
-            for (const { r, index } of candidates) {
-                const id = String(r.id ?? r.username ?? index);
-                if (await this.store.tryAcquire(id, this.opts.owner, ttl)) {
-                    const user = {
-                        id,
-                        username: String(r.username ?? id),
-                        password: String(r.password ?? ''),
-                        role,
-                        index,
-                        extra: r,
-                        leaseKey: id,
-                        owner: this.opts.owner,
-                    };
-                    this.leased.set(role, user);
-                    this.log.debug(`leased ${user.username} (${role}) for ${this.opts.owner}`);
-                    return user;
+        const ticket = this.queueTicket(role, started);
+        try {
+            while (true) {
+                // First come, first served. Without a queue the worker that just released an account won
+                // it straight back: its next scenario asks within milliseconds while every waiter polls
+                // every 500ms, so under `leaseScope: scenario` the same waiters lost round after round and
+                // failed on the timeout while the account changed hands the whole time.
+                if (ticket.ahead() < candidates.length) {
+                    for (const { r, index } of candidates) {
+                        const id = String(r.id ?? r.username ?? index);
+                        if (await this.store.tryAcquire(id, this.opts.owner, ttl)) {
+                            const user = {
+                                id,
+                                username: String(r.username ?? id),
+                                password: String(r.password ?? ''),
+                                role,
+                                index,
+                                extra: r,
+                                leaseKey: id,
+                                owner: this.opts.owner,
+                            };
+                            this.leased.set(role, user);
+                            this.log.debug(`leased ${user.username} (${role}) for ${this.opts.owner}`);
+                            return user;
+                        }
+                    }
                 }
+                if (Date.now() - started > waitMs) {
+                    const owners = await this.store.owners();
+                    throw new SdodsError('USER_POOL_EXHAUSTED', `All ${candidates.length} user(s) with role "${role}" are leased.`, {
+                        hint: `Owners: ${JSON.stringify(owners)}. Waited ${Math.round(waitMs / 1000)}s. ` +
+                            `Four ways out, in the order worth trying: (1) if these scenarios do not ` +
+                            `mutate user-scoped state, set data.userPool.mode: shared — one account ` +
+                            `then serves every worker, which is what a read-only suite needs; ` +
+                            `(2) add more accounts with role "${role}" to dataset "${pool.dataset}"; ` +
+                            `(3) set data.userPool.leaseScope: scenario, so an account is released when ` +
+                            `each scenario ends rather than when its worker exits, or raise ` +
+                            `data.userPool.waitMs (currently ${waitMs}ms); (4) lower --workers. ` +
+                            `Note env.users.poolSize slices the dataset BEFORE role filtering, so a ` +
+                            `small value can starve a role on its own.`,
+                    });
+                }
+                await new Promise((r) => setTimeout(r, POLL_MS));
+                ticket.touch();
             }
-            if (Date.now() - started > waitMs) {
-                const owners = await this.store.owners();
-                throw new SdodsError('USER_POOL_EXHAUSTED', `All ${candidates.length} user(s) with role "${role}" are leased.`, {
-                    hint: `Owners: ${JSON.stringify(owners)}. Waited ${Math.round(waitMs / 1000)}s. ` +
-                        `Four ways out, in the order worth trying: (1) if these scenarios do not ` +
-                        `mutate user-scoped state, set data.userPool.mode: shared — one account ` +
-                        `then serves every worker, which is what a read-only suite needs; ` +
-                        `(2) add more accounts with role "${role}" to dataset "${pool.dataset}"; ` +
-                        `(3) raise data.userPool.waitMs (currently ${waitMs}ms); (4) lower --workers. ` +
-                        `Note env.users.poolSize slices the dataset BEFORE role filtering, so a ` +
-                        `small value can starve a role on its own.`,
-                });
-            }
-            await new Promise((r) => setTimeout(r, 500));
         }
+        finally {
+            ticket.drop();
+        }
+    }
+    /**
+     * A place in line for `role`: an empty file named by arrival time and owner, refreshed while its
+     * waiter polls. `ahead()` counts live tickets that arrived earlier, and a waiter only tries to
+     * acquire while fewer are ahead of it than the role has accounts. A ticket nobody refreshes (its
+     * worker crashed) goes stale and stops holding the line.
+     */
+    queueTicket(role, arrivedAt) {
+        const dir = join(this.opts.queueDir ?? join(this.leaseDir, '.queue'), encodeURIComponent(role));
+        const name = `${String(arrivedAt).padStart(15, '0')}-${encodeURIComponent(this.opts.owner)}`;
+        const file = join(dir, name);
+        const write = () => {
+            try {
+                mkdirSync(dir, { recursive: true });
+                writeFileSync(file, '');
+            }
+            catch {
+                /* a queue that cannot be written degrades to unordered polling */
+            }
+        };
+        write();
+        return {
+            ahead: () => {
+                let names;
+                try {
+                    names = readdirSync(dir);
+                }
+                catch {
+                    return 0;
+                }
+                let ahead = 0;
+                for (const other of names) {
+                    if (other >= name)
+                        continue;
+                    try {
+                        if (Date.now() - statSync(join(dir, other)).mtimeMs > TICKET_STALE_MS) {
+                            unlinkSync(join(dir, other));
+                            continue;
+                        }
+                    }
+                    catch {
+                        continue; // dropped by its owner between readdir and stat
+                    }
+                    ahead++;
+                }
+                return ahead;
+            },
+            touch: () => {
+                try {
+                    const now = new Date();
+                    utimesSync(file, now, now);
+                }
+                catch {
+                    write(); // removed as stale while this worker was blocked: back in, same place
+                }
+            },
+            drop: () => {
+                try {
+                    unlinkSync(file);
+                }
+                catch {
+                    /* already gone */
+                }
+            },
+        };
     }
     async release(user) {
         // A shared user holds no lease (leaseKey is empty). Releasing it would be at
@@ -206,7 +334,9 @@ export class FileUserPool {
         this.leased.delete(user.role);
     }
     async releaseAll() {
-        await this.store.releaseAll(this.opts.owner);
+        // A store that was never created holds nothing to release.
+        if (this.storeInstance)
+            await this.storeInstance.releaseAll(this.opts.owner);
         this.leased.clear();
     }
     async status() {

package/dist/errors.d.ts

@@ -1,5 +1,5 @@
 /** Structured errors: every CLI/MCP/server surface renders `{ code, message, hint, docsUrl }`. */
-export type SdodsErrorCode = 'CONFIG_INVALID' | 'CONFIG_NOT_FOUND' | 'CONFIG_SECRET_LITERAL' | 'CONFIG_UNRESOLVED_VAR' | 'PROJECT_NOT_FOUND' | 'ENV_NOT_FOUND' | 'DATASET_NOT_FOUND' | 'DATASET_ROW_NOT_FOUND' | 'USER_POOL_EXHAUSTED' | 'HEAL_FAILED' | 'LINT_FAILED' | 'RUN_FAILED' | 'HAR_MISS' | 'DB_REQUIRED' | 'AUTH_FAILED' | 'NOT_SUPPORTED' | 'INTERNAL';
+export type SdodsErrorCode = 'CONFIG_INVALID' | 'CONFIG_NOT_FOUND' | 'CONFIG_SECRET_LITERAL' | 'CONFIG_UNRESOLVED_VAR' | 'PROJECT_NOT_FOUND' | 'ENV_NOT_FOUND' | 'DATASET_NOT_FOUND' | 'DATASET_ROW_NOT_FOUND' | 'USER_POOL_EXHAUSTED' | 'USER_POOL_TOO_SMALL' | 'HEAL_FAILED' | 'LINT_FAILED' | 'RUN_FAILED' | 'GATE_FAILED' | 'HAR_MISS' | 'DB_REQUIRED' | 'MAIL_REQUIRED' | 'MAIL_NOT_RECEIVED' | 'AUTH_FAILED' | 'NOT_SUPPORTED' | 'INTERNAL';
 export declare const DOCS_BASE_URL = "https://docs.sdods.com";
 export interface SdodsErrorOptions {
     hint?: string;

package/dist/fixtures/api-context.d.ts

@@ -1,8 +1,26 @@
 import type { ApiSnapshot } from '@sdods/contracts';
+/**
+ * A `Map` of HTTP header names to values whose names are case-insensitive, as HTTP's are.
+ *
+ * Names are stored lower-cased, so `set('X-API-Key')` followed by `delete('x-api-key')` removes
+ * the header, `get('cookie')` finds a header set as `Cookie`, and when a scenario sets the same
+ * header under two casings the last `set` wins. The client lower-cases names when it builds a
+ * request anyway, so what goes on the wire and into the evidence is unchanged.
+ *
+ * A plain `new Map(headers)` clone keeps the lower-cased names; restore it by `set`-ting each
+ * entry back into this map rather than replacing it.
+ */
+export declare class HeaderMap extends Map<string, string> {
+    set(name: string, value: string): this;
+    get(name: string): string | undefined;
+    has(name: string): boolean;
+    delete(name: string): boolean;
+}
 /** Per-scenario API state: last response, chained variables, pending headers/query. No module globals. */
 export declare class ApiContext {
     readonly vars: VarStore;
-    readonly headers: Map<string, string>;
+    /** Pending request headers. Names are case-insensitive (stored lower-cased). */
+    readonly headers: HeaderMap;
     readonly query: Map<string, string>;
     readonly history: ApiSnapshot[];
     /**

package/dist/fixtures/api-context.js

@@ -1,7 +1,34 @@
+/**
+ * A `Map` of HTTP header names to values whose names are case-insensitive, as HTTP's are.
+ *
+ * Names are stored lower-cased, so `set('X-API-Key')` followed by `delete('x-api-key')` removes
+ * the header, `get('cookie')` finds a header set as `Cookie`, and when a scenario sets the same
+ * header under two casings the last `set` wins. The client lower-cases names when it builds a
+ * request anyway, so what goes on the wire and into the evidence is unchanged.
+ *
+ * A plain `new Map(headers)` clone keeps the lower-cased names; restore it by `set`-ting each
+ * entry back into this map rather than replacing it.
+ */
+export class HeaderMap extends Map {
+    // No constructor: Map's constructor adds iterable entries through `this.set`, so they normalise too.
+    set(name, value) {
+        return super.set(name.toLowerCase(), value);
+    }
+    get(name) {
+        return super.get(name.toLowerCase());
+    }
+    has(name) {
+        return super.has(name.toLowerCase());
+    }
+    delete(name) {
+        return super.delete(name.toLowerCase());
+    }
+}
 /** Per-scenario API state: last response, chained variables, pending headers/query. No module globals. */
 export class ApiContext {
     vars = new VarStore();
-    headers = new Map();
+    /** Pending request headers. Names are case-insensitive (stored lower-cased). */
+    headers = new HeaderMap();
     query = new Map();
     history = [];
     /**

package/dist/fixtures/scenario.d.ts

@@ -17,9 +17,20 @@ export interface ScenarioInit {
 export declare class ScenarioMeta {
     readonly data: ScenarioMetaDto;
     readonly dir: string;
+    /** the run directory the scenario directory lives in */
+    readonly runDir: string;
+    /** root of the SDODS project (`projects/<slug>`) */
+    readonly projectRoot: string;
     readonly suiteTag?: string;
     constructor(init: ScenarioInit);
+    /**
+     * The first failure an after-scenario hook (`@a11y`, `@perf`) raised. Playwright marks the test
+     * failed only once every after-hook has returned, so `sdods:finalize` would otherwise record a
+     * scenario those hooks failed as passed.
+     */
+    hookFailure?: string;
     get fingerprint(): string;
+    noteFailure(message: string): void;
     file(rel: string): string;
     appendJsonl(rel: string, obj: unknown): void;
     write(): void;

package/dist/fixtures/scenario.js

@@ -7,6 +7,10 @@ import { moduleForFeature } from '../config/workspace.js';
 export class ScenarioMeta {
     data;
     dir;
+    /** the run directory the scenario directory lives in */
+    runDir;
+    /** root of the SDODS project (`projects/<slug>`) */
+    projectRoot;
     suiteTag;
     constructor(init) {
         const { config, testInfo, tags } = init;
@@ -21,6 +25,8 @@ export class ScenarioMeta {
             exampleIndex: null,
             layer,
         });
+        this.runDir = config.runtime.runDir;
+        this.projectRoot = config.project.root;
         this.dir = join(config.runtime.runDir, config.project.slug, fp, `r${testInfo.retry}`);
         this.suiteTag = suiteOfTags(tags, config.project.tags.suites.map((s) => `@${s}`));
         this.data = {
@@ -48,9 +54,18 @@ export class ScenarioMeta {
         mkdirSync(this.dir, { recursive: true });
         this.write();
     }
+    /**
+     * The first failure an after-scenario hook (`@a11y`, `@perf`) raised. Playwright marks the test
+     * failed only once every after-hook has returned, so `sdods:finalize` would otherwise record a
+     * scenario those hooks failed as passed.
+     */
+    hookFailure;
     get fingerprint() {
         return this.data.fingerprint;
     }
+    noteFailure(message) {
+        this.hookFailure ??= message;
+    }
     file(rel) {
         const f = join(this.dir, rel);
         const parent = join(f, '..');

package/dist/fixtures/test.js

@@ -2,10 +2,11 @@ import { join } from 'node:path';
 import { test as base, createBdd } from 'playwright-bdd';
 import { ProjectRegistry } from '../config/registry.js';
 import { parseTagValue, scenarioSkipReason } from '../config/tags.js';
+import { applyEmulation, emulationFromTags } from '../config/emulation.js';
 import { noopAuth } from '../auth/index.js';
 import { ApiClient, isolatedRequestFactory } from '../api/client.js';
 import { CompositeDataProvider } from '../data/provider.js';
-import { FileUserPool } from '../data/user-pool.js';
+import { FileUserPool, scenarioLeaseClock } from '../data/user-pool.js';
 import { apiHarForScenario } from '../har/hooks.js';
 import { Healer } from '../heal/healer.js';
 import { HealHistory } from '../heal/history.js';
@@ -187,16 +188,72 @@ export const test = base.extend({
     // `$sdodsTagGate` first, and it is not unused: it is here to force the ordering.
     // Leasing an account for a scenario that the tag gate is about to skip burns a
     // pool slot, and on a role with no rows it throws before the skip can happen.
-    user: async ({ $sdodsTagGate, userPool, $tags }, use, testInfo) => {
+    user: async ({ $sdodsTagGate, userPool, config, $tags }, use, testInfo) => {
         void $sdodsTagGate;
         const role = parseTagValue($tags, 'user');
-        await use(role ? await userPool.lease(role, testInfo.parallelIndex) : undefined);
+        if (!role)
+            return use(undefined);
+        const clock = scenarioLeaseClock(config.project.data.userPool, testInfo);
+        const leased = await userPool.lease(role, testInfo.parallelIndex);
+        clock.settle();
+        await use(leased);
     },
+    /**
+     * `data.userPool.leaseScope: scenario` (#153): hand back every account this worker leased once
+     * the scenario is over — the `@user:` lease above and the `I use a leased user …` steps alike.
+     * A worker runs one scenario at a time, so what it holds at teardown is exactly this scenario's.
+     *
+     * Automatic and dependent only on worker fixtures, so it is set up before and torn down after
+     * everything that could still be signed in as the account (page, context, storageState).
+     */
+    $sdodsScenarioLeases: [
+        async ({ config, userPool }, use) => {
+            await use();
+            if (config.project.data.userPool?.leaseScope === 'scenario')
+                await userPool.releaseAll();
+        },
+        { auto: true },
+    ],
     storageState: async ({ user, authCache, auth, sdods, browser, config }, use) => {
         if (!user || sdods.layer === 'api' || !config.project.auth.storageState)
             return use(undefined);
         await use(await authCache.ensure(user, auth, browser));
     },
+    // ── per-scenario emulation: @locale: @timezone: @theme: @viewport: @device: ────
+    //
+    // Mirrors `storageState` above: Playwright builds the browser context from these option
+    // fixtures, so overriding them is the one place a tag can reach the context BEFORE it opens —
+    // which locale and timezone require, because neither can change on a live context. Each
+    // override takes its own previous value (the env's `use:` via the runner project, or
+    // Playwright's default) and replaces it only when the scenario is tagged, so tags win over the
+    // env and an untagged scenario is untouched.
+    $sdodsEmulation: async ({ $tags }, use) => {
+        await use(emulationFromTags($tags));
+    },
+    locale: async ({ locale, $sdodsEmulation }, use) => {
+        await use(applyEmulation({ locale }, $sdodsEmulation).locale);
+    },
+    timezoneId: async ({ timezoneId, $sdodsEmulation }, use) => {
+        await use(applyEmulation({ timezoneId }, $sdodsEmulation).timezoneId);
+    },
+    colorScheme: async ({ colorScheme, $sdodsEmulation }, use) => {
+        await use(applyEmulation({ colorScheme }, $sdodsEmulation).colorScheme);
+    },
+    viewport: async ({ viewport, $sdodsEmulation }, use) => {
+        await use(applyEmulation({ viewport }, $sdodsEmulation).viewport);
+    },
+    userAgent: async ({ userAgent, $sdodsEmulation }, use) => {
+        await use(applyEmulation({ userAgent }, $sdodsEmulation).userAgent);
+    },
+    deviceScaleFactor: async ({ deviceScaleFactor, $sdodsEmulation }, use) => {
+        await use(applyEmulation({ deviceScaleFactor }, $sdodsEmulation).deviceScaleFactor);
+    },
+    hasTouch: async ({ hasTouch, $sdodsEmulation }, use) => {
+        await use(applyEmulation({ hasTouch }, $sdodsEmulation).hasTouch);
+    },
+    isMobile: async ({ isMobile, browserName, $sdodsEmulation }, use) => {
+        await use(applyEmulation({ isMobile, browserName }, $sdodsEmulation).isMobile);
+    },
     heal: async ({ config, healHistory, scenario, $bddContext }, use, testInfo) => {
         await use(new Healer({
             config: config.project.heal,

package/dist/fixtures/types.d.ts

@@ -1,4 +1,5 @@
 import type { BrowserName, Layer } from '@sdods/contracts';
+import type { Emulation } from '../config/emulation.js';
 import type { ProjectRegistry } from '../config/registry.js';
 import type { HarMode, ResolvedConfig } from '../config/resolve.js';
 import type { EnvConfig } from '@sdods/contracts';
@@ -48,5 +49,9 @@ export interface TestFixtures {
     $sdodsAnnotations: void;
     /** auto fixture: applies @env:, @skip:<browser>, @quarantine and @flag: */
     $sdodsTagGate: void;
+    /** auto fixture: releases the scenario's pool leases when `leaseScope: scenario` */
+    $sdodsScenarioLeases: void;
+    /** What the scenario's @locale: @timezone: @theme: @viewport: @device: tags ask for. */
+    $sdodsEmulation: Emulation;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/index.d.ts

@@ -8,11 +8,15 @@ export * from './heal/index.js';
 export * from './shots/index.js';
 export * from './lint/index.js';
 export * from './evidence/index.js';
+export * from './mail/index.js';
 export { BasePage } from './pages/base-page.js';
 export { PageRegistry } from './fixtures/pages.js';
 export { AuthStateCache } from './fixtures/auth.js';
 export { ScenarioMeta } from './fixtures/scenario.js';
+export { HeaderMap } from './fixtures/api-context.js';
 export type { TestFixtures, WorkerFixtures, SdodsOption } from './fixtures/types.js';
 export { coreStepsGlob, coreStepsPatterns, coreStepNames, coreStepsDir } from './steps/glob.js';
 export { VERSION } from './version.js';
+export * from './matrix/index.js';
+export * from './quality/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -8,10 +8,14 @@ export * from './heal/index.js';
 export * from './shots/index.js';
 export * from './lint/index.js';
 export * from './evidence/index.js';
+export * from './mail/index.js';
 export { BasePage } from './pages/base-page.js';
 export { PageRegistry } from './fixtures/pages.js';
 export { AuthStateCache } from './fixtures/auth.js';
 export { ScenarioMeta } from './fixtures/scenario.js';
+export { HeaderMap } from './fixtures/api-context.js';
 export { coreStepsGlob, coreStepsPatterns, coreStepNames, coreStepsDir } from './steps/glob.js';
 export { VERSION } from './version.js';
+export * from './matrix/index.js';
+export * from './quality/index.js';
 //# sourceMappingURL=index.js.map

package/dist/lint/index.js

@@ -3,8 +3,11 @@ 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 { emulationTagProblem } from '../config/emulation.js';
 import { parseFeatureFile, scenariosOf } from './gherkin.js';
+import { projectRequirements } from '../analyze/traceability.js';
 import { checkStepAmbiguity } from './steps.js';
+import { ROLES_MATRIX_FILE, planMatrixExpansion } from '../matrix/index.js';
 export * from './gherkin.js';
 export function listFeatureFiles(root) {
     const out = [];
@@ -32,6 +35,21 @@ export async function lintProject(opts) {
     const warnings = [];
     const rel = (f) => relative(project.root, f).replace(/\\/g, '/');
     const parsedFeatures = [];
+    const matrixPlan = planMatrixExpansion(project, files);
+    // `@req:<id>` is opaque unless the project lists its requirements; then an id must be in the list.
+    let declaredReqs = null;
+    try {
+        const defs = projectRequirements(project);
+        declaredReqs = defs ? new Set(defs.map((d) => d.id)) : null;
+    }
+    catch (e) {
+        errors.push({
+            severity: 'error',
+            rule: 'traceability/requirements',
+            message: e.message,
+            file: 'sdods.project.yaml',
+        });
+    }
     for (const file of files) {
         const parsed = parseFeatureFile(file);
         parsedFeatures.push(parsed);
@@ -158,6 +176,31 @@ export async function lintProject(opts) {
                                     ...loc,
                                 });
                             break;
+                        case 'matrix':
+                            if (!matrixPlan.loaded)
+                                errors.push({
+                                    severity: 'error',
+                                    rule: 'tags/matrix',
+                                    message: `@matrix:${value} needs a ${ROLES_MATRIX_FILE} in the project.`,
+                                    ...loc,
+                                });
+                            else if (!matrixPlan.loaded.declared.includes(value))
+                                errors.push({
+                                    severity: 'error',
+                                    rule: 'tags/matrix',
+                                    message: `@matrix:${value} is not a matrix in ${ROLES_MATRIX_FILE} (${matrixPlan.loaded.declared.join(', ') || 'none'}).`,
+                                    ...loc,
+                                });
+                            break;
+                        case 'req':
+                            if (declaredReqs && !declaredReqs.has(value))
+                                errors.push({
+                                    severity: 'error',
+                                    rule: 'tags/req',
+                                    message: `@req:${value} is not listed in ${project.traceability?.requirements}.`,
+                                    ...loc,
+                                });
+                            break;
                         case 'skip':
                             if (!BROWSERS_FOR_SKIP.includes(value))
                                 errors.push({
@@ -167,6 +210,28 @@ export async function lintProject(opts) {
                                     ...loc,
                                 });
                             break;
+                        case 'locale':
+                        case 'timezone':
+                        case 'theme':
+                        case 'viewport':
+                        case 'device': {
+                            const problem = emulationTagProblem(key, value);
+                            if (problem)
+                                errors.push({ severity: 'error', rule: `tags/${key}`, message: problem, ...loc });
+                            // One browser context per scenario, so one value per key (Feature tags included).
+                            // Outlines are exempt: their tag list folds in every Examples block, and one block
+                            // per locale (`@locale:fr` / `@locale:de`) is exactly the pattern these tags enable.
+                            // The runner still refuses a real conflict on a single example.
+                            const distinct = [...new Set(sc.tags.filter((t) => t.startsWith(`@${key}:`)))];
+                            if (!sc.isOutline && distinct.length > 1 && distinct[0] === tag)
+                                errors.push({
+                                    severity: 'error',
+                                    rule: `tags/${key}`,
+                                    message: `Conflicting ${distinct.join(' and ')}: a scenario takes one @${key}: value.`,
+                                    ...loc,
+                                });
+                            break;
+                        }
                         default:
                             if (!KNOWN_VALUE_TAGS.includes(key))
                                 warnings.push({
@@ -185,6 +250,14 @@ export async function lintProject(opts) {
                     ...loc,
                 });
             }
+            if (project.traceability?.require && !sc.tags.some((t) => t.startsWith('@req:'))) {
+                errors.push({
+                    severity: 'error',
+                    rule: 'tags/req-missing',
+                    message: 'Scenario carries no @req:<id> tag (traceability.require is on). Tag the scenario, or its Feature to cover every scenario in the file.',
+                    ...loc,
+                });
+            }
             if (mod) {
                 const missing = mod.tags.filter((t) => !sc.tags.includes(t));
                 if (missing.length)
@@ -216,6 +289,19 @@ export async function lintProject(opts) {
                 seen.set(key, sc.line);
         }
     }
+    // Role matrix (#118): the yaml, its roles and pool accounts, template placement, and staleness.
+    for (const p of [...matrixPlan.problems, ...matrixPlan.files.flatMap((f) => f.problems)]) {
+        const { severity, rule, message, file, line } = p;
+        (severity === 'error' ? errors : warnings).push({ severity, rule, message, file, line });
+    }
+    for (const f of matrixPlan.files.filter((x) => x.changed))
+        warnings.push({
+            severity: 'warning',
+            rule: 'matrix/stale',
+            message: `Generated Examples are out of date with ${ROLES_MATRIX_FILE}; run \`sdods matrix expand -p ${project.slug}\`.`,
+            file: f.path,
+            line: 1,
+        });
     // A phrasing matched by two definitions stops bddgen generating anything (#60).
     const ambiguity = await checkStepAmbiguity({ project, features: parsedFeatures });
     errors.push(...ambiguity.errors);