@anselmdk/feature-spec-md 0.5.0 → 0.6.0

package/dist/githubActionDiffReport.d.ts

@@ -1,4 +1,65 @@
 import { type GithubActionOptions } from "./githubActionFtp.js";
 export type GithubActionDiffReportOptions = GithubActionOptions;
+export type LocalDiffReportOptions = {
+    previousDir: string;
+    currentDir: string;
+    prNumber?: string;
+    baseBuild?: string;
+    currentBuild?: string;
+    baseBuildUrl?: string;
+    currentBuildUrl?: string;
+    baseLabel?: DiffReport["baseLabel"];
+    previousAssetUrlPrefix?: string;
+    currentAssetUrlPrefix?: string;
+};
+type ComparedFile = {
+    path: string;
+    kind: "report" | "screenshot" | "asset";
+    status: "added" | "removed" | "changed" | "unchanged";
+    previousHash?: string;
+    currentHash?: string;
+    previousSize?: number;
+    currentSize?: number;
+};
+type DiffLine = {
+    kind: "context" | "added" | "removed";
+    previousLine?: number;
+    currentLine?: number;
+    text: string;
+};
+type SpecDiff = {
+    key: string;
+    title: string;
+    filePath?: string;
+    status: "added" | "removed" | "changed";
+    lines: DiffLine[];
+};
+type ScreenshotDiffItem = {
+    path: string;
+    title: string;
+    status: ComparedFile["status"];
+    previousUrl?: string;
+    currentUrl?: string;
+    previousSize?: number;
+    currentSize?: number;
+};
+type ScreenshotDiffGroup = {
+    specLabel: string;
+    specPath?: string;
+    items: ScreenshotDiffItem[];
+};
+type DiffReport = {
+    prNumber: string;
+    baseBuild?: string;
+    currentBuild: string;
+    baseBuildUrl?: string;
+    currentBuildUrl: string;
+    baseLabel: "main" | "previous" | "none";
+    files: ComparedFile[];
+    specDiffs: SpecDiff[];
+    screenshotDiffs: ScreenshotDiffGroup[];
+};
 export declare function publishGithubActionDiffReport(options: GithubActionDiffReportOptions): Promise<void>;
+export declare function renderLocalDiffReport(options: LocalDiffReportOptions): Promise<string>;
+export {};
 //# sourceMappingURL=githubActionDiffReport.d.ts.map

package/dist/githubActionDiffReport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"githubActionDiffReport.d.ts","sourceRoot":"","sources":["../src/githubActionDiffReport.ts"],"names":[],"mappings":"AAKA,OAAO,EAQL,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAC;AAG9B,MAAM,MAAM,6BAA6B,GAAG,mBAAmB,CAAC;AAqBhE,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,6BAA6B,iBA4DvC"}
+{"version":3,"file":"githubActionDiffReport.d.ts","sourceRoot":"","sources":["../src/githubActionDiffReport.ts"],"names":[],"mappings":"AAKA,OAAO,EAQL,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAC;AAG9B,MAAM,MAAM,6BAA6B,GAAG,mBAAmB,CAAC;AAEhE,MAAM,MAAM,sBAAsB,GAAG;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IACpC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,KAAK,YAAY,GAAG;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,YAAY,GAAG,OAAO,CAAC;IACxC,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,KAAK,QAAQ,GAAG;IACd,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAUF,KAAK,QAAQ,GAAG;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;IACxC,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB,CAAC;AAEF,KAAK,kBAAkB,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,KAAK,mBAAmB,GAAG;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,kBAAkB,EAAE,CAAC;CAC7B,CAAC;AAEF,KAAK,UAAU,GAAG;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;IACxC,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,eAAe,EAAE,mBAAmB,EAAE,CAAC;CACxC,CAAC;AAEF,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,6BAA6B,iBAyCvC;AAED,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,mBAE1E"}

package/dist/githubActionDiffReport.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { basename, join, relative } from "node:path";
 import { tmpdir } from "node:os";
 import { html } from "./html.js";
@@ -8,29 +8,18 @@ import { writeGithubOutput, writeGithubSummary } from "./githubActionOutput.js";
 export async function publishGithubActionDiffReport(options) {
     const config = ftpConfig(options);
     const prNumber = config.prNumber;
-    if (!prNumber) {
+    if (!prNumber)
         throw new Error("Missing required option --pr-number or FEATURE_SPEC_PR_NUMBER.");
-    }
     const buildsRoot = pathJoin(config.remoteDir, "build");
     const builds = await listBuildNumbers(buildsRoot, config);
     const currentBuild = config.buildNumber;
-    const previousBuild = previousBuildNumber(builds, currentBuild);
-    const currentBuildUrl = publicUrl(config.baseUrl, "build", currentBuild, "");
-    const previousBuildUrl = previousBuild
-        ? publicUrl(config.baseUrl, "build", previousBuild, "")
-        : undefined;
-    const report = previousBuild
-        ? await compareBuilds(config, previousBuild, currentBuild, prNumber)
-        : {
-            prNumber,
-            currentBuild,
-            currentBuildUrl,
-            files: [],
-        };
-    if (previousBuild) {
-        report.previousBuild = previousBuild;
-        report.previousBuildUrl = previousBuildUrl;
-    }
+    const requestedBaseBuild = optionValue(options, "base-build-number", "FEATURE_SPEC_BASE_BUILD_NUMBER");
+    const hasRequestedBaseBuild = Boolean(requestedBaseBuild && builds.includes(requestedBaseBuild));
+    const baseBuild = hasRequestedBaseBuild ? requestedBaseBuild : previousBuildNumber(builds, currentBuild);
+    const baseLabel = hasRequestedBaseBuild ? "main" : baseBuild ? "previous" : "none";
+    const report = baseBuild
+        ? await compareBuilds(config, baseBuild, currentBuild, prNumber, baseLabel)
+        : emptyReport(config, prNumber, currentBuild);
     const localReportDir = join(tmpdir(), `feature-spec-md-pr-diff-${process.pid}-${prNumber}-${currentBuild}`);
     await mkdir(localReportDir, { recursive: true });
     await writeFile(join(localReportDir, "index.html"), renderDiffReport(report), "utf8");
@@ -41,145 +30,368 @@ export async function publishGithubActionDiffReport(options) {
         "## Feature Spec PR Diff",
         "",
         `<p><strong>Diff report:</strong> <a href=\"${html(reportUrl)}\">PR #${html(prNumber)} build ${html(currentBuild)}</a></p>`,
-        report.previousBuild
-            ? `<p>Compared build <strong>${html(report.previousBuild)}</strong> with build <strong>${html(currentBuild)}</strong>.</p>`
-            : `<p>No earlier build was found, so this report establishes the first comparison baseline.</p>`,
+        summaryComparisonSentence(report),
         "",
     ].join("\n"));
     await writeGithubOutput({
         "diff-report-url": reportUrl,
         "diff-comment-body": commentBody(report, reportUrl),
-        "previous-build": report.previousBuild ?? "",
+        "base-build": report.baseLabel === "main" ? report.baseBuild ?? "" : "",
+        "previous-build": report.baseLabel === "previous" ? report.baseBuild ?? "" : "",
         "current-build": currentBuild,
     });
     console.log(`Feature spec PR diff report uploaded to ${reportUrl}`);
 }
-async function compareBuilds(config, previousBuild, currentBuild, prNumber) {
-    const previousRoot = pathJoin(config.remoteDir, "build", previousBuild);
+export async function renderLocalDiffReport(options) {
+    return renderDiffReport(await compareLocalBuilds(options));
+}
+async function compareLocalBuilds(options) {
+    const baseBuild = options.baseBuild ?? "127";
+    const currentBuild = options.currentBuild ?? "128";
+    const files = await compareLocalFiles(options.previousDir, options.currentDir);
+    const previousIndex = await readFileMaybe(join(options.previousDir, "index.html"));
+    const currentIndex = await readFileMaybe(join(options.currentDir, "index.html"));
+    const previousSpecs = extractSpecSections(previousIndex ?? "");
+    const currentSpecs = extractSpecSections(currentIndex ?? "");
+    const specDiffs = compareSpecSections(previousSpecs, currentSpecs);
+    const scenarioToSpec = scenarioSpecMap([...previousSpecs, ...currentSpecs]);
+    const screenshotDiffs = groupScreenshotDiffs(files, scenarioToSpec, {
+        previousUrl: (filePath) => relativeAssetUrl(options.previousAssetUrlPrefix ?? "previous", filePath),
+        currentUrl: (filePath) => relativeAssetUrl(options.currentAssetUrlPrefix ?? "current", filePath),
+    });
+    return {
+        prNumber: options.prNumber ?? "42",
+        baseBuild,
+        currentBuild,
+        baseBuildUrl: options.baseBuildUrl ?? "previous/",
+        currentBuildUrl: options.currentBuildUrl ?? "current/",
+        baseLabel: options.baseLabel ?? "previous",
+        files,
+        specDiffs,
+        screenshotDiffs,
+    };
+}
+function emptyReport(config, prNumber, currentBuild) {
+    return {
+        prNumber,
+        currentBuild,
+        currentBuildUrl: publicUrl(config.baseUrl, "build", currentBuild, ""),
+        baseLabel: "none",
+        files: [],
+        specDiffs: [],
+        screenshotDiffs: [],
+    };
+}
+async function compareBuilds(config, baseBuild, currentBuild, prNumber, baseLabel) {
+    const baseRoot = pathJoin(config.remoteDir, "build", baseBuild);
     const currentRoot = pathJoin(config.remoteDir, "build", currentBuild);
-    const previousFiles = await listRemoteFilesRecursive(previousRoot, config);
+    const baseFiles = await listRemoteFilesRecursive(baseRoot, config);
     const currentFiles = await listRemoteFilesRecursive(currentRoot, config);
-    const previousRelative = new Set(previousFiles.map((file) => relativeRemotePath(previousRoot, file)));
+    const baseRelative = new Set(baseFiles.map((file) => relativeRemotePath(baseRoot, file)));
     const currentRelative = new Set(currentFiles.map((file) => relativeRemotePath(currentRoot, file)));
-    const allPaths = Array.from(new Set([...previousRelative, ...currentRelative])).sort();
-    const localRoot = join(tmpdir(), `feature-spec-md-build-compare-${process.pid}-${previousBuild}-${currentBuild}`);
+    const allPaths = Array.from(new Set([...baseRelative, ...currentRelative])).sort();
+    const localRoot = join(tmpdir(), `feature-spec-md-build-compare-${process.pid}-${baseBuild}-${currentBuild}`);
     const files = [];
     for (const filePath of allPaths) {
-        const previousRemote = previousRelative.has(filePath)
-            ? pathJoin(previousRoot, filePath)
-            : undefined;
-        const currentRemote = currentRelative.has(filePath)
-            ? pathJoin(currentRoot, filePath)
-            : undefined;
-        const previousLocal = previousRemote
-            ? join(localRoot, "previous", filePath)
-            : undefined;
+        const baseRemote = baseRelative.has(filePath) ? pathJoin(baseRoot, filePath) : undefined;
+        const currentRemote = currentRelative.has(filePath) ? pathJoin(currentRoot, filePath) : undefined;
+        const baseLocal = baseRemote ? join(localRoot, "base", filePath) : undefined;
         const currentLocal = currentRemote ? join(localRoot, "current", filePath) : undefined;
-        if (previousRemote && previousLocal) {
-            await downloadRemoteFile(previousRemote, previousLocal, config);
-        }
-        if (currentRemote && currentLocal) {
+        if (baseRemote && baseLocal)
+            await downloadRemoteFile(baseRemote, baseLocal, config);
+        if (currentRemote && currentLocal)
             await downloadRemoteFile(currentRemote, currentLocal, config);
-        }
-        const previousInfo = previousLocal ? await fileInfo(previousLocal) : undefined;
+        const baseInfo = baseLocal ? await fileInfo(baseLocal) : undefined;
         const currentInfo = currentLocal ? await fileInfo(currentLocal) : undefined;
-        const status = !previousInfo
-            ? "added"
-            : !currentInfo
-                ? "removed"
-                : previousInfo.hash === currentInfo.hash
-                    ? "unchanged"
-                    : "changed";
+        const status = !baseInfo ? "added" : !currentInfo ? "removed" : baseInfo.hash === currentInfo.hash ? "unchanged" : "changed";
         files.push({
             path: filePath,
             kind: fileKind(filePath),
             status,
-            previousHash: previousInfo?.hash,
+            previousHash: baseInfo?.hash,
             currentHash: currentInfo?.hash,
-            previousSize: previousInfo?.size,
+            previousSize: baseInfo?.size,
             currentSize: currentInfo?.size,
         });
     }
+    const previousIndex = await readFileMaybe(join(localRoot, "base", "index.html"));
+    const currentIndex = await readFileMaybe(join(localRoot, "current", "index.html"));
+    const previousSpecs = extractSpecSections(previousIndex ?? "");
+    const currentSpecs = extractSpecSections(currentIndex ?? "");
+    const specDiffs = compareSpecSections(previousSpecs, currentSpecs);
+    const scenarioToSpec = scenarioSpecMap([...previousSpecs, ...currentSpecs]);
+    const screenshotDiffs = groupScreenshotDiffs(files, scenarioToSpec, {
+        previousUrl: (filePath) => publicUrl(config.baseUrl, "build", baseBuild, filePath),
+        currentUrl: (filePath) => publicUrl(config.baseUrl, "build", currentBuild, filePath),
+    });
     return {
         prNumber,
-        previousBuild,
+        baseBuild,
         currentBuild,
-        previousBuildUrl: publicUrl(config.baseUrl, "build", previousBuild, ""),
+        baseBuildUrl: publicUrl(config.baseUrl, "build", baseBuild, ""),
         currentBuildUrl: publicUrl(config.baseUrl, "build", currentBuild, ""),
+        baseLabel,
         files,
+        specDiffs,
+        screenshotDiffs,
     };
 }
+async function compareLocalFiles(previousDir, currentDir) {
+    const previousFiles = await listLocalFilesRecursive(previousDir);
+    const currentFiles = await listLocalFilesRecursive(currentDir);
+    const previousSet = new Set(previousFiles);
+    const currentSet = new Set(currentFiles);
+    const allPaths = Array.from(new Set([...previousSet, ...currentSet])).sort();
+    const files = [];
+    for (const filePath of allPaths) {
+        const previousInfo = previousSet.has(filePath) ? await fileInfo(join(previousDir, filePath)) : undefined;
+        const currentInfo = currentSet.has(filePath) ? await fileInfo(join(currentDir, filePath)) : undefined;
+        const status = !previousInfo ? "added" : !currentInfo ? "removed" : previousInfo.hash === currentInfo.hash ? "unchanged" : "changed";
+        files.push({
+            path: filePath,
+            kind: fileKind(filePath),
+            status,
+            previousHash: previousInfo?.hash,
+            currentHash: currentInfo?.hash,
+            previousSize: previousInfo?.size,
+            currentSize: currentInfo?.size,
+        });
+    }
+    return files;
+}
+async function listLocalFilesRecursive(root) {
+    const files = [];
+    await visit("");
+    return files.sort();
+    async function visit(relativeDir) {
+        const dir = relativeDir ? join(root, relativeDir) : root;
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            const relativePath = relativeDir ? `${relativeDir}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                await visit(relativePath);
+            }
+            else if (entry.isFile()) {
+                files.push(relativePath);
+            }
+        }
+    }
+}
 function previousBuildNumber(builds, currentBuild) {
     const current = Number(currentBuild);
-    return builds
-        .map(Number)
-        .filter((build) => Number.isFinite(build) && build < current)
-        .sort((a, b) => b - a)
-        .at(0)
-        ?.toString();
+    return builds.map(Number).filter((build) => Number.isFinite(build) && build < current).sort((a, b) => b - a).at(0)?.toString();
+}
+function optionValue(options, key, envKey) {
+    return options[key] ?? process.env[envKey];
 }
 async function fileInfo(filePath) {
     const buffer = await readFile(filePath);
-    return {
-        hash: createHash("sha256").update(buffer).digest("hex"),
-        size: buffer.byteLength,
-    };
+    return { hash: createHash("sha256").update(buffer).digest("hex"), size: buffer.byteLength };
+}
+async function readFileMaybe(filePath) {
+    try {
+        return await readFile(filePath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
 }
 function relativeRemotePath(root, filePath) {
     return relative(root, filePath).split("\\").join("/");
 }
 function fileKind(filePath) {
     const name = basename(filePath).toLowerCase();
-    if (name === "index.html" || name.endsWith(".html") || name.endsWith(".json")) {
+    if (name === "index.html" || name.endsWith(".html") || name.endsWith(".json"))
         return "report";
-    }
-    if (/\.(png|jpe?g|webp|gif)$/i.test(name))
+    if (/\.(png|jpe?g|webp|gif|svg)$/i.test(name))
         return "screenshot";
     return "asset";
 }
+function extractSpecSections(source) {
+    if (!source)
+        return [];
+    const sections = [];
+    const matches = source.matchAll(/<section class="panel">([\s\S]*?)(?=<section class="panel">|<script>|<\/body>)/g);
+    for (const match of matches) {
+        const fragment = match[1] ?? "";
+        const heading = fragment.match(/<h2[^>]*>([\s\S]*?)<\/h2>/)?.[1];
+        if (!heading)
+            continue;
+        const title = textContent(heading).trim();
+        if (!title || title === "Validation" || title === "Models")
+            continue;
+        const filePaths = Array.from(fragment.matchAll(/title="([^":]+\.md):\d+"/g), (item) => item[1]);
+        const scenarioIds = Array.from(fragment.matchAll(/<summary><code>([^<]+)<\/code>/g), (item) => textContent(item[1] ?? ""));
+        const text = specText(fragment);
+        const filePath = filePaths[0];
+        sections.push({
+            key: filePath ?? title,
+            title,
+            filePath,
+            scenarioIds,
+            text,
+        });
+    }
+    return sections;
+}
+function specText(fragment) {
+    return textContent(fragment)
+        .split(/\n+/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .join("\n");
+}
+function textContent(fragment) {
+    return decodeEntities(fragment
+        .replace(/<br\s*\/?>/gi, "\n")
+        .replace(/<\/p>|<\/li>|<\/summary>|<\/h[1-6]>|<\/div>/gi, "\n")
+        .replace(/<[^>]+>/g, ""));
+}
+function decodeEntities(value) {
+    return value
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&amp;/g, "&");
+}
+function compareSpecSections(previous, current) {
+    const previousByKey = new Map(previous.map((spec) => [spec.key, spec]));
+    const currentByKey = new Map(current.map((spec) => [spec.key, spec]));
+    const keys = Array.from(new Set([...previousByKey.keys(), ...currentByKey.keys()])).sort();
+    const diffs = [];
+    for (const key of keys) {
+        const before = previousByKey.get(key);
+        const after = currentByKey.get(key);
+        const status = !before ? "added" : !after ? "removed" : before.text === after.text ? undefined : "changed";
+        if (!status)
+            continue;
+        diffs.push({
+            key,
+            title: after?.title ?? before?.title ?? key,
+            filePath: after?.filePath ?? before?.filePath,
+            status,
+            lines: diffLines(before?.text ?? "", after?.text ?? ""),
+        });
+    }
+    return diffs;
+}
+function diffLines(previous, current) {
+    const a = previous.split("\n");
+    const b = current.split("\n");
+    const matrix = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
+    for (let i = a.length - 1; i >= 0; i -= 1) {
+        for (let j = b.length - 1; j >= 0; j -= 1) {
+            matrix[i][j] = a[i] === b[j] ? matrix[i + 1][j + 1] + 1 : Math.max(matrix[i + 1][j], matrix[i][j + 1]);
+        }
+    }
+    const lines = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length || j < b.length) {
+        if (i < a.length && j < b.length && a[i] === b[j]) {
+            lines.push({ kind: "context", previousLine: i + 1, currentLine: j + 1, text: a[i] });
+            i += 1;
+            j += 1;
+        }
+        else if (j < b.length && (i === a.length || matrix[i][j + 1] >= matrix[i + 1][j])) {
+            lines.push({ kind: "added", currentLine: j + 1, text: b[j] });
+            j += 1;
+        }
+        else if (i < a.length) {
+            lines.push({ kind: "removed", previousLine: i + 1, text: a[i] });
+            i += 1;
+        }
+    }
+    return compactContext(lines);
+}
+function compactContext(lines) {
+    const keep = new Set();
+    lines.forEach((line, index) => {
+        if (line.kind === "context")
+            return;
+        for (let offset = -3; offset <= 3; offset += 1) {
+            const candidate = index + offset;
+            if (candidate >= 0 && candidate < lines.length)
+                keep.add(candidate);
+        }
+    });
+    return lines.filter((line, index) => line.kind !== "context" || keep.has(index));
+}
+function scenarioSpecMap(specs) {
+    const map = new Map();
+    for (const spec of specs) {
+        for (const scenarioId of spec.scenarioIds) {
+            map.set(scenarioId, spec);
+        }
+    }
+    return map;
+}
+function groupScreenshotDiffs(files, scenarioMap, urls) {
+    const groups = new Map();
+    for (const file of files.filter((item) => item.kind === "screenshot" && item.status !== "unchanged")) {
+        const scenarioId = scenarioIdFromScreenshotPath(file.path);
+        const spec = scenarioId ? scenarioMap.get(scenarioId) : undefined;
+        const specLabel = spec?.filePath ?? spec?.title ?? scenarioId ?? "Unmapped screenshots";
+        const group = groups.get(specLabel) ?? { specLabel, specPath: spec?.filePath, items: [] };
+        group.items.push({
+            path: file.path,
+            title: screenshotTitle(file.path, scenarioId),
+            status: file.status,
+            previousUrl: file.status !== "added" ? urls.previousUrl(file.path) : undefined,
+            currentUrl: file.status !== "removed" ? urls.currentUrl(file.path) : undefined,
+            previousSize: file.previousSize,
+            currentSize: file.currentSize,
+        });
+        groups.set(specLabel, group);
+    }
+    return Array.from(groups.values()).sort((a, b) => a.specLabel.localeCompare(b.specLabel));
+}
+function scenarioIdFromScreenshotPath(filePath) {
+    return basename(filePath).match(/^(.+?)-line-\d+-/)?.[1];
+}
+function screenshotTitle(filePath, scenarioId) {
+    const name = basename(filePath).replace(/\.(png|jpe?g|webp|gif|svg)$/i, "");
+    return scenarioId ? name.replace(`${scenarioId}-`, `${scenarioId} `) : name;
+}
+function relativeAssetUrl(prefix, filePath) {
+    return [prefix.replace(/\/+$/, ""), ...filePath.split("/").filter(Boolean)]
+        .filter(Boolean)
+        .join("/");
+}
 function renderDiffReport(report) {
-    const changed = report.files.filter((file) => file.status !== "unchanged");
-    const byKind = (kind) => changed.filter((file) => file.kind === kind);
-    const sections = [
-        renderFileSection("Report output", byKind("report")),
-        renderFileSection("Screenshots", byKind("screenshot")),
-        renderFileSection("Other assets", byKind("asset")),
-    ].join("\n");
-    return `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8">
-    <meta name="viewport" content="width=device-width,initial-scale=1">
-    <title>Feature spec PR diff</title>
-    <style>
-      body{font-family:system-ui,sans-serif;max-width:1180px;margin:0 auto;padding:40px 24px;color:#1f2328}
-      .panel{border:1px solid #d0d7de;border-radius:8px;padding:20px;margin:18px 0}
-      .badge{border:1px solid #d0d7de;border-radius:999px;padding:2px 8px;font-size:12px;white-space:nowrap}
-      .added{color:#1a7f37}.removed{color:#cf222e}.changed{color:#9a6700}.muted{color:#57606a}
-      table{border-collapse:collapse;width:100%;font-size:14px} th,td{border:1px solid #d0d7de;padding:6px 8px;text-align:left;vertical-align:top} th{background:#f6f8fa}
-      a{color:#0969da}
-    </style>
-  </head>
-  <body>
-    <h1>Feature spec PR diff for PR #${html(report.prNumber)}</h1>
-    <p>Generated ${html(new Date().toISOString())}.</p>
-    <section class="panel">
-      <h2>Compared builds</h2>
-      <p>${report.previousBuild ? `Previous: <a href="${html(report.previousBuildUrl ?? "")}">build ${html(report.previousBuild)}</a>` : "No previous build found."}</p>
-      <p>Current: <a href="${html(report.currentBuildUrl)}">build ${html(report.currentBuild)}</a></p>
-      <p><span class="badge">${changed.length} changed file${changed.length === 1 ? "" : "s"}</span> <span class="muted">${report.files.length} file${report.files.length === 1 ? "" : "s"} checked</span></p>
-    </section>
-    ${sections}
-  </body>
-</html>`;
+    const changed = report.files.filter((file) => file.status !== "unchanged" && file.kind !== "report");
+    const assetChanges = changed.filter((file) => file.kind === "asset");
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Feature spec PR diff</title><style>body{font-family:system-ui,sans-serif;max-width:1180px;margin:0 auto;padding:40px 24px;color:#1f2328}.panel{border:1px solid #d0d7de;border-radius:8px;padding:20px;margin:18px 0}.badge{border:1px solid #d0d7de;border-radius:999px;padding:2px 8px;font-size:12px}.added{color:#1a7f37}.removed{color:#cf222e}.changed{color:#9a6700}.muted{color:#57606a}table{border-collapse:collapse;width:100%;font-size:14px}th,td{border:1px solid #d0d7de;padding:6px 8px;text-align:left;vertical-align:top}th{background:#f6f8fa}a{color:#0969da}.diff{width:100%;font-family:ui-monospace,SFMono-Regular,Consolas,monospace;font-size:12px}.diff td{padding:2px 8px}.line-no{width:1%;color:#57606a;background:#f6f8fa;text-align:right;user-select:none}.diff-added td{background:#dafbe1}.diff-removed td{background:#ffebe9}.diff-context td{background:#fff}.image-pair{display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:12px}.image-card{border:1px solid #d0d7de;border-radius:8px;background:#f6f8fa;overflow:hidden}.image-card h4{margin:0;padding:8px 10px;background:#fff;border-bottom:1px solid #d0d7de}.image-card img{display:block;width:100%;height:auto}</style></head><body><h1>Feature spec PR diff for PR #${html(report.prNumber)}</h1><p>Generated ${html(new Date().toISOString())}.</p><section class="panel"><h2>Compared builds</h2><p>${report.baseBuild ? `${baseLabel(report)}: <a href="${html(report.baseBuildUrl ?? "")}">build ${html(report.baseBuild)}</a>` : "No base build found."}</p><p>PR: <a href="${html(report.currentBuildUrl)}">build ${html(report.currentBuild)}</a></p><p><span class="badge">${report.specDiffs.length} spec change${report.specDiffs.length === 1 ? "" : "s"}</span> <span class="badge">${screenshotChangeCount(report)} screenshot change${screenshotChangeCount(report) === 1 ? "" : "s"}</span></p></section>${renderSpecDiffs(report.specDiffs)}${renderScreenshotDiffs(report.screenshotDiffs)}${renderFileSection("Other assets", assetChanges)}</body></html>`;
+}
+function renderSpecDiffs(specDiffs) {
+    if (!specDiffs.length)
+        return `<section class="panel"><h2>Spec changes</h2><p class="muted">No spec text changes detected in the published report.</p></section>`;
+    return `<section class="panel"><h2>Spec changes</h2>${specDiffs.map(renderSpecDiff).join("\n")}</section>`;
+}
+function renderSpecDiff(diff) {
+    return `<details open><summary><strong>${html(diff.filePath ?? diff.title)}</strong> <span class="badge ${diff.status}">${html(diff.status)}</span></summary><table class="diff"><tbody>${diff.lines.map(renderDiffLine).join("")}</tbody></table></details>`;
+}
+function renderDiffLine(line) {
+    const marker = line.kind === "added" ? "+" : line.kind === "removed" ? "-" : "";
+    return `<tr class="diff-${line.kind}"><td class="line-no">${line.previousLine ?? ""}</td><td class="line-no">${line.currentLine ?? ""}</td><td>${html(marker)} ${html(line.text)}</td></tr>`;
+}
+function renderScreenshotDiffs(groups) {
+    if (!groups.length)
+        return `<section class="panel"><h2>Screenshots</h2><p class="muted">No screenshot changes.</p></section>`;
+    return `<section class="panel"><h2>Screenshots</h2>${groups.map(renderScreenshotGroup).join("\n")}</section>`;
+}
+function renderScreenshotGroup(group) {
+    return `<section><h3>${html(group.specPath ?? group.specLabel)}</h3>${group.items.map(renderScreenshotItem).join("\n")}</section>`;
+}
+function renderScreenshotItem(item) {
+    const before = item.previousUrl ? `<div class="image-card"><h4>Before</h4><img src="${html(item.previousUrl)}" alt="Before ${html(item.title)}"></div>` : "";
+    const after = item.currentUrl ? `<div class="image-card"><h4>After</h4><img src="${html(item.currentUrl)}" alt="After ${html(item.title)}"></div>` : "";
+    return `<details open><summary><code>${html(item.path)}</code> <span class="badge ${item.status}">${html(item.status)}</span> <span class="muted">${html(sizeChange({ previousSize: item.previousSize, currentSize: item.currentSize }))}</span></summary><div class="image-pair">${before}${after}</div></details>`;
 }
 function renderFileSection(title, files) {
-    if (!files.length) {
+    if (!files.length)
         return `<section class="panel"><h2>${html(title)}</h2><p class="muted">No changes.</p></section>`;
-    }
-    return `<section class="panel"><h2>${html(title)}</h2><table><thead><tr><th>Status</th><th>File</th><th>Size change</th></tr></thead><tbody>${files
-        .map((file) => `<tr><td class="${file.status}">${html(file.status)}</td><td><code>${html(file.path)}</code></td><td>${html(sizeChange(file))}</td></tr>`)
-        .join("")}</tbody></table></section>`;
+    return `<section class="panel"><h2>${html(title)}</h2><table><thead><tr><th>Status</th><th>File</th><th>Size change</th></tr></thead><tbody>${files.map((file) => `<tr><td class="${file.status}">${html(file.status)}</td><td><code>${html(file.path)}</code></td><td>${html(sizeChange(file))}</td></tr>`).join("")}</tbody></table></section>`;
 }
 function sizeChange(file) {
     if (file.previousSize === undefined)
@@ -187,23 +399,35 @@ function sizeChange(file) {
     if (file.currentSize === undefined)
         return `-${file.previousSize} bytes`;
     const diff = file.currentSize - file.previousSize;
-    if (diff === 0)
-        return "same size";
-    return `${diff > 0 ? "+" : ""}${diff} bytes`;
+    return diff === 0 ? "same size" : `${diff > 0 ? "+" : ""}${diff} bytes`;
+}
+function screenshotChangeCount(report) {
+    return report.screenshotDiffs.reduce((sum, group) => sum + group.items.length, 0);
 }
 function commentBody(report, reportUrl) {
-    const changed = report.files.filter((file) => file.status !== "unchanged");
-    const reportChanges = changed.filter((file) => file.kind === "report").length;
-    const screenshotChanges = changed.filter((file) => file.kind === "screenshot").length;
-    const previous = report.previousBuild
-        ? `build ${report.previousBuild} → build ${report.currentBuild}`
-        : `build ${report.currentBuild}`;
     return [
         "## Feature spec PR diff",
         "",
-        `[Open the diff report](${reportUrl}) for ${previous}.`,
+        `[Open the diff report](${reportUrl}) for ${comparisonText(report)}.`,
         "",
-        `Changed files: **${changed.length}** total, **${reportChanges}** report output, **${screenshotChanges}** screenshots.`,
+        `Changed: **${report.specDiffs.length}** spec file(s), **${screenshotChangeCount(report)}** screenshot(s).`,
     ].join("\n");
 }
+function comparisonText(report) {
+    if (!report.baseBuild)
+        return `PR build ${report.currentBuild}`;
+    return `${baseLabel(report).toLowerCase()} build ${report.baseBuild} → PR build ${report.currentBuild}`;
+}
+function summaryComparisonSentence(report) {
+    if (!report.baseBuild)
+        return `<p>No base build was found, so this report establishes the first comparison baseline.</p>`;
+    return `<p>Compared ${html(baseLabel(report).toLowerCase())} build <strong>${html(report.baseBuild)}</strong> with PR build <strong>${html(report.currentBuild)}</strong>.</p>`;
+}
+function baseLabel(report) {
+    if (report.baseLabel === "main")
+        return "Main";
+    if (report.baseLabel === "previous")
+        return "Previous";
+    return "Base";
+}
 //# sourceMappingURL=githubActionDiffReport.js.map