@wix/pathgrade 0.37.0 → 1.0.0

package/README.md

@@ -1,10 +1,10 @@
 # Pathgrade
 
-**Evaluate AI coding agents with Vitest.** Write evals as normal `.eval.ts` files, run Claude Code, Codex, or Cursor in isolated sandboxes, and score the result with deterministic checks, rubric judges, and tool-usage assertions.
+**Evaluate AI coding agents with Vitest or Jest.** Write evals as normal `.eval.ts` files, run Claude Code, Codex, or Cursor in isolated sandboxes, and score the result with deterministic checks, rubric judges, and tool-usage assertions.
 
 ## Why Pathgrade?
 
-- Write evals in plain TypeScript with Vitest
+- Write evals in plain TypeScript with Vitest or Jest
 - Run each trial in an isolated workspace and HOME directory
 - Seed trials from fixtures, real skills, or mocked MCP servers
 - Score both final artifacts and the workflow that produced them
@@ -13,12 +13,18 @@
 
 ## Quick Start
 
-**Prerequisites**: Node.js 20.11+, Vitest 4+, and at least one of [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex CLI](https://github.com/openai/codex), or the `cursor-agent` CLI
+**Prerequisites**: Node.js 20.11+, Vitest 4+ or Jest 30+, and at least one configured agent runtime. Claude uses the bundled `@anthropic-ai/claude-agent-sdk` binary by default; Codex requires the `codex` CLI; Cursor requires the `cursor-agent` CLI.
 
 ```bash
 yarn add -D @wix/pathgrade
 ```
 
+For Jest projects, install Jest too:
+
+```bash
+yarn add -D @wix/pathgrade jest
+```
+
 ### Authentication
 
 By default, Pathgrade tries to reuse the agent CLI's native auth before falling back to explicit environment variables.
@@ -27,9 +33,9 @@ By default, Pathgrade tries to reuse the agent CLI's native auth before falling
   - macOS: reuses Claude Code OAuth from Keychain
   - other platforms: forwards `ANTHROPIC_API_KEY` when present
 - **Codex**
-  - reuses cached `~/.codex/auth.json` when available
-  - or forwards `OPENAI_API_KEY`
-  - or runs `codex login --with-api-key` inside the sandbox when an API key is present but no cached login exists
+  - forwards `OPENAI_API_KEY` when present
+  - or runs `codex login --with-api-key` inside the sandbox when an API key is present
+  - `codex exec` can reuse cached `~/.codex/auth.json` when no key is available; `app-server` may reject cached ChatGPT-token refreshes, so prefer `OPENAI_API_KEY` for the default transport
 - **Cursor**
   - forwards `CURSOR_API_KEY` when set
   - macOS: reuses `cursor-agent login` OAuth tokens from the login Keychain
@@ -52,7 +58,7 @@ const agent = await createAgent({
 
 Codex supports two transports and Pathgrade defaults to `app-server`:
 
-- `app-server` (default) — uses `codex app-server` and keeps native thread state. Required for `AskUserReaction` handshakes (`request_user_input` reaches the model). Requires `OPENAI_API_KEY`; cached `~/.codex/auth.json` is not supported under this transport.
+- `app-server` (default) — uses `codex app-server` and keeps native thread state. Required for `AskUserReaction` handshakes (`request_user_input` reaches the model). Prefer `OPENAI_API_KEY`; cached ChatGPT auth can fail if the app-server asks Pathgrade to refresh tokens.
 - `exec` — uses `codex exec` and re-injects the transcript every turn. Kept for stateless CI matrices that don't need the handshake.
 
 Precedence: `createAgent({ transport })` > `PATHGRADE_CODEX_TRANSPORT` env > default (`app-server`). An invalid env value throws at `createAgent` time.
@@ -68,17 +74,17 @@ If `transport: 'exec'` is resolved and any `AskUserReaction` is present in `Conv
 
 Migrating from `exec` to `app-server`:
 
-- Export `OPENAI_API_KEY`, or set `transport: 'exec'` / `PATHGRADE_CODEX_TRANSPORT=exec` to stay on the old transport.
+- Export `OPENAI_API_KEY`, or set `transport: 'exec'` / `PATHGRADE_CODEX_TRANSPORT=exec` to stay on the old transport and its cached-auth behavior.
 - The `noninteractive-user-question` runtime policy no longer attaches under `app-server`. Snapshots that captured model output influenced by that policy text may need re-recording.
 - `MAX_TURN_RETRIES` does not apply under `app-server` — a crashed turn ends the conversation with `completionReason: 'agent_crashed'`.
 
 ### Plugin Setup
 
-Create a `vitest.config.ts` with the Pathgrade plugin:
+Create a `vitest.config.ts` with the built-in Vitest adapter plugin:
 
 ```typescript
 import { defineConfig } from 'vitest/config';
-import { pathgrade } from '@wix/pathgrade/plugin';
+import { pathgrade } from '@wix/pathgrade/adapters/vitest';
 
 export default defineConfig({
     plugins: [pathgrade({ timeout: 120 })],
@@ -87,6 +93,24 @@ export default defineConfig({
 
 The plugin registers the setup hooks Pathgrade needs, wires in the reporter, and automatically cleans up agent workspaces after each test.
 
+For Pathgrade CLI behavior, use `pathgrade.config.ts`:
+
+```typescript
+export default {
+    runner: {
+        adapter: 'vitest', // default; use 'jest' for Jest projects
+        args: [],
+    },
+    evals: {
+        include: ['**/*.eval.ts'],
+        exclude: ['**/fixtures/**'],
+    },
+    affected: {
+        global: ['package.json', 'yarn.lock'],
+    },
+};
+```
+
 ### First Eval
 
 Write an eval file such as `hello.eval.ts`:
@@ -122,7 +146,7 @@ Run your evals:
 npx pathgrade run
 ```
 
-`pathgrade run` is the recommended wrapper: it loads `.env`, warns when no auth is configured, and adds Pathgrade-specific flags such as `--changed`, `--diagnostics`, and `--verbose`. Plain `npx vitest run` works too if you do not need those extras.
+`pathgrade run` is the recommended wrapper: it loads `.env`, warns when no auth is configured, and adds Pathgrade-specific flags such as `--changed`, `--diagnostics`, and `--verbose`. Plain `npx vitest run` or direct Jest runs work too if you configure the Pathgrade adapter hooks yourself.
 
 ## Core Concepts
 
@@ -193,7 +217,7 @@ judge('spec-structure', {
 });
 ```
 
-Tool-using judges currently require the Anthropic HTTP provider (`ANTHROPIC_API_KEY`); other providers produce a clean `provider_not_supported` error. See the [User Guide](packages/pathgrade/docs/USER_GUIDE.md#tool-using-judges--judge-tools-) for the full tool list, failure codes, and the migration recipe from `input`-helper probes.
+Tool-using judges currently require the Anthropic HTTP provider (`ANTHROPIC_API_KEY`); other providers produce a clean `provider_not_supported` error. See the [User Guide](docs/USER_GUIDE.md#tool-using-judges) for the full tool list, failure codes, and the migration recipe from `input`-helper probes.
 
 ### `toolUsage()` - Tool event matching
 
@@ -207,7 +231,7 @@ toolUsage('expected-workflow', [
 
 ## Conversations
 
-Pathgrade currently supports three agent backends: `claude`, `codex`, and `cursor`. Set the backend per test via `createAgent({ agent: 'claude' })` or globally via `PATHGRADE_AGENT`.
+Pathgrade currently supports three agent backends: `claude`, `codex`, and `cursor`. Set the backend per test via `createAgent({ agent: 'claude' })`, or omit `agent` and use `PATHGRADE_AGENT` as the process-wide fallback.
 
 ### `agent.prompt()` - One shot
 
@@ -274,11 +298,11 @@ Pathgrade exposes a few useful features that are easy to miss from the basic exa
 - `conversationWindow` on agents and personas keeps long transcripts bounded with summarization instead of sending the full conversation every turn.
 - `copyIgnore` and `DEFAULT_COPY_IGNORE` let you control what gets copied into the sandbox when seeding from large fixtures or skill directories.
 
-See [sdk-showcase](packages/pathgrade/examples/sdk-showcase/) for a single example suite that demonstrates these APIs together.
+See [sdk-showcase](examples/sdk-showcase/) for a single example suite that demonstrates these APIs together.
 
 ## MCP Mock Servers
 
-Simulate MCP tools when testing Claude-driven evals:
+Simulate MCP tools when testing Claude, Codex app-server, or Cursor evals:
 
 ```typescript
 import { mockMcpServer } from '@wix/pathgrade/mcp-mock';
@@ -299,7 +323,7 @@ const agent = await createAgent({ agent: 'claude', mcpMock: mock });
 ## CLI
 
 ```bash
-pathgrade run [--changed] [--diagnostics] [--verbose] [-- vitest-args]
+pathgrade run [--changed] [--since=<ref>] [--changed-files=<path>] [--adapter=<name|path>] [--diagnostics] [--verbose] [--quiet] [-- runner-args]
 pathgrade init [--force]
 pathgrade validate <file.eval.ts>
 pathgrade validate --affected
@@ -312,36 +336,74 @@ pathgrade report [--results-path=<path>] [--no-comment] [--comment-id=<id>]
 
 Useful details:
 
-- `pathgrade run --changed` computes affected evals first, writes selection metadata to `.pathgrade/selection.json`, and only then launches Vitest.
+- `pathgrade run --changed` computes affected evals first, writes selection metadata to `.pathgrade/selection.json`, and only then launches the selected runner adapter. Vitest is the default adapter; Jest is selected with `runner.adapter: 'jest'` or `--adapter=jest`.
 - `pathgrade preview browser` starts a local viewer on `http://localhost:3847`.
 - `pathgrade report` posts or updates a PR comment in GitHub Actions; locally it prints the markdown report and then the numeric pass rate.
 - `pathgrade validate --affected` is a strict mode for CI: every discovered eval must either live under a `SKILL.md` anchor or export valid `__pathgradeMeta`.
 
 Run `pathgrade --help` for the full help text.
 
-## Plugin Options
+## Configuration
+
+```typescript
+// pathgrade.config.ts
+export default {
+    runner: {
+        adapter: 'vitest',
+        args: [],
+    },
+    evals: {
+        include: ['**/*.eval.ts'],   // default
+        exclude: ['**/fixtures/**'], // replaces the default exclude list if set
+    },
+    affected: {
+        global: ['package.json', 'yarn.lock'],
+    },
+    ci: { threshold: 0.8 },
+};
+```
+
+Pathgrade reads `pathgrade.config.*` for CLI and affected-selection behavior. `runner.adapter` and `--adapter=<name|path>` select the runner; `--adapter` wins over config. Built-in adapters currently include `vitest`, `jest`, and the narrow `node-test` proof adapter.
+
+Third-party runner adapters are supported through `@wix/pathgrade/adapter-kit`. Adapter names resolve as follows:
+
+- `vitest`, `jest`, `node-test`: built-in adapters
+- `demo`: package `@wix/pathgrade-adapter-demo`, resolved from the project
+- `@scope/pathgrade-adapter-demo` or another specifier containing `/`: package specifier, resolved from the project
+- `./local-adapter.mjs` or `/abs/local-adapter.mjs`: local adapter module
+
+External adapter modules used by `pathgrade run` must export `createPathgradeInvocationAdapter({ config })`, returning a `RunnerInvocationAdapter`. Modules used by lower-level orchestration can also export `createPathgradeAdapter()`, returning a `RunnerAdapter` with `discover`, `invoke`, and `collectNormalizedRunSnapshot`.
+
+Vitest runner behavior still belongs in `vitest.config.ts`:
 
 ```typescript
-import { pathgrade } from '@wix/pathgrade/plugin';
+import { pathgrade } from '@wix/pathgrade/adapters/vitest';
 
 pathgrade({
-    include: ['**/*.eval.ts'],   // default: ['**/*.eval.ts']
     timeout: 300,                // seconds, default: 300
     reporter: 'cli',             // 'cli' | 'browser' | 'json'
     diagnostics: false,          // print full diagnostics for passing evals too
     verbose: false,              // stream live per-turn events to stderr while evals run
-    ci: { threshold: 0.8 },      // fail when the mean test score drops below threshold
-    affected: {
-        global: ['package.json', 'yarn.lock'],
-    },
 });
 ```
 
+Jest runner behavior still belongs in `jest.config.*`. Pathgrade injects only the setup and reporter it needs when you use `pathgrade run --adapter=jest`; transforms, test environment, module resolution, and ESM/TypeScript support remain your Jest config's job.
+
+For direct Jest runs, configure the same entry points explicitly:
+
+```js
+// jest.config.mjs
+export default {
+    setupFilesAfterEnv: ['@wix/pathgrade/adapters/jest/setup'],
+    reporters: ['default', '@wix/pathgrade/adapters/jest/reporter'],
+};
+```
+
 Notes:
 
-- `exclude` is also supported. If you set it, it replaces the default exclude list instead of merging with it.
+- Legacy `@wix/pathgrade/plugin` and `@wix/pathgrade/plugin/vitest` imports remain as compatibility fallbacks, but new config should use `@wix/pathgrade/adapters/vitest` and `pathgrade.config.*`.
 - `reporter: 'browser'` writes results JSON and opens the viewer automatically after the run.
-- `affected.global` is a repo-level "rerun everything" escape hatch for `pathgrade affected` and `pathgrade run --changed`.
+- SDK-only consumers can import `@wix/pathgrade` without installing Vitest or Jest. Adapter users need their selected runner available.
 
 ## Environment Variables
 
@@ -359,6 +421,28 @@ Notes:
 | `PATHGRADE_DIAGNOSTICS` | `1` prints full diagnostics for passing evals too |
 | `NO_COLOR` | Disable ANSI colors |
 
+### Experimental `node:test` Adapter
+
+`node-test` is a small proof adapter for validating the runner boundary without Vitest. It is intentionally narrow: eval files import the `test` wrapper from `@wix/pathgrade/adapters/node-test`, run through Node's built-in test runner, and still produce the normal `.pathgrade/results.json` and trace artifacts.
+
+```ts
+import { test } from '@wix/pathgrade/adapters/node-test';
+import { createAgent, evaluate, check } from '@wix/pathgrade';
+
+test('minimal node proof', async () => {
+    const agent = await createAgent({ workspace: process.cwd() });
+    await evaluate(agent, [check('passes', () => true)]);
+});
+```
+
+Run it with:
+
+```bash
+pathgrade run --adapter=node-test
+```
+
+This proof validates Pathgrade's adapter, lifecycle, result capture, and reporting boundaries. It does not imply Mocha, Playwright, or runnerless CLI support.
+
 `pathgrade run` loads `.env` from the working directory automatically.
 
 ## CI / GitHub Actions
@@ -401,17 +485,17 @@ jobs:
 
 - `fetch-depth: 0` is required for `--changed`; shallow clones break merge-base resolution.
 - Evals under a `SKILL.md` are tracked automatically; use `__pathgradeMeta` for cross-skill or non-standard dependencies.
-- Set `ci: { threshold: 0.8 }` in the plugin config to fail the run when the mean test score drops below your threshold.
+- Set `ci: { threshold: 0.8 }` in `pathgrade.config.ts` to fail the run when the mean test score drops below your threshold.
 
-See the [User Guide - CI Integration](packages/pathgrade/docs/USER_GUIDE.md#ci-integration) for the full reference.
+See the [User Guide - CI Integration](docs/USER_GUIDE.md#ci-integration) for the full reference.
 
 ## Links
 
-- [User Guide](packages/pathgrade/docs/USER_GUIDE.md) - full API reference and usage patterns
+- [User Guide](docs/USER_GUIDE.md) - full API reference and usage patterns
 - Examples:
-  - [start-chat](packages/pathgrade/examples/start-chat/) - multi-turn conversation
-  - [sdk-showcase](packages/pathgrade/examples/sdk-showcase/) - advanced SDK features in one suite
-  - [tool-judge-demo](packages/pathgrade/examples/tool-judge-demo/) - `judge({ tools })` reading workspace artifacts
+  - [start-chat](examples/start-chat/) - multi-turn conversation
+  - [sdk-showcase](examples/sdk-showcase/) - advanced SDK features in one suite
+  - [tool-judge-demo](examples/tool-judge-demo/) - `judge({ tools })` reading workspace artifacts
 
 ## Note on AI provider dependencies
 

package/dist/adapter-kit/index.d.ts

@@ -0,0 +1,17 @@
+export { runnerAdapterContractVersion, type AdapterCaseContext, type AdapterDiagnostic, type AdapterDiscoveryInput, type AdapterDiscoveryResult, type AdapterEvalUnit, type AdapterInvocationInput, type AdapterLifecycleHooks, type AdapterRunHandle, type AdapterRunStatus, type EvalResultEvent, type RunnerAdapter, } from '../runners/adapter.js';
+export type { RunnerInvocationAdapter, RunnerInvocationInput, } from '../runners/invocation.js';
+export type { AttemptOutcome, AttemptRecord, AssertionRecord, Diagnostic, EvalUnitRecord, EvaluationRecord, GroupingHint, NativeReference, NormalizedRunModel, NormalizedRunSnapshot, RunCaseRecord, RunCaseState, RunRecord, RunStatus, ScoringPolicy, SnapshotCompleteness, } from '../runners/model.js';
+export { buildNormalizedRunSnapshotFromReportGroups } from '../runners/model-builders.js';
+export { validateNormalizedRunSnapshot } from '../runners/model-validation.js';
+export { projectNormalizedRunSnapshotToReportInput } from '../runners/report-projection.js';
+export { runWithAdapter, type PathgradeRunOptions, type AdapterReporterMode } from '../runners/orchestrator.js';
+export { createRunnerLifecycleHooks } from '../runners/lifecycle-hooks.js';
+export { discoverPathgradeEvalFiles } from '../evals/discovery.js';
+export { DEFAULT_EVAL_EXCLUDE, DEFAULT_EVAL_INCLUDE, defaultPathgradeConfig, resolvePathgradeConfig, type PathgradeConfig, type ResolvedPathgradeConfig, } from '../config/pathgrade.js';
+export { readSidecar } from '../affected/sidecar.js';
+export { getPathgradeDir } from '../reporters/results-path.js';
+export { printReportSummary } from '../reporters/report-summary.js';
+export { fmt } from '../utils/cli.js';
+export { getCurrentCaseContext, installCaseContextProvider, runWithCaseContext, type CaseContext, type CaseContextProvider, type CaseContextProviderHandle, type CaseContextScope, type CurrentCaseContext, } from '../sdk/case-context.js';
+export { subscribeToEvalResults, type EvalResultObserver, type ResultObserverHandle, type ResultObserverOptions, type ResultObserverOwner, } from '../sdk/result-capture.js';
+export type { Agent, PathgradeTestMeta, RecordedEvalResult, } from '../sdk/types.js';

package/dist/adapter-kit/index.js

@@ -0,0 +1,14 @@
+export { runnerAdapterContractVersion, } from '../runners/adapter.js';
+export { buildNormalizedRunSnapshotFromReportGroups } from '../runners/model-builders.js';
+export { validateNormalizedRunSnapshot } from '../runners/model-validation.js';
+export { projectNormalizedRunSnapshotToReportInput } from '../runners/report-projection.js';
+export { runWithAdapter } from '../runners/orchestrator.js';
+export { createRunnerLifecycleHooks } from '../runners/lifecycle-hooks.js';
+export { discoverPathgradeEvalFiles } from '../evals/discovery.js';
+export { DEFAULT_EVAL_EXCLUDE, DEFAULT_EVAL_INCLUDE, defaultPathgradeConfig, resolvePathgradeConfig, } from '../config/pathgrade.js';
+export { readSidecar } from '../affected/sidecar.js';
+export { getPathgradeDir } from '../reporters/results-path.js';
+export { printReportSummary } from '../reporters/report-summary.js';
+export { fmt } from '../utils/cli.js';
+export { getCurrentCaseContext, installCaseContextProvider, runWithCaseContext, } from '../sdk/case-context.js';
+export { subscribeToEvalResults, } from '../sdk/result-capture.js';

package/dist/adapters/jest/index.d.ts

@@ -0,0 +1,3 @@
+export { createJestAdapter, createPathgradeAdapter } from './runner-adapter.js';
+export { createJestInvocationAdapter, createPathgradeInvocationAdapter } from './invocation-adapter.js';
+export { default as PathgradeJestReporter } from './reporter.js';

package/dist/adapters/jest/index.js

@@ -0,0 +1,3 @@
+export { createJestAdapter, createPathgradeAdapter } from './runner-adapter.js';
+export { createJestInvocationAdapter, createPathgradeInvocationAdapter } from './invocation-adapter.js';
+export { default as PathgradeJestReporter } from './reporter.js';

package/dist/adapters/jest/invocation-adapter.d.ts

@@ -0,0 +1,15 @@
+import { type ResolvedPathgradeConfig, type RunnerInvocationAdapter } from '@wix/pathgrade/adapter-kit';
+export interface SpawnJestRequest {
+    argv: string[];
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+}
+export type SpawnJest = (req: SpawnJestRequest) => Promise<number> | number;
+export declare function createJestInvocationAdapter(input: {
+    config: ResolvedPathgradeConfig;
+    spawnJest?: SpawnJest;
+}): RunnerInvocationAdapter;
+export declare function createPathgradeInvocationAdapter(input: {
+    config: ResolvedPathgradeConfig;
+}): RunnerInvocationAdapter;
+export declare function resolveLocalJestBinPath(cwd: string): string;

package/dist/adapters/jest/invocation-adapter.js

@@ -0,0 +1,115 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { getPathgradeDir, printReportSummary, readSidecar, runWithAdapter, } from '@wix/pathgrade/adapter-kit';
+import { removeJestMetadata, withJestMetadataEnv } from './metadata.js';
+import { createJestAdapter } from './runner-adapter.js';
+export function createJestInvocationAdapter(input) {
+    const spawnJest = input.spawnJest ?? defaultSpawnJest;
+    return {
+        name: 'jest',
+        async run(runInput) {
+            const selection = await readSidecar(runInput.cwd, msg => {
+                process.stderr.write(`[pathgrade] ${msg}\n`);
+            }) ?? undefined;
+            const include = runInput.selectedFiles && runInput.selectedFiles.length > 0
+                ? runInput.selectedFiles
+                : input.config.evals.include;
+            const exclude = runInput.selectedFiles ? [] : input.config.evals.exclude;
+            const discovered = await createJestAdapter().discover({
+                cwd: runInput.cwd,
+                include,
+                exclude,
+                selection,
+            });
+            if (discovered.units.length === 0) {
+                return await runWithAdapter({
+                    adapter: createJestAdapter({ results: { testResults: [] } }),
+                    options: {
+                        cwd: runInput.cwd,
+                        discovery: {
+                            cwd: runInput.cwd,
+                            include,
+                            exclude,
+                            selection,
+                        },
+                        runnerArgs: [],
+                        env: runInput.env,
+                        artifactRoot: getPathgradeDir(runInput.cwd),
+                        reporterMode: input.config.reporter ?? 'cli',
+                        threshold: input.config.ci.threshold,
+                        selection,
+                        printSummary: summaries => {
+                            printReportSummary(summaries, {
+                                forceVerbose: input.config.diagnostics
+                                    || runInput.env.PATHGRADE_DIAGNOSTICS === '1',
+                            });
+                        },
+                        log: () => {
+                            process.stdout.write(`\n  Results written to ${getPathgradeDir(runInput.cwd)}\n\n`);
+                        },
+                        onThresholdFailure: ({ overallPassRate, threshold }) => {
+                            process.stdout.write(`\n  CI THRESHOLD FAILED  avg score ${overallPassRate.toFixed(3)} < threshold ${threshold}\n\n`);
+                        },
+                    },
+                });
+            }
+            const env = withJestMetadataEnv(runInput.env, runInput.cwd);
+            removeJestMetadata(env.PATHGRADE_JEST_METADATA_PATH);
+            return await spawnJest({
+                cwd: runInput.cwd,
+                env,
+                argv: [
+                    ...discovered.units.map(unit => unit.sourceRef).filter((sourceRef) => typeof sourceRef === 'string'),
+                    '--setupFilesAfterEnv',
+                    resolveAdapterFile('setup'),
+                    '--reporters',
+                    'default',
+                    '--reporters',
+                    resolveReporterFile(),
+                    ...runInput.runnerArgs,
+                ],
+            });
+        },
+    };
+}
+export function createPathgradeInvocationAdapter(input) {
+    return createJestInvocationAdapter(input);
+}
+function resolveAdapterFile(name) {
+    return path.resolve(import.meta.dirname, `${name}.js`);
+}
+function resolveReporterFile() {
+    return path.resolve(import.meta.dirname, 'reporter.cjs');
+}
+async function defaultSpawnJest(req) {
+    const jestBinPath = resolveLocalJestBinPath(req.cwd);
+    return await new Promise(resolve => {
+        const child = spawn(process.execPath, [jestBinPath, ...req.argv], {
+            stdio: 'inherit',
+            env: req.env,
+            cwd: req.cwd,
+        });
+        child.on('close', code => resolve(code ?? 0));
+        child.on('error', () => resolve(1));
+    });
+}
+export function resolveLocalJestBinPath(cwd) {
+    let packageJsonPath;
+    try {
+        const req = createRequire(path.join(cwd, 'package.json'));
+        packageJsonPath = req.resolve('jest/package.json');
+    }
+    catch {
+        throw new Error('pathgrade: Jest adapter requires Jest to be installed in the project. Install it with `npm install --save-dev jest` or the equivalent for your package manager.');
+    }
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    const bin = typeof packageJson.bin === 'string'
+        ? packageJson.bin
+        : packageJson.bin?.jest;
+    if (!bin) {
+        throw new Error(`pathgrade: could not find the Jest executable declared by ${packageJsonPath}.`);
+    }
+    return path.resolve(path.dirname(packageJsonPath), bin);
+}

package/dist/adapters/jest/lifecycle.d.ts

@@ -0,0 +1,21 @@
+import { type CaseContext, type CaseContextProviderHandle, type ResultObserverHandle, type PathgradeTestMeta, type AdapterLifecycleHooks, type EvalResultEvent } from '@wix/pathgrade/adapter-kit';
+export type JestHook = (fn: () => void | Promise<void>) => void;
+export interface JestState {
+    testPath?: string;
+    currentTestName?: string;
+}
+export interface JestLifecycleInstallInput {
+    beforeEach: JestHook;
+    afterEach: JestHook;
+    afterAll?: JestHook;
+    getState: () => JestState;
+    lifecycle?: AdapterLifecycleHooks;
+    subscribeToResults?: (callback: (event: EvalResultEvent) => void) => ResultObserverHandle;
+    installCaseContextProvider?: (provider: () => CaseContext | null) => CaseContextProviderHandle;
+}
+export interface JestLifecycleInstallHandle {
+    restore(): void;
+}
+export declare function installJestLifecycle(input: JestLifecycleInstallInput): JestLifecycleInstallHandle;
+export declare function getJestLifecycleMetadata(): Map<string, PathgradeTestMeta[]>;
+export declare function resetJestLifecycleMetadata(): void;

package/dist/adapters/jest/lifecycle.js

@@ -0,0 +1,62 @@
+import { installCaseContextProvider, subscribeToEvalResults, createRunnerLifecycleHooks, } from '@wix/pathgrade/adapter-kit';
+import { appendJestMetadata } from './metadata.js';
+import { jestCaseId } from './results.js';
+const metadataByCaseId = new Map();
+export function installJestLifecycle(input) {
+    const lifecycle = input.lifecycle ?? createRunnerLifecycleHooks();
+    const occurrenceCounts = new Map();
+    let activeCase = null;
+    let restored = false;
+    const resultCapture = (input.subscribeToResults ?? defaultSubscribeToResults)(event => lifecycle.onResult(event));
+    const contextProvider = (input.installCaseContextProvider ?? installCaseContextProvider)(() => activeCase);
+    metadataByCaseId.clear();
+    input.beforeEach(() => {
+        const state = input.getState();
+        const filePath = state.testPath ?? 'jest';
+        const caseName = state.currentTestName ?? 'Jest test';
+        const caseId = jestCaseId({
+            filePath,
+            fullName: caseName,
+            occurrenceCounts,
+        });
+        activeCase = {
+            caseId,
+            caseName,
+            filePath,
+            scope: 'runner-case',
+        };
+    });
+    input.afterEach(async () => {
+        const current = activeCase;
+        if (!current)
+            return;
+        const metadata = await lifecycle.flushCase(current.caseId);
+        if (metadata.length > 0) {
+            metadataByCaseId.set(current.caseId, metadata);
+            appendJestMetadata(current.caseId, metadata);
+        }
+        activeCase = null;
+    });
+    input.afterAll?.(async () => {
+        await lifecycle.cleanupRun();
+        restore();
+    });
+    return { restore };
+    function restore() {
+        if (restored)
+            return;
+        restored = true;
+        activeCase = null;
+        resultCapture.unsubscribe();
+        contextProvider.restore();
+    }
+}
+export function getJestLifecycleMetadata() {
+    return new Map(metadataByCaseId);
+}
+export function resetJestLifecycleMetadata() {
+    metadataByCaseId.clear();
+}
+function defaultSubscribeToResults(callback) {
+    return subscribeToEvalResults(({ result, agent }) => callback({ result, agent }), { owner: 'adapter', key: 'jest-lifecycle' });
+}

package/dist/adapters/jest/metadata.d.ts

@@ -0,0 +1,6 @@
+import type { PathgradeTestMeta } from '@wix/pathgrade/adapter-kit';
+export declare function resolveJestMetadataPath(cwd?: string): string;
+export declare function withJestMetadataEnv(env: NodeJS.ProcessEnv, cwd: string): NodeJS.ProcessEnv;
+export declare function appendJestMetadata(caseId: string, metadata: PathgradeTestMeta[]): void;
+export declare function readJestMetadata(metadataPath?: string): Map<string, PathgradeTestMeta[]>;
+export declare function removeJestMetadata(metadataPath?: string): void;

package/dist/adapters/jest/metadata.js

@@ -0,0 +1,35 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const METADATA_ENV = 'PATHGRADE_JEST_METADATA_PATH';
+const FALLBACK_METADATA_FILE = 'jest-metadata.jsonl';
+export function resolveJestMetadataPath(cwd = process.cwd()) {
+    return process.env[METADATA_ENV] ?? path.join(cwd, '.pathgrade', FALLBACK_METADATA_FILE);
+}
+export function withJestMetadataEnv(env, cwd) {
+    return {
+        ...env,
+        [METADATA_ENV]: env[METADATA_ENV] ?? path.join(cwd, '.pathgrade', `${process.pid}-${Date.now()}-${FALLBACK_METADATA_FILE}`),
+    };
+}
+export function appendJestMetadata(caseId, metadata) {
+    if (metadata.length === 0)
+        return;
+    const metadataPath = resolveJestMetadataPath();
+    fs.mkdirSync(path.dirname(metadataPath), { recursive: true });
+    fs.appendFileSync(metadataPath, `${JSON.stringify({ caseId, metadata })}\n`, 'utf8');
+}
+export function readJestMetadata(metadataPath = resolveJestMetadataPath()) {
+    if (!fs.existsSync(metadataPath))
+        return new Map();
+    const metadataByCaseId = new Map();
+    for (const line of fs.readFileSync(metadataPath, 'utf8').split('\n')) {
+        if (line.trim().length === 0)
+            continue;
+        const entry = JSON.parse(line);
+        metadataByCaseId.set(entry.caseId, entry.metadata);
+    }
+    return metadataByCaseId;
+}
+export function removeJestMetadata(metadataPath = resolveJestMetadataPath()) {
+    fs.rmSync(metadataPath, { force: true });
+}

package/dist/adapters/jest/reporter.cjs

@@ -0,0 +1,10 @@
+class PathgradeJestReporterBridge {
+    async onRunComplete(...args) {
+        const mod = await import('./reporter.js');
+        const Reporter = mod.default;
+        const reporter = new Reporter();
+        return await reporter.onRunComplete(...args);
+    }
+}
+
+module.exports = PathgradeJestReporterBridge;

package/dist/adapters/jest/reporter.d.ts

@@ -0,0 +1,5 @@
+import type { JestAggregatedResult } from './results.js';
+export default class PathgradeJestReporter {
+    onRunComplete(_contexts: unknown, results: JestAggregatedResult): Promise<void>;
+    private openBrowserViewer;
+}