@wix/pathgrade 0.29.0

package/dist/commands/preview-reactions.js

@@ -0,0 +1,88 @@
+import * as path from 'path';
+import { loadReactionSnapshotMessages, loadReactionsFromFile } from '../sdk/reaction-loader.js';
+import { previewReactions } from '../sdk/reaction-preview.js';
+function readFlag(args, flag) {
+    const exactIndex = args.findIndex((arg) => arg === flag);
+    if (exactIndex >= 0) {
+        return args[exactIndex + 1];
+    }
+    const inline = args.find((arg) => arg.startsWith(`${flag}=`));
+    return inline ? inline.slice(flag.length + 1) : undefined;
+}
+function truncate(value, limit) {
+    if (value.length <= limit)
+        return value;
+    return `${value.slice(0, Math.max(0, limit - 3))}...`;
+}
+function getStatus(result) {
+    if (result.status)
+        return result.status;
+    if (result.fired)
+        return 'fired';
+    if (result.kind === 'text' && result.unlessMatched)
+        return 'vetoed';
+    return 'no-match';
+}
+function formatCli(result) {
+    if (result.turns.length === 0) {
+        return 'No agent turns found in snapshot.\n';
+    }
+    const lines = [];
+    for (const turn of result.turns) {
+        lines.push(`Turn ${turn.turn}: ${truncate(turn.agentMessage, 120)}`);
+        if (turn.reactions.length === 0) {
+            lines.push('  (no reactions)');
+            continue;
+        }
+        for (const reaction of turn.reactions) {
+            const reply = reaction.kind === 'text' ? reaction.reply : undefined;
+            const replySuffix = reply ? ` -> ${truncate(reply, 80)}` : '';
+            lines.push(`  [${reaction.reactionIndex}] ${getStatus(reaction)}${replySuffix}`);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+function parseArgs(args) {
+    const snapshot = readFlag(args, '--snapshot');
+    if (!snapshot) {
+        throw new Error('Missing required --snapshot <path> flag for preview-reactions.');
+    }
+    const reactions = readFlag(args, '--reactions');
+    if (!reactions) {
+        throw new Error('Missing required --reactions <path> flag for preview-reactions.');
+    }
+    const format = (readFlag(args, '--format') ?? 'cli');
+    if (format !== 'cli' && format !== 'json') {
+        throw new Error('Invalid --format value. Expected "cli" or "json".');
+    }
+    return { snapshot, reactions, format };
+}
+async function buildPreview(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const snapshotPath = path.resolve(cwd, opts.snapshot);
+    const reactionsPath = path.resolve(cwd, opts.reactions);
+    const messages = await loadReactionSnapshotMessages(snapshotPath);
+    const reactions = await loadReactionsFromFile(reactionsPath);
+    return previewReactions(messages, reactions);
+}
+export async function runPreviewReactions(input) {
+    const opts = Array.isArray(input) ? parseArgs(input) : input;
+    const result = await buildPreview(opts);
+    if (Array.isArray(input)) {
+        if ((opts.format ?? 'cli') === 'json') {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(formatCli(result).trimEnd());
+        }
+        return 0;
+    }
+    const write = opts.write ?? ((chunk) => process.stdout.write(chunk));
+    if ((opts.format ?? 'cli') === 'json') {
+        write(`${JSON.stringify(result, null, 2)}\n`);
+    }
+    else {
+        write(formatCli(result));
+    }
+    return 0;
+}

package/dist/commands/preview.d.ts

@@ -0,0 +1,5 @@
+export interface PreviewOptions {
+    last?: number;
+    filter?: string;
+}
+export declare function runPreview(dir: string, mode: 'cli' | 'browser', outputDir?: string, opts?: PreviewOptions): Promise<void>;

package/dist/commands/preview.js

@@ -0,0 +1,17 @@
+/**
+ * `pathgrade preview` command.
+ *
+ * Opens the CLI or browser results viewer.
+ */
+import { runCliPreview } from '../reporters/cli.js';
+import { runBrowserPreview } from '../reporters/browser.js';
+import { getResultsDir } from '../reporters/results-path.js';
+export async function runPreview(dir, mode, outputDir, opts) {
+    const resultsDir = getResultsDir(dir, outputDir);
+    if (mode === 'browser') {
+        await runBrowserPreview(resultsDir);
+    }
+    else {
+        await runCliPreview(resultsDir, opts);
+    }
+}

package/dist/commands/report.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `pathgrade report` command.
+ *
+ * Reads the consolidated `.pathgrade/results.json` and formats a markdown
+ * report via `src/reporters/github-comment.ts`. Two observable behaviors:
+ *
+ *   - Posting path: in GitHub Actions (`GITHUB_ACTIONS === 'true'`) with a
+ *     resolvable PR context and a `GITHUB_TOKEN`, posts/updates a PR
+ *     comment and prints only the pass rate to stdout.
+ *   - Local/fallback path: prints the markdown, a blank line, then the
+ *     pass rate. Used for local runs, `--no-comment`, or any CI run
+ *     missing token/PR context.
+ *
+ * The final line of stdout is always the pass rate as a plain number so
+ * downstream workflow steps can capture it with `$(...)` or `>> $GITHUB_OUTPUT`.
+ *
+ * Display-only: the command never sets a failing exit code. Threshold
+ * enforcement stays in `PathgradeReporter` via `ci.threshold`.
+ */
+export interface ReportOptions {
+    /** Path to the consolidated results JSON, resolved against `cwd`. Defaults to `.pathgrade/results.json`. */
+    resultsPath?: string;
+    /** Skip PR comment posting; print markdown to stdout instead. */
+    noComment?: boolean;
+    /** Override the comment-id used in the dedup marker. See `resolveCommentId`. */
+    commentId?: string;
+}
+/**
+ * Resolve the comment-id used for the dedup marker.
+ *
+ * Precedence: explicit `commentId` → `$GITHUB_WORKFLOW:$GITHUB_JOB` →
+ * `$GITHUB_WORKFLOW` → hard-coded literal `"default"`.
+ */
+export declare function resolveCommentId(explicit?: string): string;
+/**
+ * Entry point for `pathgrade report`. Never throws and never sets a
+ * failing exit code — even on malformed inputs or network errors.
+ */
+export declare function runReport(cwd: string, opts?: ReportOptions): Promise<void>;

package/dist/commands/report.js

@@ -0,0 +1,108 @@
+/**
+ * `pathgrade report` command.
+ *
+ * Reads the consolidated `.pathgrade/results.json` and formats a markdown
+ * report via `src/reporters/github-comment.ts`. Two observable behaviors:
+ *
+ *   - Posting path: in GitHub Actions (`GITHUB_ACTIONS === 'true'`) with a
+ *     resolvable PR context and a `GITHUB_TOKEN`, posts/updates a PR
+ *     comment and prints only the pass rate to stdout.
+ *   - Local/fallback path: prints the markdown, a blank line, then the
+ *     pass rate. Used for local runs, `--no-comment`, or any CI run
+ *     missing token/PR context.
+ *
+ * The final line of stdout is always the pass rate as a plain number so
+ * downstream workflow steps can capture it with `$(...)` or `>> $GITHUB_OUTPUT`.
+ *
+ * Display-only: the command never sets a failing exit code. Threshold
+ * enforcement stays in `PathgradeReporter` via `ci.threshold`.
+ */
+import * as path from 'path';
+import fs from 'fs-extra';
+import { formatReportMarkdown, MISSING_RESULTS_BODY, postOrUpdateComment, resolvePrContext, } from '../reporters/github-comment.js';
+const DEFAULT_RESULTS_PATH = path.join('.pathgrade', 'results.json');
+/**
+ * Resolve the comment-id used for the dedup marker.
+ *
+ * Precedence: explicit `commentId` → `$GITHUB_WORKFLOW:$GITHUB_JOB` →
+ * `$GITHUB_WORKFLOW` → hard-coded literal `"default"`.
+ */
+export function resolveCommentId(explicit) {
+    if (explicit && explicit.length > 0)
+        return explicit;
+    const workflow = process.env.GITHUB_WORKFLOW;
+    const job = process.env.GITHUB_JOB;
+    if (workflow && job)
+        return `${workflow}:${job}`;
+    if (workflow)
+        return workflow;
+    return 'default';
+}
+function isPathgradeReport(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    return (v.version === 1 &&
+        typeof v.overall_pass_rate === 'number' &&
+        (v.status === 'pass' || v.status === 'fail') &&
+        Array.isArray(v.groups));
+}
+async function loadReport(resolvedPath) {
+    if (!(await fs.pathExists(resolvedPath))) {
+        throw new Error(`results file not found at ${resolvedPath}`);
+    }
+    const raw = await fs.readJSON(resolvedPath);
+    if (!isPathgradeReport(raw)) {
+        throw new Error(`results file at ${resolvedPath} is not a valid pathgrade report`);
+    }
+    return raw;
+}
+function printMarkdownAndPassRate(markdown, passRate) {
+    // Strip trailing newlines so we control spacing precisely:
+    // <markdown>\n\n<pass rate>\n
+    console.log(markdown.replace(/\n+$/, ''));
+    console.log('');
+    console.log(String(passRate));
+}
+/**
+ * Entry point for `pathgrade report`. Never throws and never sets a
+ * failing exit code — even on malformed inputs or network errors.
+ */
+export async function runReport(cwd, opts = {}) {
+    const resolvedPath = path.resolve(cwd, opts.resultsPath ?? DEFAULT_RESULTS_PATH);
+    const commentId = resolveCommentId(opts.commentId);
+    const inCI = process.env.GITHUB_ACTIONS === 'true';
+    const noComment = opts.noComment ?? false;
+    // Branch point: when true, post the comment and print only the pass rate.
+    const shouldPost = inCI && !noComment;
+    const prContext = shouldPost ? resolvePrContext(process.env) : null;
+    let report = null;
+    let loadError = null;
+    try {
+        report = await loadReport(resolvedPath);
+    }
+    catch (err) {
+        loadError = err instanceof Error ? err.message : String(err);
+    }
+    if (loadError) {
+        console.error(`pathgrade report: ${loadError}`);
+        if (prContext) {
+            await postOrUpdateComment(prContext, {
+                commentId,
+                body: MISSING_RESULTS_BODY,
+            });
+        }
+        // Always emit a pass rate line so downstream capture doesn't explode.
+        console.log('0');
+        return;
+    }
+    const markdown = formatReportMarkdown(report, { commentId });
+    if (prContext) {
+        await postOrUpdateComment(prContext, { commentId, body: markdown });
+        // Only the pass rate goes to stdout — the markdown lives on the PR.
+        console.log(String(report.overall_pass_rate));
+        return;
+    }
+    // Local / no-comment / missing CI context — print markdown + blank + pass rate.
+    printMarkdownAndPassRate(markdown, report.overall_pass_rate);
+}

package/dist/commands/run-args.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Parse `pathgrade run` arguments.
+ *
+ * Recognized pathgrade-specific flags are consumed here; everything else
+ * passes through to vitest. After a literal `--` separator, all remaining
+ * args are forwarded verbatim (vitest uses `--` the same way).
+ */
+export interface PathgradeRunArgs {
+    vitestArgs: string[];
+    forceDiagnostics: boolean;
+    forceVerbose: boolean;
+    changed: boolean;
+    quiet: boolean;
+    since?: string;
+    changedFilesPath?: string;
+    /**
+     * Non-fatal argument-shape warnings (e.g. `--since` without `--changed`).
+     * Callers should surface these to the user on stderr before dispatch.
+     */
+    warnings?: string[];
+}
+export declare function parsePathgradeRunArgs(args: string[]): PathgradeRunArgs;

package/dist/commands/run-args.js

@@ -0,0 +1,69 @@
+/**
+ * Parse `pathgrade run` arguments.
+ *
+ * Recognized pathgrade-specific flags are consumed here; everything else
+ * passes through to vitest. After a literal `--` separator, all remaining
+ * args are forwarded verbatim (vitest uses `--` the same way).
+ */
+export function parsePathgradeRunArgs(args) {
+    const vitestArgs = [];
+    let forceDiagnostics = false;
+    let forceVerbose = false;
+    let changed = false;
+    let quiet = false;
+    let since;
+    let changedFilesPath;
+    let passthrough = false;
+    for (const arg of args) {
+        if (passthrough) {
+            vitestArgs.push(arg);
+            continue;
+        }
+        if (arg === '--') {
+            passthrough = true;
+            continue;
+        }
+        if (arg === '--diagnostics') {
+            forceDiagnostics = true;
+            continue;
+        }
+        if (arg === '--verbose' || arg === '-v') {
+            forceVerbose = true;
+            continue;
+        }
+        if (arg === '--changed') {
+            changed = true;
+            continue;
+        }
+        if (arg === '--quiet') {
+            quiet = true;
+            continue;
+        }
+        if (arg.startsWith('--since=')) {
+            since = arg.slice('--since='.length);
+            continue;
+        }
+        if (arg.startsWith('--changed-files=')) {
+            changedFilesPath = arg.slice('--changed-files='.length);
+            continue;
+        }
+        vitestArgs.push(arg);
+    }
+    const warnings = [];
+    if (!changed && since !== undefined) {
+        warnings.push('--since has no effect without --changed; the flag is being ignored.');
+    }
+    if (!changed && changedFilesPath !== undefined) {
+        warnings.push('--changed-files has no effect without --changed; the flag is being ignored.');
+    }
+    const base = {
+        vitestArgs,
+        forceDiagnostics,
+        forceVerbose,
+        changed,
+        quiet,
+        since,
+        changedFilesPath,
+    };
+    return warnings.length > 0 ? { ...base, warnings } : base;
+}

package/dist/commands/run-changed.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `pathgrade run --changed` — orchestration.
+ *
+ * Happy-path wrapper: computes the affected-eval selection, formats the
+ * run-start summary, and spawns `vitest run <files> <extra-args>` with the
+ * selected file list as positional args.
+ *
+ * Empty selection short-circuits: print "no affected evals" and exit 0
+ * without invoking vitest (which would silently run the full suite with
+ * zero positional args — a correctness bug we must not introduce).
+ *
+ * Git-resolution failures exit non-zero. The selection pipeline is the
+ * only producer of the file list here.
+ */
+import type { PathgradeRunArgs } from './run-args.js';
+export interface SpawnVitestRequest {
+    argv: string[];
+}
+export type SpawnVitest = (req: SpawnVitestRequest) => Promise<number> | number;
+export interface RunChangedOptions {
+    cwd: string;
+    parsed: PathgradeRunArgs;
+    /** Override for tests; default spawns `npx vitest` inheriting stdio. */
+    spawnVitest?: SpawnVitest;
+}
+export declare function runChanged(opts: RunChangedOptions): Promise<number>;

package/dist/commands/run-changed.js

@@ -0,0 +1,138 @@
+/**
+ * `pathgrade run --changed` — orchestration.
+ *
+ * Happy-path wrapper: computes the affected-eval selection, formats the
+ * run-start summary, and spawns `vitest run <files> <extra-args>` with the
+ * selected file list as positional args.
+ *
+ * Empty selection short-circuits: print "no affected evals" and exit 0
+ * without invoking vitest (which would silently run the full suite with
+ * zero positional args — a correctness bug we must not introduce).
+ *
+ * Git-resolution failures exit non-zero. The selection pipeline is the
+ * only producer of the file list here.
+ */
+import * as fs from 'fs';
+import { selectAffected } from '../affected/select.js';
+import { resolveBaseRef, computeChangedFiles } from '../affected/git.js';
+import { loadAffectedConfig } from '../affected/config.js';
+import { writeSidecar } from '../affected/sidecar.js';
+import { discoverEvalFiles } from './affected.js';
+export async function runChanged(opts) {
+    const { cwd, parsed } = opts;
+    const spawnVitest = opts.spawnVitest ?? defaultSpawnVitest;
+    // 1. Change-set
+    let baseRef;
+    let changedFiles;
+    let baseRefLine;
+    if (parsed.changedFilesPath) {
+        try {
+            changedFiles = readChangedFilesList(parsed.changedFilesPath);
+        }
+        catch (err) {
+            process.stderr.write(`pathgrade run: could not read --changed-files: ${errMsg(err)}\n`);
+            return 1;
+        }
+        baseRef = 'explicit';
+    }
+    else if (parsed.since) {
+        changedFiles = computeChangedFiles(parsed.since);
+        baseRef = parsed.since;
+        baseRefLine = `pathgrade: base = ${parsed.since} (--since)`;
+    }
+    else {
+        const resolution = resolveBaseRef();
+        if ('error' in resolution) {
+            process.stderr.write(`${resolution.error}\n`);
+            return 1;
+        }
+        const shortSha = resolution.sha.slice(0, 7);
+        changedFiles = computeChangedFiles(resolution.sha);
+        baseRef = `${resolution.base}@${shortSha}`;
+        baseRefLine = `pathgrade: base = ${baseRef} (merge-base with HEAD)`;
+    }
+    // 2. Selection
+    const evalFiles = discoverEvalFiles(cwd);
+    const config = await loadAffectedConfig(cwd, {
+        onWarning: w => {
+            if (!parsed.quiet)
+                process.stderr.write(`${w}\n`);
+        },
+    });
+    let result;
+    try {
+        result = selectAffected({
+            evalFiles,
+            changedFiles,
+            repoRoot: cwd,
+            baseRef,
+            global: config.global,
+        });
+    }
+    catch (err) {
+        process.stderr.write(`pathgrade run: ${errMsg(err)}\n`);
+        return 1;
+    }
+    // 3. Summary + spawn
+    if (!parsed.quiet) {
+        printRunStartSummary({
+            baseRefLine,
+            totalEvals: evalFiles.length,
+            changedCount: changedFiles.length,
+            result,
+        });
+    }
+    // Persist the sidecar immediately — even on empty selection, so the
+    // reporter (if invoked later by another workflow step) has a coherent
+    // record. A subsequent plain `pathgrade run` clears it.
+    await writeSidecar(cwd, result);
+    if (result.selected.length === 0) {
+        if (!parsed.quiet) {
+            process.stderr.write(`pathgrade: no affected evals; nothing to run.\n`);
+        }
+        return 0;
+    }
+    const selectedFiles = result.selected.map(s => s.file);
+    const argv = ['run', ...selectedFiles, ...parsed.vitestArgs];
+    if (!parsed.quiet) {
+        process.stderr.write(`→ vitest run ${selectedFiles.join(' ')}\n`);
+    }
+    return await spawnVitest({ argv });
+}
+function printRunStartSummary(input) {
+    const { baseRefLine, totalEvals, changedCount, result } = input;
+    if (baseRefLine) {
+        process.stderr.write(`${baseRefLine}\n`);
+    }
+    process.stderr.write(`          changed files: ${changedCount}\n`);
+    const globalLabel = result.globalMatch ? `\`${result.globalMatch}\`` : 'none';
+    process.stderr.write(`          global matches: ${globalLabel}\n`);
+    process.stderr.write(`          selected: ${result.selected.length} / ${totalEvals} evals\n`);
+    for (const entry of result.selected) {
+        process.stderr.write(`            ${entry.file}\n`);
+    }
+    process.stderr.write(`          skipped: ${result.skipped.length}\n`);
+    for (const w of result.warnings) {
+        process.stderr.write(`          warning: ${w}\n`);
+    }
+    process.stderr.write(`\n`);
+}
+function readChangedFilesList(filePath) {
+    return fs.readFileSync(filePath, 'utf-8')
+        .split('\n')
+        .map(l => l.trim())
+        .filter(l => l.length > 0);
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+async function defaultSpawnVitest(req) {
+    const { spawn } = await import('child_process');
+    return await new Promise(resolve => {
+        const child = spawn('npx', ['vitest', ...req.argv], {
+            stdio: 'inherit',
+            shell: true,
+        });
+        child.on('close', code => resolve(code ?? 0));
+    });
+}

package/dist/commands/validate.d.ts

@@ -0,0 +1,13 @@
+export interface ValidateOptions {
+    /** Skip tsc subprocess check (useful in tests without full TS project setup). */
+    skipTsc?: boolean;
+}
+/**
+ * Run the validate command. Returns exit code (0 = valid, 1 = errors).
+ */
+export declare function runValidate(filePath: string, opts?: ValidateOptions): Promise<number>;
+/**
+ * Strict affected-selection validator. Exits 1 if any eval is missing
+ * both a SKILL.md ancestor and `__pathgradeMeta`, or has malformed meta.
+ */
+export declare function runValidateAffected(cwd: string): Promise<number>;