@sdods/contracts 0.7.2 → 0.9.0

package/dist/schemas/project.js

@@ -25,7 +25,18 @@ export const DataSourceSchema = z.discriminatedUnion('type', [
 export const UserPoolSchema = z.object({
     dataset: z.string(),
     roleColumn: z.string().default('role'),
-    leaseStore: z.enum(['file', 'db']).default('file'),
+    /**
+     * Where leases are recorded. Only `file` exists: O_EXCL lock files under `.sdods/leases`, which
+     * every worker on one machine sees. `db` was accepted here for a long time and silently ignored,
+     * so a sharded run that believed its machines shared leases did not (#153).
+     */
+    leaseStore: z
+        .enum(['file'], {
+        error: (issue) => issue.input === 'db'
+            ? "leaseStore 'db' was never implemented; use 'file' (see #153)"
+            : `leaseStore must be 'file' (got ${JSON.stringify(issue.input)})`,
+    })
+        .default('file'),
     leaseTtlMs: z
         .number()
         .int()
@@ -50,8 +61,26 @@ export const UserPoolSchema = z.object({
      * explicit exclusive lease even in a shared pool.
      */
     mode: z.enum(['exclusive', 'shared']).default('exclusive'),
-    /** How long to wait for a free account before failing. Was hard-coded at 30s. */
-    waitMs: z.number().int().positive().default(30_000),
+    /**
+     * How long to wait for a free account before failing. Unset, it is 30s with `leaseScope: worker`.
+     * With `leaseScope: scenario` waiting is the expected path rather than a symptom, so unset it is
+     * `leaseTtlMs` — the longest a live scenario may legitimately hold an account — and the time
+     * spent waiting is added to the scenario's timeout instead of eating into it.
+     */
+    waitMs: z.number().int().positive().optional(),
+    /**
+     * How long an exclusive lease is held.
+     *
+     * `worker` (default) — from the first scenario that asks until the Playwright worker exits. A
+     * worker keeps one account across its scenarios, which suits per-worker setup, but a role with
+     * fewer accounts than `--workers` starves every other worker: each waits `waitMs` and fails with
+     * USER_POOL_EXHAUSTED (#153).
+     *
+     * `scenario` — released when the scenario ends, including leases taken by the
+     * `I use a leased user …` steps. One account then serialises the scenarios that need it instead
+     * of starving whole workers; waiters queue in arrival order.
+     */
+    leaseScope: z.enum(['scenario', 'worker']).default('worker'),
 });
 export const AuthStrategySchema = z.enum([
     'none',
@@ -89,10 +118,22 @@ export const ProjectAuthSchema = z.object({
     })
         .optional(),
 });
+/**
+ * Settings for one named visual baseline (`the page should match the visual baseline "<name>"`).
+ * `mask` is added to the project/env `screenshots.mask`, never a replacement for it.
+ */
+export const BaselineConfigSchema = z.object({
+    mask: z.array(z.string()).optional(),
+    maxDiffPixelRatio: z.number().min(0).max(1).optional(),
+});
 export const ScreenshotConfigSchema = z.object({
     policy: z.record(z.string(), ShotPolicySchema).default({ default: 'on-failure' }),
     fullPage: z.boolean().default(false),
     mask: z.array(z.string()).default([]),
+    /** Share of pixels allowed to differ before a visual baseline check fails (0.01 = 1%). */
+    maxDiffPixelRatio: z.number().min(0).max(1).default(0.01),
+    /** Per-baseline overrides, keyed by the baseline name without `.png`. */
+    baselines: z.record(z.string(), BaselineConfigSchema).default({}),
     viewport: z
         .object({ width: z.number().int().positive(), height: z.number().int().positive() })
         .default({ width: 1280, height: 720 }),
@@ -163,6 +204,77 @@ export const EVIDENCE_DEFAULTS = {
     trace: 'on-first-retry',
     redactTraces: true,
 };
+/**
+ * Selectors the canvas steps (`canvas.steps.ts`) use to find nodes, handles, edges, node fields and
+ * badges on a graph editor. The defaults are the DOM React Flow (v11 and v12) renders; a project on
+ * another editor, or with its own markers, overrides only the keys that differ.
+ *
+ * Values are CSS selector templates. `{id}`, `{handle}`, `{source}`, `{target}`, `{field}` and
+ * `{badge}` are replaced by the step argument, escaped for a quoted CSS string, so write them inside
+ * quotes: `[data-id="{id}"]`. `{testIdAttribute}` is replaced by the project's attribute name.
+ */
+export const CANVAS_DEFAULTS = {
+    /** The editor surface; every other lookup is scoped inside it. */
+    root: '.react-flow',
+    /** Every node, for counting. */
+    nodes: '.react-flow__node',
+    /** One node by id. */
+    node: '.react-flow__node[data-id="{id}"]',
+    /** A handle, searched inside its node. */
+    handle: '.react-flow__handle[data-handleid="{handle}"]',
+    /** An edge by source and target node id. React Flow's default edge aria-label. */
+    edge: '.react-flow__edge[aria-label="Edge from {source} to {target}"]',
+    /** A field, searched inside its node. A wrapper is fine: the editable control inside it is filled. */
+    field: '[name="{field}"], [aria-label="{field}"], [{testIdAttribute}="{field}"]',
+    /** A badge, searched inside its node. */
+    badge: '[{testIdAttribute}="{badge}"]',
+    /** What a node matches once selected; `I select the node` waits for it. Empty skips the check. */
+    selected: '.selected',
+};
+const CANVAS_PLACEHOLDERS = [
+    'id',
+    'handle',
+    'source',
+    'target',
+    'field',
+    'badge',
+    'testIdAttribute',
+];
+/** A selector template that must use `required` and may use nothing but the known placeholders. */
+const canvasTemplate = (fallback, required) => z
+    .string()
+    .superRefine((value, ctx) => {
+    for (const name of required) {
+        if (!value.includes(`{${name}}`)) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `must contain the {${name}} placeholder, or every lookup matches the same element`,
+            });
+        }
+    }
+    for (const [, name] of value.matchAll(/\{(\w+)\}/g)) {
+        if (!CANVAS_PLACEHOLDERS.includes(name) ||
+            (name !== 'testIdAttribute' && !required.includes(name))) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `{${name}} is not a placeholder here; use ${required.map((r) => `{${r}}`).join(', ') || 'none'}${required.length ? ' or ' : ''}{testIdAttribute}`,
+            });
+        }
+    }
+})
+    .default(fallback);
+export const CanvasConfigSchema = z
+    .object({
+    root: canvasTemplate(CANVAS_DEFAULTS.root, []),
+    nodes: canvasTemplate(CANVAS_DEFAULTS.nodes, []),
+    node: canvasTemplate(CANVAS_DEFAULTS.node, ['id']),
+    handle: canvasTemplate(CANVAS_DEFAULTS.handle, ['handle']),
+    edge: canvasTemplate(CANVAS_DEFAULTS.edge, ['source', 'target']),
+    field: canvasTemplate(CANVAS_DEFAULTS.field, ['field']),
+    badge: canvasTemplate(CANVAS_DEFAULTS.badge, ['badge']),
+    selected: z.string().default(CANVAS_DEFAULTS.selected),
+})
+    .default({ ...CANVAS_DEFAULTS });
 /**
  * Scenarios that must pass before anything else in the run starts: probes, login, seeding.
  *
@@ -184,6 +296,37 @@ export const PerfBudgetsSchema = z.object({
     ttfbMs: z.number().positive().optional(),
     apiP95Ms: z.number().positive().optional(),
 });
+/** axe impact levels, weakest first. Mirrored by `IMPACT_ORDER` in core's a11y audit. */
+export const A11yImpactSchema = z.enum(['minor', 'moderate', 'serious', 'critical']);
+/**
+ * The audit every `@a11y` UI or hybrid scenario gets at its end.
+ *
+ * `failOn` is the weakest impact that fails the scenario: `serious` fails on serious and critical
+ * violations and reports the rest. `include` narrows the audit to these selectors, `exclude` leaves
+ * these selectors out (a third-party widget the team does not own, for instance). Both are passed
+ * to axe as they are, so a selector that matches nothing in `include` fails the audit rather than
+ * scanning an empty page.
+ */
+export const A11yConfigSchema = z.object({
+    failOn: A11yImpactSchema.default('serious'),
+    include: z.array(z.string().min(1)).default([]),
+    exclude: z.array(z.string().min(1)).default([]),
+});
+/** The env-level patch: every key optional and default-free, for the reason `EvidencePatchSchema` gives. */
+export const A11yPatchSchema = z.object({
+    failOn: A11yImpactSchema.optional(),
+    include: z.array(z.string().min(1)).optional(),
+    exclude: z.array(z.string().min(1)).optional(),
+});
+/** Branch names `integrations.github.evidence.branch` refuses: prune force-rewrites the branch. */
+export const EVIDENCE_PROTECTED_BRANCHES = [
+    'main',
+    'master',
+    'develop',
+    'development',
+    'trunk',
+    'gh-pages',
+];
 export const GitHubIntegrationSchema = z.object({
     enabled: z.boolean().default(false),
     owner: z.string().optional(),
@@ -195,6 +338,46 @@ export const GitHubIntegrationSchema = z.object({
     labels: z.array(z.string()).default(['sdods']),
     tokenEnv: z.string().default('GITHUB_TOKEN'),
     uploadToRelease: z.string().optional(),
+    /**
+     * Where issue evidence (screenshots, video, GIF preview) is hosted so it renders inline in a
+     * private repository. Absent or `host: none` keeps the links described above.
+     */
+    evidence: z
+        .object({
+        host: z.enum(['none', 'branch']).default('none'),
+        /** `owner/name`; default: the issue repository */
+        repo: z
+            .string()
+            .regex(/^[\w.-]+\/[\w.-]+$/, 'must be owner/name')
+            .optional(),
+        /**
+         * An orphan branch SDODS creates and `evidence prune` rewrites. The names people work on are
+         * refused here; the repository's default branch is refused at upload and prune time.
+         */
+        branch: z
+            .string()
+            .min(1)
+            .refine((b) => !EVIDENCE_PROTECTED_BRANCHES.includes(b.toLowerCase()), {
+            message: `must not be ${EVIDENCE_PROTECTED_BRANCHES.join(', ')}: the evidence branch is rewritten by evidence prune, which would erase that branch's history`,
+        })
+            .default('sdods-evidence'),
+        /** env var NAME of a token for the evidence repo; default: `tokenEnv` */
+        tokenEnv: z.string().optional(),
+        maxFileBytes: z
+            .number()
+            .int()
+            .positive()
+            .default(5 * 1024 * 1024),
+        maxRunBytes: z
+            .number()
+            .int()
+            .positive()
+            .default(25 * 1024 * 1024),
+        retainDays: z.number().int().positive().default(14),
+        /** an inline GIF of the video's last seconds when ffmpeg is on PATH */
+        gifPreview: z.boolean().default(true),
+    })
+        .optional(),
 });
 export const JiraIntegrationSchema = z.object({
     enabled: z.boolean().default(false),
@@ -299,6 +482,27 @@ export const ScheduleSchema = z.object({
     notify: z.array(z.enum(['github', 'jira', 'webhook'])).default([]),
     retentionRuns: z.number().int().positive().optional(),
 });
+/**
+ * Requirement traceability (`@req:<id>` tags → `sdods report traceability`).
+ *
+ * The id is opaque: SDODS does not decide whether it names a Jira story, a line in a requirements
+ * document or a clause of a regulation. That choice belongs to whoever signs the export.
+ */
+export const TraceabilitySchema = z.object({
+    /**
+     * A YAML or CSV file (relative to the project root) listing the requirement ids and titles.
+     * When set, lint rejects ids that are not in it and the export lists requirements no scenario
+     * covers.
+     */
+    requirements: z.string().min(1).optional(),
+    /** URL template for a requirement, `{id}` replaced by the id: `https://jira.example.com/browse/{id}`. */
+    link: z
+        .string()
+        .refine((s) => s.includes('{id}'), 'link must contain the {id} placeholder')
+        .optional(),
+    /** Lint fails a scenario that carries no `@req:` tag (directly or from its Feature/Rule). */
+    require: z.boolean().default(false),
+});
 /**
  * Hierarchy: organization → workspace → project → module.
  * A module is a feature area of an application (auth, inventory, checkout …) that owns a
@@ -416,6 +620,8 @@ export const ProjectConfigSchema = z.object({
     })
         .default({ core: { exclude: [] } }),
     routes: z.record(z.string(), z.string()).default({}),
+    /** Selectors for the graph-editor steps in `canvas.steps.ts`; React Flow's DOM by default. */
+    canvas: CanvasConfigSchema,
     tags: z
         .object({
         suites: z.array(z.string()).min(1).default(['smoke', 'regression', 'sanity']),
@@ -436,6 +642,8 @@ export const ProjectConfigSchema = z.object({
         policy: { default: 'on-failure' },
         fullPage: false,
         mask: [],
+        maxDiffPixelRatio: 0.01,
+        baselines: {},
         viewport: { width: 1280, height: 720 },
         onlyOnFailure: false,
     }),
@@ -462,6 +670,7 @@ export const ProjectConfigSchema = z.object({
     fullyParallel: z.boolean().default(true),
     setup: SetupSchema.optional(),
     perf: z.object({ budgets: PerfBudgetsSchema.default({}) }).default({ budgets: {} }),
+    a11y: A11yConfigSchema.default({ failOn: 'serious', include: [], exclude: [] }),
     integrations: IntegrationsSchema.default({ custom: [] }),
     mcp: McpConfigSchema.default({ servers: {} }),
     agents: AgentsConfigSchema.default({
@@ -481,6 +690,8 @@ export const ProjectConfigSchema = z.object({
         junit: z.boolean().default(false),
     })
         .default({ cucumberHtml: false, allure: false, junit: false }),
+    /** Requirement traceability: `@req:<id>` validation and the `sdods report traceability` export. */
+    traceability: TraceabilitySchema.optional(),
     /** How the CI matrix (`sdods project list --matrix`) treats this project. */
     ci: z
         .object({

package/dist/types.d.ts

@@ -33,6 +33,8 @@ export interface RunManifest {
     playwrightVersion?: string;
     exitCode?: number;
     ingestedAt?: string;
+    /** Whether the process gates passed, when the run was `--process` with gates. */
+    gatesPassed?: boolean;
 }
 export interface RunTotals {
     total: number;
@@ -142,6 +144,38 @@ export interface StepResult {
     startedAt?: string;
     finishedAt?: string;
 }
+/**
+ * One failed visual baseline check, written next to the scenario's screenshots
+ * (`<runDir>/<slug>/<fingerprint>/r<retry>/visual/<name>.failure.json`) so it survives the CI
+ * artifact upload and ingest. `sdods baselines` and the server's accept route read it.
+ */
+export interface VisualFailure {
+    /** baseline name without `.png` */
+    name: string;
+    /** the file name Playwright compared, e.g. `inventory.png` */
+    snapshot: string;
+    project: string;
+    runnerProject: string;
+    /** `process.platform` of the machine that ran the check: the baseline belongs to it */
+    platform: string;
+    fingerprint: string;
+    scenarioName: string;
+    featureUri: string;
+    retry: number;
+    stepIndex: number;
+    /** `changed`: pixels differ; `size`: dimensions differ; `missing`: no baseline yet */
+    reason: 'changed' | 'size' | 'missing';
+    /** baseline path, relative to the project root */
+    baseline: string;
+    /** image paths, relative to the run directory */
+    actual: string;
+    expected?: string;
+    diff?: string;
+    diffPixels?: number;
+    diffRatio?: number;
+    maxDiffPixelRatio: number;
+    recordedAt: string;
+}
 export type ArtifactKind = 'screenshot' | 'trace' | 'video' | 'har' | 'log' | 'report' | 'visual' | 'diff' | 'attachment';
 export type ArtifactPhase = 'before' | 'after' | 'scenario-start' | 'scenario-end' | 'failure' | 'expected' | 'actual' | 'diff';
 export interface ScreenshotArtifact {
@@ -267,6 +301,24 @@ export interface RunSummary {
         messages?: string;
         junit?: string;
     };
+    /** The process gate verdict, when the run was `--process` with gates. */
+    gates?: GateResult;
+}
+/** One evaluated process gate (`gates:` on a process). */
+export interface GateRow {
+    gate: 'minPassRate' | 'maxFlaky' | 'a11y' | 'perfBudgets';
+    /** What the process asks for, as written. */
+    threshold: string;
+    /** What the run produced. */
+    actual: string;
+    passed: boolean;
+    detail?: string;
+}
+/** Every gate a process declares, evaluated over one run. Written to `gates.json` in the run dir. */
+export interface GateResult {
+    process: string;
+    passed: boolean;
+    rows: GateRow[];
 }
 export interface Evidence {
     file: string;
@@ -411,6 +463,114 @@ export interface CoverageReport {
         uncoveredModules: string[];
     };
 }
+/** Outcome of one requirement in the chosen run. `not-covered` needs a requirements file. */
+export type TraceRequirementStatus = 'passed' | 'failed' | 'not-run' | 'not-covered';
+/** Outcome of one scenario across every runner project / example row it ran as. */
+export type TraceScenarioStatus = 'passed' | 'failed' | 'skipped' | 'not-run';
+/** The final attempt of one scenario in one runner project (and one Examples row for outlines). */
+export interface TraceResult {
+    runnerProject: string;
+    layer?: string;
+    browser?: string;
+    /** 1-based Examples row for a Scenario Outline, null for a plain scenario. */
+    exampleIndex: number | null;
+    status: SuiteStatus;
+    attempts: number;
+    /** failed at least once, then passed on a retry */
+    flaky: boolean;
+    durationMs?: number;
+    startedAt?: string;
+    finishedAt?: string;
+    error?: string;
+}
+export interface TraceScenario {
+    /** feature file, relative to the project root */
+    feature: string;
+    featureName: string;
+    line: number;
+    name: string;
+    /** effective tags: Feature + Rule + Scenario + Examples */
+    tags: string[];
+    requirements: string[];
+    status: TraceScenarioStatus;
+    results: TraceResult[];
+}
+export interface TraceRequirement {
+    id: string;
+    title?: string;
+    url?: string;
+    /**
+     * Whether the id is listed in the requirements file: `true`/`false` when one is configured,
+     * `null` when the project has none (ids are then whatever the tags say).
+     */
+    declared: boolean | null;
+    status: TraceRequirementStatus;
+    scenarios: TraceScenario[];
+}
+export interface TraceRunInfo {
+    id: string;
+    env?: string;
+    trigger?: string;
+    command?: string;
+    tagsExpr?: string;
+    startedAt?: string;
+    finishedAt?: string;
+    exitCode?: number;
+    git?: {
+        sha?: string;
+        branch?: string;
+        dirty?: boolean;
+    };
+    ci?: {
+        provider?: string;
+        runId?: string;
+        url?: string;
+    };
+    sdodsVersion?: string;
+    playwrightVersion?: string;
+    /** where scenario results were read from */
+    resultsSource: 'cucumber-messages' | 'scenario-meta' | 'none';
+}
+/**
+ * Filled in by a person, never by SDODS. Sign-off authority is human and not delegable, so the
+ * export carries the empty block and every field stays null in what the framework writes.
+ */
+export interface TraceSignOff {
+    signedBy: null;
+    role: null;
+    date: null;
+    decision: null;
+    notes: null;
+}
+export interface TraceabilityReport {
+    kind: 'sdods-traceability';
+    version: 1;
+    project: string;
+    projectName: string;
+    generatedAt: string;
+    /** requirements file, relative to the project root */
+    requirementsFile?: string;
+    run: TraceRunInfo | null;
+    requirements: TraceRequirement[];
+    /** scenarios that carry no `@req:` tag */
+    untraced: Array<Pick<TraceScenario, 'feature' | 'line' | 'name' | 'status'>>;
+    summary: {
+        requirements: number;
+        covered: number;
+        passed: number;
+        failed: number;
+        notRun: number;
+        /** null when no requirements file is configured: uncovered ids cannot be known */
+        notCovered: number | null;
+        /** ids tagged on scenarios but missing from the requirements file */
+        undeclared: number;
+        scenarios: number;
+        tracedScenarios: number;
+        untracedScenarios: number;
+    };
+    signOff: TraceSignOff;
+    notes: string[];
+}
 export interface ProjectProposal {
     slug: string;
     name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdods/contracts",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "description": "Shared schemas, identifiers and DTO types for SDODS.",
   "license": "Apache-2.0",
   "type": "module",