tewip-ai 0.4.0

package/dist/outlets/views/developer.js

@@ -0,0 +1,59 @@
+// PR comment for developers: which failures in this run are likely caused by their change.
+import { errorShape, truncate } from '../../engine/signature.js';
+import { itemBlock, sourceNote } from '../view.js';
+/** Failures sharing a cause, before this many are read one by one, get a single line up front. */
+const SHARED_CAUSE_MIN = 3;
+/**
+ * Groups of failures with the same category and the same error: one outage or one changed
+ * component often fails many tests, and the reader should see that before twenty entries.
+ */
+export function sharedCauses(items) {
+    const groups = new Map();
+    // Undecided failures are left out: the agent does not know their cause, so it cannot say two share one.
+    for (const i of items.filter((x) => x.diagnosis.category !== 'UNKNOWN')) {
+        // The locator is part of the cause: two tests timing out on different elements are two problems.
+        const key = [i.diagnosis.category, errorShape(i.errorHead), i.locator ?? ''].join('|');
+        groups.set(key, [...(groups.get(key) ?? []), i]);
+    }
+    return [...groups.entries()]
+        .filter(([, xs]) => xs.length >= SHARED_CAUSE_MIN)
+        .map(([key, xs]) => ({ category: key.split('|')[0], error: xs[0].errorHead, items: xs }))
+        .sort((a, b) => b.items.length - a.items.length);
+}
+/**
+ * The order the PR comment shows failures in: likely caused by this change, then probably not,
+ * then unclear. The visible "#n" numbers follow it, and the hidden map that turns a person's
+ * "/triage ... #n" back into a test is written in the same order, so the two always agree.
+ */
+export function commentOrder(items) {
+    const by = (verdict) => items.filter((i) => i.relation.verdict === verdict);
+    return [...by('likely-this-change'), ...by('not-this-change'), ...by('unclear')];
+}
+export function prCommentView(items, runId, dataset) {
+    const commit = items[0]?.commit.slice(0, 8) || 'unknown commit';
+    const by = (verdict) => items.filter((i) => i.relation.verdict === verdict);
+    const likely = by('likely-this-change');
+    const not = by('not-this-change');
+    const unclear = by('unclear');
+    const numbers = new Map(commentOrder(items).map((i, n) => [i, n + 1]));
+    const section = (title, xs) => xs.length === 0 ? [] : [`### ${title} (${xs.length})`, '', ...xs.map((i) => itemBlock(i, [`Related to your change? ${i.relation.why}`], numbers.get(i))), ''];
+    // Nothing failed: say so plainly instead of an empty list under "0 failing test(s)".
+    if (items.length === 0) {
+        const markdown = ['## Tewip: all tests passed', '', 'Nothing to triage in this run.', '', sourceNote(dataset), ''].join('\n');
+        return { id: 'pr-comment', role: 'developer', title: `PR comment for run ${runId}`, scope: 'run', items, markdown };
+    }
+    const markdown = [
+        `## Tewip: ${items.length} failing test(s) on \`${commit}\``,
+        '',
+        `**${likely.length} likely caused by this change**, ${not.length} probably not, ${unclear.length} unclear.`,
+        '',
+        ...sharedCauses(items).slice(0, 3).map((g) => `> **${g.items.length} failures look like one cause** (${g.category}, same error${g.items[0].locator ? ' on the same element' : ''}): \`${truncate(g.error, 110)}\`. Fixing it once may clear them all.`),
+        ...(sharedCauses(items).length > 0 ? [''] : []),
+        sourceNote(dataset),
+        '',
+        ...section('Likely caused by this change', likely),
+        ...section('Probably not caused by this change', not),
+        ...section('Unclear', unclear),
+    ].join('\n');
+    return { id: 'pr-comment', role: 'developer', title: `PR comment for run ${runId}`, scope: 'run', items, markdown };
+}

package/dist/outlets/views/digest.js

@@ -0,0 +1,66 @@
+import { componentOf, isDefaultBranch } from '../items.js';
+import { clean, itemBlock, PLAIN_CATEGORY, sourceNote } from '../view.js';
+/** Degrading: the failure rate grew by at least this factor, with at least MIN_FAILURES in the later half. */
+const GROWTH = 1.5;
+const MIN_FAILURES = 3;
+/** Spec file inside a test id ("chromium > editor/blocks/image.spec.js > ..."), or its first segment. */
+const fileOfTestId = (testId) => testId.split(' > ').find((s) => /\.(spec|test)\.[jt]sx?$/.test(s)) ?? testId.split(' > ')[0];
+export function digestView(allItems, allSummaries, dataset) {
+    // Leads care about the main branch: pull-request runs fail on unfinished work by design.
+    const mainRuns = allSummaries.filter((s) => isDefaultBranch(s.branch ?? ''));
+    const mainOnly = mainRuns.length >= 2 && mainRuns.length < allSummaries.length;
+    const summaries = mainOnly ? mainRuns : allSummaries;
+    const items = mainOnly ? allItems.filter((i) => i.onDefaultBranch) : allItems;
+    const scope = mainOnly ? `${summaries.length} main-branch runs (pull-request runs left out)` : `all ${summaries.length} runs`;
+    const times = summaries.map((s) => s.startedAt).sort();
+    const middle = times[Math.floor(times.length / 2)] ?? '';
+    const half = (at) => (at < middle ? 0 : 1);
+    const period = (h) => (h === 0 ? `${times[0]?.slice(0, 10)} to ${middle.slice(0, 10)}` : `${middle.slice(0, 10)} to ${times.at(-1)?.slice(0, 10)}`);
+    const attempts = new Map();
+    for (const s of summaries) {
+        for (const [testId, n] of Object.entries(s.attempts)) {
+            const c = componentOf(fileOfTestId(testId));
+            const a = attempts.get(c) ?? [0, 0];
+            a[half(s.startedAt)] += n;
+            attempts.set(c, a);
+        }
+    }
+    const rows = [...attempts.entries()]
+        .map(([component, [a0, a1]]) => {
+        const xs = items.filter((i) => i.component === component);
+        const f0 = xs.filter((i) => half(i.timestamp) === 0).length;
+        const later = xs.filter((i) => half(i.timestamp) === 1);
+        return { component, r0: a0 ? f0 / a0 : 0, r1: a1 ? later.length / a1 : 0, f0, later };
+    })
+        .filter((r) => r.later.length >= MIN_FAILURES && r.r1 >= r.r0 * GROWTH)
+        .sort((a, b) => b.r1 - a.r1)
+        .slice(0, 6);
+    const shown = [];
+    const pct = (r) => `${(r * 100).toFixed(2)}%`;
+    const main = (xs) => {
+        const counts = new Map();
+        for (const i of xs)
+            counts.set(i.diagnosis.category, (counts.get(i.diagnosis.category) ?? 0) + 1);
+        return [...counts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
+    };
+    const markdown = [
+        '# Risk digest',
+        '',
+        `Comparing ${period(0)} with ${period(1)}, over ${scope}. ${rows.length === 0 ? 'No area got noticeably worse.' : `${rows.length} area(s) got worse.`}`,
+        '',
+        sourceNote(dataset),
+        '',
+        ...rows.flatMap((r) => {
+            const example = [...r.later].sort((a, b) => b.diagnosis.confidence - a.diagnosis.confidence)[0];
+            shown.push(example);
+            return [
+                `## ${clean(r.component)}: failure rate ${pct(r.r0)} → ${pct(r.r1)} (${r.later.length} failures, mostly ${PLAIN_CATEGORY[main(r.later)]})`,
+                `Next action: ask the "${clean(r.component)}" owners to review the new failures this week.`,
+                '',
+                itemBlock(example, ['(example)']),
+                '',
+            ];
+        }),
+    ].join('\n');
+    return { id: 'digest', role: 'lead', title: 'Risk digest', scope: 'window', items: shown, markdown };
+}

package/dist/outlets/views/infra.js

@@ -0,0 +1,49 @@
+// Infrastructure view for senior DevOps / SRE: environment failures of the run grouped by the
+// failing dependency, with retry recovery and one grouped alert instead of N pages.
+import { errorShape, truncate } from '../../engine/signature.js';
+import { clean, itemBlock, sourceNote } from '../view.js';
+/** What broke, as specific as the evidence allows: the network signal, else the error shape. */
+export function signatureOf(i) {
+    const net = i.diagnosis.evidence.find((e) => e.source === 'env-network')?.data;
+    if (net?.match)
+        return `${net.kind ?? 'network'}: ${truncate(net.match, 60)}`;
+    return truncate(errorShape(i.errorHead), 80) || 'environment failure (no error text)';
+}
+export function groupEnv(items) {
+    const groups = new Map();
+    for (const i of items.filter((x) => x.diagnosis.category === 'ENV'))
+        groups.set(signatureOf(i), [...(groups.get(signatureOf(i)) ?? []), i]);
+    return [...groups.entries()]
+        .map(([signature, xs]) => ({
+        signature,
+        items: xs,
+        recovered: xs.filter((x) => x.recoveredOnRetry).length,
+        hosts: [...new Set(xs.flatMap((x) => [x.errorHead, ...x.evidence].join(' ').match(/https?:\/\/[^\s/'"]+/g) ?? []))].slice(0, 3),
+    }))
+        .sort((a, b) => b.items.length - a.items.length);
+}
+export function infraView(items, runId, dataset) {
+    const groups = groupEnv(items);
+    const env = groups.flatMap((g) => g.items);
+    const alert = [
+        `[tewip] run ${runId}: ${env.length} test failure(s) caused by the test environment, not by code.`,
+        ...groups.map((g) => `- ${clean(g.signature)}: ${g.items.length} test(s), ${g.recovered} recovered on retry${g.hosts.length ? ` (hosts: ${g.hosts.join(', ')})` : ''}`),
+        'Test code was not changed. Next: re-run the affected tests once; if they fail again, investigate the dependency above.',
+    ];
+    const markdown = [
+        `# Infrastructure view: run ${runId}`,
+        '',
+        env.length === 0 ? 'No environment failures in this run.' : `${env.length} of ${items.length} failing test(s) are environment problems, in ${groups.length} group(s).`,
+        '',
+        sourceNote(dataset),
+        '',
+        ...(env.length === 0 ? [] : ['## One grouped alert (send this instead of one page per test)', '', '```text', ...alert, '```', '']),
+        ...groups.flatMap((g) => [
+            `## ${clean(g.signature)}: ${g.items.length} test(s), ${g.recovered} recovered on retry`,
+            '',
+            ...g.items.map((i) => itemBlock(i, [`Recovered on retry: ${i.recoveredOnRetry ? 'yes' : 'no'}`])),
+            '',
+        ]),
+    ].join('\n');
+    return { id: 'infra', role: 'devops', title: `Infrastructure view for run ${runId}`, scope: 'run', items: env, markdown };
+}

package/dist/outlets/views/quality.js

@@ -0,0 +1,108 @@
+// Engineering-quality view for senior / principal engineers, over the whole dataset window:
+// flakiness hotspots, recurring root-cause patterns and test-design debt ranked by CI cost.
+import { errorShape, truncate } from '../../engine/signature.js';
+import { clean, itemBlock, PLAIN_CATEGORY, sourceNote } from '../view.js';
+const minutes = (ms) => `${(ms / 60_000).toFixed(1)} CI min`;
+const groupBy = (xs, key) => {
+    const m = new Map();
+    for (const x of xs)
+        m.set(key(x), [...(m.get(key(x)) ?? []), x]);
+    return [...m.entries()];
+};
+const wasted = (xs) => xs.reduce((sum, i) => sum + i.wastedMs, 0);
+/** Separate runs a test must have flaked in before it is worth naming for quarantine. */
+const QUARANTINE_MIN_RUNS = 2;
+/** The shortest tail of a test's name that no other listed test shares, so rows stay telling apart. */
+function name(testId, others) {
+    const parts = testId.split(' > ');
+    for (let take = 1; take < parts.length; take++) {
+        const tail = parts.slice(-take).join(' > ');
+        if (others.filter((o) => o.testId.endsWith(tail)).length === 1)
+            return tail;
+    }
+    return testId;
+}
+export function qualityView(items, dataset) {
+    const shown = [];
+    const example = (xs) => {
+        const pick = [...xs].sort((a, b) => b.diagnosis.confidence - a.diagnosis.confidence)[0];
+        shown.push(pick);
+        return itemBlock(pick, ['(example)']);
+    };
+    const hotspots = groupBy(items.filter((i) => i.diagnosis.category === 'TIMING'), (i) => i.component)
+        .map(([component, xs]) => ({ component, xs, tests: new Set(xs.map((i) => i.testId)).size }))
+        .sort((a, b) => wasted(b.xs) - wasted(a.xs))
+        .slice(0, 8);
+    // The flaky tests that cost the most, named one by one: a hotspot per component tells a lead
+    // where to look, but an SDET needs the list of tests to quarantine this morning.
+    const quarantine = groupBy(items.filter((i) => i.diagnosis.category === 'TIMING'), (i) => i.testId)
+        .map(([testId, xs]) => ({ testId, xs, runs: new Set(xs.map((i) => i.runId)).size }))
+        .filter((q) => q.runs >= QUARANTINE_MIN_RUNS)
+        .sort((a, b) => wasted(b.xs) - wasted(a.xs))
+        .slice(0, 5);
+    const patterns = groupBy(items, (i) => `${i.diagnosis.category} ${truncate(errorShape(i.errorHead), 90)}`)
+        .filter(([, xs]) => xs.length >= 3)
+        .sort((a, b) => b[1].length - a[1].length)
+        .slice(0, 6);
+    const debt = groupBy(items.flatMap((i) => i.debt.map((d) => ({ d, i }))), (x) => `${x.d.kind} ${x.d.detail}`)
+        .map(([, xs]) => ({ debt: xs[0].d, xs: xs.map((x) => x.i) }))
+        .sort((a, b) => wasted(b.xs) - wasted(a.xs))
+        .slice(0, 10);
+    const markdown = [
+        '# Engineering quality: whole window',
+        '',
+        `${items.length} failing test case(s), ${minutes(wasted(items))} spent on failed attempts.`,
+        '',
+        sourceNote(dataset),
+        '',
+        '## Flakiness hotspots (TIMING), ranked by CI time lost',
+        '',
+        ...(hotspots.length === 0
+            ? ['None.', '']
+            : hotspots.flatMap((h) => [
+                `### ${h.component}: ${h.xs.length} flaky failure(s) in ${h.tests} test(s), ${minutes(wasted(h.xs))}`,
+                `Next action: give "${h.component}" an owner to stabilize its flakiest test first.`,
+                '',
+                example(h.xs),
+                '',
+            ])),
+        '## Quarantine candidates: flaky tests ranked by CI time lost',
+        '',
+        ...(quarantine.length === 0
+            ? [`None: no test was diagnosed TIMING in ${QUARANTINE_MIN_RUNS} or more separate runs.`, '']
+            : [
+                `| Test | File | Failed runs | CI time lost | Next action |`,
+                `|---|---|---:|---:|---|`,
+                ...quarantine.map((q) => {
+                    const first = q.xs[0];
+                    return `| ${clean(name(q.testId, quarantine))} | \`${first.file}\` | ${q.runs} | ${minutes(wasted(q.xs))} | Quarantine it (\`test.fixme\`) and open one issue to fix the race; it is costing this much every window |`;
+                }),
+                '',
+                'Quarantining stops a flaky test from blocking other people while the race is fixed. It is a decision for a person: the agent never edits a test to skip it.',
+                '',
+            ]),
+        '## Recurring root-cause patterns (3+ occurrences)',
+        '',
+        ...(patterns.length === 0
+            ? ['None.', '']
+            : patterns.flatMap(([key, xs]) => [
+                `### ${xs.length}x ${PLAIN_CATEGORY[xs[0].diagnosis.category]}: ${clean(key.slice(key.indexOf(' ') + 1)) || '(no error text)'}`,
+                `Next action: fix the shared cause once instead of triaging ${xs.length} failures one by one.`,
+                '',
+                example(xs),
+                '',
+            ])),
+        '## Test-design debt, ranked by CI time lost',
+        '',
+        ...(debt.length === 0
+            ? ['No fixed waits or brittle selectors found near the failing lines.', '']
+            : debt.flatMap((d) => [
+                `### ${d.debt.kind === 'hard-wait' ? 'Fixed wait' : 'Brittle selector'}: \`${clean(d.debt.detail)}\` (${d.xs.length} failure(s), ${minutes(wasted(d.xs))})`,
+                `Next action: ${d.debt.kind === 'hard-wait' ? 'replace it with a web-first assertion on the awaited element' : 'switch to a role, label or test-id locator'}.`,
+                '',
+                example(d.xs),
+                '',
+            ])),
+    ].join('\n');
+    return { id: 'quality', role: 'senior-engineer', title: 'Engineering quality view', scope: 'window', items: [...new Set(shown)], markdown };
+}

package/dist/outlets/views/release.js

@@ -0,0 +1,33 @@
+// Release-readiness report for UAT / business users: is the product broken, in plain words.
+// Only confident product problems block; everything else is explained as "not the product".
+import { ESCALATE_BELOW } from '../../engine/decide.js';
+import { clean, itemBlock, PLAIN_CATEGORY, sourceNote } from '../view.js';
+export function releaseView(items, runId, dataset) {
+    const blockers = items.filter((i) => i.diagnosis.category === 'REAL_BUG' && i.diagnosis.confidence >= ESCALATE_BELOW);
+    const review = items.filter((i) => (i.diagnosis.category === 'REAL_BUG' && i.diagnosis.confidence < ESCALATE_BELOW) || i.diagnosis.category === 'UNKNOWN');
+    const fine = items.filter((i) => !blockers.includes(i) && !review.includes(i));
+    const areas = [...new Set(blockers.map((i) => i.component))];
+    const verdict = blockers.length > 0
+        ? `**NOT READY**: ${blockers.length} product problem(s) found, in ${areas.map((a) => `"${a}"`).join(', ')}.`
+        : review.length > 0
+            ? `**WAIT**: no confirmed product problem, but ${review.length} failure(s) are still being looked at.`
+            : `**READY from a product point of view**: none of the ${items.length} failing test(s) is a product problem.`;
+    const plain = (i) => review.includes(i)
+        ? `In plain words: not understood yet; someone is checking whether "${clean(i.title)}" is a product problem.`
+        : i.diagnosis.category === 'REAL_BUG'
+            ? `In plain words: in the "${i.component}" area, "${clean(i.title)}" did not work as expected.`
+            : `In plain words: ${PLAIN_CATEGORY[i.diagnosis.category]}, not a problem in the product itself.`;
+    const section = (title, xs) => (xs.length === 0 ? [] : [`## ${title} (${xs.length})`, '', ...xs.map((i) => itemBlock(i, [plain(i)])), '']);
+    const markdown = [
+        `# Release readiness: run ${runId}`,
+        '',
+        verdict,
+        '',
+        sourceNote(dataset),
+        '',
+        ...section('Product problems (block the release)', blockers),
+        ...section('Still being looked at', review),
+        ...section('Not product problems (do not block)', fine),
+    ].join('\n');
+    return { id: 'release', role: 'business', title: `Release readiness for run ${runId}`, scope: 'run', items, markdown };
+}

package/dist/outlets/views/sdet.js

@@ -0,0 +1,29 @@
+import { itemBlock, sourceNote } from '../view.js';
+const ORDER = [
+    { kind: 'escalate', title: 'Needs a human decision' },
+    { kind: 'fix-locator', title: 'Fix a locator (UI changed)' },
+    { kind: 'fix-wait', title: 'Replace a fixed wait' },
+    { kind: 'stabilize-test', title: 'Stabilize a flaky test' },
+    { kind: 'fix-precondition', title: 'Fix test data / setup' },
+    { kind: 'file-bug', title: 'Product bugs: file and move on' },
+    { kind: 'rerun-and-notify', title: 'Environment: re-run, do not touch the test' },
+];
+export function sdetBoardView(items, runId, dataset) {
+    const counts = ORDER.map(({ kind, title }) => ({ title, n: items.filter((i) => i.action.kind === kind).length })).filter((c) => c.n > 0);
+    const agentCan = items.filter((i) => i.action.autonomous).length;
+    const markdown = [
+        `# Triage board: run ${runId}`,
+        '',
+        `${items.length} failing test(s). ${agentCan} can be handled by the agent without a human (once each action is automated); ${items.length - agentCan} need a person.`,
+        '',
+        sourceNote(dataset),
+        '',
+        ...counts.map((c) => `- ${c.title}: **${c.n}**`),
+        '',
+        ...ORDER.flatMap(({ kind, title }) => {
+            const xs = items.filter((i) => i.action.kind === kind);
+            return xs.length === 0 ? [] : [`## ${title} (${xs.length})`, '', ...xs.map((i) => itemBlock(i, [`Why this action: ${i.action.reason}`])), ''];
+        }),
+    ].join('\n');
+    return { id: 'sdet-board', role: 'sdet', title: `SDET triage board for run ${runId}`, scope: 'run', items, markdown };
+}

package/dist/reporters/run-context.js

@@ -0,0 +1,20 @@
+/**
+ * Resolves the run id once per `playwright test` invocation. The value is stored in
+ * process.env so the config (for the per-run outputDir), the reporter and worker
+ * processes (which inherit env) all agree on it.
+ */
+export function resolveRunId() {
+    const existing = process.env.TRIAGE_RUN_ID;
+    if (existing)
+        return existing;
+    const runId = process.env.CI_RUN_ID || `run-${new Date().toISOString().replace(/[-:.]/g, '')}`;
+    process.env.TRIAGE_RUN_ID = runId;
+    return runId;
+}
+export function resolveGitSha() {
+    return process.env.GIT_SHA || process.env.GITHUB_SHA || '';
+}
+/** On pull requests GitHub sets GITHUB_HEAD_REF (the PR branch); on pushes GITHUB_REF_NAME. */
+export function resolveBranch() {
+    return process.env.GIT_BRANCH || process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME || '';
+}

package/dist/reporters/store.js

@@ -0,0 +1,46 @@
+// JSONL persistence shared by the reporter, the history script and future layers.
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+export const PROJECT_ROOT = join(import.meta.dirname, '..');
+export const DATA_DIR = join(PROJECT_ROOT, 'data');
+/** Where the reporter collects failures. TRIAGE_DATA_DIR redirects it (e.g. the drift lab uses data/lab). */
+const COLLECT_DIR = process.env.TRIAGE_DATA_DIR ? resolve(PROJECT_ROOT, process.env.TRIAGE_DATA_DIR) : DATA_DIR;
+export const TRIAGE_FILE = join(COLLECT_DIR, 'triage.jsonl');
+export const RUNS_FILE = join(COLLECT_DIR, 'runs.jsonl');
+export function appendJsonl(file, rows) {
+    if (rows.length === 0)
+        return;
+    mkdirSync(dirname(file), { recursive: true });
+    appendFileSync(file, rows.map((row) => JSON.stringify(row)).join('\n') + '\n', 'utf8');
+}
+/** Reads a JSONL file; missing file yields []. Malformed lines are skipped with a warning. */
+export function readJsonl(file) {
+    if (!existsSync(file))
+        return [];
+    const rows = [];
+    readFileSync(file, 'utf8')
+        .split(/\r?\n/)
+        .forEach((line, i) => {
+        if (!line.trim())
+            return;
+        try {
+            rows.push(JSON.parse(line));
+        }
+        catch {
+            console.warn(`[triage] skipping malformed line ${i + 1} in ${file}`);
+        }
+    });
+    return rows;
+}
+export const readTriageRecords = (file = TRIAGE_FILE) => readJsonl(file);
+export const readRunSummaries = (file = RUNS_FILE) => readJsonl(file);
+/**
+ * The triage/runs files of a dataset directory. The default dataset is data/ (what the
+ * reporter collects); imported datasets live elsewhere, e.g. data/real/<source>/.
+ */
+export function datasetFiles(dir) {
+    if (!dir)
+        return { dir: DATA_DIR, triage: TRIAGE_FILE, runs: RUNS_FILE };
+    const abs = isAbsolute(dir) ? dir : join(PROJECT_ROOT, dir);
+    return { dir: abs, triage: join(abs, 'triage.jsonl'), runs: join(abs, 'runs.jsonl') };
+}

package/dist/reporters/triage-reporter.js

@@ -0,0 +1,101 @@
+import { relative, sep } from 'node:path';
+import { stripVTControlCharacters } from 'node:util';
+import { HistoryIndex } from '../engine/history.js';
+import { llmFromEnv } from '../engine/llm/client.js';
+import { diagnosePipeline } from '../engine/pipeline.js';
+import { resolveBranch, resolveGitSha, resolveRunId } from './run-context.js';
+import { appendJsonl, PROJECT_ROOT, readRunSummaries, readTriageRecords, RUNS_FILE, TRIAGE_FILE } from './store.js';
+import { SCHEMA_VERSION } from './types.js';
+const COLLECTED_ATTACHMENTS = new Set(['trace', 'screenshot', 'error-context']);
+const projectPath = (p) => relative(PROJECT_ROOT, p).split(sep).join('/');
+export function testIdOf(test) {
+    return test.titlePath().filter(Boolean).join(' > ');
+}
+/**
+ * Collects failed / timed-out attempts and appends them to data/triage.jsonl when the
+ * run ends. Also appends one run summary line to data/runs.jsonl so failure rates can
+ * be computed later.
+ */
+export default class TriageReporter {
+    runId = resolveRunId();
+    gitSha = resolveGitSha();
+    startedAt = new Date().toISOString();
+    records = [];
+    attempts = {};
+    onBegin() {
+        this.startedAt = new Date().toISOString();
+    }
+    onTestEnd(test, result) {
+        const testId = testIdOf(test);
+        if (result.status !== 'skipped' && result.status !== 'interrupted') {
+            this.attempts[testId] = (this.attempts[testId] ?? 0) + 1;
+        }
+        if (result.status !== 'failed' && result.status !== 'timedOut')
+            return;
+        this.records.push(this.toRecord(test, result, testId));
+    }
+    async onEnd(result) {
+        const summary = {
+            schemaVersion: SCHEMA_VERSION,
+            runId: this.runId,
+            gitSha: this.gitSha,
+            branch: resolveBranch(),
+            startedAt: this.startedAt,
+            finishedAt: new Date().toISOString(),
+            status: result.status,
+            attempts: this.attempts,
+        };
+        const records = await this.enrich(this.records, summary);
+        appendJsonl(TRIAGE_FILE, records);
+        appendJsonl(RUNS_FILE, [summary]);
+        const by = (source) => records.filter((r) => r.diagnosis?.source === source && r.diagnosis.category !== 'UNKNOWN').length;
+        const unknown = records.filter((r) => !r.diagnosis || r.diagnosis.category === 'UNKNOWN').length;
+        console.log(`[triage] ${records.length} failure record(s) appended to ${projectPath(TRIAGE_FILE)} (runId=${this.runId}); ` +
+            `rules classified ${by('rules')}, LLM ${by('llm')}, ${unknown} UNKNOWN`);
+    }
+    /**
+     * Diagnosis step: runs after the run finishes and before records are persisted. Rules
+     * decide first; failures they leave UNKNOWN go to the LLM layer when OPENAI_API_KEY is set
+     * (TRIAGE_LLM=off disables it). A failing engine must never cost us the collected data.
+     */
+    async enrich(records, summary) {
+        if (records.length === 0)
+            return records;
+        try {
+            const index = new HistoryIndex([...readTriageRecords(), ...records], [...readRunSummaries(), summary]);
+            const diagnoses = await diagnosePipeline(records, index, llmFromEnv());
+            return records.map((record, i) => ({ ...record, diagnosis: diagnoses[i] }));
+        }
+        catch (error) {
+            console.warn(`[triage] rule engine failed, saving records without a diagnosis: ${String(error)}`);
+            return records;
+        }
+    }
+    printsToStdio() {
+        return false;
+    }
+    toRecord(test, result, testId) {
+        const error = result.error ?? result.errors[0];
+        const attachments = result.attachments
+            .filter((a) => COLLECTED_ATTACHMENTS.has(a.name) && a.path)
+            .map((a) => ({
+            name: a.name,
+            contentType: a.contentType,
+            path: projectPath(a.path),
+        }));
+        return {
+            schemaVersion: SCHEMA_VERSION,
+            testId,
+            file: projectPath(test.location.file),
+            status: result.status,
+            errorMessage: stripVTControlCharacters(error?.message ?? ''),
+            errorStack: stripVTControlCharacters(error?.stack ?? ''),
+            duration: result.duration,
+            retry: result.retry,
+            attachments,
+            runId: this.runId,
+            gitSha: this.gitSha,
+            timestamp: new Date(result.startTime.getTime() + result.duration).toISOString(),
+        };
+    }
+}

package/dist/reporters/types.js

@@ -0,0 +1,4 @@
+/** Bump when the on-disk record shape changes incompatibly. */
+export const SCHEMA_VERSION = 1;
+/** The fixed root-cause taxonomy from ROADMAP.md. No layer may add to it. */
+export const ROOT_CAUSES = ['REAL_BUG', 'LOCATOR_DRIFT', 'TIMING', 'ENV', 'TEST_DATA'];

package/dist/scripts/explain.js

@@ -0,0 +1,58 @@
+// Explains a test report on your own machine, no CI needed: run your tests, then
+//   node scripts/explain.ts <report>
+// where <report> is a JUnit XML or TRX file, a directory of them, or a Playwright blob report
+// directory. Works for any stack the importer reads (see QUICKSTART.md). Each run is kept in a
+// .tewip folder in the directory you run it from (your project, not the installed tool), so later
+// runs judge failures against their history, as CI does.
+// Options: --name <project> keeps a separate history per project (default: the report's folder).
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { loadCorrections } from '../engine/corrections.js';
+import { HistoryIndex } from '../engine/history.js';
+import { importBlobReportDir } from '../engine/import/blob.js';
+import { importJunit } from '../engine/import/junit.js';
+import { llmFromEnv } from '../engine/llm/client.js';
+import { usageLine } from '../engine/llm/usage.js';
+import { buildItems } from '../outlets/items.js';
+import { sdetBoardView } from '../outlets/views/sdet.js';
+import { appendJsonl, datasetFiles, readRunSummaries, readTriageRecords } from '../reporters/store.js';
+const arg = (name) => {
+    const i = process.argv.indexOf(`--${name}`);
+    return i > 0 ? process.argv[i + 1] : undefined;
+};
+/** A Playwright blob report is a directory of report-*.zip files; anything else is JUnit or TRX. */
+function isBlobDir(path) {
+    return statSync(path).isDirectory() && readdirSync(path).some((f) => /^report.*\.zip$/.test(f));
+}
+async function main() {
+    const target = process.argv[2];
+    if (!target || target.startsWith('--') || !existsSync(target)) {
+        console.error('usage: node scripts/explain.ts <report.xml | report.trx | reports-dir | blob-report-dir> [--name project]');
+        process.exitCode = 1;
+        return;
+    }
+    const path = resolve(target);
+    const name = (arg('name') ?? basename(statSync(path).isDirectory() ? path : dirname(path))).replace(/[^\w.-]+/g, '-');
+    const historyDir = join(process.cwd(), '.tewip', 'history', name);
+    const history = datasetFiles(historyDir);
+    const runId = `local-${new Date().toISOString().replace(/[-:.TZ]/g, '').slice(0, 14)}`;
+    const meta = { runId, gitSha: '', workspace: process.cwd() };
+    const imported = isBlobDir(path) ? importBlobReportDir(path, meta, join(historyDir, 'files')) : importJunit(path, meta);
+    const pastRecords = readTriageRecords(history.triage);
+    const pastRuns = readRunSummaries(history.runs);
+    const index = new HistoryIndex([...pastRecords, ...imported.records], [...pastRuns, imported.summary]);
+    const items = await buildItems(imported.records, index, { dataset: `local: ${name}`, llm: llmFromEnv(), corrections: loadCorrections(historyDir) });
+    const tests = Object.keys(imported.summary.attempts).length;
+    if (items.length === 0)
+        console.log(`All ${tests} test(s) passed. Nothing to explain.`);
+    else
+        console.log(sdetBoardView(items, runId, `local: ${name}`).markdown);
+    // Keep this run as history for the next one, with its diagnoses.
+    const diagnosed = imported.records.map((r) => ({ ...r, diagnosis: items.find((i) => i.testId === r.testId)?.diagnosis }));
+    appendJsonl(history.triage, diagnosed);
+    appendJsonl(history.runs, [imported.summary]);
+    const runs = pastRuns.length + 1;
+    console.log(`\n${usageLine()}`);
+    console.log(`History: ${runs} run(s) of "${name}" kept in ${historyDir}.${runs === 1 ? ' A test\'s first failure often stays undecided; later runs are judged against this one. Add .tewip/ to your .gitignore.' : ''}`);
+}
+await main();