tewip-ai 0.36.0 → 0.38.0

package/README.md

@@ -138,17 +138,19 @@ and you always get the current version.
 
 ### The editor extension (VS Code, Cursor, Windsurf, VSCodium)
 
-Download **[tewip-0.5.0.vsix](https://github.com/hmamut39/tewip/releases/tag/vscode-0.5.0)**, then in the
-editor press `Ctrl+Shift+P` and run **Extensions: Install from VSIX…**. It needs the command line:
-`npm install -g tewip-ai`.
+**Open the Extensions pane and search for "Tewip".** It is in both registries, so that works in
+VS Code, Cursor, Windsurf, VSCodium, Gitpod and Eclipse Theia:
 
-Press `Ctrl+Shift+P` and type "Tewip" for: *Explain a test report…*, *Why did CI fail on this
-branch?*, *Risk review of this change*, *Which flaky tests to quarantine*, *Check secrets and
-dependencies*, and *What our corrections add up to*. The editor's AI assistant also picks Tewip up
-as an MCP server with nothing to configure.
+- **VS Code** — [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=hmamut39.tewip)
+- **Cursor, Windsurf, VSCodium, Gitpod, Theia** — [Open VSX](https://open-vsx.org/extension/hmamut39/tewip)
 
-It is not in the Visual Studio Marketplace: publishing there now requires an Azure subscription,
-which means a credit card for a free extension. The file above installs exactly the same thing.
+Or install the `.vsix` attached to any [release](https://github.com/hmamut39/tewip/releases) with
+**Extensions: Install from VSIX…**. Either way it needs the command line: `npm install -g tewip-ai`.
+
+Press `Ctrl+Shift+P` and type "Tewip" for: *Is this work done?*, *Can everybody use this?*, *Could
+these tests ever fail?*, *Would the tests catch a bug in this file?*, *Which tests could notice this
+change?*, *What will this migration do to a live database?*, *Why did CI fail on this branch?*, and
+more. The editor's AI assistant also picks Tewip up as an MCP server with nothing to configure.
 
 ### 2. From any AI assistant, through MCP (the whole IT team)
 
@@ -574,6 +576,89 @@ With `--json` the verdict is **sealed**: editing `not-ready` to `ready` in the f
 fail, so a verdict that travels into a ticket or a release note can be checked rather than trusted. It is
 also an MCP tool, so an agent can ask whether its own work is done before saying that it is.
 
+## Is this change slower? (Phase 30, new)
+
+```bash
+tewip perf summary.json --record            # on main: add this run to the baseline
+tewip perf summary.json --strict            # on a branch: fail the build on a real regression
+```
+
+Tewip has imported k6 results for a while and never had an opinion about them. Now it answers the
+question every team asks before a release.
+
+**The hard part is not the arithmetic.** "p95 went from 180ms to 210ms, +16%" is four lines of code
+and worthless, because nobody knows whether 16% is the change or the laptop. Here are **four real k6
+runs of code that did not change**:
+
+```
+run 1   p95 = 60.9ms
+run 2   p95 = 60.8ms
+run 3   p95 = 62.8ms
+run 4   p95 = 61.4ms
+```
+
+A 3% spread from nothing at all. A tool that calls that a regression gets switched off.
+
+So Tewip answers **two questions separately**, because they fail separately:
+
+| | |
+|---|---|
+| **Did your own thresholds hold?** | You already wrote what "fast enough" means in your k6 script. Tewip reads the result instead of asking you to write a budget twice. |
+| **Is it slower than it was?** | Answered **only** from three or more recorded baselines. Below that: *cannot say*. |
+
+Given those three real baselines, a fourth identical run at 61.4ms is **not** called a regression —
+and a genuine one is:
+
+```
+- `http_req_duration` p95 282.5ms — **slower**
+  - baseline 60.8ms–62.8ms over 3 runs, middle 60.9ms
+  - 282.5ms is outside everything 3 baseline runs produced (60.8-62.8ms) by more than
+    their own spread, so the runs cannot explain it. That is +364% on the middle run.
+```
+
+**Recording is deliberately not automatic.** A tool that files every run into the baseline ratchets:
+today's regression becomes tomorrow's normal, the comparison keeps saying "within range", and a
+service triples in latency over a quarter without one report ever being wrong. `--record` on main,
+compare everywhere else.
+
+**It never predicts a duration, a capacity, or what a user will feel.** It cannot see your production
+hardware, your real data volume or your real traffic, and every report says so.
+
+### Lighthouse too (Phase 31, new)
+
+```bash
+tewip perf lighthouse-report.json --record
+```
+
+k6 measures what your server does under load. Lighthouse measures what **one page load costs in a real
+browser** — Largest Contentful Paint, layout shift, blocking time — which is nearer to what a person
+actually waits for. `tewip perf` takes either and works out which it was given.
+
+Lighthouse needs the same discipline *more*, not less. **Four real Lighthouse runs of an unchanged
+page gave LCP of 922, 912, 936 and 916ms.** Same rule: three baselines, outside the range by more than
+its own width.
+
+**And Tewip does not invent a verdict.** "Is 2112ms bad?" has a published answer and it is Google's:
+Lighthouse scores every metric on its own curve. Tewip reads that score rather than hard-coding
+thresholds it remembered — which matters, because on the real slowed run FCP and LCP had the *identical*
+value of 2112ms and Lighthouse rates them differently:
+
+```
+- good — `largest-contentful-paint`: 2112ms
+- needs improvement — `first-contentful-paint`: 2112ms
+- **poor** — `server-response-time`: 611ms
+```
+
+One remembered threshold applied to both would have been wrong.
+
+It also surfaces the **ten accessibility audits Lighthouse refuses to score** — logical tab order, focus
+traps, whether visual order follows the DOM. Those are neither failures nor passes, and a page with no
+failures and ten unanswered manual checks is not a page that passed.
+
+One more thing it refuses: if your summary came from `--new-machine-readable-summary`, that export
+records **no threshold results at all** — the word appears in it only inside a copy of your script.
+Tewip says "this export cannot tell me" rather than "nothing was breached".
+
 ## Can everybody use it? (Phase 28, new)
 
 ```bash

package/dist/cli/help.js

@@ -118,6 +118,18 @@ Usage:
                                     is what was asked for covered. Answers ready, not ready, or cannot
                                     say - and cannot say is never rounded up to ready. --json writes a
                                     sealed verdict that can be checked later. No model, no cost.
+  tewip perf <k6-summary.json | lighthouse.json> [--record] [--label checkout] [--strict] [--out perf.md]
+                                    Is this change slower, and does it matter? Reads a k6 run (what
+                                    the server does under load) or a Lighthouse report (what one
+                                    page load costs in a browser), and answers two questions apart:
+                                    is anything in a bad state now - from the thresholds you wrote,
+                                    or from Lighthouse's own scoring, never a budget Tewip invented
+                                    - and is this slower than it was. The second only from repeated
+                                    baselines: with fewer than three it says cannot say, because one
+                                    run against one cannot tell a regression from a busy machine.
+                                    --record adds a run to the baseline, and is deliberately not
+                                    automatic: a regression recorded by accident becomes next week's
+                                    normal. It never predicts a duration or a capacity. No cost.
   tewip access [<file or directory>] [--report axe.json] [--strict] [--out access.md]
                                     Can everybody use this? Reads your markup and names the barriers
                                     that reading alone can prove - a picture with no alt text, a field

package/dist/cli/verbs-prove.js

@@ -20,6 +20,24 @@ export async function proveVerb(verb, args) {
             });
             return true;
         }
+        case 'perf': {
+            const { runPerf } = await import('../engine/perf/perf-command.js');
+            const paths = args.filter((a, i) => !a.startsWith('--') && !['--out', '--label'].includes(args[i - 1] ?? ''));
+            if (paths.length === 0) {
+                console.error('tewip perf needs the JSON from a k6 run: tewip perf summary.json [--record] [--label checkout]');
+                process.exitCode = 1;
+                return true;
+            }
+            runPerf({
+                root: process.cwd(),
+                summary: paths[0],
+                label: flag(args, 'label'),
+                record: args.includes('--record'),
+                out: flag(args, 'out'),
+                gate: args.includes('--strict'),
+            });
+            return true;
+        }
         case 'access': {
             const { runAccess } = await import('../engine/access/access-command.js');
             const paths = args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--out' && args[i - 1] !== '--report');

package/dist/engine/perf/compare.js

@@ -0,0 +1,97 @@
+// Phase 30: deciding whether a run is actually slower.
+//
+// This is the whole phase. Reporting "p95 went from 180ms to 210ms, +16%" is trivial and worthless:
+// nobody knows whether 16% is the change or the laptop. Performance numbers move between identical
+// runs - a background process, a warm cache, a noisy CI runner - and a tool that calls every
+// movement a regression gets muted within a week, which is the same failure mode as the
+// accessibility scanners in Phase 28.
+//
+// So Tewip refuses unless it can tell the difference, and it can only tell the difference from
+// **repeated baseline runs**. One run against one run says nothing, however large the gap looks,
+// and Tewip says that rather than guessing. With three or more baselines there is an observed
+// spread to compare against, and a change outside the baseline's own range by more than the width
+// of that range is a change the runs themselves cannot explain.
+//
+// A k6 summary carries no raw samples - only avg, min, med, p90, p95, max - so a proper confidence
+// interval is not available, and nothing here pretends otherwise. The test is deliberately crude
+// and deliberately conservative: it is better to say "cannot say" to a real 4% regression than to
+// cry wolf at noise, because the second one costs the team the tool.
+import { MAIN_TIMING } from './k6.js';
+/** The fewest baseline runs from which run-to-run noise can be estimated at all. */
+export const ENOUGH_BASELINES = 3;
+/**
+ * A change smaller than this is not called even when the baselines are unusually tight, because a
+ * handful of identical runs can make the observed spread implausibly small and a 1% move is not
+ * worth a person's afternoon.
+ */
+const SMALLEST_CHANGE = 0.05;
+const median = (values) => {
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+};
+const round = (n) => Math.round(n * 10) / 10;
+/**
+ * Compares one metric of a candidate run against the same metric in the baseline runs.
+ *
+ * `baseline` is every stored value for the metric, oldest first. It is not averaged into a single
+ * number, because its spread is the only evidence available about what noise looks like here.
+ */
+export function compareMetric(metric, now, baseline) {
+    const runs = baseline.length;
+    const before = runs > 0 ? median(baseline) : 0;
+    const low = runs > 0 ? Math.min(...baseline) : 0;
+    const high = runs > 0 ? Math.max(...baseline) : 0;
+    const spread = high - low;
+    const margin = Math.max(spread, before * SMALLEST_CHANGE);
+    const base = {
+        metric,
+        now: round(now),
+        before: round(before),
+        baselineRuns: runs,
+        baselineLow: round(low),
+        baselineHigh: round(high),
+        margin: round(margin),
+    };
+    if (runs < ENOUGH_BASELINES) {
+        return {
+            ...base,
+            direction: 'cannot-say',
+            why: runs === 0
+                ? 'there is nothing to compare this against yet'
+                : `${runs} baseline ${runs === 1 ? 'run is' : 'runs are'} not enough to know what noise looks like here; ` +
+                    `Tewip needs ${ENOUGH_BASELINES}. Two runs can differ by this much for reasons that have nothing to do with the code.`,
+        };
+    }
+    const percent = before > 0 ? Math.round(((now - before) / before) * 100) : 0;
+    if (now > high + margin) {
+        return {
+            ...base,
+            direction: 'slower',
+            why: `${round(now)}ms is outside everything ${runs} baseline runs produced (${round(low)}-${round(high)}ms) ` +
+                `by more than their own spread, so the runs cannot explain it. That is ${percent > 0 ? '+' : ''}${percent}% on the middle run.`,
+        };
+    }
+    if (now < low - margin) {
+        return {
+            ...base,
+            direction: 'faster',
+            why: `${round(now)}ms is below everything ${runs} baseline runs produced (${round(low)}-${round(high)}ms) by more than their own spread.`,
+        };
+    }
+    return {
+        ...base,
+        direction: 'cannot-say',
+        why: `${round(now)}ms is within what ${runs} baseline runs already did on their own (${round(low)}-${round(high)}ms, ` +
+            `allowing ${round(margin)}ms either side). A difference the baseline runs produce by themselves is not evidence about this change.`,
+    };
+}
+/** Enough requests for a percentile to mean anything. Below this, p95 is three data points. */
+export const ENOUGH_REQUESTS = 100;
+/** Timings worth comparing, in the order a person would want them. */
+export function timingsToCompare(run) {
+    const named = Object.keys(run.timings).filter((m) => !m.includes('{'));
+    const first = named.filter((m) => m === MAIN_TIMING);
+    const rest = named.filter((m) => m !== MAIN_TIMING && /duration|waiting|blocked/.test(m)).sort();
+    return [...first, ...rest];
+}

package/dist/engine/perf/history.js

@@ -0,0 +1,89 @@
+// Phase 30: the stored baseline.
+//
+// Recording is deliberately **not** automatic, and that is the most important decision in this
+// file. A tool that files every run it sees into the baseline ratchets: today's regression becomes
+// tomorrow's normal, the comparison keeps saying "within range", and a service gets three times
+// slower over a quarter without one report ever being wrong. Tewip records only when asked, so the
+// intended use is `--record` on the main branch and a plain comparison everywhere else.
+//
+// The file is JSON Lines so that a run can be appended without reading or rewriting what is already
+// there, and so a person can read it or delete a bad line with an editor.
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const file = (root) => join(root, '.tewip', 'perf', 'runs.jsonl');
+/** Everything recorded for this label, oldest first. */
+export function storedRuns(root, label) {
+    const path = file(root);
+    if (!existsSync(path))
+        return [];
+    const out = [];
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            // A line Tewip cannot read is skipped rather than throwing: one bad line written by a crashed
+            // run must not make the whole baseline unreadable.
+            // Either shape counts: `metrics` is what is written now, `timings` what older versions wrote.
+            if (parsed && typeof parsed.at === 'string' && parsed.label === label && (parsed.metrics ?? parsed.timings))
+                out.push(parsed);
+        }
+        catch {
+            continue;
+        }
+    }
+    return out;
+}
+export function recordRun(root, label, run, gitSha) {
+    const stored = {
+        at: run.at,
+        label,
+        ...(gitSha ? { gitSha } : {}),
+        source: run.source,
+        metrics: Object.fromEntries(Object.entries(run.metrics).map(([m, v]) => [m, v.value])),
+        requests: run.volume.n,
+    };
+    const path = file(root);
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, `${JSON.stringify(stored)}\n`, 'utf8');
+    return stored;
+}
+/**
+ * Every stored value for one metric, oldest first, for the comparison to read the spread from.
+ *
+ * Reads the older shape as well, so upgrading Tewip does not quietly empty a project's baseline -
+ * which would drop it below three runs and make Tewip refuse to judge a project it judged fine the
+ * day before.
+ */
+export function baselineFor(runs, metric) {
+    return runs
+        .map((r) => r.metrics?.[metric] ?? r.timings?.[metric]?.p95)
+        .filter((v) => typeof v === 'number' && Number.isFinite(v));
+}
+/** Runs from the same tool. A k6 p95 and a Lighthouse LCP are not each other's baseline. */
+export function fromSameTool(runs, source) {
+    // Runs recorded before the field existed were all k6, which is what the absence means.
+    return runs.filter((r) => (r.source ?? 'k6') === source);
+}
+/** The labels this project has recorded, so a typo in --label does not look like an empty history. */
+export function knownLabels(root) {
+    const path = file(root);
+    if (!existsSync(path))
+        return [];
+    const labels = new Set();
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed?.label === 'string')
+                labels.add(parsed.label);
+        }
+        catch {
+            continue;
+        }
+    }
+    return [...labels].sort();
+}

package/dist/engine/perf/k6.js

@@ -0,0 +1,111 @@
+// Phase 30: reading a k6 run.
+//
+// k6 writes two different summary shapes and Tewip reads both, because which one a team has depends
+// on a flag they probably did not choose deliberately:
+//
+//   --summary-export                     the classic shape: metrics as a map, percentiles keyed
+//                                        "p(95)", and - the part that matters - the result of every
+//                                        threshold the team wrote.
+//   --new-machine-readable-summary       metrics as an array, percentiles keyed p95, and **no
+//                                        threshold results at all**.
+//
+// Both facts below were established by running k6 v2.3.0 against a real server rather than read
+// from documentation, and both would have been got wrong from memory:
+//
+//  1. In the classic shape a threshold entry is `{"p(95)<120": true}` where **true means breached**.
+//     It reads like "the condition holds". It means the opposite. A run whose p95 was 282ms against
+//     a 120ms threshold is the one that produced `true`.
+//  2. The machine-readable shape drops thresholds entirely. The word appears in the file only inside
+//     `config.script`, which is the source text of the test. So a team on that flag has no pass or
+//     fail recorded anywhere in their export, and Tewip has to say so rather than report "no
+//     threshold was breached", which would be a lie of omission.
+import { readFileSync } from 'node:fs';
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+function measurement(metric, values) {
+    return {
+        metric,
+        avg: num(values.avg),
+        min: num(values.min),
+        med: num(values.med),
+        // The two shapes disagree on how a percentile is spelled.
+        p90: num(values['p(90)'] ?? values.p90),
+        p95: num(values['p(95)'] ?? values.p95),
+        max: num(values.max),
+    };
+}
+/** A trend metric is one with a median: a timing, rather than a counter or a rate. */
+const isTrend = (v) => 'med' in v || 'p(95)' in v || 'p95' in v;
+function classic(parsed, at) {
+    const metrics = (parsed.metrics ?? {});
+    const run = { tool: 'k6', format: 'classic', at, timings: {}, rates: {}, counts: {}, thresholds: [] };
+    for (const [name, values] of Object.entries(metrics)) {
+        if (typeof values !== 'object' || values === null)
+            continue;
+        for (const [expression, breached] of Object.entries((values.thresholds ?? {}))) {
+            // `true` is a breach. See the note at the top: this is the opposite of how it reads.
+            run.thresholds.push({ metric: name, expression, breached: breached === true });
+        }
+        if (isTrend(values))
+            run.timings[name] = measurement(name, values);
+        else if ('rate' in values || ('passes' in values && 'fails' in values)) {
+            const passes = num(values.passes);
+            const fails = num(values.fails);
+            run.rates[name] = { rate: num(values.rate ?? values.value), total: passes + fails };
+        }
+        else if ('count' in values)
+            run.counts[name] = num(values.count);
+    }
+    return run;
+}
+function machineReadable(parsed, at) {
+    const results = (parsed.results ?? {});
+    const metrics = Array.isArray(results.metrics) ? results.metrics : [];
+    // Not an empty list: this export records no threshold results, which is a different statement.
+    const run = { tool: 'k6', format: 'machine-readable', at, timings: {}, rates: {}, counts: {}, thresholds: null };
+    for (const entry of metrics) {
+        const name = typeof entry.name === 'string' ? entry.name : '';
+        const values = (entry.values ?? {});
+        if (name === '' || typeof values !== 'object' || values === null)
+            continue;
+        if (entry.type === 'trend')
+            run.timings[name] = measurement(name, values);
+        else if (entry.type === 'rate')
+            run.rates[name] = { rate: num(values.rate), total: num(values.total) };
+        else if (entry.type === 'counter' || 'count' in values)
+            run.counts[name] = num(values.count);
+    }
+    return run;
+}
+/** True of either shape k6 writes. */
+function looksLikeK6Summary(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const o = v;
+    if (typeof o.metrics === 'object' && o.metrics !== null && !Array.isArray(o.metrics))
+        return true;
+    const results = o.results;
+    return typeof results === 'object' && results !== null && Array.isArray(results.metrics);
+}
+export function readK6Summary(path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        throw new Error(`${path} is not JSON. Tewip reads the JSON k6 writes with --summary-export.`);
+    }
+    if (!looksLikeK6Summary(parsed)) {
+        throw new Error(`${path} is JSON, but not a k6 summary: Tewip looked for a "metrics" object or a "results.metrics" array. ` +
+            'Write one with: k6 run --summary-export=summary.json your-test.js');
+    }
+    const o = parsed;
+    const metadata = (o.metadata ?? {});
+    const at = typeof metadata.generated_at === 'string' ? metadata.generated_at : new Date().toISOString();
+    return Array.isArray(o.results?.metrics) ? machineReadable(o, at) : classic(o, at);
+}
+/** The metric a team means by "how slow is it", when they have not said which. */
+export const MAIN_TIMING = 'http_req_duration';
+/** How much work the run did. A verdict from a handful of requests is not worth printing. */
+export function requestCount(run) {
+    return run.counts.http_reqs ?? run.rates.http_req_failed?.total ?? run.counts.iterations ?? 0;
+}

package/dist/engine/perf/lighthouse.js

@@ -0,0 +1,149 @@
+// Phase 31: reading a Lighthouse report.
+//
+// k6 measures what a server does under load. Lighthouse measures what one page load costs in a real
+// browser - Largest Contentful Paint, layout shift, blocking time - which is nearer to what a person
+// actually waits for, and is what most teams already run. Tewip could read neither until now.
+//
+// The same discipline as everywhere else applies, and Lighthouse needs it more than k6 does. Four
+// real Lighthouse runs of an unchanged page, measured here, gave LCP of 922, 912, 936 and 916ms: a
+// 2.6% spread from nothing happening. Lighthouse's own score moved between runs too. So the
+// comparison is the same one k6 gets - outside the baseline range by more than its own width, with
+// three baselines required before anything is called at all.
+//
+// One thing is deliberately not invented. "Is 2112ms bad?" has a published answer, and it is
+// Google's, not Tewip's: Lighthouse scores every metric 0 to 1 on its own curve and renders the
+// bands at 0.9 and 0.5. Tewip reads that score rather than hard-coding thresholds it remembered,
+// so the word "poor" in a report is Lighthouse's judgement and is traceable to it.
+import { readFileSync } from 'node:fs';
+/** The audits worth comparing between runs: what the page load cost, not advice about it. */
+const MEASURED = new Set([
+    'largest-contentful-paint',
+    'first-contentful-paint',
+    'total-blocking-time',
+    'cumulative-layout-shift',
+    'speed-index',
+    'interaction-to-next-paint',
+    'server-response-time',
+    'time-to-first-byte',
+]);
+/** Lighthouse renders green at 0.9 and orange at 0.5. The bands are its own, and so is the word. */
+function rating(score) {
+    if (typeof score !== 'number' || !Number.isFinite(score))
+        return null;
+    if (score >= 0.9)
+        return 'good';
+    if (score >= 0.5)
+        return 'needs-improvement';
+    return 'poor';
+}
+const text = (v) => (typeof v === 'string' ? v : '');
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+function looksLikeLighthouse(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const o = v;
+    return typeof o.lighthouseVersion === 'string' && typeof o.audits === 'object' && o.audits !== null;
+}
+/** The nodes a failing accessibility audit points at. */
+function failingNodes(audit) {
+    const details = (audit.details ?? {});
+    const items = Array.isArray(details.items) ? details.items : [];
+    const out = [];
+    for (const item of items) {
+        const node = (item?.node ?? {});
+        out.push({
+            selector: text(node.selector),
+            snippet: text(node.snippet).replace(/\s+/g, ' ').slice(0, 160),
+            explanation: text(node.explanation)
+                .split(/\r?\n/)
+                .map((l) => l.trim())
+                .filter((l) => l !== '' && !/^Fix (any|all) of the following:$/.test(l))
+                .join('; '),
+        });
+    }
+    return out;
+}
+export function readLighthouse(path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        throw new Error(`${path} is not JSON. Tewip reads the JSON Lighthouse writes with --output=json.`);
+    }
+    if (!looksLikeLighthouse(parsed)) {
+        throw new Error(`${path} is JSON, but not a Lighthouse report: Tewip looked for "lighthouseVersion" and an "audits" object. ` +
+            'Write one with: lighthouse <url> --output=json --output-path=report.json');
+    }
+    const o = parsed;
+    // A report can carry a runtime error and still be valid JSON with empty audits. Reporting "no
+    // regression" from a run that never loaded the page would be the worst kind of wrong.
+    const runtimeError = (o.runtimeError ?? null);
+    if (runtimeError && text(runtimeError.code) !== 'NO_ERROR' && text(runtimeError.message) !== '') {
+        throw new Error(`that Lighthouse run did not complete: ${text(runtimeError.message)}`);
+    }
+    const audits = (o.audits ?? {});
+    const categories = (o.categories ?? {});
+    const metrics = {};
+    for (const [id, audit] of Object.entries(audits)) {
+        if (!MEASURED.has(id) || typeof audit.numericValue !== 'number')
+            continue;
+        metrics[id] = {
+            value: num(audit.numericValue),
+            unit: audit.numericUnit === 'millisecond' ? 'ms' : 'unitless',
+            rating: rating(audit.score),
+        };
+    }
+    // The category score itself is worth tracking: it is the number teams quote at each other.
+    for (const [name, category] of Object.entries(categories)) {
+        if (typeof category?.score === 'number') {
+            metrics[`${name}-score`] = { value: category.score, unit: 'score', rating: rating(category.score) };
+        }
+    }
+    const accessibilityFailures = [];
+    const manual = [];
+    const a11yRefs = (categories.accessibility?.auditRefs ?? []);
+    for (const ref of a11yRefs) {
+        const audit = audits[text(ref.id)];
+        if (!audit)
+            continue;
+        const id = text(audit.id);
+        if (audit.scoreDisplayMode === 'manual') {
+            manual.push({ id, title: text(audit.title) });
+            continue;
+        }
+        if (typeof audit.score === 'number' && audit.score < 1) {
+            const nodes = failingNodes(audit);
+            if (nodes.length === 0)
+                accessibilityFailures.push({ id, title: text(audit.title), selector: '', snippet: '', explanation: '' });
+            for (const node of nodes)
+                accessibilityFailures.push({ id, title: text(audit.title), ...node });
+        }
+    }
+    return {
+        run: {
+            source: 'lighthouse',
+            at: text(o.fetchTime) || new Date().toISOString(),
+            metrics,
+            // Lighthouse has no user-written thresholds the way a k6 script does. That is an absence of
+            // the feature, not an export that forgot to record them, so an empty list is the honest value.
+            thresholds: [],
+            volume: { kind: 'page load', n: 1 },
+        },
+        categories: Object.fromEntries(Object.entries(categories).map(([k, v]) => [k, num(v?.score)])),
+        accessibilityFailures,
+        manual,
+        url: text(o.finalDisplayedUrl) || text(o.finalUrl) || text(o.requestedUrl),
+        lighthouseVersion: text(o.lighthouseVersion),
+    };
+}
+/** True of a Lighthouse report, for a command that accepts either tool's output. */
+export function isLighthouseFile(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return looksLikeLighthouse(parsed);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/engine/perf/perf-command.js

@@ -0,0 +1,165 @@
+// Phase 30, extended in Phase 31: `tewip perf` - is this change slower, and does it matter?
+//
+// Reads a k6 run (what a server does under load) or a Lighthouse report (what one page load costs in
+// a browser), whichever it is handed, and answers two questions separately because they fail
+// separately:
+//
+//   1. **Is anything in a bad state right now?** From the team's own k6 thresholds, or from
+//      Lighthouse's published scoring bands. Never from a budget Tewip invented.
+//   2. **Is it slower than it was?** Only from repeated baselines, and refused below three, because
+//      one run against one run is not evidence. Four real k6 runs of unchanged code gave p95 of
+//      60.8-62.8ms; four real Lighthouse runs of an unchanged page gave LCP of 912-936ms. Both move
+//      on their own, and a tool that calls that a regression is muted within a week.
+//
+// It never predicts a duration, a capacity or a user impact: it cannot see the production hardware,
+// the real data volume or the real traffic, and an invented number for any of those is worse than
+// silence.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { readK6Summary, requestCount } from './k6.js';
+import { isLighthouseFile, readLighthouse } from './lighthouse.js';
+import { fromK6, metricsInOrder, show } from './run.js';
+import { compareMetric, ENOUGH_BASELINES } from './compare.js';
+import { baselineFor, fromSameTool, knownLabels, recordRun, storedRuns } from './history.js';
+/** Enough requests for a percentile to mean anything. Below this, p95 is three data points. */
+export const ENOUGH_REQUESTS = 100;
+export function readPerfFile(path) {
+    if (isLighthouseFile(path)) {
+        const report = readLighthouse(path);
+        return { run: report.run, manual: report.manual, url: report.url };
+    }
+    const k6 = readK6Summary(path);
+    return { run: fromK6(k6, requestCount(k6)), manual: [], url: '' };
+}
+export function renderPerf(run, comparisons, label, baselineCount, recorded, manual = []) {
+    const lines = ['# Tewip performance check', ''];
+    const breaches = (run.thresholds ?? []).filter((t) => t.breached);
+    const poor = Object.entries(run.metrics).filter(([, m]) => m.rating === 'poor');
+    const slower = comparisons.filter((c) => c.direction === 'slower');
+    const faster = comparisons.filter((c) => c.direction === 'faster');
+    const unsure = comparisons.filter((c) => c.direction === 'cannot-say');
+    const tool = run.source === 'k6' ? 'k6' : 'Lighthouse';
+    lines.push(`Read a ${tool} run of **${run.volume.n} ${run.volume.kind}${run.volume.n === 1 ? '' : 's'}**, compared against **${baselineCount}** recorded ` +
+        `${tool} baseline ${baselineCount === 1 ? 'run' : 'runs'} for \`${label}\`.`, '');
+    if (breaches.length > 0)
+        lines.push(`**${breaches.length} of your own thresholds ${breaches.length === 1 ? 'was' : 'were'} breached.**`, '');
+    if (poor.length > 0)
+        lines.push(`**${poor.length} ${poor.length === 1 ? 'metric is' : 'metrics are'} in ${tool}'s worst band.**`, '');
+    if (slower.length > 0)
+        lines.push(`**${slower.length} ${slower.length === 1 ? 'metric is' : 'metrics are'} slower than the baseline runs can explain.**`, '');
+    if (breaches.length === 0 && poor.length === 0 && slower.length === 0) {
+        lines.push(run.thresholds === null
+            ? '**No regression this baseline can detect.** Your thresholds are not in this export, so nothing is said about them.'
+            : '**Nothing in a bad state, and no regression this baseline can detect.**', '');
+    }
+    lines.push('## Is anything in a bad state right now?', '');
+    if (run.source === 'k6') {
+        if (run.thresholds === null) {
+            lines.push('**Cannot say.** This summary came from `--new-machine-readable-summary`, and that export records no threshold ' +
+                'results at all - the word appears in it only inside the copy of your script. Tewip will not report "nothing was ' +
+                'breached" from a file that does not say. Re-run with plain `--summary-export` to get the answer.', '');
+        }
+        else if (run.thresholds.length === 0) {
+            lines.push('This run has no thresholds. Add them to your k6 script and the team decides what "fast enough" means, rather than Tewip.', '');
+        }
+        else {
+            for (const t of run.thresholds)
+                lines.push(`- ${t.breached ? '**breached**' : 'held'} — \`${t.metric}\`: \`${t.expression}\``);
+            lines.push('');
+        }
+    }
+    else {
+        // The bands are Lighthouse's own, computed by Lighthouse. Tewip is relaying a judgement with a
+        // published basis, not applying numbers it chose.
+        lines.push("Rated by Lighthouse's own scoring, not by any threshold Tewip invented:", '');
+        for (const name of metricsInOrder(run)) {
+            const m = run.metrics[name];
+            if (m.rating === null)
+                continue;
+            const mark = m.rating === 'poor' ? '**poor**' : m.rating === 'needs-improvement' ? 'needs improvement' : 'good';
+            lines.push(`- ${mark} — \`${name}\`: ${show(m)}`);
+        }
+        lines.push('');
+    }
+    lines.push('## Is it slower than it was?', '');
+    if (baselineCount < ENOUGH_BASELINES) {
+        lines.push(`**Cannot say.** There ${baselineCount === 1 ? 'is' : 'are'} ${baselineCount} recorded ${tool} ${baselineCount === 1 ? 'run' : 'runs'} ` +
+            `for \`${label}\`, and Tewip needs ${ENOUGH_BASELINES} before it will call anything a regression. Performance numbers move ` +
+            'between identical runs, and without several of them there is no way to tell a change from the machine having a busy moment. ' +
+            'Record baselines on your main branch with `tewip perf <file> --record`.', '');
+    }
+    for (const c of [...slower, ...faster, ...unsure]) {
+        const verdict = c.direction === 'slower' ? '**slower**' : c.direction === 'faster' ? 'faster' : 'cannot say';
+        const unit = run.metrics[c.metric]?.unit ?? 'ms';
+        const u = (n) => (unit === 'ms' ? `${n}ms` : `${n}`);
+        lines.push(`- \`${c.metric}\` ${u(c.now)} — ${verdict}`);
+        lines.push(`  - baseline ${u(c.baselineLow)}–${u(c.baselineHigh)} over ${c.baselineRuns} runs, middle ${u(c.before)}`);
+        lines.push(`  - ${c.why}`);
+    }
+    lines.push('');
+    if (run.source === 'k6' && run.volume.n < ENOUGH_REQUESTS) {
+        lines.push(`**${run.volume.n} requests is thin.** A p95 from this few is a handful of data points and will move on its own. ` +
+            'Treat everything above as indicative and lengthen the run before deciding anything.', '');
+    }
+    lines.push('## What this does not tell you', '');
+    lines.push('- **Nothing about production.** This is the hardware the run happened on, with that data volume and that ' +
+        'concurrency. Tewip cannot see your real machines, your real data or your real traffic, and will not guess.', '- **No duration is predicted.** How long a real user waits depends on network, device and cache, none of which are here.', '- **Only what the run exercised.** A page or endpoint it never touched is not covered, however green this looks.', '- **Not capacity.** This says whether it changed, not how many users it would hold.');
+    if (run.source === 'lighthouse') {
+        lines.push(`- **One page load.** k6 reports a percentile over many requests; this is a single load of one page, and a single ` +
+            'load is the noisiest measurement either tool offers.');
+        if (manual.length > 0) {
+            lines.push(`- **${manual.length} accessibility checks Lighthouse refuses to score** and hands to a person - ` +
+                `${manual.slice(0, 3).map((m) => `\`${m.id}\``).join(', ')} and others. They are not failures and not passes. ` +
+                'Run `tewip access` for the accessibility side.');
+        }
+    }
+    lines.push('');
+    if (recorded)
+        lines.push(`This run was added to the baseline for \`${label}\`.`, '');
+    else
+        lines.push('This run was **not** recorded. Add `--record` on your main branch to make it part of the baseline; a regression recorded by accident becomes next week\'s normal.', '');
+    return lines.join('\n');
+}
+export function runPerf(cmd) {
+    const root = resolve(cmd.root);
+    const label = cmd.label ?? 'default';
+    const { run, manual } = readPerfFile(resolve(root, cmd.summary));
+    const all = storedRuns(root, label);
+    const history = fromSameTool(all, run.source);
+    if (all.length === 0) {
+        const known = knownLabels(root);
+        if (known.length > 0 && !known.includes(label)) {
+            console.error(`[tewip] no recorded runs for label "${label}". This project has: ${known.join(', ')}.`);
+        }
+    }
+    const comparisons = metricsInOrder(run)
+        .map((metric) => compareMetric(metric, run.metrics[metric].value, baselineFor(history, metric)))
+        // A metric that is zero now and was zero every time before says nothing, and printing
+        // "0ms is within 0-0ms" three times buries the real lines.
+        .filter((c) => c.now > 0 || c.baselineHigh > 0);
+    const recorded = cmd.record === true;
+    if (recorded)
+        recordRun(root, label, run, cmd.gitSha);
+    const breached = (run.thresholds ?? []).some((t) => t.breached);
+    const poor = Object.values(run.metrics).some((m) => m.rating === 'poor');
+    const regressed = comparisons.some((c) => c.direction === 'slower');
+    const report = renderPerf(run, comparisons, label, history.length, recorded, manual);
+    console.log(report);
+    if (cmd.gate && (breached || regressed || poor)) {
+        const why = [
+            breached ? 'a threshold you wrote was breached' : '',
+            poor ? "something is in Lighthouse's worst band" : '',
+            regressed ? 'something is slower than the baselines explain' : '',
+        ]
+            .filter(Boolean)
+            .join(', and ');
+        console.error(`${String.fromCharCode(10)}Performance gate failed: ${why}.`);
+        process.exitCode = 1;
+    }
+    if (cmd.out) {
+        const path = resolve(root, cmd.out);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, report, 'utf8');
+    }
+    return { run, comparisons, regressed, breached: breached || poor, report };
+}

package/dist/engine/perf/run.js

@@ -0,0 +1,39 @@
+/** k6's percentiles, reduced to the one number a comparison needs: p95. */
+export function fromK6(run, requests) {
+    const metrics = {};
+    for (const [name, m] of Object.entries(run.timings)) {
+        // Tagged duplicates (`http_req_duration{expected_response:true}`) are the same measurement
+        // sliced, and comparing both says the same thing twice.
+        if (name.includes('{'))
+            continue;
+        // k6 publishes no bands. It reports numbers and leaves "fast enough" to the team's thresholds,
+        // which is the right division and the reason rating is null here.
+        metrics[name] = { value: m.p95, unit: 'ms', rating: null };
+    }
+    return { source: 'k6', at: run.at, metrics, thresholds: run.thresholds, volume: { kind: 'request', n: requests } };
+}
+/** Metrics worth putting in front of a person, most important first. */
+const ORDER = [
+    'largest-contentful-paint',
+    'cumulative-layout-shift',
+    'total-blocking-time',
+    'interaction-to-next-paint',
+    'first-contentful-paint',
+    'speed-index',
+    'server-response-time',
+    'http_req_duration',
+];
+export function metricsInOrder(run) {
+    const names = Object.keys(run.metrics);
+    const known = ORDER.filter((m) => names.includes(m));
+    const rest = names.filter((m) => !ORDER.includes(m)).sort();
+    return [...known, ...rest];
+}
+/** How a metric is written in a report: 2112ms, 0.08, 97. */
+export function show(metric) {
+    if (metric.unit === 'ms')
+        return `${Math.round(metric.value)}ms`;
+    if (metric.unit === 'score')
+        return `${Math.round(metric.value * 100)}`;
+    return `${Math.round(metric.value * 1000) / 1000}`;
+}

package/dist/mcp/tools-prove.js

@@ -95,6 +95,33 @@ export function registerProofTools(server, { answer, readOnly, project }) {
             return 'No migration or schema file in that change.';
         return renderSchema(migrations, stillUsed(root, migrations.flatMap((m) => m.findings)));
     }));
+    server.registerTool('is_this_slower', {
+        title: 'Is this change slower, and does it matter?',
+        description: "Judges a k6 load-test run, rather than restating its numbers. Two answers kept apart: whether the thresholds the team wrote in their own k6 script held, and whether this run is slower than the recorded baseline. The second is answered only from three or more baseline runs - below that it returns 'cannot say', because one run against one run cannot distinguish a regression from a busy machine, and a percentage printed without that distinction is how performance tooling gets ignored. It never predicts a duration, a capacity or a user impact, and it says what the run does not cover. Use it when asked whether a change made something slower.",
+        inputSchema: {
+            project,
+            summary: z.string().describe('Path to the JSON from `k6 run --summary-export=summary.json`'),
+            label: z.string().optional().describe('Which load test this is, so two different suites do not become each other baseline'),
+        },
+        annotations: readOnly,
+    }, ({ project: root, summary, label }) => answer(async () => {
+        if (!isAbsolute(root) || !existsSync(root))
+            throw new Error(`project must be an existing absolute path, got "${root}"`);
+        // Never records: an assistant adding runs to a team's baseline unasked is how a regression
+        // silently becomes the new normal. Recording stays a deliberate act on the command line.
+        const { compareMetric } = await import('../engine/perf/compare.js');
+        const { baselineFor, fromSameTool, storedRuns } = await import('../engine/perf/history.js');
+        const { readPerfFile, renderPerf } = await import('../engine/perf/perf-command.js');
+        const { metricsInOrder } = await import('../engine/perf/run.js');
+        const { isAbsolute: abs, resolve } = await import('node:path');
+        const { run, manual } = readPerfFile(abs(summary) ? summary : resolve(root, summary));
+        const name = label ?? 'default';
+        const history = fromSameTool(storedRuns(root, name), run.source);
+        const comparisons = metricsInOrder(run)
+            .map((m) => compareMetric(m, run.metrics[m].value, baselineFor(history, m)))
+            .filter((c) => c.now > 0 || c.baselineHigh > 0);
+        return renderPerf(run, comparisons, name, history.length, false, manual);
+    }));
     server.registerTool('accessibility_barriers', {
         title: 'Can everybody use this interface?',
         description: "Accessibility barriers in a project's markup, each named against the WCAG 2.2 criterion a regulator would cite, with the evidence to check it. Two kinds of answer, kept apart on purpose: barriers that reading the markup proves (no alt attribute at all, a field with no label anywhere, a div that only a mouse can activate), and the ones only a person can settle, where something is written as an expression or a component and the markup cannot say. It also returns every criterion it did NOT check - contrast, focus order, whether alt text is any good - because those need a rendered page. Use it before shipping an interface, or when asked whether something is accessible; a clean result means these checks found nothing, never that the product is accessible. No browser, no network, no model.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tewip-ai",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "mcpName": "io.github.hmamut39/tewip",
   "description": "Tewip finds why each failing test failed - real bug, flaky test, environment, test data or changed selector - for any stack, from the command line, CI, or your editor.",
   "keywords": [