@wix/pathgrade 0.36.0 → 1.0.0

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;
+}

package/dist/adapters/jest/reporter.js

@@ -0,0 +1,67 @@
+import * as path from 'node:path';
+import { execSync } from 'node:child_process';
+import { fmt, getPathgradeDir, printReportSummary, readSidecar, resolvePathgradeConfig, runWithAdapter, } from '@wix/pathgrade/adapter-kit';
+import { getJestLifecycleMetadata } from './lifecycle.js';
+import { readJestMetadata, removeJestMetadata } from './metadata.js';
+import { createJestAdapter } from './runner-adapter.js';
+export default class PathgradeJestReporter {
+    async onRunComplete(_contexts, results) {
+        const cwd = process.cwd();
+        const config = await resolvePathgradeConfig({ cwd });
+        const mode = config.reporter ?? 'cli';
+        const outputDir = getPathgradeDir(cwd);
+        const metadataByCaseId = new Map([
+            ...readJestMetadata(),
+            ...getJestLifecycleMetadata(),
+        ]);
+        const exitCode = await runWithAdapter({
+            adapter: createJestAdapter({
+                results,
+                metadataByCaseId,
+            }),
+            options: {
+                cwd,
+                discovery: { cwd },
+                runnerArgs: [],
+                env: process.env,
+                artifactRoot: outputDir,
+                reporterMode: mode,
+                threshold: config.ci.threshold,
+                writeEmptyReport: false,
+                warn: warning => console.warn(warning),
+                log: () => console.log(`\n  ${fmt.dim('Results written to')} ${outputDir}\n`),
+                loadSelection: async () => (await readSidecar(cwd, msg => {
+                    console.warn(`[pathgrade] ${msg}`);
+                })) ?? undefined,
+                printSummary: summaries => {
+                    printReportSummary(summaries, {
+                        forceVerbose: config.diagnostics
+                            || process.env.PATHGRADE_DIAGNOSTICS === '1',
+                    });
+                },
+                openBrowser: () => this.openBrowserViewer(),
+                onThresholdFailure: ({ overallPassRate, threshold }) => {
+                    process.exitCode = 1;
+                    console.log(`\n  ${fmt.fail('CI THRESHOLD FAILED')}  avg score ${fmt.bold(overallPassRate.toFixed(3))} < threshold ${fmt.bold(String(threshold))}\n`);
+                },
+            },
+        });
+        if (exitCode !== 0 && (process.exitCode === undefined || process.exitCode === 0)) {
+            process.exitCode = exitCode;
+        }
+        removeJestMetadata();
+    }
+    openBrowserViewer() {
+        const viewerPath = path.resolve(import.meta.dirname, '..', '..', 'viewer.html');
+        try {
+            const openCmd = process.platform === 'darwin' ? 'open'
+                : process.platform === 'win32' ? 'start'
+                    : 'xdg-open';
+            execSync(`${openCmd} "${viewerPath}"`, { stdio: 'ignore' });
+            console.log(`\n  ${fmt.dim('Opened viewer in browser')}\n`);
+        }
+        catch {
+            console.log(`\n  ${fmt.dim('Open manually:')} ${viewerPath}\n`);
+        }
+    }
+}

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

@@ -0,0 +1,31 @@
+import type { AdapterRunHandle, NormalizedRunSnapshot, PathgradeTestMeta } from '@wix/pathgrade/adapter-kit';
+export interface JestAggregatedResult {
+    testResults?: JestFileResult[];
+}
+export interface JestFileResult {
+    testFilePath: string;
+    assertionResults?: JestAssertionResult[];
+    testResults?: JestAssertionResult[];
+}
+export interface JestAssertionResult {
+    ancestorTitles?: string[];
+    title: string;
+    fullName?: string;
+    status: string;
+    duration?: number | null;
+    failureMessages?: string[];
+    location?: {
+        line?: number | null;
+        column?: number | null;
+    } | null;
+}
+export declare function normalizeJestRunResults(input: {
+    run: AdapterRunHandle;
+    results: JestAggregatedResult;
+    metadataByCaseId?: Map<string, PathgradeTestMeta[]>;
+}): NormalizedRunSnapshot;
+export declare function jestCaseId(input: {
+    filePath: string;
+    fullName: string;
+    occurrenceCounts?: Map<string, number>;
+}): string;

package/dist/adapters/jest/results.js

@@ -0,0 +1,144 @@
+export function normalizeJestRunResults(input) {
+    const runId = `${input.run.adapterName}:run`;
+    const files = input.results.testResults ?? [];
+    const units = files.map((fileResult, index) => ({
+        id: unitId(index),
+        runId,
+        displayName: fileResult.testFilePath,
+        groupingHints: [{
+                kind: 'source',
+                key: fileResult.testFilePath,
+                label: fileResult.testFilePath,
+                order: index,
+            }],
+        nativeReferences: [{ kind: 'jest-file', id: fileResult.testFilePath }],
+    }));
+    const occurrenceCounts = new Map();
+    return {
+        version: 1,
+        completeness: 'final',
+        model: {
+            run: {
+                id: runId,
+                adapterName: input.run.adapterName,
+                status: input.run.status,
+            },
+            units,
+            cases: files.flatMap((fileResult, fileIndex) => assertionsForFile(fileResult).map(assertion => {
+                const caseId = jestCaseId({
+                    filePath: fileResult.testFilePath,
+                    fullName: assertion.fullName ?? fullCaseName(assertion),
+                    occurrenceCounts,
+                });
+                return runCase({
+                    runId,
+                    unitId: unitId(fileIndex),
+                    caseId,
+                    assertion,
+                    filePath: fileResult.testFilePath,
+                    evaluations: input.metadataByCaseId?.get(caseId) ?? [],
+                });
+            })),
+        },
+    };
+}
+function assertionsForFile(fileResult) {
+    return fileResult.assertionResults ?? fileResult.testResults ?? [];
+}
+export function jestCaseId(input) {
+    const base = `jest:${input.filePath}:${slug(input.fullName)}`;
+    const current = input.occurrenceCounts?.get(base) ?? 0;
+    const occurrence = current + 1;
+    input.occurrenceCounts?.set(base, occurrence);
+    return `${base}:${occurrence}`;
+}
+function runCase(input) {
+    const state = normalizeState(input.assertion.status);
+    const attemptId = `${input.caseId}:attempt-1`;
+    const evaluations = input.evaluations.map((entry, index) => ({
+        id: `${attemptId}:evaluation-${index + 1}`,
+        attemptId,
+        score: entry.score,
+        ...(entry.trial ? { trial: entry.trial } : {}),
+        ...(entry.diagnostics ? { diagnostics: entry.diagnostics } : {}),
+    }));
+    const failureMessage = input.assertion.failureMessages?.find(message => message.trim().length > 0);
+    return {
+        id: input.caseId,
+        runId: input.runId,
+        unitId: input.unitId,
+        name: fullCaseName(input.assertion),
+        state,
+        scoringPolicy: scoringPolicyForCase(state, evaluations),
+        groupingHints: [{
+                kind: 'source',
+                key: input.filePath,
+                label: input.filePath,
+                order: 0,
+            }],
+        nativeReferences: [{
+                kind: 'jest-case',
+                id: input.caseId,
+                metadata: {
+                    status: input.assertion.status,
+                    ...(input.assertion.location?.line ? { line: input.assertion.location.line } : {}),
+                    ...(input.assertion.location?.column ? { column: input.assertion.location.column } : {}),
+                },
+            }],
+        attempts: [{
+                id: attemptId,
+                caseId: input.caseId,
+                outcome: outcomeForCase(state, failureMessage),
+                durationMs: input.assertion.duration ?? 0,
+                ...(evaluations.length > 0 ? { evaluations } : {}),
+                ...(failureMessage ? {
+                    assertions: [{
+                            id: `${attemptId}:assertion-1`,
+                            attemptId,
+                            name: 'Jest assertion failure',
+                            status: 'failed',
+                            severity: 'error',
+                            message: failureMessage,
+                        }],
+                } : {}),
+            }],
+    };
+}
+function fullCaseName(assertion) {
+    const ancestors = assertion.ancestorTitles ?? [];
+    return [...ancestors, assertion.title].filter(Boolean).join(' > ');
+}
+function normalizeState(status) {
+    if (status === 'passed')
+        return 'passed';
+    if (status === 'skipped')
+        return 'skipped';
+    if (status === 'pending' || status === 'todo' || status === 'disabled')
+        return 'pending';
+    return 'failed';
+}
+function scoringPolicyForCase(state, evaluations) {
+    if (state === 'skipped' || state === 'pending')
+        return { kind: 'non-scoring', reason: state };
+    if (evaluations.length > 0)
+        return { kind: 'from-evaluations' };
+    return { kind: 'score', score: state === 'passed' ? 1 : 0 };
+}
+function outcomeForCase(state, failureMessage) {
+    if (state === 'passed')
+        return { kind: 'passed' };
+    if (state === 'failed')
+        return { kind: 'failed', ...(failureMessage ? { reason: failureMessage } : {}) };
+    return { kind: 'not-run', reason: state };
+}
+function unitId(index) {
+    return `jest:unit-${index + 1}`;
+}
+function slug(value) {
+    const clean = value
+        .trim()
+        .toLowerCase()
+        .replaceAll(/[^a-z0-9]+/g, '-')
+        .replaceAll(/^-|-$/g, '');
+    return clean || 'case';
+}

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

@@ -0,0 +1,9 @@
+import { type JestAggregatedResult } from './results.js';
+import { type PathgradeTestMeta, RunnerAdapter } from '@wix/pathgrade/adapter-kit';
+interface JestRunNative {
+    results?: JestAggregatedResult;
+    metadataByCaseId?: Map<string, PathgradeTestMeta[]>;
+}
+export declare function createJestAdapter(options?: JestRunNative): RunnerAdapter;
+export declare function createPathgradeAdapter(): RunnerAdapter;
+export {};

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

@@ -0,0 +1,49 @@
+import { normalizeJestRunResults } from './results.js';
+import { discoverPathgradeEvalFiles, } from '@wix/pathgrade/adapter-kit';
+export function createJestAdapter(options = {}) {
+    return {
+        name: 'jest',
+        async discover(input) {
+            const include = input.include ?? ['**/*.eval.ts'];
+            const exclude = input.exclude ?? [];
+            const files = discoverPathgradeEvalFiles({
+                cwd: input.cwd,
+                include,
+                exclude,
+            });
+            return {
+                units: files.map(file => ({
+                    id: file,
+                    displayName: file,
+                    sourceRef: file,
+                    native: { file, cwd: input.cwd },
+                })),
+            };
+        },
+        async invoke(input) {
+            return {
+                adapterName: this.name,
+                status: input.signal?.aborted ? 'cancelled' : 'completed',
+                exitCode: input.signal?.aborted ? 1 : 0,
+                native: options,
+            };
+        },
+        async collectNormalizedRunSnapshot(run) {
+            const native = readJestRunNative(run);
+            return normalizeJestRunResults({
+                run,
+                results: native.results ?? { testResults: [] },
+                metadataByCaseId: native.metadataByCaseId,
+            });
+        },
+    };
+}
+export function createPathgradeAdapter() {
+    return createJestAdapter();
+}
+function readJestRunNative(run) {
+    if (typeof run.native === 'object' && run.native !== null) {
+        return run.native;
+    }
+    return {};
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/adapters/jest/setup.js

@@ -0,0 +1,10 @@
+import { installJestLifecycle } from './lifecycle.js';
+const jestGlobals = globalThis;
+if (jestGlobals.beforeEach && jestGlobals.afterEach && jestGlobals.expect?.getState) {
+    installJestLifecycle({
+        beforeEach: jestGlobals.beforeEach,
+        afterEach: jestGlobals.afterEach,
+        afterAll: jestGlobals.afterAll,
+        getState: () => jestGlobals.expect?.getState?.() ?? {},
+    });
+}

package/dist/adapters/node-test/index.d.ts

@@ -0,0 +1,8 @@
+import type { TestContext } from 'node:test';
+type NodeTestFn = (t: TestContext) => unknown | Promise<unknown>;
+type NodeTestOptions = Record<string, unknown>;
+export declare function test(name: string, fn: NodeTestFn): void;
+export declare function test(name: string, options: NodeTestOptions, fn: NodeTestFn): void;
+export default test;
+export { createNodeTestAdapter } from './runner-adapter.js';
+export { createNodeTestInvocationAdapter } from './invocation-adapter.js';