donobu 5.60.1 → 5.60.2

package/dist/esm/cli/donobu-cli.js

@@ -62,6 +62,7 @@ const path = __importStar(require("path"));
 const v4_1 = require("zod/v4");
 const envVars_1 = require("../envVars");
 const gptClients_1 = require("../lib/test/fixtures/gptClients");
+const healRerunGate_1 = require("../lib/test/healRerunGate");
 const donobuTestStack_1 = require("../lib/test/utils/donobuTestStack");
 const triageTestFailure_1 = require("../lib/test/utils/triageTestFailure");
 const fileUploadWorkerRegistry_1 = require("../persistence/files/fileUploadWorkerRegistry");
@@ -73,6 +74,7 @@ const render_1 = require("../reporter/render");
 const renderMarkdown_1 = require("../reporter/renderMarkdown");
 const renderPullRequestBody_1 = require("../reporter/renderPullRequestBody");
 const renderSlack_1 = require("../reporter/renderSlack");
+const reportWalk_1 = require("../reporter/reportWalk");
 const slack_1 = require("../reporter/slack");
 const Logger_1 = require("../utils/Logger");
 const FAILURE_EVIDENCE_PREFIX = 'failure-evidence-';
@@ -988,12 +990,21 @@ function evaluateAutoHealEligibility(plans) {
 /**
  * Coalesce directives from one or more treatment plans into a single Playwright
  * invocation. Multiple failed tests can be healed in a single rerun, so we
- * gather all relevant files/projects/titles here.
+ * gather all relevant projects (or files, as a fallback) here.
+ *
+ * The rerun deliberately targets whole Playwright *projects*, not individual
+ * failed tests. Suites commonly chain ordered tests — checkpoint guards,
+ * serial files, cross-file prerequisites within a project — and a rerun that
+ * filters down to just the failed titles can never heal such a test: its
+ * prerequisite never runs, the test skips itself, and no fix is exercised.
+ * The project is the unit where Playwright encodes that ordering (testMatch
+ * order, workers, dependencies), so it is the narrowest scope that is always
+ * safe to re-run. File narrowing is kept only as a fallback when no project
+ * name could be resolved.
  */
 function derivePlaywrightDirectiveArgs(descriptors) {
     const targetFiles = new Set();
     const targetProjects = new Set();
-    const targetTitles = new Set();
     const additionalArgs = [];
     for (const descriptor of descriptors) {
         const directives = descriptor.plan.automationDirectives;
@@ -1008,9 +1019,6 @@ function derivePlaywrightDirectiveArgs(descriptors) {
         if (projectCandidate && !looksLikePath(projectCandidate)) {
             targetProjects.add(projectCandidate);
         }
-        if (descriptor.testCase.title) {
-            targetTitles.add(descriptor.testCase.title);
-        }
         if (directives.additionalPlaywrightArgs) {
             directives.additionalPlaywrightArgs.forEach((arg) => {
                 additionalArgs.push(arg);
@@ -1018,20 +1026,11 @@ function derivePlaywrightDirectiveArgs(descriptors) {
         }
     }
     return {
-        files: Array.from(targetFiles),
+        files: targetProjects.size > 0 ? [] : Array.from(targetFiles),
         projects: Array.from(targetProjects),
-        grepPattern: targetTitles.size > 0
-            ? Array.from(targetTitles)
-                .map((title) => escapeRegex(title))
-                .join('|')
-            : undefined,
         extras: additionalArgs,
     };
 }
-// We match test titles via `--grep`, so ensure literal characters are escaped.
-function escapeRegex(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
 // Some teams name projects after directories (e.g. `projects/mobile`); treat those as file paths.
 function looksLikePath(value) {
     return value.includes('/') || value.includes('\\');
@@ -1057,21 +1056,34 @@ function extractOriginalFiles(args) {
 }
 /**
  * Preserve most user-provided Playwright flags (e.g. `--config`, `--workers`).
- * We only strip flags we know we're going to replace (projects, grep, reporter).
+ * We only strip flags we know we're going to replace (projects, reporter).
+ * The user's own `--grep` IS preserved: it scoped the initial run, so the heal
+ * rerun must stay inside it (the rerun no longer adds a grep of its own).
  */
 function extractPreservedOptions(args) {
-    return args.slice(1).filter((arg) => {
+    const preserved = [];
+    const rest = args.slice(1);
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
         if (!arg.startsWith('--')) {
-            return false;
+            continue;
         }
-        const optionName = arg.startsWith('--') ? arg.split('=')[0] : arg;
-        return (optionName !== '--project' &&
-            !optionName.startsWith('--project=') &&
-            optionName !== '--grep' &&
-            optionName !== '--reporter' &&
-            !optionName.startsWith('--grep=') &&
-            !optionName.startsWith('--reporter='));
-    });
+        const optionName = arg.split('=')[0];
+        if (optionName === '--project' || optionName === '--reporter') {
+            continue;
+        }
+        preserved.push(arg);
+        // Space-separated flag values (`--grep pattern`) would otherwise be
+        // dropped by the `--`-prefix filter above; carry the grep value along.
+        if ((optionName === '--grep' || optionName === '--grep-invert') &&
+            arg === optionName &&
+            i + 1 < rest.length &&
+            !rest[i + 1].startsWith('--')) {
+            preserved.push(rest[i + 1]);
+            i += 1;
+        }
+    }
+    return preserved;
 }
 /**
  * Merge the user's original Playwright command with the automation directives
@@ -1084,14 +1096,14 @@ function buildPlaywrightArgsWithDirectives(originalArgs, directives) {
         : extractOriginalFiles(originalArgs);
     const preservedOptions = extractPreservedOptions(originalArgs);
     const projectArgs = directives.projects.map((project) => `--project=${project}`);
-    const grepArgs = directives.grepPattern
-        ? ['--grep', directives.grepPattern]
-        : [];
+    // When the rerun targets whole projects, file filters from the original
+    // invocation would shrink the scope below the project's testMatch and can
+    // exclude prerequisite tests — drop them; `--project` already narrows.
+    const fileArgs = directives.projects.length > 0 ? [] : files;
     const finalArgs = [
         'test',
-        ...files,
+        ...fileArgs,
         ...projectArgs,
-        ...grepArgs,
         ...directives.extras,
         ...preservedOptions,
     ];
@@ -1317,12 +1329,28 @@ async function attemptAutoHealRun(params) {
     let healExitCode = params.currentExitCode;
     const healOptions = {
         ...params.options,
-        clearAiCache: params.options.clearAiCache || evaluation.clearPageAiCache === true,
         autoHeal: false,
         triageOutputDir: staging.triageBaseDir,
     };
-    if (evaluation.clearPageAiCache && !params.options.clearAiCache) {
-        Logger_1.appLogger.info('Auto-heal: clearing Page.AI cache as recommended by the treatment plan.');
+    // Heal targets, expanded with their declared `describe.serial` siblings so
+    // the rerun executes the whole declared group (Playwright's own retry
+    // semantics for serial chains). The serial flags come from the initial
+    // run's Donobu report; without it, targets run unexpanded.
+    const healTargets = (0, healRerunGate_1.expandTargetsWithSerialCompanions)(evaluation.eligiblePlans.map((record) => ({
+        file: record.evidence.failureContext.testCase.file ?? '',
+        title: record.evidence.failureContext.testCase.title,
+        projectName: record.evidence.failureContext.testCase.projectName,
+    })), params.initialReport ?? null);
+    // Cache invalidation is scoped to the heal targets' spec files: serial
+    // prerequisites and any other re-running test keep their fast cache replay.
+    // The user's own `--clear-ai-cache` flag stays run-wide.
+    const clearCacheFiles = evaluation.clearPageAiCache && !params.options.clearAiCache
+        ? Array.from(new Set(healTargets
+            .map((target) => target.file)
+            .filter((file) => Boolean(file))))
+        : [];
+    if (clearCacheFiles.length > 0) {
+        Logger_1.appLogger.info(`Auto-heal: clearing Page.AI cache for ${clearCacheFiles.length} target spec file(s) as recommended by the treatment plan.`);
     }
     const healArgsWithDirectives = buildPlaywrightArgsWithDirectives(params.playwrightArgs, evaluation.directives);
     const healArgsForRun = overrideOutputDir(healArgsWithDirectives, staging.playwrightOutputDir);
@@ -1346,7 +1374,18 @@ async function attemptAutoHealRun(params) {
         applyJsonReportEnv(envOverrides, staging.playwrightOutputDir);
         // Flag downstream systems so they know this invocation came from auto-heal.
         envOverrides.DONOBU_AUTO_HEAL_ACTIVE = '1';
-        Logger_1.appLogger.info(`Auto-heal: applying directives from ${evaluation.eligiblePlans.length} treatment plan(s) and re-running Playwright...`);
+        if (clearCacheFiles.length > 0) {
+            envOverrides.DONOBU_PAGE_AI_CLEAR_CACHE_FILES =
+                JSON.stringify(clearCacheFiles);
+        }
+        // The rerun plan drives the collection-time gate in the test wrapper:
+        // only the heal targets (and their declared `describe.serial` siblings)
+        // execute; every other collected test statically skips. Declared
+        // dependency projects still run in full — Playwright's semantics.
+        const healPlanPath = path.join(staging.rootDir, 'heal-rerun-plan.json');
+        await fs_1.promises.writeFile(healPlanPath, JSON.stringify({ targets: healTargets }), 'utf8');
+        envOverrides.DONOBU_AUTO_HEAL_PLAN_PATH = healPlanPath;
+        Logger_1.appLogger.info(`Auto-heal: re-running ${healTargets.length} targeted test(s) from ${evaluation.eligiblePlans.length} treatment plan(s)...`);
         const healJsonReportPath = path.join(staging.playwrightOutputDir, PLAYWRIGHT_JSON_REPORT_FILENAME);
         const reporterSetup = await ensureJsonReporter(healArgsForRun, {
             jsonOutputFile: healJsonReportPath,
@@ -1396,6 +1435,30 @@ async function attemptAutoHealRun(params) {
         // Prefer the heal reporter's state file; fall back to Playwright's JSON
         // reporter output for configs that don't wire up the Donobu reporter.
         const healReport = await loadDonobuReportForMerge(staging.playwrightOutputDir, healReportCopy?.destinationPath ?? undefined);
+        // A heal rerun "succeeds" only when every test it set out to heal
+        // actually passed in the rerun. The rerun's exit code alone can't tell:
+        // a target that skipped itself (e.g. a precondition guard fired) exits
+        // zero, and the project-scope rerun includes unrelated tests. Matched on
+        // title + project — file paths differ in shape between treatment plans
+        // (absolute) and reports (rootDir-relative).
+        if (healExitCode === 0) {
+            const unhealedTargets = evaluation.eligiblePlans.filter((record) => {
+                const testCase = record.evidence.failureContext.testCase;
+                const healTest = findTestInReport(healReport, testCase.title, testCase.projectName);
+                if (!healTest) {
+                    return true;
+                }
+                const status = (0, reportWalk_1.statusOf)(healTest);
+                return status !== 'passed' && status !== 'flaky' && status !== 'healed';
+            });
+            if (unhealedTargets.length > 0) {
+                const titles = unhealedTargets
+                    .map((record) => record.evidence.failureContext.testCase.title)
+                    .join('", "');
+                Logger_1.appLogger.warn(`Auto-heal rerun did not fix ${unhealedTargets.length} targeted test(s): "${titles}" (failed again, or never re-attempted because a precondition was missing). Keeping failing status.`);
+                healExitCode = 1;
+            }
+        }
         if (params.initialReport || healReport) {
             // Write the merged report directly to the user's JSON reporter target
             // when one exists. When the user did not configure a JSON reporter,
@@ -1409,20 +1472,15 @@ async function attemptAutoHealRun(params) {
                 healReport,
                 healReportSourcePath: healReportCopy?.destinationPath ?? undefined,
                 mergedReportPath: params.userJsonOutputFile ?? undefined,
-                healedTests: evaluation.eligiblePlans.map((record) => ({
-                    plan: record.plan,
-                    testCase: record.evidence.failureContext.testCase,
-                })),
-                healSucceeded: healExitCode === 0,
                 outputDir: params.playwrightOutputDir,
                 triageRunDir: params.triageRunDir,
             });
             if (mergedReport) {
                 await regenerateDonobuReports(mergedReport);
                 await writeAutoHealPullRequestBody(mergedReport, params.playwrightOutputDir);
-                // The heal rerun only re-runs the grep-filtered subset of healable
-                // tests, so `healExitCode` is blind to failures triage declined to
-                // retry (e.g. real product bugs). Re-derive the status from the merged
+                // The heal rerun only re-runs the projects containing healable tests,
+                // so `healExitCode` is blind to failures triage declined to retry
+                // (e.g. real product bugs). Re-derive the status from the merged
                 // report so those remaining failures still fail CI. We only escalate
                 // (never downgrade a non-zero heal exit) to preserve infra/crash codes.
                 const remainingFailures = countUnexpectedTests(mergedReport);
@@ -1450,6 +1508,43 @@ function countUnexpectedTests(report) {
     const unexpected = stats?.unexpected;
     return typeof unexpected === 'number' ? unexpected : undefined;
 }
+/**
+ * Find a test entry in a report by title + project name. File paths are
+ * deliberately not part of the lookup: treatment plans carry absolute paths
+ * while reports carry rootDir-relative ones, and title + project is already
+ * how Playwright disambiguates tests within a run.
+ */
+function findTestInReport(report, title, projectName) {
+    if (!report?.suites || !title) {
+        return null;
+    }
+    const visitSuite = (suite) => {
+        for (const spec of suite.specs ?? []) {
+            if (spec.title !== title) {
+                continue;
+            }
+            for (const test of spec.tests ?? []) {
+                if (!projectName || (test.projectName ?? '') === projectName) {
+                    return test;
+                }
+            }
+        }
+        for (const child of suite.suites ?? []) {
+            const found = visitSuite(child);
+            if (found) {
+                return found;
+            }
+        }
+        return null;
+    };
+    for (const suite of report.suites) {
+        const found = visitSuite(suite);
+        if (found) {
+            return found;
+        }
+    }
+    return null;
+}
 /**
  * Filename of the auto-heal PR body artifact. Lands in the Playwright output
  * directory alongside the merged JSON / HTML / Markdown reports so the
@@ -1667,8 +1762,6 @@ async function mergePlaywrightJsonReports(params) {
     const merged = (0, merge_1.mergeReports)({
         initialReport: params.initialReport,
         healReport: params.healReport,
-        healedTests: params.healedTests,
-        healSucceeded: params.healSucceeded,
         triageRunDir: params.triageRunDir,
         initialReportSourcePath: params.initialReportSourcePath,
         healReportSourcePath: params.healReportSourcePath,
@@ -2085,6 +2178,19 @@ async function runHealCommand(cliArgs) {
     applyJsonReportEnv(envOverrides, playwrightOutputDir);
     // Downstream hooks check this flag to avoid recursive auto-heal loops.
     envOverrides.DONOBU_AUTO_HEAL_ACTIVE = '1';
+    // Same collection-time gating as the automatic rerun: only the plan's test
+    // (plus declared `describe.serial` siblings) executes.
+    const healPlanPath = path.join(os.tmpdir(), `donobu-heal-rerun-plan-${Date.now()}.json`);
+    await fs_1.promises.writeFile(healPlanPath, JSON.stringify({
+        targets: [
+            {
+                file: persisted.failure.testCase.file,
+                title: persisted.failure.testCase.title,
+                projectName: persisted.failure.testCase.projectName,
+            },
+        ],
+    }), 'utf8');
+    envOverrides.DONOBU_AUTO_HEAL_PLAN_PATH = healPlanPath;
     Logger_1.appLogger.info(`Re-running Playwright using treatment plan at ${parsed.planPath}...`);
     const healJsonReportPath = path.join(playwrightOutputDir, PLAYWRIGHT_JSON_REPORT_FILENAME);
     const reporterSetup = await ensureJsonReporter(healArgsWithDirectives, {
@@ -2123,13 +2229,6 @@ async function runHealCommand(cliArgs) {
             healReport,
             healReportSourcePath: healReportCopy?.destinationPath ?? undefined,
             mergedReportPath,
-            healedTests: [
-                {
-                    plan: persisted.plan,
-                    testCase: persisted.failure.testCase,
-                },
-            ],
-            healSucceeded: exitCode === 0,
             outputDir: path.dirname(mergedReportPath),
         });
         if (mergedReport) {

package/dist/esm/envVars.d.ts

@@ -59,6 +59,8 @@ export declare const env: Env<{
         true: "true";
         false: "false";
     }>>;
+    DONOBU_PAGE_AI_CLEAR_CACHE_FILES: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    DONOBU_AUTO_HEAL_PLAN_PATH: z.ZodOptional<z.ZodString>;
     GOOGLE_GENERATIVE_AI_API_KEY: z.ZodOptional<z.ZodString>;
     GOOGLE_GENERATIVE_AI_MODEL_NAME: z.ZodOptional<z.ZodString>;
     OLLAMA_MODEL_NAME: z.ZodOptional<z.ZodString>;
@@ -116,6 +118,8 @@ export declare const env: Env<{
     CI_COMMIT_REF_NAME?: string | undefined;
     PLAYWRIGHT_JSON_OUTPUT_DIR?: string | undefined;
     DONOBU_PAGE_AI_CLEAR_CACHE?: "0" | "1" | "true" | "false" | undefined;
+    DONOBU_PAGE_AI_CLEAR_CACHE_FILES?: string[] | undefined;
+    DONOBU_AUTO_HEAL_PLAN_PATH?: string | undefined;
     GOOGLE_GENERATIVE_AI_API_KEY?: string | undefined;
     GOOGLE_GENERATIVE_AI_MODEL_NAME?: string | undefined;
     OLLAMA_MODEL_NAME?: string | undefined;

package/dist/esm/envVars.js

@@ -128,6 +128,18 @@ re-render reports from merged data).`),
 bypass and invalidate Page.AI cache entries for the current run. The Donobu
 CLI sets this automatically when invoked with \`--clear-ai-cache\` so a retry
 always regenerates selectors from scratch.`),
+    DONOBU_PAGE_AI_CLEAR_CACHE_FILES: v4_1.z.array(v4_1.z.string()).optional()
+        .describe(`Spec file paths whose Page.AI cache entries should be bypassed and
+invalidated for the current run (JSON-encoded on the wire). Set by the
+auto-heal orchestrator so the rerun regenerates selectors only for the spec
+files that contain heal targets, while every other re-running test keeps its
+fast deterministic cache replay.`),
+    DONOBU_AUTO_HEAL_PLAN_PATH: v4_1.z.string().optional()
+        .describe(`Path to the auto-heal rerun plan (JSON) written by the Donobu CLI before the
+heal rerun. When set, a Donobu auto fixture skips every test that is not part
+of the plan (heal targets and, for targets inside a \`describe.serial\` group,
+their serial siblings) before any browser fixture initializes, so the rerun
+only pays for what the heal actually needs.`),
     GOOGLE_GENERATIVE_AI_API_KEY: v4_1.z.string().optional()
         .describe(`Automatically create GPT configurations for Google Gemini using this API key.
 For convenience, the created configuration names will reflect the

package/dist/esm/lib/page/extendPage.d.ts

@@ -20,6 +20,12 @@ export declare function extendPage(page: Page, options?: {
     flowId?: string;
     visualCueDurationMs?: number;
     cacheFilepath?: string;
+    /**
+     * Spec file this page is serving. Used to decide whether the file-scoped
+     * Page.AI cache invalidation (`DONOBU_PAGE_AI_CLEAR_CACHE_FILES`) applies
+     * to this context.
+     */
+    specFilePath?: string;
     envVars?: string[];
     gptClient?: GptClient;
     headless?: boolean;

package/dist/esm/lib/page/extendPage.js

@@ -1,7 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extendPage = extendPage;
 const crypto_1 = require("crypto");
+const path_1 = __importDefault(require("path"));
 const v4_1 = require("zod/v4");
 const GptClient_1 = require("../../clients/GptClient");
 const VercelAiGptClient_1 = require("../../clients/VercelAiGptClient");
@@ -60,6 +64,25 @@ function resolveBaseUrl(page, url) {
 // Donobu page extension helpers: decorate Playwright pages with Donobu behaviors and keep one
 // coherent flow (and persistence record) per browser context so new tabs share state safely.
 const PLACEHOLDER_FLOW_URL = 'https://example.com';
+/**
+ * Whether Page.AI cache entries should be bypassed and invalidated for this
+ * context. Two knobs:
+ * - `DONOBU_PAGE_AI_CLEAR_CACHE` — run-wide, set by `--clear-ai-cache`.
+ * - `DONOBU_PAGE_AI_CLEAR_CACHE_FILES` — JSON array of spec paths, set by the
+ *   auto-heal rerun so only heal-target spec files regenerate selectors while
+ *   other re-running tests (serial prerequisites) keep their cache replay.
+ */
+function shouldClearPageAiCache(specFilePath) {
+    if (MiscUtils_1.MiscUtils.yn(envVars_1.env.data.DONOBU_PAGE_AI_CLEAR_CACHE)) {
+        return true;
+    }
+    const files = envVars_1.env.data.DONOBU_PAGE_AI_CLEAR_CACHE_FILES;
+    if (!files?.length || !specFilePath) {
+        return false;
+    }
+    const resolved = path_1.default.resolve(specFilePath);
+    return files.some((file) => path_1.default.resolve(file) === resolved);
+}
 // Cache the shared Donobu state per browser context so every tab in that context reuses the same
 // flow metadata, persistence, GPT client, and visualizer. WeakMap ensures cleanup when contexts die.
 const contextSharedState = new WeakMap();
@@ -137,7 +160,7 @@ async function extendPage(page, options) {
             gptClient: resolvedGptClient,
             controlPanelFactory: options?.controlPanelFactory,
             runtimeDirectives: {
-                clearPageAiCache: MiscUtils_1.MiscUtils.yn(envVars_1.env.data.DONOBU_PAGE_AI_CLEAR_CACHE),
+                clearPageAiCache: shouldClearPageAiCache(options?.specFilePath),
             },
             tbdSessions: [],
             aiInvocations: [],

package/dist/esm/lib/test/healRerunGate.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @fileoverview Runtime gate for auto-heal reruns.
+ *
+ * The auto-heal rerun is launched with the same project-level arguments as the
+ * initial run so Playwright's scheduling (declared project `dependencies`,
+ * workers, ordering) behaves with full fidelity. Within the targeted projects,
+ * however, only the tests the heal actually needs should execute. This module
+ * enforces that from an auto fixture that runs before any browser fixture:
+ * when `DONOBU_AUTO_HEAL_PLAN_PATH` is set, every test not in the rerun plan
+ * skips immediately — before a context or page is created — annotated with
+ * `donobu-heal-skip-replay` so the merge step drops the entry and leaves the
+ * initial run's result untouched.
+ *
+ * What runs during a heal rerun (the "declared signals only" policy):
+ *   - Heal targets (the failed tests with actionable treatment plans).
+ *   - For a target inside a `test.describe.serial` scope (or a file marked
+ *     serial via `test.describe.configure({ mode: 'serial' })`): the other
+ *     serial-scoped tests in that file. Serial mode is Playwright's declared
+ *     intra-file ordering contract — Playwright itself re-runs whole serial
+ *     groups on retry, and we mirror that. The orchestrator expands the plan
+ *     with these companions before the rerun (see
+ *     `expandTargetsWithSerialCompanions`) using the `serialScoped` flags the
+ *     Donobu reporter recorded during the initial run — the runner process
+ *     sees the suite tree; the worker (where this gate runs) does not.
+ *   - Declared dependency projects, which Playwright always runs in full.
+ *
+ * Implicit ordering (checkpoint files between plain tests, cross-file state
+ * with `workers: 1`) is deliberately NOT honored: tests relying on it will
+ * skip themselves during the rerun and surface as honest failures with
+ * guidance to declare the dependency.
+ *
+ * The gate runs at test runtime rather than collection time so Playwright's
+ * test-location attribution stays untouched (a collection-time wrapper would
+ * become every test's reported call site, breaking the merge's file-based
+ * matching) and so the plan can be matched against `testInfo.file`/`title`
+ * exactly instead of via stack inspection.
+ */
+import type { TestInfo } from '@playwright/test';
+/** Shape of the plan file the auto-heal orchestrator writes before the rerun. */
+export interface HealRerunPlan {
+    targets: Array<{
+        /** Spec file path; absolute, or relative to the rerun's CWD. */
+        file: string;
+        title: string;
+        projectName?: string;
+    }>;
+}
+/** Targets indexed by absolute spec path for O(1) per-test decisions. */
+export type HealRerunPlanIndex = Map<string, Set<string>>;
+export declare function buildPlanIndex(plan: HealRerunPlan): HealRerunPlanIndex;
+/**
+ * Pure decision: should the test in `file` with `title` actually execute
+ * during the heal rerun? The plan is fully explicit — serial companions were
+ * already expanded into it by the orchestrator.
+ */
+export declare function shouldRunDuringHealRerun(params: {
+    index: HealRerunPlanIndex;
+    file: string;
+    title: string;
+}): boolean;
+/**
+ * Expand heal targets with their `describe.serial` siblings, using the
+ * `serialScoped` flags the Donobu reporter recorded in the initial run's
+ * report. Companions live in the same file as their target by construction
+ * (serial scopes are intra-file), so they inherit the target's absolute file
+ * path; report file paths are rootDir-relative, hence the suffix match.
+ *
+ * Degrades to the unexpanded targets when the report (or the flags) are
+ * unavailable — serial chains then surface as honest not-reattempted
+ * failures instead of healing.
+ */
+export declare function expandTargetsWithSerialCompanions(targets: HealRerunPlan['targets'], initialReport: {
+    suites?: unknown;
+} | null): HealRerunPlan['targets'];
+/** Test-only: reset the memoized plan so each test can load its own. */
+export declare function resetHealRerunPlanCacheForTesting(): void;
+/**
+ * Called from the Donobu auto fixture before any browser fixture initializes.
+ * Outside heal reruns this is a no-op. During a rerun, tests outside the plan
+ * are annotated and skipped on the spot — no context, no page, no cost.
+ */
+export declare function maybeSkipForHealRerun(testInfo: TestInfo, options?: {
+    planPath?: string;
+}): void;
+//# sourceMappingURL=healRerunGate.d.ts.map