@sdods/core 0.7.1 → 0.8.0

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