@sentinelqa/playwright-reporter 0.1.47 → 0.1.50

package/dist/quickDiagnosis.js

@@ -3,24 +3,213 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildQuickDiagnosis = exports.summarizeSignal = exports.buildSimilarityKey = exports.buildDebugSummary = exports.describeFailure = exports.parseFailureFacts = exports.collectFailureFacts = void 0;
+exports.buildQuickDiagnosis = exports.summarizeSignal = exports.buildSimilarityKey = exports.buildDebugSummary = exports.collectFailureFacts = exports.parseFailureFacts = exports.describeFailure = void 0;
 const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const REPORTER_HISTORY_DIR = node_path_1.default.join(".sentinel", "reporter-history");
+const stripAnsi = (value) => value.replace(/\u001b\[[0-9;]*m/g, "");
+const normalizeTitleParts = (value) => value
+    .split(" > ")
+    .map((part) => part.trim())
+    .filter(Boolean);
+const cleanTitleParts = (parts) => {
+    const withoutUnnamed = parts.filter((part) => part && part !== "Unnamed test");
+    return withoutUnnamed.length ? withoutUnnamed : parts.filter(Boolean);
+};
+const pickHumanTitleParts = (value) => cleanTitleParts(normalizeTitleParts(value)).slice(-2);
+const formatTitle = (title) => pickHumanTitleParts(title).join(" > ") || title;
+const shortenTitle = (value) => {
+    const parts = pickHumanTitleParts(value);
+    return parts[parts.length - 1] || value;
+};
+const normalizePath = (value) => (value || "").replace(/\\/g, "/").toLowerCase().trim();
+const basename = (value) => {
+    const normalized = normalizePath(value);
+    if (!normalized)
+        return "";
+    return normalized.split("/").pop() || normalized;
+};
+const dirnameToken = (value) => {
+    const normalized = normalizePath(value);
+    if (!normalized || !normalized.includes("/"))
+        return "";
+    const parts = normalized.split("/").filter(Boolean);
+    return parts.length > 1 ? parts[parts.length - 2] : "";
+};
+const gitOutput = (args) => {
+    try {
+        return (0, node_child_process_1.execFileSync)("git", args, {
+            cwd: process.cwd(),
+            stdio: ["ignore", "pipe", "ignore"],
+            encoding: "utf8"
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+};
+const currentSha = () => (process.env.GITHUB_SHA ||
+    process.env.CI_COMMIT_SHA ||
+    process.env.VERCEL_GIT_COMMIT_SHA ||
+    gitOutput(["rev-parse", "HEAD"]) ||
+    "").trim();
+const currentBranch = () => (process.env.GITHUB_REF_NAME ||
+    process.env.CI_COMMIT_REF_NAME ||
+    process.env.CI_COMMIT_BRANCH ||
+    process.env.BRANCH_NAME ||
+    gitOutput(["rev-parse", "--abbrev-ref", "HEAD"]) ||
+    "main").trim();
 const normalizeMessageFingerprint = (message) => stripAnsi(message)
     .split(/\r?\n/)
     .map((line) => line.trim())
     .filter(Boolean)
-    .slice(0, 3)
+    .slice(0, 4)
     .join(" | ")
     .replace(/\b\d+ms\b/gi, "<ms>")
     .replace(/:\d+:\d+/g, ":<line>:<col>")
     .replace(/\s+/g, " ")
-    .slice(0, 200);
-const stripAnsi = (value) => value.replace(/\u001b\[[0-9;]*m/g, "");
+    .slice(0, 240);
+const readJson = (filePath) => {
+    if (!node_fs_1.default.existsSync(filePath))
+        return null;
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(filePath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+};
+const isMeaningfulHistorySnapshot = (snapshot) => {
+    if (!snapshot)
+        return false;
+    if (typeof snapshot.totalTests === 'number' && snapshot.totalTests <= 0)
+        return false;
+    if (typeof snapshot.failedCount === 'number' && typeof snapshot.passedCount === 'number') {
+        if (snapshot.failedCount === 0 && snapshot.passedCount === 0)
+            return false;
+    }
+    return true;
+};
+const listHistorySnapshots = (branch) => {
+    const dir = node_path_1.default.resolve(process.cwd(), REPORTER_HISTORY_DIR);
+    if (!node_fs_1.default.existsSync(dir))
+        return [];
+    return node_fs_1.default
+        .readdirSync(dir)
+        .filter((file) => file.endsWith(".json"))
+        .map((file) => readJson(node_path_1.default.join(dir, file)))
+        .filter((value) => Boolean(value))
+        .filter((snapshot) => (snapshot.branch || branch) === branch)
+        .filter((snapshot) => isMeaningfulHistorySnapshot(snapshot))
+        .sort((a, b) => String(b.generatedAt || "").localeCompare(String(a.generatedAt || "")));
+};
+const getLastPassingSnapshot = () => {
+    const branch = currentBranch();
+    const sha = currentSha();
+    const snapshots = listHistorySnapshots(branch);
+    const sameCommitFailure = sha
+        ? snapshots.find((snapshot) => snapshot.gitSha === sha &&
+            Number(snapshot.failedCount || 0) > 0)
+        : null;
+    if (sameCommitFailure) {
+        return {
+            sha: sameCommitFailure.gitSha || "unknown",
+            reason: "current commit has already failed in local history"
+        };
+    }
+    const sameCommitPass = sha
+        ? snapshots.find((snapshot) => snapshot.gitSha === sha &&
+            Number(snapshot.failedCount || 0) === 0 &&
+            Number(snapshot.passedCount || 0) > 0)
+        : null;
+    if (sameCommitPass) {
+        return {
+            sha: sameCommitPass.gitSha || "unknown",
+            reason: "current commit already passed locally; no new code change separates that pass from this failure"
+        };
+    }
+    const match = snapshots.find((snapshot) => Number(snapshot.failedCount || 0) === 0 &&
+        Number(snapshot.passedCount || 0) > 0 &&
+        Number(snapshot.totalTests || 0) > 0 &&
+        snapshot.gitSha !== sha &&
+        snapshot.gitSha &&
+        snapshot.gitSha !== "unknown");
+    if (!match?.gitSha)
+        return null;
+    return { sha: match.gitSha, reason: null };
+};
+const resolveAttachmentPath = (filePath) => {
+    if (!filePath)
+        return null;
+    return node_path_1.default.isAbsolute(filePath) ? filePath : node_path_1.default.resolve(process.cwd(), filePath);
+};
+const readAttachmentJson = (result, name) => {
+    const attachment = (result?.attachments || []).find((item) => item?.name === name && item.path);
+    const resolved = resolveAttachmentPath(attachment?.path);
+    return resolved ? readJson(resolved) : null;
+};
+const extractFocusLineFromSnippet = (snippet) => {
+    if (!snippet)
+        return null;
+    const lines = snippet.split(/\r?\n/);
+    const marked = lines.find((line) => /^\s*>\s*\d+\s*\|/.test(line));
+    const preferred = marked || lines.find((line) => /\S/.test(line));
+    if (!preferred)
+        return null;
+    return preferred
+        .replace(/^\s*>\s*/, "")
+        .replace(/^\s*\d+\s*\|\s*/, "")
+        .trim() || null;
+};
+const parseCommitLine = (line) => {
+    const [sha, author, message] = line.split("\u001f");
+    if (!sha)
+        return null;
+    const changedFilesRaw = gitOutput(["show", "--pretty=", "--name-only", sha]) || "";
+    return {
+        sha,
+        author: author || "Unknown",
+        message: message || "Recent commit",
+        changedFiles: changedFilesRaw
+            .split(/\r?\n/)
+            .map((item) => item.trim())
+            .filter(Boolean)
+            .slice(0, 80)
+    };
+};
+const getCommitWindow = (limit = 24) => {
+    const sha = currentSha();
+    const lastPassing = getLastPassingSnapshot();
+    const lastPassingSha = lastPassing?.sha || null;
+    const pretty = `--pretty=format:%H%x1f%an%x1f%s`;
+    if (!sha || !lastPassingSha || lastPassingSha === sha) {
+        return { commits: [], trusted: false, reason: lastPassing?.reason || "no trusted last passing commit available yet" };
+    }
+    const mergeBase = gitOutput(["merge-base", lastPassingSha, sha]);
+    if (!mergeBase || mergeBase !== lastPassingSha) {
+        return { commits: [], trusted: false, reason: "local git history does not contain a safe pass-to-fail commit range" };
+    }
+    const log = gitOutput(["log", "--first-parent", "--ancestry-path", `${lastPassingSha}..${sha}`, pretty]) || "";
+    const commits = log
+        .split(/\r?\n/)
+        .map((line) => parseCommitLine(line))
+        .filter((value) => Boolean(value))
+        .slice(0, limit);
+    if (!commits.length) {
+        return { commits: [], trusted: false, reason: "no commits found between the last pass and current failure" };
+    }
+    return { commits, trusted: true, reason: null };
+};
+const normalizeStatus = (status) => {
+    if (status === "failed" || status === "timedOut" || status === "interrupted")
+        return "failed";
+    if (status === "passed" || status === "flaky")
+        return "passed";
+    return "skipped";
+};
 const toMessage = (result) => {
-    const direct = result.error?.message ||
-        result.error?.stack ||
-        result.error?.value ||
-        null;
+    const direct = result.error?.message || result.error?.stack || result.error?.value || null;
     if (direct)
         return stripAnsi(String(direct));
     const first = result.errors?.find(Boolean);
@@ -28,7 +217,10 @@ const toMessage = (result) => {
 };
 const classifySignal = (message) => {
     const lower = message.toLowerCase();
-    if (/expected substring|expected string|received string|tohavetext|tocontaintext/.test(lower)) {
+    if (/browser has been closed|target page, context or browser has been closed|crash|page crashed|browser disconnected/.test(lower)) {
+        return "infra";
+    }
+    if (/expected substring|expected string|received string|tohavetext|tocontaintext|tohavevalue|tobechecked/.test(lower)) {
         return "assertion_mismatch";
     }
     if (/timeout|timed out|waiting for/.test(lower))
@@ -39,10 +231,12 @@ const classifySignal = (message) => {
     if (/not visible|not enabled|not stable|intercepts pointer events|not actionable/.test(lower)) {
         return "actionability";
     }
-    if (/status\s*[45]\d{2}|net::|failed to fetch|network|request failed/.test(lower)) {
+    if (/status\s*[45]\d{2}|net::|failed to fetch|network|request failed|socket hang up|econnreset|503|502|500/.test(lower)) {
         return "network";
     }
-    if (/typeerror|referenceerror|syntaxerror|unhandled/.test(lower))
+    if (/simulated flaky retry|retry guard|flaky retry/.test(lower))
+        return "runtime";
+    if (/^error:|\nerror:|typeerror|referenceerror|syntaxerror|unhandled/.test(lower))
         return "runtime";
     return "unknown";
 };
@@ -77,82 +271,282 @@ const extractLastUrl = (message) => {
     const match = message.match(/https?:\/\/[^\s)"']+/i);
     return match?.[0] || null;
 };
-const signalSummary = (signal) => {
-    switch (signal) {
-        case "timeout":
-            return "timeout while waiting for UI or network conditions";
-        case "assertion_mismatch":
-            return "assertion mismatch between expected and rendered UI state";
-        case "locator_not_found":
-            return "missing or changed locator";
-        case "actionability":
-            return "target element was not actionable";
-        case "network":
-            return "network or API failure";
-        case "runtime":
-            return "frontend runtime error";
-        default:
-            return "failure signal could not be classified cleanly";
+const extractApiHint = (message, codeContext) => {
+    if (codeContext?.apiCall)
+        return codeContext.apiCall;
+    const url = extractLastUrl(message);
+    if (url)
+        return url;
+    const apiMatch = message.match(/\/(api|graphql|rest)\/[^\s)"']+/i);
+    return apiMatch?.[0] || null;
+};
+const extractStackLocation = (message) => {
+    const lines = stripAnsi(message).split(/\r?\n/);
+    for (const line of lines) {
+        const match = line.match(/((?:[A-Za-z]:)?[^:\n]+\.[cm]?[jt]sx?):(\d+):(\d+)/);
+        if (!match)
+            continue;
+        const file = match[1]?.trim();
+        if (!file || file.includes("node_modules"))
+            continue;
+        const lineNumber = Number(match[2]);
+        const columnNumber = Number(match[3]);
+        return {
+            file,
+            line: Number.isFinite(lineNumber) ? lineNumber : null,
+            column: Number.isFinite(columnNumber) ? columnNumber : null
+        };
     }
+    return null;
+};
+const loadCodeContext = (result) => readAttachmentJson(result, "sentinel-code-context");
+const loadDomCapture = (result) => readAttachmentJson(result, "sentinel-dom-capture");
+const inferLikelyFile = (file, codeContext) => codeContext?.file || file || null;
+const inferLikelyModule = (file, locator, codeContext) => {
+    const fileBase = basename(inferLikelyFile(file, codeContext));
+    if (fileBase)
+        return fileBase.replace(/\.(spec|test|e2e)?\.[cm]?[jt]sx?$/i, "");
+    const locatorToken = (locator || "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, " ")
+        .split(" ")
+        .find((token) => token.length >= 4);
+    return locatorToken || null;
 };
+const describeDomState = (failure) => {
+    const dom = failure.domCapture;
+    if (!dom)
+        return null;
+    if (dom.targetFound === false || dom.matchedCount === 0) {
+        return failure.locator
+            ? `${failure.locator} never appeared before the timeout`
+            : "the expected target never appeared before the timeout";
+    }
+    if (dom.visible === false) {
+        return failure.locator
+            ? `${failure.locator} was found but stayed hidden before the timeout`
+            : "the target was found but stayed hidden before the timeout";
+    }
+    if (dom.enabled === false) {
+        return failure.locator
+            ? `${failure.locator} was found but stayed disabled before the timeout`
+            : "the target was found but stayed disabled before the timeout";
+    }
+    if (dom.targetFound === true && dom.visible === true && failure.codeContext?.action) {
+        return failure.locator
+            ? `${failure.codeContext.action} on ${failure.locator} never completed even though the target was present`
+            : `${failure.codeContext.action} never completed even though the target was present`;
+    }
+    return null;
+};
+const buildTouchedFileReason = (label, files) => `${label}: ${files.slice(0, 2).map((file) => basename(file)).join(", ")}`;
+const commitTouchedFailure = (commit, failure) => {
+    const reasons = [];
+    const touchedFiles = new Set();
+    let score = 0;
+    const likelyFileBase = basename(failure.likelyFile);
+    const likelyDir = dirnameToken(failure.likelyFile);
+    const likelyModule = (failure.likelyModule || "").toLowerCase();
+    const locatorToken = (failure.locator || failure.domCapture?.testId || "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, " ")
+        .split(" ")
+        .find((token) => token.length >= 4) || null;
+    const apiToken = (failure.apiHint || "")
+        .toLowerCase()
+        .replace(/https?:\/\//g, "")
+        .replace(/[^a-z0-9/]+/g, " ")
+        .split(/[\s/]+/)
+        .find((token) => token.length >= 4) || null;
+    const titleToken = cleanTitleParts(failure.titlePath)
+        .join(" ")
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .find((token) => token.length >= 4) || null;
+    if (commit.sha === currentSha()) {
+        score += 0.08;
+        reasons.push("current failing commit");
+    }
+    const exactFileMatches = commit.changedFiles.filter((item) => basename(item) === likelyFileBase);
+    if (exactFileMatches.length) {
+        score += 0.42;
+        exactFileMatches.forEach((file) => touchedFiles.add(file));
+        reasons.push(buildTouchedFileReason("touches likely file", exactFileMatches));
+    }
+    const dirMatches = likelyDir ? commit.changedFiles.filter((item) => normalizePath(item).includes(`/${likelyDir}/`) || normalizePath(item).endsWith(`/${likelyDir}`)) : [];
+    if (dirMatches.length) {
+        score += 0.18;
+        dirMatches.slice(0, 2).forEach((file) => touchedFiles.add(file));
+        reasons.push(buildTouchedFileReason("touches same area", dirMatches));
+    }
+    const moduleMatches = likelyModule ? commit.changedFiles.filter((item) => normalizePath(item).includes(likelyModule)) : [];
+    if (moduleMatches.length) {
+        score += 0.16;
+        moduleMatches.slice(0, 2).forEach((file) => touchedFiles.add(file));
+        reasons.push(buildTouchedFileReason("overlaps likely module", moduleMatches));
+    }
+    const locatorMatches = locatorToken ? commit.changedFiles.filter((item) => normalizePath(item).includes(locatorToken)) : [];
+    if (locatorMatches.length) {
+        score += 0.22;
+        locatorMatches.slice(0, 2).forEach((file) => touchedFiles.add(file));
+        reasons.push(buildTouchedFileReason(`overlaps selector token (${locatorToken})`, locatorMatches));
+    }
+    const apiMatches = apiToken ? commit.changedFiles.filter((item) => normalizePath(item).includes(apiToken)) : [];
+    if (apiMatches.length) {
+        score += 0.24;
+        apiMatches.slice(0, 2).forEach((file) => touchedFiles.add(file));
+        reasons.push(buildTouchedFileReason(`overlaps API token (${apiToken})`, apiMatches));
+    }
+    if (locatorToken && commit.message.toLowerCase().includes(locatorToken)) {
+        score += 0.12;
+        reasons.push("commit message overlaps the failing selector");
+    }
+    if (apiToken && commit.message.toLowerCase().includes(apiToken)) {
+        score += 0.12;
+        reasons.push("commit message overlaps the failing API");
+    }
+    if (titleToken && commit.changedFiles.some((item) => normalizePath(item).includes(titleToken))) {
+        score += 0.12;
+        reasons.push(`changed file overlaps the failing flow (${titleToken})`);
+    }
+    if (failure.signal === "network" && /api|request|fetch|backend|service|latency|timeout/i.test(commit.message)) {
+        score += 0.14;
+        reasons.push("commit message points to backend or network changes");
+    }
+    if (["assertion_mismatch", "locator_not_found", "actionability"].includes(failure.signal) && /ui|button|modal|page|auth|login|checkout|selector|form/i.test(commit.message)) {
+        score += 0.14;
+        reasons.push("commit message points to the failing UI flow");
+    }
+    if (failure.signal === "infra" && /browser|playwright|infra|ci|worker|build|docker|image/i.test(commit.message)) {
+        score += 0.16;
+        reasons.push("commit message points to CI or browser infrastructure changes");
+    }
+    return {
+        commit,
+        score,
+        reasons: Array.from(new Set(reasons)).slice(0, 3),
+        touchedFiles: Array.from(touchedFiles).slice(0, 3)
+    };
+};
+const rankCommitsForFailure = (failure, window) => window.commits
+    .map((commit) => commitTouchedFailure(commit, failure))
+    .filter((entry) => entry.score > 0.2)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, 2);
 const flattenFailedCases = (node, titlePath = []) => {
     const currentTitlePath = node.title ? [...titlePath, node.title] : titlePath;
-    const failedCases = [];
+    const failures = [];
+    for (const child of node.suites || [])
+        failures.push(...flattenFailedCases(child, currentTitlePath));
+    for (const child of node.specs || [])
+        failures.push(...flattenFailedCases(child, currentTitlePath));
     for (const test of node.tests || []) {
-        const title = [...currentTitlePath, test.title || "Unnamed test"].join(" > ");
-        for (const result of test.results || []) {
-            if (!["failed", "timedOut", "interrupted"].includes(result.status || ""))
-                continue;
-            const message = toMessage(result);
-            failedCases.push({
-                title,
-                message,
-                signal: classifySignal(message)
-            });
+        const results = Array.isArray(test.results) ? test.results : [];
+        const finalResult = results[results.length - 1];
+        if (!finalResult)
+            continue;
+        const finalStatus = normalizeStatus(finalResult.status);
+        if (finalStatus !== "failed")
+            continue;
+        const message = toMessage(finalResult);
+        const titleParts = cleanTitleParts([...currentTitlePath, test.title || "Unnamed test"]);
+        failures.push((0, exports.parseFailureFacts)(titleParts.join(" > "), titleParts, message, "failed", node.file || node.location?.file || test.location?.file || null, {
+            projectName: test.projectName || null,
+            timeoutBudgetMs: typeof test.timeout === "number" ? test.timeout : null,
+            codeContext: loadCodeContext(finalResult),
+            domCapture: loadDomCapture(finalResult),
+            errorLocation: finalResult.error?.location || finalResult.errors?.find(Boolean)?.location || null,
+            errorSnippet: finalResult.error?.snippet || null
+        }));
+    }
+    return failures;
+};
+const checkFirst = (failure) => {
+    if (failure.signal === "runtime" && /retry|flaky/i.test(failure.message)) {
+        const file = basename(failure.codeContext?.file || failure.likelyFile);
+        const line = failure.codeContext?.line;
+        if (file && line) {
+            return `inspect the throw at ${file}:${line} before opening the trace`;
         }
+        if (failure.codeContext?.focusLine) {
+            return `inspect ${failure.codeContext.focusLine.trim()} before opening the trace`;
+        }
+        return "inspect the shared retry or flaky helper before opening the trace";
+    }
+    if (failure.signal === "infra") {
+        return "inspect the browser crash or CI worker logs before digging into the test code";
     }
-    for (const child of node.specs || []) {
-        failedCases.push(...flattenFailedCases(child, currentTitlePath));
+    if (failure.signal === "network") {
+        return failure.apiHint ? `inspect ${failure.apiHint}` : "inspect the failing request and backend response";
     }
-    for (const child of node.suites || []) {
-        failedCases.push(...flattenFailedCases(child, currentTitlePath));
+    if (failure.signal === "timeout" && failure.codeContext?.action) {
+        if (failure.locator && failure.domCapture?.targetFound === false) {
+            return `inspect why ${failure.locator} never appeared before the ${failure.codeContext.action}`;
+        }
+        if (failure.locator && failure.domCapture?.visible === false) {
+            return `inspect why ${failure.locator} stayed hidden before the ${failure.codeContext.action}`;
+        }
+        if (failure.locator && failure.domCapture?.enabled === false) {
+            return `inspect why ${failure.locator} stayed disabled before the ${failure.codeContext.action}`;
+        }
+        if (failure.locator && failure.domCapture?.targetFound === true && failure.domCapture?.visible === true) {
+            return `inspect what blocked ${failure.codeContext.action} on ${failure.locator} (overlay or pointer interception is likely)`;
+        }
+        return `inspect the blocked ${failure.codeContext.action} step before the timeout`;
     }
-    return failedCases;
+    if (failure.locator)
+        return `verify ${failure.locator}`;
+    if (failure.codeContext?.focusLine)
+        return `inspect ${failure.codeContext.focusLine.trim()}`;
+    if (failure.likelyFile)
+        return `inspect ${basename(failure.likelyFile)}`;
+    return "open the failing trace step";
 };
-const shortenTitle = (value) => {
-    const parts = value.split(" > ").filter(Boolean);
-    return parts[parts.length - 1] || value;
+const confidenceLabel = (score) => {
+    if (score >= 0.62)
+        return "High";
+    if (score >= 0.34)
+        return "Medium";
+    return "Low";
 };
-const collectFailureFacts = (playwrightJsonPath) => {
-    if (!node_fs_1.default.existsSync(playwrightJsonPath))
-        return [];
-    try {
-        const raw = node_fs_1.default.readFileSync(playwrightJsonPath, "utf8");
-        const parsed = JSON.parse(raw);
-        const failedCases = flattenFailedCases(parsed);
-        return failedCases.map((failed) => (0, exports.parseFailureFacts)(shortenTitle(failed.title), failed.title.split(" > ").filter(Boolean), failed.message, "failed"));
-    }
-    catch {
-        return [];
+const compactCommitLine = (match) => {
+    if (!match)
+        return null;
+    return `Suspected commit: ${match.commit.sha.slice(0, 7)} "${match.commit.message}"`;
+};
+const compactWhyLine = (match) => {
+    if (!match?.reasons.length)
+        return null;
+    return match.reasons.join("; ");
+};
+const alternateCommitLine = (match) => {
+    if (!match)
+        return null;
+    return `Also changed: ${match.commit.sha.slice(0, 7)} "${match.commit.message}"`;
+};
+const rootCauseLabel = (failure) => {
+    switch (failure.signal) {
+        case "assertion_mismatch":
+            return "UI assertion mismatch";
+        case "locator_not_found":
+            return "Locator or render regression";
+        case "actionability":
+            return "Actionability regression";
+        case "network":
+            return "Backend or network failure";
+        case "runtime":
+            return /retry|flaky/i.test(failure.message) ? "Same test-side throw before the app flow completed" : "Runtime error during the flow";
+        case "timeout":
+            return "Timeout waiting for state change";
+        case "infra":
+            return "Browser or CI infrastructure failure";
+        default:
+            return "Failure pattern";
     }
 };
-exports.collectFailureFacts = collectFailureFacts;
-const parseFailureFacts = (title, titlePath, message, status) => ({
-    title,
-    titlePath,
-    message,
-    signal: classifySignal(message),
-    locator: extractLocator(message),
-    expected: extractExpected(message),
-    received: extractReceived(message),
-    timeoutMs: extractTimeoutMs(message),
-    lastUrl: extractLastUrl(message),
-    status
-});
-exports.parseFailureFacts = parseFailureFacts;
 const describeFailure = (failure) => {
     if (failure.signal === "assertion_mismatch" && failure.locator && failure.expected && failure.received) {
-        return `${failure.locator} showed "${failure.received}" instead of "${failure.expected}" before timeout.`;
+        return `${failure.locator} showed "${failure.received}" instead of "${failure.expected}".`;
     }
     if (failure.signal === "locator_not_found" && failure.locator) {
         return `${failure.locator} was not found when the test expected it to be available.`;
@@ -161,68 +555,390 @@ const describeFailure = (failure) => {
         return `${failure.locator} was found but was not actionable when the interaction ran.`;
     }
     if (failure.signal === "network") {
-        return `The test likely failed because a network or API request did not complete successfully.`;
+        return failure.apiHint
+            ? `A network or API request around ${failure.apiHint} did not complete successfully.`
+            : `A network or API request did not complete successfully.`;
     }
     if (failure.signal === "timeout") {
-        return `The expected UI or network condition did not complete before timeout.`;
+        const domState = describeDomState(failure);
+        if (domState)
+            return `${domState}.`;
+        return failure.timeoutMs
+            ? `The expected UI or network condition did not complete before the ${failure.timeoutMs}ms timeout.`
+            : `The expected UI or network condition did not complete before timeout.`;
+    }
+    if (failure.signal === "runtime" && /retry|flaky/i.test(failure.message)) {
+        return `The test code threw a retry or flaky guard error before the app flow completed.`;
     }
     if (failure.signal === "runtime") {
-        return `A frontend runtime error interrupted the test flow.`;
+        return `A runtime error interrupted the test flow before the expected state was reached.`;
+    }
+    if (failure.signal === "infra") {
+        return `The test failed because the browser or CI worker became unstable before the flow completed.`;
     }
     return `The failure signal could not be classified cleanly from the captured error.`;
 };
 exports.describeFailure = describeFailure;
-const buildDebugSummary = (failure) => {
-    const lines = [
-        `Test: ${failure.title}`,
-        `Diagnosis: ${(0, exports.describeFailure)(failure)}`
-    ];
+const describeCluster = (cluster) => {
+    const failure = cluster.sample;
+    if (failure.signal === "runtime" && /retry|flaky/i.test(failure.message)) {
+        const location = buildLocationLine(failure);
+        const origin = location ? ` The same helper threw at ${location.replace(/^Error location: /, '').replace(/^Likely file: /, '')}.` : "";
+        return `${cluster.count} tests hit the same test-side throw before the app flow completed.${origin}`;
+    }
+    if (cluster.count > 1 && failure.signal === "assertion_mismatch") {
+        return `${cluster.count} tests hit the same UI assertion mismatch, which usually means one shared UI regression.`;
+    }
+    if (cluster.count > 1 && failure.signal === "network") {
+        return `${cluster.count} tests failed behind the same network or API signal.`;
+    }
+    if (cluster.count > 1 && failure.signal === "timeout") {
+        return `${cluster.count} tests timed out behind the same blocked state transition.`;
+    }
+    if (cluster.count > 1 && failure.signal === "infra") {
+        return `${cluster.count} tests failed behind the same browser or CI instability signal.`;
+    }
+    return (0, exports.describeFailure)(failure);
+};
+const clusterCheckFirst = (cluster) => {
+    const failure = cluster.sample;
+    if (failure.signal === "runtime" && /retry|flaky/i.test(failure.message)) {
+        const file = basename(failure.codeContext?.file || failure.likelyFile);
+        const line = failure.codeContext?.line;
+        if (file && line) {
+            return `inspect the throw at ${file}:${line} before opening the trace`;
+        }
+        return "inspect the shared retry/flaky helper or intentional throw in these tests before opening the trace";
+    }
+    return checkFirst(failure);
+};
+const formatAffectedTests = (titles) => {
+    const unique = Array.from(new Set(titles.map((title) => shortenTitle(title)))).slice(0, 3);
+    if (!unique.length)
+        return null;
+    return `Affected tests: ${unique.join("; ")}`;
+};
+const buildLocationLine = (failure) => {
+    const file = failure.codeContext?.file || failure.likelyFile;
+    const line = failure.codeContext?.line;
+    const column = failure.codeContext?.column;
+    if (!file)
+        return null;
+    if (line && column)
+        return `Error location: ${basename(file)}:${line}:${column}`;
+    if (line)
+        return `Error location: ${basename(file)}:${line}`;
+    return `Likely file: ${basename(file)}`;
+};
+const compactLocation = (failure) => {
+    const file = failure.codeContext?.file || failure.likelyFile;
+    const line = failure.codeContext?.line;
+    if (!file)
+        return null;
+    return line ? `${basename(file)}:${line}` : basename(file);
+};
+const buildClusterLocationLine = (failures) => {
+    const locations = Array.from(new Set(failures.map((failure) => compactLocation(failure)).filter(Boolean)));
+    if (!locations.length)
+        return null;
+    const label = locations.length > 1 ? 'Error locations' : 'Error location';
+    return `${label}: ${locations.slice(0, 3).join('; ')}`;
+};
+const buildEvidenceLines = (failure) => {
+    const lines = [];
+    const locationLine = buildLocationLine(failure);
+    if (locationLine)
+        lines.push(locationLine);
+    if (failure.codeContext?.focusLine)
+        lines.push(`Failing code: ${failure.codeContext.focusLine.trim()}`);
+    if (failure.codeContext?.action)
+        lines.push(`Failing step: ${failure.codeContext.action}`);
     if (failure.locator)
-        lines.push(`Locator: ${failure.locator}`);
+        lines.push(`Selector: ${failure.locator}`);
+    if (failure.signal === "timeout" && failure.domCapture) {
+        if (failure.domCapture.targetFound === false || failure.domCapture.matchedCount === 0) {
+            lines.push(`Target state: locator never appeared`);
+        }
+        else if (failure.domCapture.visible === false) {
+            lines.push(`Target state: found but hidden`);
+        }
+        else if (failure.domCapture.enabled === false) {
+            lines.push(`Target state: found but disabled`);
+        }
+        else if (failure.domCapture.targetFound === true && failure.domCapture.visible === true) {
+            lines.push(`Target state: found and visible before timeout`);
+        }
+    }
+    if (failure.apiHint)
+        lines.push(`API: ${failure.apiHint}`);
+    return lines.slice(0, 4);
+};
+const withoutPrefix = (value, prefix) => value.startsWith(prefix) ? value.slice(prefix.length).trim() : value;
+const buildSecondaryEvidenceLines = (failure) => buildEvidenceLines(failure)
+    .filter((line) => !line.startsWith("Error location:") && !line.startsWith("Likely file:"))
+    .slice(0, 3);
+const compactRootCauseSummary = (cluster) => {
+    const failure = cluster.sample;
+    if (failure.signal === "runtime" && /retry|flaky/i.test(failure.message)) {
+        return "Same test-side throw before the app flow completed";
+    }
+    if (failure.signal === "network") {
+        return failure.apiHint
+            ? `Same network/API failure around ${failure.apiHint}`
+            : "Same network/API failure across these tests";
+    }
+    if (failure.signal === "timeout") {
+        return "Same blocked state transition timed out across these tests";
+    }
+    if (failure.signal === "assertion_mismatch") {
+        return "Same UI assertion mismatch across these tests";
+    }
+    if (failure.signal === "locator_not_found") {
+        return "Same missing or changed locator across these tests";
+    }
+    if (failure.signal === "actionability") {
+        return "Same element actionability problem across these tests";
+    }
+    if (failure.signal === "infra") {
+        return "Same browser/CI instability affected these tests";
+    }
+    return describeCluster(cluster);
+};
+const compactErrorLine = (failure) => {
+    if (!failure.firstErrorLine)
+        return null;
+    return withoutPrefix(failure.firstErrorLine, "Error:");
+};
+const parseFailureFacts = (title, titlePath, message, status, file = null, options) => {
+    const signal = classifySignal(message);
+    const fallbackLocation = options?.errorLocation || extractStackLocation(message);
+    const fallbackCodeContext = fallbackLocation || options?.errorSnippet
+        ? {
+            file: fallbackLocation?.file || file || null,
+            line: typeof fallbackLocation?.line === "number" ? fallbackLocation.line : null,
+            column: typeof fallbackLocation?.column === "number" ? fallbackLocation.column : null,
+            action: null,
+            locator: null,
+            expectedText: null,
+            timeoutMs: null,
+            apiCall: null,
+            assertion: null,
+            methodName: null,
+            focusLine: extractFocusLineFromSnippet(options?.errorSnippet),
+            previousActionLine: null,
+            found: Boolean(fallbackLocation?.file || options?.errorSnippet)
+        }
+        : null;
+    const codeContext = options?.codeContext
+        ? {
+            ...fallbackCodeContext,
+            ...options.codeContext,
+            file: options.codeContext.file || fallbackCodeContext?.file || null,
+            line: options.codeContext.line ?? fallbackCodeContext?.line ?? null,
+            column: options.codeContext.column ?? fallbackCodeContext?.column ?? null,
+            focusLine: options.codeContext.focusLine || fallbackCodeContext?.focusLine || null,
+            found: options.codeContext.found ?? fallbackCodeContext?.found ?? false
+        }
+        : fallbackCodeContext || null;
+    const domCapture = options?.domCapture || null;
+    const locator = extractLocator(message) || codeContext?.locator || domCapture?.locator || null;
+    const expected = extractExpected(message) || codeContext?.expectedText || domCapture?.expectedText || null;
+    const received = extractReceived(message) || domCapture?.observedText || domCapture?.textContent || null;
+    const likelyFile = inferLikelyFile(file, codeContext);
+    const likelyModule = inferLikelyModule(file, locator, codeContext);
+    const apiHint = extractApiHint(message, codeContext);
+    return {
+        title,
+        titlePath,
+        projectName: options?.projectName || null,
+        message,
+        firstErrorLine: stripAnsi(message).split(/\r?\n/).map((line) => line.trim()).find(Boolean) || null,
+        signal,
+        locator,
+        expected,
+        received,
+        timeoutMs: extractTimeoutMs(message) || codeContext?.timeoutMs || options?.timeoutBudgetMs || null,
+        timeoutBudgetMs: options?.timeoutBudgetMs || codeContext?.timeoutMs || null,
+        lastUrl: extractLastUrl(message),
+        status,
+        file,
+        likelyFile,
+        likelyModule,
+        apiHint,
+        codeContext,
+        domCapture
+    };
+};
+exports.parseFailureFacts = parseFailureFacts;
+const collectFailureFacts = (playwrightJsonPath) => {
+    if (!node_fs_1.default.existsSync(playwrightJsonPath))
+        return [];
+    try {
+        const raw = node_fs_1.default.readFileSync(playwrightJsonPath, "utf8");
+        const parsed = JSON.parse(raw);
+        return flattenFailedCases(parsed);
+    }
+    catch {
+        return [];
+    }
+};
+exports.collectFailureFacts = collectFailureFacts;
+const buildDebugSummary = (failure) => {
+    const lines = [`Test: ${failure.title}`, `Diagnosis: ${(0, exports.describeFailure)(failure)}`];
+    for (const line of buildEvidenceLines(failure))
+        lines.push(line);
     if (failure.expected)
         lines.push(`Expected: ${failure.expected}`);
     if (failure.received)
         lines.push(`Observed: ${failure.received}`);
     if (failure.timeoutMs)
         lines.push(`Timeout: ${failure.timeoutMs}ms`);
-    if (failure.lastUrl)
-        lines.push(`URL: ${failure.lastUrl}`);
     return lines.join("\n");
 };
 exports.buildDebugSummary = buildDebugSummary;
 const buildSimilarityKey = (failure) => {
-    if (failure.locator || failure.expected || failure.received) {
+    const locationKey = failure.codeContext?.line ? `${basename(failure.codeContext.file)}:${failure.codeContext.line}` : basename(failure.likelyFile) || "unknown-file";
+    if (failure.signal === 'runtime' || failure.signal === 'unknown') {
         return [
             failure.signal,
-            failure.locator || "unknown-locator",
+            normalizeMessageFingerprint(failure.message),
+            locationKey
+        ].join('|');
+    }
+    if (failure.locator || failure.expected || failure.received || failure.apiHint) {
+        return [
+            failure.signal,
+            failure.locator || failure.apiHint || "unknown-target",
             failure.expected || "unknown-expected",
-            failure.received || "unknown-received"
+            failure.received || "unknown-received",
+            locationKey
         ].join("|");
     }
-    return `${failure.signal}|${normalizeMessageFingerprint(failure.message)}`;
+    return `${failure.signal}|${normalizeMessageFingerprint(failure.message)}|${locationKey}`;
 };
 exports.buildSimilarityKey = buildSimilarityKey;
-exports.summarizeSignal = signalSummary;
+const summarizeSignal = (signal) => {
+    switch (signal) {
+        case "timeout":
+            return "timeout while waiting for UI or network conditions";
+        case "assertion_mismatch":
+            return "assertion mismatch between expected and rendered UI state";
+        case "locator_not_found":
+            return "missing or changed locator";
+        case "actionability":
+            return "target element was not actionable";
+        case "network":
+            return "network or API failure";
+        case "runtime":
+            return "runtime error thrown before the flow completed";
+        case "infra":
+            return "browser or CI infrastructure failure";
+        default:
+            return "failure signal could not be classified cleanly";
+    }
+};
+exports.summarizeSignal = summarizeSignal;
+const buildClusterSuspects = (clusterFailures, window) => {
+    return window.commits
+        .map((commit) => {
+        const combined = clusterFailures.map((failure) => commitTouchedFailure(commit, failure));
+        const score = combined.reduce((sum, item) => sum + item.score, 0);
+        const reasons = Array.from(new Set(combined.flatMap((item) => item.reasons))).slice(0, 3);
+        const touchedFiles = Array.from(new Set(combined.flatMap((item) => item.touchedFiles))).slice(0, 3);
+        return { commit, score, reasons, touchedFiles };
+    })
+        .filter((entry) => entry.score > 0.2)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 2);
+};
 const buildQuickDiagnosis = (playwrightJsonPath) => {
     const failures = (0, exports.collectFailureFacts)(playwrightJsonPath);
     if (!failures.length)
         return null;
+    const commitWindow = getCommitWindow();
     if (failures.length === 1) {
         const failed = failures[0];
+        const suspects = commitWindow.trusted ? rankCommitsForFailure(failed, commitWindow) : [];
+        const top = suspects[0];
+        const alt = suspects[1];
+        const lines = [`${formatTitle(failed.title)} failed.`, `What broke: ${(0, exports.describeFailure)(failed)}`];
+        const primaryLocation = buildLocationLine(failed);
+        if (primaryLocation)
+            lines.push(`Where: ${withoutPrefix(withoutPrefix(primaryLocation, "Error location:"), "Likely file:")}`);
+        if (failed.firstErrorLine)
+            lines.push(`Error: ${failed.firstErrorLine}`);
+        for (const evidence of buildSecondaryEvidenceLines(failed))
+            lines.push(evidence);
+        if (top) {
+            lines.push(compactCommitLine(top));
+            lines.push(`Why Sentinel picked it: ${compactWhyLine(top)}.`);
+            if (top.touchedFiles.length) {
+                lines.push(`Touched files: ${top.touchedFiles.map((file) => basename(file)).join(", ")}`);
+            }
+            if (alt)
+                lines.push(alternateCommitLine(alt));
+        }
+        lines.push(`Check first: ${checkFirst(failed)}.`);
         return {
-            lines: [`Test "${failed.title}" likely failed due to ${signalSummary(failed.signal)}.`]
+            lines,
+            footer: [
+                ...(top ? [`Confidence: ${confidenceLabel(top.score)}`] : []),
+                ...(commitWindow.trusted ? [`Commits analyzed: ${commitWindow.commits.length}`] : [`Commit blame skipped: ${commitWindow.reason}`])
+            ]
         };
     }
-    const counts = new Map();
-    for (const failed of failures) {
-        counts.set(failed.signal, (counts.get(failed.signal) || 0) + 1);
+    const clusterMap = new Map();
+    for (const failure of failures) {
+        const key = (0, exports.buildSimilarityKey)(failure);
+        const bucket = clusterMap.get(key) || [];
+        bucket.push(failure);
+        clusterMap.set(key, bucket);
+    }
+    const clusters = Array.from(clusterMap.entries())
+        .map(([key, clusterFailures]) => ({
+        key,
+        count: clusterFailures.length,
+        sample: clusterFailures[0],
+        titles: clusterFailures.map((item) => item.title),
+        suspects: commitWindow.trusted ? buildClusterSuspects(clusterFailures, commitWindow) : []
+    }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 2);
+    const topCluster = clusters[0];
+    const lines = [
+        `${failures.length} tests failed.`,
+        `Collapsed into ${clusters.length} likely root cause${clusters.length === 1 ? "" : "s"}:`
+    ];
+    for (const [index, cluster] of clusters.entries()) {
+        const clusterFailures = clusterMap.get(cluster.key) || [cluster.sample];
+        const clusterLocation = buildClusterLocationLine(clusterFailures);
+        const top = cluster.suspects[0];
+        const locationValue = clusterLocation
+            ? withoutPrefix(clusterLocation, clusterLocation.startsWith("Error locations:") ? "Error locations:" : "Error location:")
+            : null;
+        const rootCause = compactRootCauseSummary(cluster);
+        const errorLine = compactErrorLine(cluster.sample);
+        lines.push(`[${index + 1}] ${rootCauseLabel(cluster.sample)} (${cluster.count} tests)`);
+        lines.push(`    Root cause: ${rootCause}`);
+        if (errorLine) {
+            lines.push(`    Error: ${errorLine}`);
+        }
+        if (locationValue) {
+            lines.push(`    Where: ${locationValue}`);
+        }
+        if (top && top.touchedFiles.length) {
+            lines.push(`    Changed files: ${top.touchedFiles.map((file) => basename(file)).join(", ")}`);
+        }
+        lines.push(`    Check first: ${clusterCheckFirst(cluster)}.`);
     }
-    const topSignal = Array.from(counts.entries()).sort((a, b) => b[1] - a[1])[0]?.[0] || "unknown";
     return {
-        lines: [
-            `${failures.length} tests failed.`,
-            `Most common signal: ${signalSummary(topSignal)}.`
-        ]
+        lines,
+        footer: topCluster
+            ? [
+                ...(topCluster.suspects[0] ? [`Top confidence: ${confidenceLabel(topCluster.suspects[0].score)}`] : []),
+                ...(commitWindow.trusted ? [`Commits analyzed: ${commitWindow.commits.length}`] : [`Commit blame skipped: ${commitWindow.reason}`])
+            ]
+            : []
     };
 };
 exports.buildQuickDiagnosis = buildQuickDiagnosis;