@sdods/core 0.7.2 → 0.9.0

package/dist/a11y/audit.d.ts

@@ -0,0 +1,88 @@
+import type { Page } from '@playwright/test';
+/**
+ * The axe audit itself, shared by the explicit accessibility steps (`steps/a11y.steps.ts`) and the
+ * end-of-scenario audit every `@a11y` scenario gets (`quality/hooks.ts`).
+ *
+ * It lives outside the step file on purpose. A step file registers its phrases when it is imported,
+ * and a project can switch a whole core library off with `steps.core.exclude: [a11y]` because its
+ * own steps already use those phrases. If the tag hook imported the step file, it would register
+ * those phrases again behind the project's back and bring back the collision it had excluded.
+ */
+/**
+ * Structural subset of axe-core's result types. Declared locally rather than imported from
+ * `axe-core`: that package is a transitive dependency of `@axe-core/playwright`, not a direct
+ * dependency of this one, so importing its types would couple the whole step library's
+ * compilation to a package a consumer may not have installed.
+ */
+export interface A11yViolationNode {
+    target: unknown[];
+    html?: string;
+    failureSummary?: string;
+}
+export interface A11yViolation {
+    id: string;
+    impact?: string | null;
+    help?: string;
+    helpUrl?: string;
+    nodes: A11yViolationNode[];
+}
+export interface A11yResults {
+    violations: A11yViolation[];
+    passes: {
+        id: string;
+    }[];
+    incomplete: {
+        id: string;
+    }[];
+    inapplicable: {
+        id: string;
+    }[];
+    url?: string;
+}
+/** axe impact levels, weakest first. `impact: null` is treated as `minor`. */
+export declare const IMPACT_ORDER: readonly ["minor", "moderate", "serious", "critical"];
+/**
+ * WCAG 2.0/2.1/2.2 level A and AA, and deliberately nothing else. axe's `best-practice` tag set
+ * changes between axe releases, so including it would let the same unchanged page pass one week
+ * and fail the next — a step whose verdict moves on its own teaches teams to ignore it.
+ */
+export declare const WCAG_AA_TAGS: string[];
+/** Rank of an axe impact level; an absent impact ranks as `minor` rather than vanishing. */
+export declare function impactRank(impact: string | null | undefined): number;
+/** Rejects an impact level the feature file invented, instead of silently matching nothing. */
+export declare function parseImpactFloor(level: string): number;
+export declare function violationsAtOrAbove(violations: A11yViolation[], floor: number): A11yViolation[];
+/** Human-readable violation list: rule, impact, help text and the first few offending nodes. */
+export declare function describeViolations(violations: A11yViolation[]): string;
+/**
+ * PROVES the audit actually executed. axe reporting zero violations is indistinguishable from
+ * axe never having run: a nonce'd CSP that blocks the injected source, an `about:blank` page, or
+ * an `include` that matched nothing all produce an empty, green-looking result. If no rule landed
+ * in passes, violations or incomplete, then nothing was examined and the verdict means nothing.
+ */
+export declare function assertAxeChecked(results: A11yResults, where: string): void;
+export interface AxeRunOptions {
+    include?: string | string[];
+    exclude?: string[];
+    tags?: string[];
+    rules?: string[];
+}
+/**
+ * Runs axe through `@axe-core/playwright`, which injects the source with `page.evaluate` rather
+ * than `addScriptTag`. That matters: an app serving a nonce'd CSP blocks an injected `<script>`
+ * silently, and the audit would report zero violations because it never ran.
+ *
+ * The import is lazy so a project that never audits does not need the dependency — a top-level
+ * import would fail the load of every step file that reaches this module.
+ */
+export declare function runAxe(page: Page, opts: AxeRunOptions): Promise<A11yResults>;
+/** The file writer and attacher both audits use; the name and path are the caller's. */
+export declare function writeAndAttachJson(testInfo: {
+    attach(name: string, opts: {
+        path: string;
+        contentType: string;
+    }): Promise<void>;
+}, name: string, file: string, body: unknown): Promise<void>;
+export declare function markPageAudited(scenario: object, url: string): void;
+export declare function wasPageAudited(scenario: object, url: string): boolean;
+//# sourceMappingURL=audit.d.ts.map

package/dist/a11y/audit.js

@@ -0,0 +1,134 @@
+import { writeFileSync } from 'node:fs';
+import { SdodsError } from '../errors.js';
+/** axe impact levels, weakest first. `impact: null` is treated as `minor`. */
+export const IMPACT_ORDER = ['minor', 'moderate', 'serious', 'critical'];
+/**
+ * WCAG 2.0/2.1/2.2 level A and AA, and deliberately nothing else. axe's `best-practice` tag set
+ * changes between axe releases, so including it would let the same unchanged page pass one week
+ * and fail the next — a step whose verdict moves on its own teaches teams to ignore it.
+ */
+export const WCAG_AA_TAGS = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'];
+/* ── pure judges ───────────────────────────────────────────────────────── */
+/** Rank of an axe impact level; an absent impact ranks as `minor` rather than vanishing. */
+export function impactRank(impact) {
+    const i = IMPACT_ORDER.indexOf((impact ?? 'minor'));
+    return i === -1 ? 0 : i;
+}
+/** Rejects an impact level the feature file invented, instead of silently matching nothing. */
+export function parseImpactFloor(level) {
+    const i = IMPACT_ORDER.indexOf(level);
+    if (i === -1)
+        throw new SdodsError('CONFIG_INVALID', `"${level}" is not an axe impact level.`, {
+            hint: `Use one of: ${IMPACT_ORDER.join(', ')}.`,
+        });
+    return i;
+}
+export function violationsAtOrAbove(violations, floor) {
+    return violations.filter((v) => impactRank(v.impact) >= floor);
+}
+/** Human-readable violation list: rule, impact, help text and the first few offending nodes. */
+export function describeViolations(violations) {
+    return violations
+        .map((v) => {
+        const nodes = v.nodes ?? [];
+        const shown = nodes
+            .slice(0, 3)
+            .map((n) => (Array.isArray(n.target) ? n.target.join(' ') : String(n.target)))
+            .join(' | ');
+        const more = nodes.length > 3 ? ` (+${nodes.length - 3} more node(s))` : '';
+        return `${v.id} [${v.impact ?? 'minor'}] ${v.help ?? ''} → ${nodes.length} node(s): ${shown}${more}`;
+    })
+        .join('\n');
+}
+/**
+ * PROVES the audit actually executed. axe reporting zero violations is indistinguishable from
+ * axe never having run: a nonce'd CSP that blocks the injected source, an `about:blank` page, or
+ * an `include` that matched nothing all produce an empty, green-looking result. If no rule landed
+ * in passes, violations or incomplete, then nothing was examined and the verdict means nothing.
+ */
+export function assertAxeChecked(results, where) {
+    const checked = (results.passes?.length ?? 0) +
+        (results.violations?.length ?? 0) +
+        (results.incomplete?.length ?? 0);
+    if (checked === 0)
+        throw new SdodsError('RUN_FAILED', `axe examined nothing ${where}; the audit proves nothing.`, {
+            hint: 'The page may be blank, the scoped selector may match an empty element, or a Content-Security-Policy may have blocked axe from running. Open the attached sdods/a11y JSON to see what axe reported.',
+        });
+}
+/**
+ * Runs axe through `@axe-core/playwright`, which injects the source with `page.evaluate` rather
+ * than `addScriptTag`. That matters: an app serving a nonce'd CSP blocks an injected `<script>`
+ * silently, and the audit would report zero violations because it never ran.
+ *
+ * The import is lazy so a project that never audits does not need the dependency — a top-level
+ * import would fail the load of every step file that reaches this module.
+ */
+export async function runAxe(page, opts) {
+    let AxeBuilder;
+    try {
+        const mod = await import('@axe-core/playwright');
+        // Named export first: the package exports the class as both `AxeBuilder` and `default`, and a
+        // CJS interop path can hand `default` back as the namespace object rather than the class.
+        AxeBuilder = (mod.AxeBuilder ?? mod.default);
+    }
+    catch (cause) {
+        throw new SdodsError('NOT_SUPPORTED', 'Accessibility audits need @axe-core/playwright.', {
+            hint: 'Install it in the project that runs these steps: `npm i -D @axe-core/playwright`.',
+            cause,
+        });
+    }
+    const include = typeof opts.include === 'string' ? [opts.include] : (opts.include ?? []);
+    const builder = new AxeBuilder({ page });
+    for (const sel of include)
+        builder.include(sel);
+    for (const sel of opts.exclude ?? [])
+        builder.exclude(sel);
+    // withTags and withRules are mutually exclusive in axe-core; never set both.
+    if (opts.rules)
+        builder.withRules(opts.rules);
+    else
+        builder.withTags(opts.tags ?? WCAG_AA_TAGS);
+    try {
+        return await builder.analyze();
+    }
+    catch (cause) {
+        // axe raises "unknown rule `x` in options.runOnly" for a rule id that does not exist, and
+        // "No elements found for include in page Context" for a selector that matched nothing. Both
+        // are defects in the step rather than in the page under test, so both are re-raised as such.
+        const message = cause instanceof Error ? cause.message : String(cause);
+        if (/unknown rule/i.test(message))
+            throw new SdodsError('CONFIG_INVALID', `axe rejected the rule id: ${message}`, {
+                hint: 'Check the rule id against https://dequeuniversity.com/rules/axe.',
+                cause,
+            });
+        if (/no elements found for include/i.test(message))
+            throw new SdodsError('RUN_FAILED', `axe found nothing to scan: ${message}`, {
+                hint: `The selector "${include.join(', ')}" matched no element by the time axe ran. Wait for the region to render first, or fix the selector.`,
+                cause,
+            });
+        throw new SdodsError('RUN_FAILED', `axe failed to analyse the page: ${message}`, { cause });
+    }
+}
+/** The file writer and attacher both audits use; the name and path are the caller's. */
+export async function writeAndAttachJson(testInfo, name, file, body) {
+    writeFileSync(file, JSON.stringify(body, null, 2));
+    await testInfo.attach(name, { path: file, contentType: 'application/json' });
+}
+/* ── which URLs a scenario has already audited ─────────────────────────── */
+/**
+ * Whole-page audits an explicit step already ran in this scenario, by URL. The `@a11y` tag audit
+ * skips a URL listed here: the author wrote the step, chose its threshold, and it has already passed
+ * or failed. Scoped (`within …`) and single-rule audits are not recorded, because they did not look
+ * at the whole page. Keyed on the per-test `scenario` object, so nothing leaks between tests.
+ */
+const audited = new WeakMap();
+export function markPageAudited(scenario, url) {
+    let set = audited.get(scenario);
+    if (!set)
+        audited.set(scenario, (set = new Set()));
+    set.add(url);
+}
+export function wasPageAudited(scenario, url) {
+    return audited.get(scenario)?.has(url) ?? false;
+}
+//# sourceMappingURL=audit.js.map

package/dist/analyze/index.d.ts

@@ -4,4 +4,6 @@ export { proposeProject, slugify, type ProposeOptions } from './propose.js';
 export { applyProposal, importPlaywrightSpecs, type ApplyOptions, type ApplyResult, } from './apply.js';
 export { computeCoverage, parseFeatures, pomRouteSteps, type CoverageOptions } from './coverage.js';
 export * from './detectors.js';
+export { REQ_TAG, buildTraceabilityReport, latestRunFor, loadRequirements, projectRequirements, readRunManifest, readRunResults, requirementUrl, traceScenarios, type RequirementDef, type RunAttempt, type RunResults, type TraceabilityOptions, } from './traceability.js';
+export { TRACEABILITY_FORMATS, renderTraceability, type TraceabilityFormat, } from './traceability-render.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/analyze/index.js

@@ -4,4 +4,6 @@ export { proposeProject, slugify } from './propose.js';
 export { applyProposal, importPlaywrightSpecs, } from './apply.js';
 export { computeCoverage, parseFeatures, pomRouteSteps } from './coverage.js';
 export * from './detectors.js';
+export { REQ_TAG, buildTraceabilityReport, latestRunFor, loadRequirements, projectRequirements, readRunManifest, readRunResults, requirementUrl, traceScenarios, } from './traceability.js';
+export { TRACEABILITY_FORMATS, renderTraceability, } from './traceability-render.js';
 //# sourceMappingURL=index.js.map

package/dist/analyze/traceability-render.d.ts

@@ -0,0 +1,5 @@
+import type { TraceabilityReport } from '@sdods/contracts';
+export declare const TRACEABILITY_FORMATS: readonly ["json", "csv", "md", "html"];
+export type TraceabilityFormat = (typeof TRACEABILITY_FORMATS)[number];
+export declare function renderTraceability(report: TraceabilityReport, format: TraceabilityFormat): string;
+//# sourceMappingURL=traceability-render.d.ts.map

package/dist/analyze/traceability-render.js

@@ -0,0 +1,254 @@
+export const TRACEABILITY_FORMATS = ['json', 'csv', 'md', 'html'];
+const SIGN_OFF_FIELDS = [
+    ['signedBy', 'Signed by'],
+    ['role', 'Role'],
+    ['date', 'Date'],
+    ['decision', 'Decision'],
+    ['notes', 'Notes'],
+];
+export function renderTraceability(report, format) {
+    switch (format) {
+        case 'json':
+            return `${JSON.stringify(report, null, 2)}\n`;
+        case 'csv':
+            return renderCsv(report);
+        case 'md':
+            return renderMarkdown(report);
+        case 'html':
+            return renderHtml(report);
+    }
+}
+const resultLabel = (r) => `${r.runnerProject}${r.exampleIndex != null ? ` #${r.exampleIndex}` : ''}: ${r.status}${r.flaky ? ' (flaky)' : ''}`;
+const duration = (ms) => (ms == null ? '' : `${(ms / 1000).toFixed(1)}s`);
+function runLines(report) {
+    const run = report.run;
+    if (!run)
+        return [['Run', 'none (static matrix)']];
+    const git = run.git?.sha
+        ? `${run.git.sha}${run.git.branch ? ` (${run.git.branch})` : ''}${run.git.dirty ? ', uncommitted changes' : ''}`
+        : '';
+    return [
+        ['Run', run.id],
+        ['Environment', run.env ?? ''],
+        ['Started', run.startedAt ?? ''],
+        ['Finished', run.finishedAt ?? ''],
+        ['Exit code', run.exitCode == null ? '' : String(run.exitCode)],
+        ['Git', git],
+        ['SDODS version', run.sdodsVersion ?? ''],
+        ['Tags', run.tagsExpr ?? ''],
+        ['CI', run.ci?.url ?? ''],
+        ['Results from', run.resultsSource],
+    ].filter(([, v]) => v !== '');
+}
+function summaryLines(report) {
+    const s = report.summary;
+    return [
+        ['Requirements', String(s.requirements)],
+        ['Covered', String(s.covered)],
+        ['Passed', String(s.passed)],
+        ['Failed', String(s.failed)],
+        ['Not run', String(s.notRun)],
+        ['Not covered', s.notCovered == null ? 'unknown (no requirements file)' : String(s.notCovered)],
+        ['Undeclared ids', String(s.undeclared)],
+        ['Scenarios', `${s.scenarios} (${s.tracedScenarios} traced, ${s.untracedScenarios} untraced)`],
+    ];
+}
+// ── Markdown ─────────────────────────────────────────────────────────────────
+const md = (s) => s.replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+function mdTable(head, rows) {
+    return [
+        `| ${head.join(' | ')} |`,
+        `| ${head.map(() => '---').join(' | ')} |`,
+        ...rows.map((r) => `| ${r.map(md).join(' | ')} |`),
+    ].join('\n');
+}
+function renderMarkdown(report) {
+    const out = [];
+    out.push(`# Traceability: ${md(report.projectName)} (${report.project})`, '');
+    out.push(`Generated ${report.generatedAt}.`, '');
+    out.push(mdTable(['Field', 'Value'], runLines(report)), '');
+    out.push('## Summary', '', mdTable(['Field', 'Value'], summaryLines(report)), '');
+    out.push('## Requirements', '');
+    out.push(report.requirements.length
+        ? mdTable(['Requirement', 'Title', 'Status', 'Scenarios'], report.requirements.map((r) => [
+            r.url ? `[${r.id}](${r.url})` : r.id,
+            `${r.title ?? ''}${r.declared === false ? ' (not in requirements file)' : ''}`,
+            r.status,
+            String(r.scenarios.length),
+        ]))
+        : 'No requirements: no scenario carries an `@req:<id>` tag and no requirements file is configured.', '');
+    for (const r of report.requirements) {
+        out.push(`### ${md(r.id)}${r.title ? `: ${md(r.title)}` : ''}`, '');
+        out.push(`Status: **${r.status}**`, '');
+        if (!r.scenarios.length) {
+            out.push('No scenario covers this requirement.', '');
+            continue;
+        }
+        out.push(scenarioTable(r.scenarios), '');
+    }
+    if (report.untraced.length) {
+        out.push('## Scenarios without a requirement', '');
+        out.push(mdTable(['Scenario', 'Location', 'Status'], report.untraced.map((s) => [s.name, `${s.feature}:${s.line}`, s.status])), '');
+    }
+    out.push('## Notes', '', ...report.notes.map((n) => `- ${n}`), '');
+    out.push('## Sign-off', '');
+    out.push('To be completed by a person. SDODS does not fill in this section.', '');
+    out.push(mdTable(['Field', 'Value'], SIGN_OFF_FIELDS.map(([, label]) => [label, ''])), '');
+    return out.join('\n');
+}
+function scenarioTable(scenarios) {
+    return mdTable(['Scenario', 'Location', 'Tags', 'Status', 'Results', 'Duration'], scenarios.map((s) => [
+        s.name,
+        `${s.feature}:${s.line}`,
+        s.tags.join(' '),
+        s.status,
+        s.results.map(resultLabel).join('; '),
+        duration(s.results.reduce((n, r) => n + (r.durationMs ?? 0), 0) || undefined),
+    ]));
+}
+// ── CSV ──────────────────────────────────────────────────────────────────────
+const csvCell = (v) => {
+    const s = v == null ? '' : String(v);
+    return /[",\r\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+};
+const csvRow = (cells) => cells.map(csvCell).join(',');
+/**
+ * One row per requirement × scenario × result, so a spreadsheet can filter and pivot it. The
+ * sign-off block follows after an empty line, with its values left blank.
+ */
+function renderCsv(report) {
+    const run = report.run;
+    const head = [
+        'requirement_id',
+        'requirement_title',
+        'requirement_url',
+        'declared',
+        'requirement_status',
+        'feature',
+        'line',
+        'scenario',
+        'tags',
+        'scenario_status',
+        'runner_project',
+        'browser',
+        'example',
+        'result_status',
+        'attempts',
+        'flaky',
+        'duration_ms',
+        'finished_at',
+        'run_id',
+        'env',
+        'git_sha',
+        'sdods_version',
+    ];
+    const runCells = [run?.id, run?.env, run?.git?.sha, run?.sdodsVersion];
+    const rows = [csvRow(head)];
+    for (const r of report.requirements) {
+        const reqCells = [r.id, r.title, r.url, r.declared == null ? '' : r.declared, r.status];
+        if (!r.scenarios.length) {
+            rows.push(csvRow([...reqCells, '', '', '', '', '', '', '', '', '', '', '', '', '', ...runCells]));
+            continue;
+        }
+        for (const s of r.scenarios) {
+            const scCells = [s.feature, s.line, s.name, s.tags.join(' '), s.status];
+            if (!s.results.length) {
+                rows.push(csvRow([...reqCells, ...scCells, '', '', '', '', '', '', '', '', ...runCells]));
+                continue;
+            }
+            for (const res of s.results) {
+                rows.push(csvRow([
+                    ...reqCells,
+                    ...scCells,
+                    res.runnerProject,
+                    res.browser,
+                    res.exampleIndex,
+                    res.status,
+                    res.attempts,
+                    res.flaky,
+                    res.durationMs,
+                    res.finishedAt,
+                    ...runCells,
+                ]));
+            }
+        }
+    }
+    rows.push('', csvRow(['sign_off', 'value']));
+    for (const [key] of SIGN_OFF_FIELDS)
+        rows.push(csvRow([key, '']));
+    return `${rows.join('\n')}\n`;
+}
+// ── HTML ─────────────────────────────────────────────────────────────────────
+const esc = (s) => String(s ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+const safeHref = (url) => (/^https?:\/\//i.test(url) ? esc(url) : '');
+const badge = (status) => `<span class="st st-${esc(status)}">${esc(status)}</span>`;
+function renderHtml(report) {
+    const kv = (rows) => `<table class="kv">${rows.map(([k, v]) => `<tr><th>${esc(k)}</th><td>${esc(v)}</td></tr>`).join('')}</table>`;
+    const reqLink = (id, url) => url && safeHref(url) ? `<a href="${safeHref(url)}">${esc(id)}</a>` : esc(id);
+    const overview = report.requirements
+        .map((r) => `<tr><td>${reqLink(r.id, r.url)}</td><td>${esc(r.title)}${r.declared === false ? ' <em>(not in requirements file)</em>' : ''}</td><td>${badge(r.status)}</td><td>${r.scenarios.length}</td></tr>`)
+        .join('');
+    const details = report.requirements
+        .map((r) => {
+        const body = r.scenarios.length
+            ? `<table><thead><tr><th>Scenario</th><th>Location</th><th>Tags</th><th>Status</th><th>Results</th></tr></thead><tbody>${r.scenarios
+                .map((s) => `<tr><td>${esc(s.name)}</td><td><code>${esc(`${s.feature}:${s.line}`)}</code></td><td>${esc(s.tags.join(' '))}</td><td>${badge(s.status)}</td><td>${s.results.length
+                ? s.results
+                    .map((x) => `${esc(resultLabel(x))}${x.durationMs != null ? ` <span class="dim">${esc(duration(x.durationMs))}</span>` : ''}`)
+                    .join('<br>')
+                : '<span class="dim">no result</span>'}</td></tr>`)
+                .join('')}</tbody></table>`
+            : '<p class="dim">No scenario covers this requirement.</p>';
+        return `<section><h3>${reqLink(r.id, r.url)}${r.title ? `: ${esc(r.title)}` : ''} ${badge(r.status)}</h3>${body}</section>`;
+    })
+        .join('');
+    const untraced = report.untraced.length
+        ? `<h2>Scenarios without a requirement</h2><table><thead><tr><th>Scenario</th><th>Location</th><th>Status</th></tr></thead><tbody>${report.untraced
+            .map((s) => `<tr><td>${esc(s.name)}</td><td><code>${esc(`${s.feature}:${s.line}`)}</code></td><td>${badge(s.status)}</td></tr>`)
+            .join('')}</tbody></table>`
+        : '';
+    const signOff = SIGN_OFF_FIELDS.map(([, label]) => `<tr><th>${esc(label)}</th><td class="blank"></td></tr>`).join('');
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Traceability: ${esc(report.projectName)}</title>
+<style>
+body{font:14px/1.5 system-ui,-apple-system,Segoe UI,sans-serif;color:#1a1a1a;background:#fff;margin:0;padding:24px 16px;max-width:1100px;margin-inline:auto}
+h1{font-size:22px;margin:0 0 4px}h2{font-size:17px;margin:28px 0 8px}h3{font-size:15px;margin:20px 0 6px}
+table{border-collapse:collapse;width:100%;margin:6px 0}th,td{border:1px solid #d9d9d9;padding:5px 8px;text-align:left;vertical-align:top}
+thead th{background:#f4f4f4}table.kv{width:auto}table.kv th{background:#f8f8f8;font-weight:600}
+code{font-size:12px}.dim{color:#6b6b6b}.wrap{overflow-x:auto}
+.st{display:inline-block;padding:0 6px;border-radius:3px;font-size:12px;font-weight:600;border:1px solid}
+.st-passed{color:#11633a;border-color:#11633a}.st-failed{color:#a1161c;border-color:#a1161c}
+.st-not-run,.st-skipped{color:#6b5300;border-color:#6b5300}.st-not-covered{color:#5a2d91;border-color:#5a2d91}
+td.blank{height:28px;min-width:320px}
+@media print{body{padding:0}section{break-inside:avoid}}
+</style>
+</head>
+<body>
+<h1>Traceability: ${esc(report.projectName)} <span class="dim">(${esc(report.project)})</span></h1>
+<p class="dim">Generated ${esc(report.generatedAt)}</p>
+${kv(runLines(report))}
+<h2>Summary</h2>
+${kv(summaryLines(report))}
+<h2>Requirements</h2>
+<div class="wrap"><table><thead><tr><th>Requirement</th><th>Title</th><th>Status</th><th>Scenarios</th></tr></thead><tbody>${overview}</tbody></table></div>
+<div class="wrap">${details}</div>
+${untraced}
+<h2>Notes</h2>
+<ul>${report.notes.map((n) => `<li>${esc(n)}</li>`).join('')}</ul>
+<h2>Sign-off</h2>
+<p>To be completed by a person. SDODS does not fill in this section.</p>
+<table class="kv">${signOff}</table>
+</body>
+</html>
+`;
+}
+//# sourceMappingURL=traceability-render.js.map

package/dist/analyze/traceability.d.ts

@@ -0,0 +1,87 @@
+import { type ProjectConfig, type RunManifest, type SuiteStatus, type TraceabilityReport, type TraceRunInfo } from '@sdods/contracts';
+/**
+ * Requirement traceability: `@req:<id>` tags on scenarios → the scenarios' results in one run.
+ *
+ * Deliberately read-only over files that already exist (feature files, the run directory). The
+ * requirement id is opaque — SDODS does not know or decide what it points at — and the sign-off
+ * block of the export is left empty for a person to fill in.
+ */
+export declare const REQ_TAG = "req";
+export interface RequirementDef {
+    id: string;
+    title?: string;
+}
+type Project = ProjectConfig & {
+    root: string;
+};
+/**
+ * Read a requirements file. YAML/JSON accepts a list (`- id: REQ-1` / `title:` or plain strings),
+ * a map (`REQ-1: Title`), or either under a top-level `requirements:` key. CSV needs an `id`
+ * column and may have a `title` column.
+ */
+export declare function loadRequirements(file: string): RequirementDef[];
+/** The requirements declared by the project, or null when it configures no requirements file. */
+export declare function projectRequirements(project: Project): RequirementDef[] | null;
+export declare function requirementUrl(project: ProjectConfig, id: string): string | undefined;
+interface StaticScenario {
+    feature: string;
+    featureName: string;
+    line: number;
+    name: string;
+    tags: string[];
+    requirements: string[];
+}
+/** Every scenario of the project with its effective tags (Feature and Rule tags inherited). */
+export declare function traceScenarios(project: Project, files?: string[]): StaticScenario[];
+/** One attempt of one scenario in one runner project, as recorded in the run directory. */
+export interface RunAttempt {
+    runnerProject: string;
+    /** feature path as the run recorded it (repo- or project-relative) */
+    uri: string;
+    /** line of the Scenario / Scenario Outline keyword, when known */
+    line?: number;
+    name: string;
+    exampleIndex: number | null;
+    attempt: number;
+    status: SuiteStatus;
+    durationMs?: number;
+    startedAt?: string;
+    finishedAt?: string;
+    error?: string;
+}
+export interface RunResults {
+    source: TraceRunInfo['resultsSource'];
+    attempts: RunAttempt[];
+}
+/**
+ * Read the scenario results of a run directory without a database.
+ *
+ * Cucumber messages (`messages.ndjson`, or its shard files) are the authoritative record: they hold
+ * every attempt in every runner project. The per-scenario `meta.json` files are the fallback — their
+ * directory is keyed without the browser, so a multi-browser run keeps only one of them per scenario.
+ */
+export declare function readRunResults(runDir: string): Promise<RunResults>;
+export declare function readRunManifest(runDir: string): RunManifest | undefined;
+/**
+ * The most recent run of `project` (and `env`, when given) under the artifacts root. Runs without a
+ * `run.json` are skipped: without it there is no way to tell which project or environment they ran.
+ */
+export declare function latestRunFor(artifactsRoot: string, project: string, env?: string): {
+    runId: string;
+    dir: string;
+} | null;
+export interface TraceabilityOptions {
+    project: Project;
+    /** run directory to read results from; omit for a static requirement → scenario matrix */
+    run?: {
+        runId: string;
+        dir: string;
+    };
+    /** feature files to consider (default: every feature of the project) */
+    files?: string[];
+    /** clock for `generatedAt` (tests pass a fixed date) */
+    now?: Date;
+}
+export declare function buildTraceabilityReport(opts: TraceabilityOptions): Promise<TraceabilityReport>;
+export {};
+//# sourceMappingURL=traceability.d.ts.map