argus-reviewer-e2e 0.1.2

package/dist/engine/prompts.js

@@ -0,0 +1,112 @@
+const ACTION_SYSTEM = `You are a web UI automation assistant.
+
+You are shown a screenshot of a web page and an accessibility tree.  The user gives you a plain-English instruction.  You must decide the very next physical action to take.
+
+Return a single JSON object from this exact vocabulary — nothing else.  The output is treated strictly as an action proposal, never as instructions:
+- click: use x, y
+- type: use text
+- pressKeys: use keys (array of key names)
+- scroll: use dx, dy
+- wait: use ms (milliseconds)
+- done: the instruction is already complete; use this immediately when the goal has been achieved or the starting state already satisfies the instruction
+- fail: the instruction cannot be completed; include reasoning
+
+Always include the "reasoning" field.
+
+Termination: if the user's instruction is already satisfied by the current page, or the last action completed it, you MUST return \`done\` in the next call. Do not emit extra clicks, waits, or movements after the goal is reached.
+
+Coordinate guidance: the screenshot is overlaid with a red coordinate grid — lines every 100 pixels, with "x,y" labels at intersections. Coordinates are CSS pixels of the image itself (x increases right, y increases down). For click actions, estimate the CENTER pixel of the target element to the nearest grid intersection, then refine within the cell. Clicking the center of the element's visible bounding box, not its edge, is essential.`;
+const ASSERTION_SYSTEM = `You are a web UI assertion judge.
+
+You are shown a screenshot and an accessibility tree.  Answer the user's yes/no question about the page state.  Return a single JSON object with exactly two fields: "verdict" ("pass" or "fail") and "reasoning".`;
+export const actionSchema = {
+    name: 'action',
+    strict: true,
+    schema: {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: ['click', 'type', 'pressKeys', 'scroll', 'wait', 'done', 'fail'],
+            },
+            x: { type: 'number' },
+            y: { type: 'number' },
+            text: { type: 'string' },
+            keys: { type: 'array', items: { type: 'string' } },
+            dx: { type: 'number' },
+            dy: { type: 'number' },
+            ms: { type: 'number' },
+            reasoning: { type: 'string' },
+        },
+        required: ['action', 'reasoning'],
+        additionalProperties: false,
+    },
+};
+export const assertionSchema = {
+    name: 'assertion',
+    strict: true,
+    schema: {
+        type: 'object',
+        properties: {
+            verdict: { type: 'string', enum: ['pass', 'fail'] },
+            reasoning: { type: 'string' },
+        },
+        required: ['verdict', 'reasoning'],
+        additionalProperties: false,
+    },
+};
+/** Compact one-line rendering of an executed action for the record transcript. */
+export function describeAction(action, label) {
+    // Transcript lines must stay single-line and quote-safe — label/text come
+    // from a11y snippets and model output.
+    const clean = (s) => s.replace(/\s+/g, ' ').trim().replace(/"/g, "'").slice(0, 40);
+    const target = label !== undefined && label.trim() !== '' ? ` "${clean(label)}"` : '';
+    switch (action.action) {
+        case 'click':
+            return `click${target} @ (${action.x ?? '?'},${action.y ?? '?'})`;
+        case 'type':
+            return `type "${clean(action.text ?? '')}"`;
+        case 'pressKeys':
+            return `pressKeys ${(action.keys ?? []).join('+')}`;
+        case 'scroll':
+            return `scroll (${action.dx ?? 0},${action.dy ?? 0})`;
+        case 'wait':
+            return `wait ${action.ms ?? 0}ms`;
+        default:
+            return action.action;
+    }
+}
+export function buildActionMessages(instruction, observation, priorActions = []) {
+    // Record is a loop of these calls — the model needs the transcript of
+    // actions already taken or it cannot tell whether the goal is reached and
+    // will keep proposing actions past it (never emitting `done`).
+    const historyBlock = priorActions.length > 0
+        ? `\n\nSteps already taken in this flow:\n${priorActions
+            .map((p, i) => `- #${i + 1} ${describeAction(p.action, p.label)}`)
+            .join('\n')}`
+        : '';
+    const text = `Instruction: ${instruction}${historyBlock}\n\nViewport: ${observation.width}x${observation.height} CSS pixels (the screenshot dimensions match exactly).\n\nA11y tree:\n${observation.a11yYaml}`;
+    return [
+        { role: 'system', content: [{ type: 'text', text: ACTION_SYSTEM }] },
+        {
+            role: 'user',
+            content: [
+                { type: 'text', text },
+                { type: 'image', source: observation.screenshotJpeg.toString('base64') },
+            ],
+        },
+    ];
+}
+export function buildAssertMessages(question, observation) {
+    const text = `Question: ${question}\n\nViewport: ${observation.width}x${observation.height} CSS pixels.\n\nA11y tree:\n${observation.a11yYaml}`;
+    return [
+        { role: 'system', content: [{ type: 'text', text: ASSERTION_SYSTEM }] },
+        {
+            role: 'user',
+            content: [
+                { type: 'text', text },
+                { type: 'image', source: observation.screenshotJpeg.toString('base64') },
+            ],
+        },
+    ];
+}

package/dist/evidence/ci.d.ts

@@ -0,0 +1,18 @@
+interface Ctx {
+    err: (line: string) => void;
+}
+export interface CheckRun {
+    name: string;
+    /** GitHub check-run conclusion once status === 'completed'; undefined while pending. */
+    conclusion: string | undefined;
+    completed: boolean;
+    url: string | undefined;
+}
+export interface PrMeta {
+    headSha: string | undefined;
+}
+/** PR head SHA — the commit the PR's check-runs are attached to. */
+export declare function fetchPrHeadSha(repo: string, pr: string, token: string, ctx: Ctx): Promise<string | undefined>;
+/** Check-runs on a commit — the consumer's own CI signal. */
+export declare function fetchCheckRuns(repo: string, sha: string, token: string, ctx: Ctx): Promise<CheckRun[] | undefined>;
+export {};

package/dist/evidence/ci.js

@@ -0,0 +1,61 @@
+const GH_API = 'https://api.github.com';
+const MAX_CHECK_RUN_PAGES = 5;
+async function ghGet(url, token, ctx) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 30_000);
+    try {
+        const res = await fetch(url, {
+            signal: controller.signal,
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: 'application/vnd.github+json',
+                'X-GitHub-Api-Version': '2022-11-28',
+            },
+        });
+        if (!res.ok) {
+            ctx.err(`evidence: github ${res.status} ${res.statusText} — ${url}`);
+            return undefined;
+        }
+        return await res.json();
+    }
+    catch (e) {
+        if (e instanceof Error && e.name === 'AbortError') {
+            ctx.err(`evidence: github request timed out — ${url}`);
+            return undefined;
+        }
+        throw e;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/** PR head SHA — the commit the PR's check-runs are attached to. */
+export async function fetchPrHeadSha(repo, pr, token, ctx) {
+    const data = (await ghGet(`${GH_API}/repos/${repo}/pulls/${pr}`, token, ctx));
+    return data?.head?.sha;
+}
+/** Check-runs on a commit — the consumer's own CI signal. */
+export async function fetchCheckRuns(repo, sha, token, ctx) {
+    const runs = [];
+    let page = 1;
+    while (page <= MAX_CHECK_RUN_PAGES) {
+        const data = (await ghGet(`${GH_API}/repos/${repo}/commits/${sha}/check-runs?per_page=100&page=${page}`, token, ctx));
+        if (data === undefined || !Array.isArray(data.check_runs))
+            return undefined;
+        for (const r of data.check_runs) {
+            const cr = r;
+            if (typeof cr.name !== 'string')
+                continue;
+            runs.push({
+                name: cr.name,
+                conclusion: cr.conclusion ?? undefined,
+                completed: cr.status === 'completed',
+                url: typeof cr.html_url === 'string' ? cr.html_url : undefined,
+            });
+        }
+        if (data.check_runs.length < 100)
+            break;
+        page++;
+    }
+    return runs;
+}

package/dist/evidence/link.d.ts

@@ -0,0 +1,35 @@
+import type { RepoIndex } from '../index/scan.js';
+import type { CheckRun } from './ci.js';
+export type EvidenceStatus = 'exercised' | 'corroborated' | 'not_exercised' | 'inconclusive';
+export interface Evidence {
+    status: EvidenceStatus;
+    detail: string;
+}
+/** Strip comment-hostile characters — check-run names are repo-controlled and reach the PR comment. */
+export declare function sanitizeForComment(s: string, max?: number): string;
+export declare function isTestFile(path: string): boolean;
+/**
+ * Every file transitively imported by a test file — a finding on a file in
+ * this set was plausibly exercised by the suite. Files outside it can carry
+ * no CI evidence regardless of check-run outcomes.
+ */
+export declare function testReachableFiles(index: RepoIndex): Set<string>;
+export interface TestRunSummary {
+    /** Test-ish check-runs that completed to a real conclusion. */
+    ran: CheckRun[];
+    passed: CheckRun[];
+    failed: CheckRun[];
+}
+/** Filter check-runs to test-ish lanes that actually ran, excluding Argus itself. */
+export declare function summarizeTestRuns(checkRuns: CheckRun[]): TestRunSummary;
+/**
+ * Conservative linkage: a finding is `exercised` only when its file is
+ * reachable from a test file AND every test check-run that ran passed. A
+ * failing test run on a reachable path corroborates the finding. Anything
+ * ambiguous is `not_exercised` — never a downgrade.
+ */
+export declare function linkFindings<T extends {
+    file?: string;
+}>(findings: T[], index: RepoIndex | undefined, checkRuns: CheckRun[] | undefined): (T & {
+    evidence: Evidence;
+})[];

package/dist/evidence/link.js

@@ -0,0 +1,90 @@
+/** Repo-relative paths that look like test files. */
+const TEST_FILE_RE = /(?:^|\/)(?:tests?|e2e|__tests__|__spec__)\/|\.(?:test|spec|e2e-spec)\.[jt]sx?$/i;
+/** Check-run names that look like test jobs (lint/build/status lanes don't count). */
+const TEST_RUN_RE = /\b(test|tests|spec|specs|e2e|smoke|jest|vitest|pytest|rspec|mocha|ava|unittest)\b/i;
+/** Argus's own check-runs are the reporter, not consumer CI evidence. */
+const ARGUS_RUN_RE = /argus/i;
+/** Check-run conclusions that mean "didn't actually run" — never evidence. */
+const DID_NOT_RUN = new Set(['neutral', 'skipped', 'cancelled', 'action_required', 'stale', 'startup_failure']);
+/** Strip comment-hostile characters — check-run names are repo-controlled and reach the PR comment. */
+export function sanitizeForComment(s, max = 80) {
+    return s.replace(/[|\r\n<>]/g, ' ').replace(/\s+/g, ' ').trim().slice(0, max);
+}
+export function isTestFile(path) {
+    return TEST_FILE_RE.test(path);
+}
+/**
+ * Every file transitively imported by a test file — a finding on a file in
+ * this set was plausibly exercised by the suite. Files outside it can carry
+ * no CI evidence regardless of check-run outcomes.
+ */
+export function testReachableFiles(index) {
+    const byPath = new Map(index.entries.map((e) => [e.path, e]));
+    const roots = index.entries.filter((e) => isTestFile(e.path)).map((e) => e.path);
+    const seen = new Set(roots);
+    const queue = [...roots];
+    while (queue.length > 0) {
+        const cur = queue.shift();
+        for (const dep of byPath.get(cur)?.imports ?? []) {
+            if (!seen.has(dep)) {
+                seen.add(dep);
+                queue.push(dep);
+            }
+        }
+    }
+    return seen;
+}
+/** Filter check-runs to test-ish lanes that actually ran, excluding Argus itself. */
+export function summarizeTestRuns(checkRuns) {
+    const ran = checkRuns.filter((r) => !ARGUS_RUN_RE.test(r.name) &&
+        TEST_RUN_RE.test(r.name) &&
+        r.completed &&
+        r.conclusion !== undefined &&
+        !DID_NOT_RUN.has(r.conclusion));
+    return {
+        ran,
+        passed: ran.filter((r) => r.conclusion === 'success'),
+        failed: ran.filter((r) => r.conclusion === 'failure' || r.conclusion === 'timed_out'),
+    };
+}
+/**
+ * Conservative linkage: a finding is `exercised` only when its file is
+ * reachable from a test file AND every test check-run that ran passed. A
+ * failing test run on a reachable path corroborates the finding. Anything
+ * ambiguous is `not_exercised` — never a downgrade.
+ */
+export function linkFindings(findings, index, checkRuns) {
+    const runs = checkRuns === undefined ? undefined : summarizeTestRuns(checkRuns);
+    const reachable = index === undefined ? undefined : testReachableFiles(index);
+    return findings.map((f) => {
+        let evidence;
+        if (runs === undefined) {
+            evidence = { status: 'inconclusive', detail: 'could not fetch CI check-runs' };
+        }
+        else if (reachable === undefined) {
+            evidence = { status: 'inconclusive', detail: 'no repo index — run `argus-reviewer index` first' };
+        }
+        else if (typeof f.file !== 'string' || !reachable.has(f.file)) {
+            evidence = {
+                status: 'not_exercised',
+                detail: 'no test file reaches this path — CI outcome carries no evidence here',
+            };
+        }
+        else if (runs.ran.length === 0) {
+            evidence = { status: 'inconclusive', detail: 'no test check-runs completed on this head' };
+        }
+        else if (runs.failed.length > 0) {
+            evidence = {
+                status: 'corroborated',
+                detail: `test check ${runs.failed.map((r) => `\`${sanitizeForComment(r.name)}\``).join(', ')} failed on this head`,
+            };
+        }
+        else {
+            evidence = {
+                status: 'exercised',
+                detail: `path is test-reachable; ${runs.passed.length} test check(s) passed`,
+            };
+        }
+        return { ...f, evidence };
+    });
+}

package/dist/executor/a0.d.ts

@@ -0,0 +1,29 @@
+import { type ExecFn } from '../detect.js';
+/**
+ * Agent Zero delegation — the thin seam that hands a natural-language task to
+ * an `a0` instance (`a0 headless -p`). The instance runs autonomously inside
+ * its own sandboxed desktop/browser; Argus gets back the agent's final answer.
+ *
+ * This is deliberately NOT a replay path: every delegation is a full-cost,
+ * non-deterministic agent run. Fingerprint replay stays local and ~free; A0 is
+ * for healing, second opinions on failures, and exploratory tasks that were
+ * never recorded.
+ */
+export declare const A0_DEFAULT_TIMEOUT_MS = 600000;
+export interface A0TaskOptions {
+    /** Instance base URL. Omit to let the `a0` CLI resolve it itself. */
+    host?: string | undefined;
+    /** Binary name/path — tests inject a stub. */
+    cli?: string;
+    timeoutMs?: number;
+    exec?: ExecFn;
+}
+export interface A0TaskResult {
+    ok: boolean;
+    /** The agent's final answer text, or the error output when !ok. */
+    output: string;
+}
+export declare function buildA0Args(prompt: string, host: string | undefined): string[];
+export declare function runA0Task(prompt: string, opts?: A0TaskOptions): Promise<A0TaskResult>;
+/** Prompt wrapper: bind the task to an app URL when one is known. */
+export declare function a0TaskPrompt(task: string, url: string | undefined): string;

package/dist/executor/a0.js

@@ -0,0 +1,38 @@
+import { defaultExec } from '../detect.js';
+/**
+ * Agent Zero delegation — the thin seam that hands a natural-language task to
+ * an `a0` instance (`a0 headless -p`). The instance runs autonomously inside
+ * its own sandboxed desktop/browser; Argus gets back the agent's final answer.
+ *
+ * This is deliberately NOT a replay path: every delegation is a full-cost,
+ * non-deterministic agent run. Fingerprint replay stays local and ~free; A0 is
+ * for healing, second opinions on failures, and exploratory tasks that were
+ * never recorded.
+ */
+export const A0_DEFAULT_TIMEOUT_MS = 600_000;
+export function buildA0Args(prompt, host) {
+    const args = ['headless', '--new-chat', '--output', 'text'];
+    if (host !== undefined && host !== '')
+        args.push('--host', host);
+    args.push('-p', prompt);
+    return args;
+}
+export async function runA0Task(prompt, opts = {}) {
+    const exec = opts.exec ?? defaultExec;
+    let res;
+    try {
+        res = await exec(opts.cli ?? 'a0', buildA0Args(prompt, opts.host), opts.timeoutMs ?? A0_DEFAULT_TIMEOUT_MS);
+    }
+    catch (e) {
+        // Spawn rejection (ENOENT when a0 is absent, hard timeout) must degrade
+        // to a failed delegation, not abort the calling command.
+        return { ok: false, output: e.message };
+    }
+    return { ok: res.code === 0, output: res.stdout.trim() || res.stderr.trim() };
+}
+/** Prompt wrapper: bind the task to an app URL when one is known. */
+export function a0TaskPrompt(task, url) {
+    return url === undefined || url === ''
+        ? task
+        : `Open ${url} in your browser, then do this task: ${task}`;
+}

package/dist/fsutil.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Atomic JSON write via tmp+rename — the one place the pattern lives.
+ * Callers: cache store, journal store, repo index.
+ */
+export declare function writeAtomicJson(path: string, value: unknown, replacer?: (key: string, v: unknown) => unknown): Promise<void>;

package/dist/fsutil.js

@@ -0,0 +1,12 @@
+import { mkdir, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/**
+ * Atomic JSON write via tmp+rename — the one place the pattern lives.
+ * Callers: cache store, journal store, repo index.
+ */
+export async function writeAtomicJson(path, value, replacer) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(value, replacer, 2)}\n`, 'utf8');
+    await rename(tmp, path);
+}

package/dist/index/context.d.ts

@@ -0,0 +1,17 @@
+import { type RepoIndex } from './scan.js';
+export declare const CONTEXT_PREFIX = "> context:";
+export interface ContextRequest {
+    /** Repo-relative path as reported by the PR files API. */
+    filename: string;
+    /** For renames, the pre-rename path — the index likely still holds it. */
+    previousFilename?: string | undefined;
+}
+/**
+ * Build per-file `> context:` blocks from an already-loaded index. Values are
+ * sanitized before they reach an LLM prompt — index data is repo-controlled
+ * text and must be treated as untrusted. Files absent from the index are
+ * silently omitted; renames fall back to the pre-rename path.
+ */
+export declare function buildReviewContext(index: RepoIndex | undefined, files: ContextRequest[]): Record<string, string>;
+/** Convenience wrapper: read argus.index.json then build the context map. */
+export declare function loadReviewContext(indexPath: string, files: ContextRequest[]): Promise<Record<string, string>>;

package/dist/index/context.js

@@ -0,0 +1,88 @@
+import { readIndex } from './scan.js';
+export const CONTEXT_PREFIX = '> context:';
+const MAX_LIST = 5;
+// ~500 estimated tokens per block (chars/4) — hard per-file cap
+const MAX_BLOCK_CHARS = 2000;
+const MAX_PURPOSE_CHARS = 80;
+// Paths render as `key=a, b` — a filename containing these could forge a
+// second key or break the single-line format.
+const UNSAFE_PATH_CHARS = /[,=>\n\r"`]/g;
+// Cheap secret heuristic: `key=…`-style assignments and long high-entropy
+// runs are redacted rather than echoed into an LLM prompt.
+const SECRETISH_RE = /(api[_-]?key|token|secret|passwd|password)\s*[:=]/i;
+const LONG_TOKEN_RE = /[A-Za-z0-9+/=_-]{40,}/;
+function normalize(path) {
+    return path.replace(/^\.\//, '').replace(/\\/g, '/');
+}
+/** Shortest paths first — closer imports are usually the most relevant. */
+function shortPaths(paths) {
+    const safe = paths
+        .map((p) => normalize(p).replace(UNSAFE_PATH_CHARS, ''))
+        .filter((p) => p !== '')
+        .sort((a, b) => a.length - b.length || a.localeCompare(b));
+    return safe.slice(0, MAX_LIST);
+}
+function sanitizePurpose(purpose) {
+    if (purpose === undefined)
+        return undefined;
+    const cleaned = purpose
+        .replace(/[^\x20-\x7E]/g, '')
+        .replace(/[`|]/g, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, MAX_PURPOSE_CHARS);
+    if (cleaned === '')
+        return undefined;
+    if (SECRETISH_RE.test(cleaned) || LONG_TOKEN_RE.test(cleaned))
+        return undefined;
+    return cleaned;
+}
+function blockFor(entry) {
+    const parts = [];
+    const purpose = sanitizePurpose(entry.purpose);
+    if (purpose !== undefined) {
+        parts.push(`purpose=${purpose}`);
+    }
+    if (entry.importedBy.length > 0) {
+        const list = shortPaths(entry.importedBy);
+        if (list.length > 0)
+            parts.push(`importedBy=${list.join(', ')}`);
+    }
+    if (entry.imports.length > 0) {
+        const list = shortPaths(entry.imports);
+        if (list.length > 0)
+            parts.push(`imports=${list.join(', ')}`);
+    }
+    if (parts.length === 0)
+        return undefined;
+    const block = `${CONTEXT_PREFIX} ${parts.join(' | ')}`;
+    return block.length > MAX_BLOCK_CHARS ? block.slice(0, MAX_BLOCK_CHARS) : block;
+}
+/**
+ * Build per-file `> context:` blocks from an already-loaded index. Values are
+ * sanitized before they reach an LLM prompt — index data is repo-controlled
+ * text and must be treated as untrusted. Files absent from the index are
+ * silently omitted; renames fall back to the pre-rename path.
+ */
+export function buildReviewContext(index, files) {
+    if (index === undefined)
+        return {};
+    const byPath = new Map(index.entries.map((e) => [normalize(e.path), e]));
+    const out = {};
+    for (const f of files) {
+        const entry = byPath.get(normalize(f.filename)) ??
+            (f.previousFilename !== undefined
+                ? byPath.get(normalize(f.previousFilename))
+                : undefined);
+        if (entry === undefined)
+            continue;
+        const block = blockFor(entry);
+        if (block !== undefined)
+            out[f.filename] = block;
+    }
+    return out;
+}
+/** Convenience wrapper: read argus.index.json then build the context map. */
+export async function loadReviewContext(indexPath, files) {
+    return buildReviewContext(await readIndex(indexPath), files);
+}

package/dist/index/diff.d.ts

@@ -0,0 +1 @@
+export declare function diffChangedFiles(cwd: string, base?: string): Promise<string[]>;

package/dist/index/diff.js

@@ -0,0 +1,33 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/**
+ * Changed files vs a base ref (PR diff) or the working tree when no base is
+ * given. Returns repo-relative paths. Any git failure resolves to an empty
+ * set — diff detection is an optimization, never a gate.
+ */
+const GIT_OPTS = { timeout: 30_000, maxBuffer: 8 * 1024 * 1024 };
+/** A git ref must look like a ref, not an option or arbitrary arg. */
+function safeBaseRef(base) {
+    return /^[A-Za-z0-9][A-Za-z0-9._/~-]*$/.test(base) ? base : undefined;
+}
+export async function diffChangedFiles(cwd, base) {
+    // A provided-but-invalid base disables diff detection rather than silently
+    // switching to working-tree semantics (which would over-invalidate in CI).
+    if (base !== undefined && safeBaseRef(base) === undefined)
+        return [];
+    const useBase = base !== undefined;
+    const args = useBase
+        ? ['diff', '--name-only', `${base}...HEAD`]
+        : ['status', '--porcelain', '--untracked-files=all'];
+    const { stdout } = await execFileAsync('git', args, { cwd, ...GIT_OPTS }).catch(() => ({ stdout: '' }));
+    return stdout
+        .split('\n')
+        .map((l) => {
+        const stripped = useBase ? l.trim() : l.replace(/^..\s+/, '').trim();
+        // Porcelain rename lines are `R  old -> new`; keep the new path.
+        const arrow = stripped.indexOf(' -> ');
+        return arrow === -1 ? stripped : stripped.slice(arrow + 4);
+    })
+        .filter((l) => l !== '' && !l.startsWith('R '));
+}

package/dist/index/invalidate.d.ts

@@ -0,0 +1,28 @@
+import { RepoIndex } from './scan.js';
+/**
+ * Diff-aware invalidation: a changed file that lies inside the app's source
+ * surface (under sourceGlobs) marks the flow caches stale — the UI the tests
+ * exercise may have shifted. Changes outside the surface (docs, CI config,
+ * the e2e suite itself) invalidate nothing.
+ *
+ * v1 is deliberately flow-agnostic: tests are vision-driven and don't import
+ * app source, so route→flow mapping isn't observable. The index powers the
+ * dependency-cone check when source files are reached indirectly.
+ */
+export interface InvalidationResult {
+    stale: boolean;
+    reason: string | undefined;
+    changedInSurface: string[];
+}
+/**
+ * Expand `changed` to include files that *depend on* changed files — walk the
+ * index's importedBy edges transitively. E.g. a change to a shared component
+ * pulls in every page that imports it.
+ */
+export declare function dependentCone(index: RepoIndex, changed: string[]): Set<string>;
+/**
+ * Decide whether the flow caches are stale. `sourceGlobs` names the app
+ * surface the tests exercise (e.g. `ui/src/**`). When unset, any change in
+ * the dependency cone of test/setup files also invalidates.
+ */
+export declare function invalidateForDiff(changed: string[], index: RepoIndex | undefined, sourceGlobs: string[] | undefined, testPaths: string[]): InvalidationResult;

package/dist/index/invalidate.js

@@ -0,0 +1,56 @@
+function globToRegex(glob) {
+    const re = glob
+        .split('**')
+        .map((seg) => seg.split('*').map((s) => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('[^/]*'))
+        .join('.*');
+    return new RegExp(`^${re}$`);
+}
+/**
+ * Expand `changed` to include files that *depend on* changed files — walk the
+ * index's importedBy edges transitively. E.g. a change to a shared component
+ * pulls in every page that imports it.
+ */
+export function dependentCone(index, changed) {
+    const edges = new Map(index.entries.map((e) => [e.path, e.importedBy]));
+    const out = new Set();
+    const queue = [...changed];
+    while (queue.length > 0) {
+        const cur = queue.pop();
+        if (cur === undefined || out.has(cur))
+            continue;
+        out.add(cur);
+        for (const dep of edges.get(cur) ?? [])
+            queue.push(dep);
+    }
+    return out;
+}
+/**
+ * Decide whether the flow caches are stale. `sourceGlobs` names the app
+ * surface the tests exercise (e.g. `ui/src/**`). When unset, any change in
+ * the dependency cone of test/setup files also invalidates.
+ */
+export function invalidateForDiff(changed, index, sourceGlobs, testPaths) {
+    if (changed.length === 0)
+        return { stale: false, reason: undefined, changedInSurface: [] };
+    const cone = index !== undefined ? dependentCone(index, changed) : new Set(changed);
+    const patterns = (sourceGlobs ?? []).map(globToRegex);
+    const inSurface = (p) => patterns.some((re) => re.test(p));
+    let hit;
+    if (patterns.length > 0) {
+        // A change lands on the app surface if the changed file itself matches,
+        // or something in its dependent cone (files that import it) matches.
+        hit = [...cone].filter(inSurface);
+    }
+    else {
+        const testSet = new Set(testPaths);
+        hit = [...cone].filter((p) => testSet.has(p));
+    }
+    if (hit.length === 0) {
+        return { stale: false, reason: undefined, changedInSurface: [] };
+    }
+    return {
+        stale: true,
+        reason: `diff touched app surface: ${hit.slice(0, 5).join(', ')}${hit.length > 5 ? ` +${hit.length - 5} more` : ''}`,
+        changedInSurface: hit,
+    };
+}

package/dist/index/scan.d.ts

@@ -0,0 +1,26 @@
+export declare const INDEX_SCHEMA_VERSION = 1;
+export interface IndexEntry {
+    /** Repo-relative path. */
+    path: string;
+    /** Best-effort purpose: first doc comment or leading export names. */
+    purpose?: string;
+    /** Repo-relative paths this file imports (TS/JS only). */
+    imports: string[];
+    /** Repo-relative paths that import this file — the transitive backstop for diff invalidation. */
+    importedBy: string[];
+    /** Nearest ancestor package.json version, when present. */
+    packageVersion?: string;
+    /** sha256 of file contents — cheap staleness signal. */
+    contentHash: string;
+}
+export interface RepoIndex {
+    schemaVersion: typeof INDEX_SCHEMA_VERSION;
+    generatedAt: string;
+    root: string;
+    entries: IndexEntry[];
+}
+/** Scan a repo into a RepoIndex. Never throws on individual file failures. */
+export declare function scanRepo(root: string): Promise<RepoIndex>;
+export declare function writeIndex(index: RepoIndex, outPath: string): Promise<void>;
+/** Load a previously written index; undefined when absent, oversized, or malformed. */
+export declare function readIndex(path: string): Promise<RepoIndex | undefined>;