playwright-mutation-gate 0.2.2 → 0.3.0

package/README.md

@@ -109,6 +109,36 @@ npx playwright-mutation-gate tests/dashboard.spec.ts --test-id authedTest
 A runtime `authedTest.skip(condition)` inside a test is respected: if the test
 skips, the mutation reports `cannot-mutate` rather than a false `survived`.
 
+## Acknowledged skips
+
+A skipped test reports `cannot-mutate` and fails the gate: its assertion never
+runs, so there is nothing to verify. That is the right default, but it leaves no
+room for a skip the team has *consciously* accepted for a while. The two escapes
+are both bad: keep the gate red until someone fixes the test (so people stop
+running it), or work around the skip so it quietly lives for months with no
+owner and no deadline.
+
+A `// @gate-skip` marker turns that skip into a loan with a due date. Put it on
+its own line right above the test, or trailing the declaration:
+
+```ts
+// @gate-skip owner=vlad expires=2026-08-15 reason="checkout redesign in flight"
+test.skip('checkout shows confirmation', async ({ page }) => {
+  // @primary-assert
+  await expect(page.getByText('Order confirmed')).toBeVisible();
+});
+```
+
+- Before `expires`, the verdict stays `cannot-mutate` but is reported as
+  **acknowledged** (owner, expiry and reason in the table and `--json`), and the
+  run can exit 0.
+- After `expires`, the gate **fails closed** again. Extending the deadline means
+  editing the marker, a deliberate commit, not silent drift.
+- `owner` and a real `expires=YYYY-MM-DD` are required. A marker missing either,
+  with an unparseable date, or not sitting on a test is **malformed** and fails
+  the gate, same as a malformed `@primary-assert`.
+- Unmarked skips keep the default: `cannot-mutate`, gate fails.
+
 ## CI recipe
 
 ```yaml
@@ -152,6 +182,49 @@ do not want the full sweep on every push. Two patterns that work well:
   catching it a day later is fine. `--playwright-args` is available if you
   need to shard or point at a specific config.
 
+## Behavior mutation mode (`--behavior`)
+
+Assertion inversion answers "can this test fail". It cannot answer "does this
+test fail when the thing it names breaks". An assertion on a value that renders
+on every page is killed by inversion and clears the gate, even if the feature it
+claims to check is broken.
+
+`--behavior` adds a second, opt-in pass that closes part of that gap. Instead of
+inverting the assertion, it keeps it intact and corrupts the *value the
+assertion names* in the response, using Playwright's own `page.route()` to
+rewrite the body and headers in transit. Then it re-runs and expects red.
+
+```bash
+npx playwright-mutation-gate "tests/**/*.spec.ts" --behavior
+```
+
+- **killed** -- the test failed once its named value was broken. (A red here can
+  also be flow breakage rather than the assertion itself; the report says so.)
+- **weak** -- the test stayed green while the value it names was broken. The
+  assertion does not actually depend on the behavior it claims to check. This
+  fails the gate.
+- **cannot-locate** -- the named value never appeared in a rewritable response,
+  so nothing was corrupted. Reported honestly and, unlike `cannot-mutate`, this
+  does **not** fail the gate: a value that is not in an interceptable response
+  (a visibility check, a client-computed string, an API-request-fixture call) is
+  expected, not a defect.
+
+The two modes compose and neither replaces the other. Inversion is cheap and
+catches assertions that cannot fail at all (dead selectors, missing `await`,
+silent skips). Behavior mutation is expensive and catches weak assertions.
+Running `--behavior` performs both passes, so **the run cost roughly doubles**;
+keep it for a nightly sweep or the specs a PR touches rather than every push.
+
+**v1 scope: exact string values.** Behavior mutation locates a plain string
+literal argument (`toContain`, `toContainText`, `toHaveText`, `toHaveValue`,
+`toBe('...')`) and corrupts every occurrence in HTML/JSON bodies and header
+values. Numbers, status codes, regex/URL matchers, `toHaveCount`,
+`toBeVisible`, negated matchers, interpolated values and request-only fixtures
+all report `cannot-locate`. Values that are template-rendered or reconstructed
+on the client (common on SPAs) also report `cannot-locate`, since the literal
+never reaches an interceptable response. As with inversion, the gate reports
+what it could not do rather than guessing.
+
 ## CLI reference
 
 ```
@@ -160,6 +233,8 @@ npx playwright-mutation-gate [options] <specs...>
 Options:
   --json                    machine-readable JSON report
   --no-require-sentinel     do not fail on tests without a marker
+  --behavior                also corrupt each asserted value in the response
+                            and expect red (weak assertions fail the gate)
   --playwright-args <args>  extra arguments for playwright test
   --test-id <name>          treat <name> as a test builder (repeatable)
   -V, --version             output the version number
@@ -192,9 +267,12 @@ if (!summary.gatePassed) {
 `killed` / `survived` / `cannot-mutate` / `error`, plus unmarked/stray/malformed
 markers). `summarize(specs, opts)` folds one or more results into a `Summary`
 with the `gatePassed` verdict. `jsonReport` and `renderTable` produce the CLI's
-two output formats. Advanced: `planSpecMutations` and `invertAssertLine` expose
-the mutation planner and the single-line inverter directly. Full types ship with
-the package.
+two output formats. Pass `{ behavior: true }` to also run the behavior pass;
+the result then carries a `behavior` array of `BehaviorResult`s (`killed` /
+`weak` / `cannot-locate` / `error`). Advanced: `planSpecMutations`,
+`planBehaviorMutations`, `invertAssertLine` and `extractAssertValue` expose the
+planners, the single-line inverter and the value extractor directly. Full types
+ship with the package.
 
 ## Limitations
 
@@ -206,6 +284,9 @@ guarantees is narrower and mechanical: every marked assertion actually runs and
 is load-bearing, so the test cannot stay green regardless of what the app does.
 Judging whether the assertion is the *right* one still takes review, or
 application-code mutation testing (Stryker-style), which is a different tool.
+[Behavior mutation mode](#behavior-mutation-mode---behavior) (`--behavior`)
+closes part of this gap for string-valued assertions by corrupting the named
+value in the response and expecting red.
 
 **A kill is slightly generous by construction.** `killed` means the mutated
 run failed, not that the flipped assertion is what failed. Playwright actions
@@ -240,7 +321,9 @@ test was skipped at runtime (conditional test.skip), so the inverted
 assertion never ran"). In
 practice this is a feature: a `test.skip(true, ...)` from months ago looks
 identical to a healthy passing spec in normal CI output, and the gate is
-often what surfaces it.
+often what surfaces it. When a skip is a conscious, temporary decision, an
+[`// @gate-skip`](#acknowledged-skips) marker records its owner and expiry so
+the gate accepts it until the deadline instead of staying red.
 
 ## Why
 

package/dist/behavior.d.ts

@@ -0,0 +1,34 @@
+import { type PlanOptions } from './mutate.js';
+/**
+ * A behavior mutation for one marked test: either an injected copy that
+ * corrupts the asserted value in transit, or a cannot-locate reason. Unlike
+ * inversion (which rewrites the assertion), behavior mutation keeps the
+ * assertion intact and injects a `page.route()` preamble that rewrites the
+ * value the assertion names in the response, then expects the test to go red.
+ */
+export type BehaviorMutation = {
+    testTitle: string;
+    testLine: number;
+    markerLine: number;
+    /** 1-based line of the assertion whose value is corrupted. */
+    assertLine: number;
+    /** The string value corrupted in the response. */
+    value: string;
+    /** Full spec source with the route-interception preamble injected. */
+    mutatedSource: string;
+} | {
+    testTitle: string;
+    testLine: number;
+    markerLine: number;
+    assertLine: number | null;
+    cannotLocate: string;
+};
+/**
+ * Plan behavior mutations for a spec: for each marked test, extract the value
+ * its `@primary-assert` names, confirm the test can be routed (a `page`
+ * fixture is destructured), and inject a response-corrupting preamble. Every
+ * test the gate cannot mutate this way is reported with a reason, never
+ * skipped silently. Marker-level findings (unmarked, stray, malformed) are the
+ * inversion pass's job and are not repeated here.
+ */
+export declare function planBehaviorMutations(source: string, opts?: PlanOptions): BehaviorMutation[];

package/dist/behavior.js

@@ -0,0 +1,167 @@
+import { extractAssertValue } from './extract.js';
+import { CODE } from './lex.js';
+import { analyzeSpec, UNGATEABLE_MODES } from './mutate.js';
+/**
+ * The token the injected handler substitutes for the asserted value. Distinct
+ * enough that it will not collide with real content and will fail any equality
+ * or substring assertion on the original value.
+ */
+const REPLACE = 'PMG_MUTATED_VALUE';
+/**
+ * Plan behavior mutations for a spec: for each marked test, extract the value
+ * its `@primary-assert` names, confirm the test can be routed (a `page`
+ * fixture is destructured), and inject a response-corrupting preamble. Every
+ * test the gate cannot mutate this way is reported with a reason, never
+ * skipped silently. Marker-level findings (unmarked, stray, malformed) are the
+ * inversion pass's job and are not repeated here.
+ */
+export function planBehaviorMutations(source, opts = {}) {
+    const analysis = analyzeSpec(source, opts);
+    const { lines, kind } = analysis;
+    const mutations = [];
+    for (const t of analysis.markedTests) {
+        const base = { testTitle: t.title, testLine: t.testLine, markerLine: t.markerLine };
+        if (UNGATEABLE_MODES.has(t.mode)) {
+            const why = t.mode === 'fail'
+                ? 'test.fail() expects failure, so a behavior verdict would be meaningless'
+                : `test.${t.mode}() never runs, so behavior cannot be observed`;
+            mutations.push({ ...base, assertLine: t.assertLine, cannotLocate: why });
+            continue;
+        }
+        if (t.markerCount > 1) {
+            mutations.push({
+                ...base,
+                assertLine: t.assertLine,
+                cannotLocate: `found ${t.markerCount} @primary-assert markers in one test, expected exactly one`,
+            });
+            continue;
+        }
+        if (t.assertLine === null) {
+            mutations.push({ ...base, assertLine: null, cannotLocate: t.resolveError ?? 'assertion line not found' });
+            continue;
+        }
+        const extracted = extractAssertValue(lines[t.assertLine - 1]);
+        if ('cannotLocate' in extracted) {
+            mutations.push({ ...base, assertLine: t.assertLine, cannotLocate: extracted.cannotLocate });
+            continue;
+        }
+        const callback = findCallback(source, kind, t.open, t.close);
+        if ('error' in callback) {
+            mutations.push({ ...base, assertLine: t.assertLine, cannotLocate: callback.error });
+            continue;
+        }
+        if (!callback.fixtures.includes('page')) {
+            mutations.push({
+                ...base,
+                assertLine: t.assertLine,
+                cannotLocate: 'no page fixture destructured; route interception is unsupported for this test in v1',
+            });
+            continue;
+        }
+        const preamble = buildPreamble(extracted.value);
+        const mutatedSource = source.slice(0, callback.bodyOpen + 1) + '\n' + preamble + source.slice(callback.bodyOpen + 1);
+        mutations.push({ ...base, assertLine: t.assertLine, value: extracted.value, mutatedSource });
+    }
+    return mutations;
+}
+/**
+ * Locate the test callback inside a test() call: its destructured fixtures and
+ * the `{` that opens its body. Supports the arrow-function form Playwright
+ * tests use (`async ({ page }) => { ... }`); other forms are reported so the
+ * caller can fall back to cannot-locate rather than inject blindly.
+ */
+function findCallback(src, kind, open, close) {
+    // The callback's `=>` is the first arrow in code context within the call.
+    let arrow = -1;
+    for (let i = open; i < close; i++) {
+        if (kind[i] === CODE && src[i] === '=' && src[i + 1] === '>') {
+            arrow = i;
+            break;
+        }
+    }
+    if (arrow === -1)
+        return { error: 'could not locate the test callback (arrow function expected)' };
+    // The `)` closing the params sits just before the arrow.
+    let j = arrow - 1;
+    while (j > open && /\s/.test(src[j]))
+        j--;
+    if (src[j] !== ')')
+        return { error: 'unexpected test callback parameter form' };
+    let depth = 0;
+    let paramOpen = -1;
+    for (let k = j; k > open; k--) {
+        if (kind[k] !== CODE)
+            continue;
+        if (src[k] === ')')
+            depth++;
+        else if (src[k] === '(' && --depth === 0) {
+            paramOpen = k;
+            break;
+        }
+    }
+    if (paramOpen === -1)
+        return { error: 'could not parse test callback parameters' };
+    const fixtures = parseDestructuredFixtures(src.slice(paramOpen + 1, j));
+    // The body opens at the first `{` in code context after the arrow.
+    let bodyOpen = -1;
+    for (let i = arrow + 2; i < close; i++) {
+        if (kind[i] === CODE && src[i] === '{') {
+            bodyOpen = i;
+            break;
+        }
+    }
+    if (bodyOpen === -1)
+        return { error: 'test callback has no block body' };
+    return { fixtures, bodyOpen };
+}
+/** Read fixture names from a destructured params string like `{ page, request }`. */
+function parseDestructuredFixtures(params) {
+    const trimmed = params.trim();
+    if (!trimmed.startsWith('{'))
+        return []; // `(arg)` form: fixtures not detectable
+    const end = trimmed.lastIndexOf('}');
+    if (end <= 0)
+        return [];
+    return trimmed
+        .slice(1, end)
+        .split(',')
+        .map((part) => part.split(':')[0].trim()) // `page: p` -> the source fixture name `page`
+        .filter(Boolean);
+}
+/**
+ * Build the route-interception preamble injected at the top of the test body.
+ * It fetches each response, replaces every occurrence of the asserted value in
+ * the headers and body with a sentinel, and records via PMG_HIT_FILE whether
+ * any occurrence was found. `await import('node:fs')` keeps the preamble
+ * self-contained, with no top-level import that could clash with the spec.
+ */
+function buildPreamble(value) {
+    const needle = JSON.stringify(value);
+    const replace = JSON.stringify(REPLACE);
+    return [
+        `  await page.route('**/*', async (route) => {`,
+        `    const resp = await route.fetch();`,
+        `    const headers = resp.headers();`,
+        `    const NEEDLE = ${needle};`,
+        `    const REPLACE = ${replace};`,
+        `    let hit = false;`,
+        `    for (const k of Object.keys(headers)) {`,
+        `      if (typeof headers[k] === 'string' && headers[k].includes(NEEDLE)) {`,
+        `        headers[k] = headers[k].split(NEEDLE).join(REPLACE);`,
+        `        hit = true;`,
+        `      }`,
+        `    }`,
+        `    let body = null;`,
+        `    try { body = await resp.text(); } catch {}`,
+        `    if (body !== null && body.includes(NEEDLE)) {`,
+        `      body = body.split(NEEDLE).join(REPLACE);`,
+        `      hit = true;`,
+        `    }`,
+        `    if (hit && process.env.PMG_HIT_FILE) {`,
+        `      const fs = await import('node:fs');`,
+        `      fs.appendFileSync(process.env.PMG_HIT_FILE, '1');`,
+        `    }`,
+        `    await route.fulfill({ response: resp, headers, ...(body !== null ? { body } : {}) });`,
+        `  });`,
+    ].join('\n');
+}

package/dist/cli.js

@@ -14,6 +14,9 @@ const program = new Command()
     .argument('<specs...>', 'Playwright spec files to gate')
     .option('--json', 'print a machine-readable JSON report instead of the table', false)
     .option('--no-require-sentinel', 'do not fail the gate when a test() has no @primary-assert marker')
+    .option('--behavior', 'also run behavior mutation: corrupt each @primary-assert value in the response\n' +
+    'via page.route and expect red. A test that stays green is weak and fails the\n' +
+    'gate. Opt-in: this roughly doubles the run cost.', false)
     .option('--playwright-args <args>', 'extra arguments passed to `npx playwright test`, split on spaces\n' +
     '(values containing spaces are not supported)')
     .option('--test-id <name>', 'treat <name> as a test builder in addition to `test` (repeatable);\n' +
@@ -23,7 +26,12 @@ const program = new Command()
     .addHelpText('after', '\nMarking:\n' +
     '  Put `// @primary-assert` at the end of the primary assertion line,\n' +
     '  or on its own line right above it. One marker per test().\n' +
-    '    await expect(page.getByText(\'Saved\')).toBeVisible(); // @primary-assert')
+    '    await expect(page.getByText(\'Saved\')).toBeVisible(); // @primary-assert\n' +
+    '\nModes:\n' +
+    '  Default: assertion inversion (proves the test can fail at all).\n' +
+    '  --behavior: also corrupt the asserted value in the response and expect\n' +
+    '  red (proves the test fails when the thing it names breaks). The modes\n' +
+    '  compose; weak assertions fail the gate, cannot-locate is informational.')
     .action(async (specPaths, opts) => {
     const missing = specPaths.filter((p) => !existsSync(p));
     if (missing.length > 0) {
@@ -35,7 +43,7 @@ const program = new Command()
     for (const spec of specPaths) {
         process.stderr.write(`gating ${spec}\n`);
         try {
-            results.push(await runSpec(spec, { playwrightArgs, testIds: opts.testId }));
+            results.push(await runSpec(spec, { playwrightArgs, testIds: opts.testId, behavior: opts.behavior }));
         }
         catch (err) {
             console.error(`failed to gate ${spec}: ${err instanceof Error ? err.message : String(err)}`);

package/dist/extract.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The value a `@primary-assert` assertion names, extracted for behavior
+ * mutation. `string` is a plain string literal the gate can locate in a
+ * response body/header and corrupt in transit. Everything the gate cannot
+ * honestly turn into a response mutation is `cannotLocate` with a reason,
+ * never guessed.
+ */
+export type AssertValue = {
+    kind: 'string';
+    value: string;
+} | {
+    cannotLocate: string;
+};
+/**
+ * Extract the string value a single assertion line names, for behavior
+ * mutation. Purely string-based, reusing the same chain walk as invert.ts:
+ * `[await] expect[.soft|.poll](...) [.resolves|.rejects] .toXxx(<string>)`.
+ * A negated matcher (`.not`) has inverted semantics that behavior mutation
+ * does not model in v1, so it is reported as cannot-locate rather than guessed.
+ */
+export declare function extractAssertValue(line: string): AssertValue;

package/dist/extract.js

@@ -0,0 +1,103 @@
+import { CODE, findCloseMasked, lex } from './lex.js';
+// Matchers whose first argument, when a plain string literal, is the observed
+// value the assertion depends on. Corrupting that string in the response is a
+// meaningful behavior mutation. Others (toBeVisible, toHaveCount, toHaveURL
+// with a regex, numeric toBe) do not carry a locatable string value in v1.
+const STRING_MATCHERS = new Set(['toContain', 'toContainText', 'toHaveText', 'toHaveValue', 'toBe']);
+const isWord = (c) => c !== undefined && /[\w$]/.test(c);
+const ESCAPES = { n: '\n', t: '\t', r: '\r', b: '\b', f: '\f', v: '\v', '0': '\0' };
+/**
+ * Extract the string value a single assertion line names, for behavior
+ * mutation. Purely string-based, reusing the same chain walk as invert.ts:
+ * `[await] expect[.soft|.poll](...) [.resolves|.rejects] .toXxx(<string>)`.
+ * A negated matcher (`.not`) has inverted semantics that behavior mutation
+ * does not model in v1, so it is reported as cannot-locate rather than guessed.
+ */
+export function extractAssertValue(line) {
+    const kind = lex(line);
+    // First CODE index at or after j: skips whitespace, comments and other
+    // non-code chars, matching invert.ts's walk.
+    const skip = (j) => {
+        while (j < line.length && (kind[j] !== CODE || /\s/.test(line[j])))
+            j++;
+        return j;
+    };
+    const anchors = [...line.matchAll(/\bexpect\s*[.(]/g)].filter((m) => kind[m.index] === CODE);
+    if (anchors.length === 0)
+        return { cannotLocate: 'no expect() call on this line' };
+    if (anchors.length > 1)
+        return { cannotLocate: 'multiple expect calls on one line' };
+    let i = anchors[0].index + anchors[0][0].length - 1;
+    if (line[i] === '.') {
+        i = skip(i + 1);
+        const start = i;
+        while (isWord(line[i]))
+            i++;
+        const form = line.slice(start, i);
+        if (form !== 'soft' && form !== 'poll')
+            return { cannotLocate: `unsupported expect form "expect.${form}"` };
+        i = skip(i);
+        if (line[i] !== '(')
+            return { cannotLocate: `expect.${form} is not called on this line` };
+    }
+    const close = findCloseMasked(line, kind, i);
+    if (close === -1)
+        return { cannotLocate: 'expect(...) does not close on this line (multi-line expect)' };
+    i = skip(close + 1);
+    for (;;) {
+        if (i >= line.length || line[i] !== '.')
+            return { cannotLocate: 'no matcher call after expect(...) on this line' };
+        i = skip(i + 1);
+        const start = i;
+        while (isWord(line[i]))
+            i++;
+        const id = line.slice(start, i);
+        if (id === '')
+            return { cannotLocate: 'unexpected character in expect(...) chain' };
+        const lookahead = skip(i);
+        if (line[lookahead] === '(') {
+            if (!STRING_MATCHERS.has(id)) {
+                return { cannotLocate: `matcher .${id}() does not carry a locatable string value` };
+            }
+            return readFirstStringArg(line, lookahead);
+        }
+        if (id === 'not')
+            return { cannotLocate: 'negated matcher (.not); behavior mutation semantics undefined in v1' };
+        if (id === 'resolves' || id === 'rejects') {
+            i = skip(i);
+            continue;
+        }
+        return { cannotLocate: `unsupported chain segment ".${id}"` };
+    }
+}
+/** Read a plain string literal as the first argument at the matcher's `(`. */
+function readFirstStringArg(line, open) {
+    let i = open + 1;
+    while (i < line.length && /\s/.test(line[i]))
+        i++;
+    const quote = line[i];
+    if (quote !== "'" && quote !== '"' && quote !== '`') {
+        return { cannotLocate: 'asserted value is not a plain string literal (number, variable, or expression)' };
+    }
+    let value = '';
+    for (i++; i < line.length; i++) {
+        const c = line[i];
+        if (c === '\\' && i + 1 < line.length) {
+            const next = line[i + 1];
+            value += ESCAPES[next] ?? next;
+            i++;
+        }
+        else if (quote === '`' && c === '$' && line[i + 1] === '{') {
+            return { cannotLocate: 'asserted value is an interpolated template literal' };
+        }
+        else if (c === quote) {
+            if (value === '')
+                return { cannotLocate: 'asserted value is an empty string' };
+            return { kind: 'string', value };
+        }
+        else {
+            value += c;
+        }
+    }
+    return { cannotLocate: 'unterminated string literal in assertion' };
+}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
-export { runSpec, sweepStaleMutationFiles, DEFAULT_TIMEOUT_MS, type SpecResult, type MutationResult, type Verdict, type RunOptions, } from './run.js';
+export { runSpec, sweepStaleMutationFiles, DEFAULT_TIMEOUT_MS, type SpecResult, type MutationResult, type Verdict, type RunOptions, type BehaviorResult, type BehaviorVerdict, } from './run.js';
 export { summarize, jsonReport, renderTable, type Summary, type GateOptions, type RenderOptions, } from './report.js';
-export { planSpecMutations, MARKER, type SpecPlan, type Mutation, type PlanOptions, } from './mutate.js';
+export { planSpecMutations, analyzeSpec, parseGateSkip, MARKER, type SpecPlan, type SpecAnalysis, type MarkedTest, type Mutation, type PlanOptions, type GateSkip, } from './mutate.js';
 export { invertAssertLine, type InvertResult } from './invert.js';
+export { planBehaviorMutations, type BehaviorMutation } from './behavior.js';
+export { extractAssertValue, type AssertValue } from './extract.js';

package/dist/index.js

@@ -11,5 +11,7 @@
 export { runSpec, sweepStaleMutationFiles, DEFAULT_TIMEOUT_MS, } from './run.js';
 export { summarize, jsonReport, renderTable, } from './report.js';
 // Advanced: build or inspect the mutation plan directly.
-export { planSpecMutations, MARKER, } from './mutate.js';
+export { planSpecMutations, analyzeSpec, parseGateSkip, MARKER, } from './mutate.js';
 export { invertAssertLine } from './invert.js';
+export { planBehaviorMutations } from './behavior.js';
+export { extractAssertValue } from './extract.js';

package/dist/mutate.d.ts

@@ -16,6 +16,8 @@ export type Mutation = {
     /** 1-based line of the assertion candidate; null when none was located. */
     assertLine: number | null;
     cannotMutate: string;
+    /** A valid @gate-skip acknowledgement decorating this test, if any. */
+    gateSkip?: GateSkip;
 };
 export interface PlanOptions {
     /**
@@ -43,7 +45,105 @@ export interface SpecPlan {
     onlyTestLines: number[];
     /** 1-based lines mentioning @primary-assert that do not form a valid marker. */
     malformedMarkerLines: number[];
+    /** 1-based lines mentioning @gate-skip that do not form a valid, placed marker. */
+    malformedGateSkipLines: number[];
 }
+/**
+ * One test() block that carries at least one valid `@primary-assert` marker,
+ * with its assertion line already resolved. Shared between inversion planning
+ * (planSpecMutations) and behavior planning (planBehaviorMutations) so the
+ * marker/block parser lives in one place.
+ */
+/**
+ * A parsed, valid `// @gate-skip owner=.. expires=YYYY-MM-DD reason=".."`
+ * acknowledgement decorating a test. It turns a skip's cannot-mutate verdict
+ * from a gate failure into an accepted, time-boxed one - until `expires`.
+ */
+export interface GateSkip {
+    owner: string;
+    /** ISO date (YYYY-MM-DD) after which the acknowledgement expires. */
+    expires: string;
+    reason?: string;
+}
+export interface MarkedTest {
+    title: string;
+    /** 1-based line of the test() declaration. */
+    testLine: number;
+    mode: TestBlock['mode'];
+    /** How many valid markers sit inside this block (>1 is a mistake). */
+    markerCount: number;
+    /** 1-based line of the first marker. */
+    markerLine: number;
+    /** Char offsets of the test call's `(` and its matching `)`. */
+    open: number;
+    close: number;
+    /** 1-based line of the assertion the first marker points at; null when unresolved. */
+    assertLine: number | null;
+    /** Set when assertLine is null: why the assertion line could not be located. */
+    resolveError: string | null;
+    /** A valid @gate-skip acknowledgement decorating this test, if any. */
+    gateSkip?: GateSkip;
+}
+/**
+ * The parsed view of a spec that both planners build on: the lexed source, the
+ * test() blocks that carry a marker (assertion line resolved), and the
+ * spec-level marker findings (unmarked tests, stray/malformed markers, .only).
+ */
+export interface SpecAnalysis {
+    source: string;
+    lines: string[];
+    kind: Uint8Array;
+    markedTests: MarkedTest[];
+    unmarkedTests: {
+        title: string;
+        line: number;
+    }[];
+    strayMarkerLines: number[];
+    onlyTestLines: number[];
+    malformedMarkerLines: number[];
+    /** 1-based lines mentioning @gate-skip that do not form a valid, placed marker. */
+    malformedGateSkipLines: number[];
+}
+/**
+ * A valid `// @primary-assert` marker. `sameLine` is true when the marker
+ * trails the assertion on its own line (`expect(x).toY(); // @primary-assert`),
+ * false when it sits on its own line above the assertion.
+ */
+interface Marker {
+    line: number;
+    sameLine: boolean;
+}
+interface TestBlock {
+    title: string;
+    mode: '' | 'only' | 'skip' | 'fixme' | 'fail';
+    /** Char offset of the `test` token. */
+    anchor: number;
+    /** Char offsets of the call's `(` and its matching `)` (source end when unclosed). */
+    open: number;
+    close: number;
+    /** Valid markers inside this block. */
+    markers: Marker[];
+    /** A valid @gate-skip acknowledgement decorating this test, if any. */
+    gateSkip?: GateSkip;
+}
+/** True when `s` is a real calendar date in strict YYYY-MM-DD form. */
+export declare function isValidYmd(s: string): boolean;
+/**
+ * Parse a `@gate-skip owner=.. expires=YYYY-MM-DD reason=".."` line comment.
+ * Returns the acknowledgement, or null when it is malformed (missing owner or
+ * expires, or an unparseable date) - the same fail-closed policy as a malformed
+ * @primary-assert marker.
+ */
+export declare function parseGateSkip(commentText: string): GateSkip | null;
+export declare const UNGATEABLE_MODES: Set<string>;
+/**
+ * Parse a spec source into the shared view both planners build on: which
+ * test() blocks carry a valid `@primary-assert` marker (with the assertion
+ * line already resolved), plus the spec-level marker findings. The parser
+ * (lexer, test-id collection, block finding, marker association, assertion-line
+ * resolution) lives here so inversion and behavior planning cannot diverge.
+ */
+export declare function analyzeSpec(source: string, opts?: PlanOptions): SpecAnalysis;
 /**
  * Parse a spec source and plan its mutations: one inverted copy per marked
  * test. Anything the gate cannot honestly mutate is reported with a reason,
@@ -64,3 +164,4 @@ export declare function mutationFilePath(specPath: string, index: number, tag?:
  * collide. The caller owns cleanup.
  */
 export declare function writeMutationFile(specPath: string, index: number, mutatedSource: string): string;
+export {};