@sdods/core 0.7.2 → 0.8.0

package/dist/config/emulation.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Per-scenario browser emulation from tags: `@locale:<bcp47>`, `@timezone:<IANA>`,
+ * `@theme:<light|dark|no-preference>`, `@viewport:<W>x<H>` and `@device:<name>`.
+ *
+ * Six locales × dark/light used to mean twelve env yamls, because the only place a browser
+ * context's locale and colour scheme could be set was the env's `use:` block. The tags move that
+ * axis onto the scenario (or a Feature, or a tagged `Examples:` block), so one env file covers
+ * every combination.
+ *
+ * Locale and timezone are fixed when Playwright creates the browser context and cannot be
+ * changed afterwards, which is why these are tags resolved by fixtures before the context opens,
+ * rather than steps. Precedence, highest first: the tag, then the env's `use:`, then Playwright's
+ * default. `@viewport:` wins over the viewport of `@device:`.
+ *
+ * Kept pure (no fixtures, no browser) so the precedence and the validation that lint shares with
+ * the runtime are testable on their own — the `scenarioSkipReason` precedent.
+ */
+export declare const EMULATION_TAGS: readonly ["locale", "timezone", "theme", "viewport", "device"];
+export type EmulationTag = (typeof EMULATION_TAGS)[number];
+export declare const COLOR_SCHEMES: readonly ["light", "dark", "no-preference"];
+export type ColorScheme = (typeof COLOR_SCHEMES)[number];
+export interface ViewportSize {
+    width: number;
+    height: number;
+}
+export interface EmulatedDevice {
+    /** The Playwright device descriptor name, e.g. `iPhone 15`. */
+    name: string;
+    userAgent: string;
+    viewport: ViewportSize;
+    deviceScaleFactor: number;
+    isMobile: boolean;
+    hasTouch: boolean;
+}
+export interface Emulation {
+    locale?: string;
+    timezoneId?: string;
+    colorScheme?: ColorScheme;
+    viewport?: ViewportSize;
+    device?: EmulatedDevice;
+}
+/** `320x640` → `{ width: 320, height: 640 }`, or undefined when it is not a usable size. */
+export declare function parseViewport(value: string): ViewportSize | undefined;
+/**
+ * A tag value cannot contain a space, and every Playwright device name does (`iPhone 15`,
+ * `Galaxy S9+`). Names match case-insensitively with any run of spaces, hyphens or underscores
+ * treated as one separator, so `@device:iPhone-15` and `@device:iphone_15` both find `iPhone 15`.
+ */
+export declare function findDevice(value: string): string | undefined;
+/** Why `@<key>:<value>` is unusable, or undefined when it is fine. Shared by lint and runtime. */
+export declare function emulationTagProblem(key: EmulationTag, value: string): string | undefined;
+/**
+ * The emulation a scenario's tags ask for. Keys the tags do not mention are absent, so the
+ * caller falls back to whatever the env or Playwright would have used.
+ *
+ * Throws on an unusable value or on two different values for the same key: lint reports both
+ * first, and a scenario that reaches the runner anyway must fail loudly rather than run under
+ * an emulation nobody asked for.
+ */
+export declare function emulationFromTags(tags: readonly string[]): Emulation;
+/** The browser-context option values a scenario gets: tags first, then what the project resolved. */
+export interface ContextEmulationBase {
+    locale?: string;
+    timezoneId?: string;
+    colorScheme?: ColorScheme | null;
+    viewport?: ViewportSize | null;
+    userAgent?: string;
+    deviceScaleFactor?: number;
+    isMobile?: boolean;
+    hasTouch?: boolean;
+    browserName?: string;
+}
+export declare function applyEmulation<T extends ContextEmulationBase>(base: T, emulation: Emulation): Omit<T, 'browserName'>;
+//# sourceMappingURL=emulation.d.ts.map

package/dist/config/emulation.js

@@ -0,0 +1,154 @@
+import { devices } from '@playwright/test';
+import { SdodsError } from '../errors.js';
+import { parseTagValues } from './tags.js';
+/**
+ * Per-scenario browser emulation from tags: `@locale:<bcp47>`, `@timezone:<IANA>`,
+ * `@theme:<light|dark|no-preference>`, `@viewport:<W>x<H>` and `@device:<name>`.
+ *
+ * Six locales × dark/light used to mean twelve env yamls, because the only place a browser
+ * context's locale and colour scheme could be set was the env's `use:` block. The tags move that
+ * axis onto the scenario (or a Feature, or a tagged `Examples:` block), so one env file covers
+ * every combination.
+ *
+ * Locale and timezone are fixed when Playwright creates the browser context and cannot be
+ * changed afterwards, which is why these are tags resolved by fixtures before the context opens,
+ * rather than steps. Precedence, highest first: the tag, then the env's `use:`, then Playwright's
+ * default. `@viewport:` wins over the viewport of `@device:`.
+ *
+ * Kept pure (no fixtures, no browser) so the precedence and the validation that lint shares with
+ * the runtime are testable on their own — the `scenarioSkipReason` precedent.
+ */
+export const EMULATION_TAGS = ['locale', 'timezone', 'theme', 'viewport', 'device'];
+export const COLOR_SCHEMES = ['light', 'dark', 'no-preference'];
+/** `320x640` → `{ width: 320, height: 640 }`, or undefined when it is not a usable size. */
+export function parseViewport(value) {
+    const m = /^(\d{1,5})x(\d{1,5})$/.exec(value.trim());
+    if (!m)
+        return undefined;
+    const width = Number(m[1]);
+    const height = Number(m[2]);
+    return width > 0 && height > 0 ? { width, height } : undefined;
+}
+/**
+ * A tag value cannot contain a space, and every Playwright device name does (`iPhone 15`,
+ * `Galaxy S9+`). Names match case-insensitively with any run of spaces, hyphens or underscores
+ * treated as one separator, so `@device:iPhone-15` and `@device:iphone_15` both find `iPhone 15`.
+ */
+export function findDevice(value) {
+    if (value in devices)
+        return value;
+    const norm = (s) => s.toLowerCase().replace(/[\s_-]+/g, '-');
+    const wanted = norm(value);
+    return Object.keys(devices).find((name) => norm(name) === wanted);
+}
+/** Why `@<key>:<value>` is unusable, or undefined when it is fine. Shared by lint and runtime. */
+export function emulationTagProblem(key, value) {
+    switch (key) {
+        case 'locale':
+            try {
+                // Throws RangeError on anything that is not a structurally valid BCP 47 tag.
+                Intl.getCanonicalLocales(value);
+                return undefined;
+            }
+            catch {
+                return `@locale:${value} is not a BCP 47 locale (e.g. fr, fr-FR, pt-BR${value.includes('_') ? ' — use a hyphen, not an underscore' : ''}).`;
+            }
+        case 'timezone':
+            try {
+                // Accepts every IANA zone and its aliases (UTC, Etc/GMT+1) — `Intl.supportedValuesOf`
+                // lists canonical names only, so it would reject `UTC` on some runtimes.
+                new Intl.DateTimeFormat('en-US', { timeZone: value });
+                return undefined;
+            }
+            catch {
+                return `@timezone:${value} is not an IANA time zone (e.g. Europe/Paris, America/New_York, UTC).`;
+            }
+        case 'theme':
+            return COLOR_SCHEMES.includes(value)
+                ? undefined
+                : `@theme:${value} must be one of ${COLOR_SCHEMES.join(', ')}.`;
+        case 'viewport':
+            return parseViewport(value)
+                ? undefined
+                : `@viewport:${value} must be <width>x<height> in CSS pixels (e.g. @viewport:320x640).`;
+        case 'device':
+            return findDevice(value)
+                ? undefined
+                : `@device:${value} is not a Playwright device. Write the descriptor name with hyphens for spaces (e.g. @device:iPhone-15, @device:Pixel-7).`;
+    }
+}
+/**
+ * The emulation a scenario's tags ask for. Keys the tags do not mention are absent, so the
+ * caller falls back to whatever the env or Playwright would have used.
+ *
+ * Throws on an unusable value or on two different values for the same key: lint reports both
+ * first, and a scenario that reaches the runner anyway must fail loudly rather than run under
+ * an emulation nobody asked for.
+ */
+export function emulationFromTags(tags) {
+    const one = (key) => {
+        const values = [...new Set(parseTagValues(tags, key))];
+        if (values.length > 1)
+            throw new SdodsError('CONFIG_INVALID', `Conflicting tags @${key}:${values.join(` and @${key}:`)} on one scenario.`, {
+                hint: `A scenario runs in one browser context, so it takes one @${key}: value. Tags on the Feature apply to every scenario in it — remove the duplicate from the scenario or the Feature.`,
+            });
+        const value = values[0];
+        if (value === undefined)
+            return undefined;
+        const problem = emulationTagProblem(key, value);
+        if (problem)
+            throw new SdodsError('CONFIG_INVALID', problem, { hint: 'Run `sdods lint`.' });
+        return value;
+    };
+    const out = {};
+    const locale = one('locale');
+    // Canonical form (`fr-fr` → `fr-FR`), so the context and `I use the locale` agree on spelling.
+    if (locale)
+        out.locale = Intl.getCanonicalLocales(locale)[0];
+    const timezone = one('timezone');
+    if (timezone)
+        out.timezoneId = timezone;
+    const theme = one('theme');
+    if (theme)
+        out.colorScheme = theme;
+    const viewport = one('viewport');
+    if (viewport)
+        out.viewport = parseViewport(viewport);
+    const deviceTag = one('device');
+    if (deviceTag) {
+        const name = findDevice(deviceTag);
+        const d = devices[name];
+        out.device = {
+            name,
+            userAgent: d.userAgent,
+            viewport: d.viewport,
+            deviceScaleFactor: d.deviceScaleFactor,
+            isMobile: d.isMobile,
+            hasTouch: d.hasTouch,
+        };
+    }
+    return out;
+}
+export function applyEmulation(base, emulation) {
+    const { browserName, ...rest } = base;
+    const d = emulation.device;
+    return {
+        ...rest,
+        ...(emulation.locale !== undefined ? { locale: emulation.locale } : {}),
+        ...(emulation.timezoneId !== undefined ? { timezoneId: emulation.timezoneId } : {}),
+        ...(emulation.colorScheme !== undefined ? { colorScheme: emulation.colorScheme } : {}),
+        ...(d
+            ? {
+                viewport: d.viewport,
+                userAgent: d.userAgent,
+                deviceScaleFactor: d.deviceScaleFactor,
+                hasTouch: d.hasTouch,
+                // Firefox rejects `isMobile` at context creation. The engine is the run target's, so a
+                // device tag on the firefox target emulates size, agent and touch only.
+                ...(browserName === 'firefox' ? {} : { isMobile: d.isMobile }),
+            }
+            : {}),
+        ...(emulation.viewport !== undefined ? { viewport: emulation.viewport } : {}),
+    };
+}
+//# sourceMappingURL=emulation.js.map

package/dist/config/index.d.ts

@@ -7,4 +7,5 @@ export * from './resolve.js';
 export * from './registry.js';
 export * from './workspace.js';
 export * from './runner.js';
+export * from './emulation.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/config/index.js

@@ -7,4 +7,5 @@ export * from './resolve.js';
 export * from './registry.js';
 export * from './workspace.js';
 export * from './runner.js';
+export * from './emulation.js';
 //# sourceMappingURL=index.js.map

package/dist/config/runner.js

@@ -228,7 +228,10 @@ export function buildRunnerConfig(registry, sel = {}) {
                         ...browserUse(browser, p.channel),
                         baseURL: cfg.env.ui.baseUrl,
                         testIdAttribute: p.testIdAttribute,
-                        viewport: browser.startsWith('mobile') ? undefined : p.screenshots.viewport,
+                        // Mobile targets keep their device descriptor's viewport. The key must be ABSENT, not
+                        // `undefined`: Playwright treats an explicit undefined option as "use the default",
+                        // so `viewport: undefined` reset Pixel 7 and iPhone 15 to a 1280x720 desktop window.
+                        ...(browser.startsWith('mobile') ? {} : { viewport: p.screenshots.viewport }),
                         ...envUse,
                         ...evidenceUse,
                         sdods: { project: p.slug, layer, browser },

package/dist/config/tags.d.ts

@@ -5,7 +5,7 @@ export declare const RUNNER_SPECIAL_TAGS: RegExp;
 /** @deprecated Use {@link RUNNER_SPECIAL_TAGS}. Removed in the next minor. */
 export declare const PLAYWRIGHT_BDD_SPECIAL: RegExp;
 export declare const VALUE_TAG: RegExp;
-export declare const KNOWN_VALUE_TAGS: readonly ["env", "user", "data", "har", "jira", "github", "skip", "title", "flag"];
+export declare const KNOWN_VALUE_TAGS: readonly ["env", "user", "data", "har", "jira", "github", "skip", "title", "flag", "matrix", "req", "locale", "timezone", "theme", "viewport", "device"];
 /**
  * Values `@skip:<browser>` accepts. Derived from the schema rather than copied, so adding a browser
  * to `BrowserSchema` is the only edit needed — and the lint message lists the new name for free.

package/dist/config/tags.js

@@ -17,6 +17,13 @@ export const KNOWN_VALUE_TAGS = [
     'skip',
     'title',
     'flag',
+    'matrix',
+    'req',
+    'locale',
+    'timezone',
+    'theme',
+    'viewport',
+    'device',
 ];
 /**
  * Values `@skip:<browser>` accepts. Derived from the schema rather than copied, so adding a browser

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' | 'HEAL_FAILED' | 'LINT_FAILED' | 'RUN_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/test.js

@@ -2,6 +2,7 @@ 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';
@@ -197,6 +198,41 @@ export const test = base.extend({
             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,7 @@ export interface TestFixtures {
     $sdodsAnnotations: void;
     /** auto fixture: applies @env:, @skip:<browser>, @quarantine and @flag: */
     $sdodsTagGate: 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,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 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';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -8,10 +8,13 @@ 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';
 //# 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);

package/dist/load/index.d.ts

@@ -0,0 +1,4 @@
+export * from './profile.js';
+export * from './script.js';
+export * from './run.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/load/index.js

@@ -0,0 +1,4 @@
+export * from './profile.js';
+export * from './script.js';
+export * from './run.js';
+//# sourceMappingURL=index.js.map

package/dist/load/profile.d.ts

@@ -0,0 +1,22 @@
+import { type EnvConfig, type LoadProfile } from '@sdods/contracts';
+export declare const LOAD_DIR = "load";
+/** Profile names under `projects/<slug>/load/`, without the extension. */
+export declare function listLoadProfiles(projectRoot: string): string[];
+export declare function loadProfileFile(projectRoot: string, name: string): string | undefined;
+export declare function parseLoadProfile(raw: unknown, file?: string): LoadProfile;
+export declare function readLoadProfile(projectRoot: string, name: string): LoadProfile;
+/** The most virtual users the profile reaches: `vus`, or the highest stage target. */
+export declare function peakVus(profile: LoadProfile): number;
+/**
+ * Why this environment may not take this profile. Empty means it may.
+ * Checked before every real run; `--dry-run` only reports it.
+ */
+export declare function loadGuardProblems(env: EnvConfig, profile: LoadProfile): string[];
+/**
+ * The load goes to `SDODS_API_BASE_URL` when it is set. The opt-in is for the environment file, so
+ * an override that points at another host is refused unless that file sets
+ * `load.allowBaseUrlOverride: true`. Both URLs are compared without trailing slashes.
+ */
+export declare function baseUrlOverrideProblems(env: EnvConfig, envBaseUrl: string, override: string | undefined): string[];
+export declare function assertLoadAllowed(env: EnvConfig, profile: LoadProfile, extraProblems?: string[]): void;
+//# sourceMappingURL=profile.d.ts.map