tewip-ai 0.4.0

package/dist/engine/quality/frameworks.js

@@ -0,0 +1,181 @@
+// Which test frameworks a project uses, where their tests live, and how to run one test file.
+// Tewip writes tests in the project's own framework and style, so it reads this from the project
+// (config files, dependencies, existing tests) instead of assuming Playwright. It looks in the root
+// and two levels below, because many repositories keep browser tests in their own folder.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, dirname, join, relative } from 'node:path';
+/**
+ * A Chrome for Karma when CHROME_BIN is not set: the Chromium Playwright installed, if any. Karma
+ * cannot start without one, and many machines have Playwright's browsers but no Chrome.
+ */
+function karmaChrome() {
+    if (process.env.CHROME_BIN)
+        return {};
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
+    const root = process.env.PLAYWRIGHT_BROWSERS_PATH ?? (process.platform === 'win32' ? join(process.env.LOCALAPPDATA ?? '', 'ms-playwright') : process.platform === 'darwin' ? join(home, 'Library', 'Caches', 'ms-playwright') : join(home, '.cache', 'ms-playwright'));
+    if (!existsSync(root))
+        return {};
+    const builds = readdirSync(root).filter((d) => /^chromium-\d+$/.test(d)).sort((a, b) => Number(b.split('-')[1]) - Number(a.split('-')[1]));
+    const exe = ['chrome-win64/chrome.exe', 'chrome-win/chrome.exe', 'chrome-linux64/chrome', 'chrome-linux/chrome', 'chrome-mac/Chromium.app/Contents/MacOS/Chromium', 'chrome-mac-arm64/Chromium.app/Contents/MacOS/Chromium'];
+    for (const build of builds)
+        for (const e of exe)
+            if (existsSync(join(root, build, e)))
+                return { CHROME_BIN: join(root, build, e) };
+    return {};
+}
+const SKIP = new Set(['node_modules', '.git', '.tewip', 'dist', 'build', 'target', 'venv', '.venv', '__pycache__', 'bin', 'obj', 'vendor']);
+const q = (s) => `"${s}"`;
+const read = (p) => (existsSync(p) ? readFileSync(p, 'utf8') : '');
+function dirs(root, depth = 2) {
+    const out = [root];
+    if (depth === 0)
+        return out;
+    for (const name of readdirSync(root)) {
+        if (SKIP.has(name) || name.startsWith('.'))
+            continue;
+        const p = join(root, name);
+        if (statSync(p).isDirectory())
+            out.push(...dirs(p, depth - 1));
+    }
+    return out;
+}
+/** Test files under `dir` whose names match, newest-looking first (shortest path wins ties). */
+function testFiles(dir, match, depth = 6) {
+    if (!existsSync(dir) || depth < 0)
+        return [];
+    const out = [];
+    for (const name of readdirSync(dir)) {
+        if (SKIP.has(name))
+            continue;
+        const p = join(dir, name);
+        if (statSync(p).isDirectory())
+            out.push(...testFiles(p, match, depth - 1));
+        else if (match.test(name) && !/tewip/i.test(name))
+            out.push(p);
+    }
+    return out.sort((a, b) => a.length - b.length);
+}
+const kebab = (id) => id.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+const pascal = (id) => kebab(id).split('-').filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join('');
+/** "tewip-<id><suffix>", with the suffix the project's own tests use. */
+function sameSuffix(example, fallback, known) {
+    const suffix = example?.match(known)?.[0] ?? fallback;
+    return (id) => `tewip-${kebab(id)}${suffix}`;
+}
+/** Every JavaScript test framework set up in this folder: a project often has e2e and unit tests. */
+function jsFrameworks(dir, deps) {
+    const out = [];
+    const config = (names) => names.map((n) => join(dir, n)).find(existsSync);
+    const pw = config(['playwright.config.ts', 'playwright.config.js', 'playwright.config.mjs']);
+    if (pw) {
+        const testDir = join(dir, read(pw).match(/testDir:\s*['"`]([^'"`]+)/)?.[1] ?? '.');
+        const example = testFiles(testDir, /\.(spec|test)\.[mc]?[jt]s$/)[0] ?? null;
+        out.push({ id: 'playwright', label: 'Playwright Test (TypeScript/JavaScript)', browser: true, cwd: dir, testDir: example ? dirname(example) : testDir, example, fileFor: sameSuffix(example, '.spec.ts', /\.(spec|test)\.[mc]?[jt]s$/), command: (f) => `npx playwright test ${q(relative(dir, f).replaceAll('\\', '/'))} --retries=0 --workers=1 --reporter=line` });
+    }
+    const cy = config(['cypress.config.ts', 'cypress.config.js', 'cypress.config.mjs']);
+    if (cy) {
+        const example = testFiles(join(dir, 'cypress'), /\.cy\.[jt]sx?$/)[0] ?? null;
+        out.push({ id: 'cypress', label: 'Cypress (JavaScript/TypeScript)', browser: true, cwd: dir, testDir: example ? dirname(example) : join(dir, 'cypress', 'e2e'), example, fileFor: sameSuffix(example, '.cy.ts', /\.cy\.[jt]sx?$/), command: (f) => `npx cypress run --spec ${q(relative(dir, f))}` });
+    }
+    const wdio = config(['wdio.conf.ts', 'wdio.conf.js']);
+    if (wdio) {
+        const example = testFiles(dir, /\.(e2e|spec|test)\.[jt]s$/)[0] ?? null;
+        out.push({ id: 'webdriverio', label: 'WebdriverIO (JavaScript/TypeScript)', browser: true, cwd: dir, testDir: example ? dirname(example) : join(dir, 'test', 'specs'), example, fileFor: sameSuffix(example, '.e2e.ts', /\.(e2e|spec|test)\.[jt]s$/), command: (f) => `npx wdio run ${q(basename(wdio))} --spec ${q(relative(dir, f))}` });
+    }
+    // Angular runs its unit tests through the CLI (Karma with Jasmine, or the Vitest-based unit-test
+    // builder), with the project's TestBed setup, so a spec must run through `ng test` as well.
+    const angular = read(join(dir, 'angular.json'));
+    const builder = angular.match(/"test"\s*:\s*\{\s*"builder"\s*:\s*"([^"]+)"/)?.[1] ?? '';
+    const hasAngular = Boolean(angular && /karma|unit-test/.test(builder));
+    if (hasAngular) {
+        const example = testFiles(join(dir, 'src'), /\.spec\.ts$/)[0] ?? null;
+        const karma = builder.includes('karma');
+        out.push({
+            id: 'angular',
+            label: `Angular (ng test with ${karma ? 'Karma and Jasmine' : 'Vitest'}, TestBed; TypeScript)`,
+            browser: false,
+            cwd: dir,
+            testDir: example ? dirname(example) : join(dir, 'src', 'app'),
+            example,
+            fileFor: (id) => `tewip-${kebab(id)}.spec.ts`,
+            command: (f) => `npx ng test --watch=false --include=${q(relative(dir, f).replaceAll('\\', '/'))}${karma ? ' --browsers=ChromeHeadless' : ''}`,
+            env: karma ? karmaChrome() : undefined,
+        });
+    }
+    for (const id of ['vitest', 'jest']) {
+        if (!new RegExp(`"${id}"\\s*:`).test(deps))
+            continue;
+        const example = testFiles(dir, /\.(spec|test)\.[mc]?[jt]sx?$/)[0] ?? null;
+        const browser = /"selenium-webdriver"\s*:|"puppeteer"\s*:/.test(deps);
+        // Name the UI library and Testing Library, so component tests are written the way this project writes them.
+        const ui = [['react', 'React'], ['vue', 'Vue'], ['svelte', 'Svelte'], ['solid-js', 'Solid'], ['@angular/core', 'Angular']].filter(([dep]) => new RegExp(`"${dep}"\\s*:`).test(deps)).map(([, name]) => name);
+        const testingLibrary = /"@testing-library\/[\w-]+"\s*:/.test(deps) ? ' and Testing Library' : '';
+        const label = `${id === 'jest' ? 'Jest' : 'Vitest'}${browser ? ' with Selenium/Puppeteer' : ''}${ui.length ? ` for ${ui.join('/')}${testingLibrary}` : ''} (JavaScript/TypeScript)`;
+        const run = id === 'jest' ? 'npx jest' : 'npx vitest run';
+        out.push({ id, label, browser, cwd: dir, testDir: example ? dirname(example) : join(dir, 'test'), example, fileFor: sameSuffix(example, '.test.ts', /\.(spec|test)\.[mc]?[jt]sx?$/), command: (f) => `${run} ${q(relative(dir, f).replaceAll('\\', '/'))}` });
+        break;
+    }
+    return out;
+}
+/** The project's own Python (its virtual environment) when it has one, else the one on the PATH. */
+function pythonOf(dir) {
+    for (const env of ['.venv', 'venv', 'env']) {
+        for (const bin of process.platform === 'win32' ? ['Scripts/python.exe'] : ['bin/python']) {
+            if (existsSync(join(dir, env, bin)))
+                return join(dir, env, bin);
+        }
+    }
+    return 'python';
+}
+function otherFramework(dir) {
+    const py = ['pytest.ini', 'conftest.py', 'pyproject.toml', 'requirements.txt', 'setup.cfg', 'tox.ini'].map((n) => read(join(dir, n))).join('\n');
+    const pyExample = testFiles(dir, /^test_.*\.py$|_test\.py$/)[0] ?? null;
+    if (pyExample && (/pytest/i.test(py) || existsSync(join(dir, 'conftest.py')))) {
+        const lib = /selenium/i.test(py) ? ' with Selenium' : /playwright/i.test(py) ? ' with Playwright' : '';
+        return { id: 'pytest', label: `pytest${lib} (Python)`, browser: lib !== '', cwd: dir, testDir: dirname(pyExample), example: pyExample, fileFor: (id) => `test_tewip_${kebab(id).replaceAll('-', '_')}.py`, command: (f) => `${q(pythonOf(dir))} -m pytest ${q(relative(dir, f))} -q -p no:cacheprovider` };
+    }
+    const javaExample = testFiles(join(dir, 'src', 'test'), /Tests?\.(java|kt)$/)[0] ?? null;
+    const pom = read(join(dir, 'pom.xml'));
+    const gradle = read(join(dir, 'build.gradle')) + read(join(dir, 'build.gradle.kts'));
+    if (javaExample && (pom || gradle)) {
+        const build = pom || gradle;
+        const lib = /selenium/i.test(build) ? ' with Selenium' : /spring-boot-starter-test/.test(build) ? ' on Spring Boot' : '';
+        const cls = (f) => basename(f).replace(/\.(java|kt)$/, '');
+        const lang = javaExample.endsWith('.kt') ? 'Kotlin' : 'Java';
+        const wrapper = existsSync(join(dir, process.platform === 'win32' ? 'gradlew.bat' : 'gradlew')) ? (process.platform === 'win32' ? 'gradlew.bat' : './gradlew') : 'gradle';
+        return pom
+            ? { id: 'maven', label: `JUnit via Maven${lib} (${lang})`, browser: lib === ' with Selenium', cwd: dir, testDir: dirname(javaExample), example: javaExample, fileFor: (id) => `Tewip${pascal(id)}Test.${javaExample.endsWith('.kt') ? 'kt' : 'java'}`, command: (f) => `mvn -q test -Dtest=${cls(f)} -Dsurefire.failIfNoSpecifiedTests=false` }
+            : { id: 'gradle', label: `JUnit via Gradle${lib} (${lang})`, browser: lib === ' with Selenium', cwd: dir, testDir: dirname(javaExample), example: javaExample, fileFor: (id) => `Tewip${pascal(id)}Test.${javaExample.endsWith('.kt') ? 'kt' : 'java'}`, command: (f) => `${wrapper} test --tests ${cls(f)}` };
+    }
+    const csproj = readdirSync(dir).find((n) => n.endsWith('.csproj') && /Microsoft\.NET\.Test\.Sdk/.test(read(join(dir, n))));
+    if (csproj) {
+        const example = testFiles(dir, /Tests?\.cs$/)[0] ?? null;
+        const lib = /Selenium/.test(read(join(dir, csproj))) ? ' with Selenium' : /Playwright/.test(read(join(dir, csproj))) ? ' with Playwright' : '';
+        return { id: 'dotnet', label: `.NET test${lib} (C#)`, browser: lib !== '', cwd: dir, testDir: example ? dirname(example) : dir, example, fileFor: (id) => `Tewip${pascal(id)}Tests.cs`, command: (f) => `dotnet test --filter FullyQualifiedName~${basename(f, '.cs')}` };
+    }
+    if (existsSync(join(dir, 'go.mod'))) {
+        const example = testFiles(dir, /_test\.go$/)[0] ?? null;
+        if (example)
+            return { id: 'go', label: 'Go testing', browser: false, cwd: dir, testDir: dirname(example), example, fileFor: (id) => `tewip_${kebab(id).replaceAll('-', '_')}_test.go`, command: (f) => `go test ./${relative(dir, dirname(f)).replaceAll('\\', '/') || '.'}` };
+    }
+    return null;
+}
+/** Every test framework found in the project, browser frameworks first. */
+export function detectFrameworks(root) {
+    const found = [];
+    for (const dir of dirs(root)) {
+        const deps = read(join(dir, 'package.json'));
+        for (const f of [...jsFrameworks(dir, deps), otherFramework(dir)])
+            if (f && !found.some((x) => x.id === f.id && x.cwd === f.cwd))
+                found.push(f);
+    }
+    return found.sort((a, b) => Number(b.browser) - Number(a.browser));
+}
+/** The framework to write in: the one asked for, else the first of the kind the scenarios need, else the first. */
+export function chooseFramework(found, wanted, browser = true) {
+    if (wanted)
+        return found.find((f) => f.id === wanted) ?? null;
+    // Scenarios on pages of the running app are browser tests; without pages they are unit or
+    // component tests, which belong in the project's unit framework even when it also has e2e tests.
+    return found.find((f) => f.browser === browser) ?? found[0] ?? null;
+}

package/dist/engine/quality/grounding.js

@@ -0,0 +1,203 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// Facts Tewip reads before it plans or writes tests, so the model works from the project as it is
+// instead of inventing it: the tests that already exist, what a change touched, and what the
+// running app's pages actually contain.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.tewip', '.venv', 'venv', '__pycache__', 'target', 'vendor', 'coverage', 'test-results', 'playwright-report', 'blob-report']);
+const CODE_FILE = /\.(?:[cm]?[jt]sx?|py|java|kt|cs|go|rb|php|rs)$/;
+const TEST_FILE = /(\.(spec|test)\.[cm]?[jt]sx?$)|(^test_.*\.py$)|(_test\.(py|go)$)|(Tests?\.(java|kt|cs)$)|(_spec\.rb$)|(Test\.php$)/;
+/** Test names found in one file, for the languages Tewip reads reports from. */
+function testNames(source) {
+    const patterns = [
+        /\b(?:test|it)(?:\.only|\.skip)?\(\s*(['"`])((?:(?!\1).)+)\1/g, // Playwright, Jest, Vitest, Mocha, node:test
+        /^\s*def (test_\w+)/gm, // pytest, unittest
+        /^func (Test\w+)\(/gm, // Go
+        /@Test[\s\S]{0,120}?\bvoid (\w+)\s*\(/g, // JUnit, TestNG
+        /\[(?:Fact|Test|TestMethod)\][\s\S]{0,120}?\bvoid (\w+)\s*\(/g, // xUnit, NUnit, MSTest
+        /^\s*it\s+['"]([^'"]+)['"]/gm, // RSpec
+        /function (test\w+)\s*\(/g, // PHPUnit
+    ];
+    const out = [];
+    for (const p of patterns)
+        for (const m of source.matchAll(p))
+            out.push((m[2] ?? m[1]).trim());
+    return out;
+}
+/** The tests already in the project, found by file name and read for their names. */
+export function existingTests(root, cap = 300) {
+    const tests = [];
+    let files = 0;
+    const walk = (dir, depth) => {
+        if (depth > 8)
+            return;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.'))
+                    walk(join(dir, entry.name), depth + 1);
+            }
+            else if (TEST_FILE.test(entry.name)) {
+                const path = join(dir, entry.name);
+                if (statSync(path).size > 1_000_000)
+                    continue;
+                files++;
+                const rel = relative(root, path).replaceAll('\\', '/');
+                for (const name of testNames(readFileSync(path, 'utf8')))
+                    if (tests.length < cap)
+                        tests.push(`${rel}: ${name}`);
+            }
+        }
+    };
+    walk(root, 0);
+    return { files, tests };
+}
+const STOPWORDS = new Set(['with', 'that', 'this', 'from', 'into', 'when', 'then', 'them', 'they', 'their', 'each', 'what', 'which', 'reads', 'back', 'sees', 'must', 'should', 'have', 'does', 'test', 'tests', 'user', 'page', 'able', 'also', 'only', 'other', 'more', 'than', 'will']);
+/**
+ * The full text of the tests most related to a feature. Test names alone hide what table-driven
+ * tests (test.each, parametrize, @ParameterizedTest, a list of cases in a loop) already check, so
+ * the planner also reads the files that mention the feature's words most, rare words counting
+ * most. With kind 'code', the same for the source files the feature lives in. Tests Tewip wrote
+ * itself are left out: they are not the project's own conventions.
+ */
+export function relatedTestSources(root, feature, maxFiles = 4, maxChars = 8_000, kind = 'tests') {
+    const wanted = (name) => (kind === 'tests' ? TEST_FILE.test(name) : CODE_FILE.test(name) && !TEST_FILE.test(name) && !/\.d\.ts$|\.min\.js$|\.config\./.test(name));
+    const words = [...new Set(feature.match(/[A-Za-z_][A-Za-z0-9_]{3,}/g) ?? [])].filter((t) => !STOPWORDS.has(t.toLowerCase()));
+    // Names written like code (with_query, withQuery) almost surely point at the right file.
+    const codeLike = words.map((t) => /[a-z][A-Z]|_/.test(t));
+    const terms = words.map((t) => t.toLowerCase());
+    if (terms.length === 0)
+        return [];
+    const files = [];
+    const walk = (dir, depth) => {
+        if (depth > 8)
+            return;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.'))
+                    walk(path, depth + 1);
+            }
+            else if (wanted(entry.name) && !/tewip/i.test(entry.name) && statSync(path).size <= 1_000_000) {
+                const content = readFileSync(path, 'utf8');
+                const lower = content.toLowerCase();
+                files.push({ file: relative(root, path).replaceAll('\\', '/'), content, hits: terms.map((t) => Math.min(20, lower.split(t).length - 1)) });
+            }
+        }
+    };
+    walk(root, 0);
+    // A word found in few files says more about which file is meant than one found everywhere
+    // (tf-idf): "naturalsize" picks the file-size tests, "number" or "format" pick nothing in particular.
+    const weight = terms.map((_, i) => Math.log(1 + files.length / Math.max(1, files.filter((f) => f.hits[i] > 0).length)) * (codeLike[i] ? 3 : 1));
+    // Pick greedily by what each file adds: once a chosen file covers a word, that word counts a
+    // quarter as much, so a feature naming two functions gets the tests of both.
+    const left = [...weight];
+    const chosen = [];
+    const gain = (f) => f.hits.reduce((sum, h, i) => sum + Math.log(1 + h) * left[i], 0);
+    while (chosen.length < maxFiles) {
+        const best = files.filter((f) => !chosen.includes(f)).sort((x, y) => gain(y) - gain(x))[0];
+        if (!best || gain(best) <= 0)
+            break;
+        chosen.push(best);
+        best.hits.forEach((h, i) => (left[i] = h > 0 ? left[i] / 4 : left[i]));
+    }
+    return chosen.map(({ file, content }) => ({ file, content: content.length > maxChars ? `${content.slice(0, maxChars)}\n... (cut)` : content }));
+}
+/** What a git range changed (e.g. "main...HEAD"); null outside a git checkout. */
+export function changeSummary(root, range, maxPatch = 12_000) {
+    try {
+        const git = (args) => execFileSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+        const files = git(['diff', '--name-only', range]).split('\n').filter(Boolean);
+        const patch = git(['diff', '--unified=2', range]);
+        return { range, files, patch: patch.length > maxPatch ? `${patch.slice(0, maxPatch)}\n... (diff cut at ${maxPatch} characters)` : patch };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Playwright as the project installed it, found from the project's own folders (the root, or a
+ * browser-test folder such as e2e/ one or two levels down), then Tewip's own copy. An installed
+ * Tewip cannot see the project's node_modules through a plain import, so it resolves them here.
+ */
+async function loadChromium(root) {
+    const dirs = [root];
+    for (const a of readdirSync(root, { withFileTypes: true })) {
+        if (!a.isDirectory() || SKIP_DIRS.has(a.name) || a.name.startsWith('.'))
+            continue;
+        dirs.push(join(root, a.name));
+        for (const b of readdirSync(join(root, a.name), { withFileTypes: true })) {
+            if (b.isDirectory() && !SKIP_DIRS.has(b.name) && !b.name.startsWith('.'))
+                dirs.push(join(root, a.name, b.name));
+        }
+    }
+    for (const dir of dirs) {
+        for (const name of ['@playwright/test', 'playwright']) {
+            if (!existsSync(join(dir, 'node_modules', ...name.split('/'))))
+                continue;
+            try {
+                const entry = createRequire(join(dir, 'package.json')).resolve(name);
+                const m = (await import(__rewriteRelativeImportExtension(pathToFileURL(entry).href)));
+                if (m.chromium ?? m.default?.chromium)
+                    return m.chromium ?? m.default.chromium;
+            }
+            catch {
+                // an unusable install here; try the next folder
+            }
+        }
+    }
+    for (const name of ['@playwright/test', 'playwright']) {
+        try {
+            return (await import(__rewriteRelativeImportExtension(name))).chromium;
+        }
+        catch {
+            // not bundled with Tewip either
+        }
+    }
+    return null;
+}
+/**
+ * What a page of the running app contains, read with Playwright. Returns no pages and a reason when
+ * Playwright or its browser is not available, rather than failing the whole command.
+ */
+export async function readPages(urls, root = process.cwd(), maxAria = 8_000) {
+    if (urls.length === 0)
+        return { pages: [], note: null };
+    const chromium = await loadChromium(root);
+    if (!chromium)
+        return { pages: [], note: 'Playwright is not installed in this project, so the pages were not read (npm install -D @playwright/test && npx playwright install chromium).' };
+    let browser;
+    try {
+        browser = await chromium.launch();
+    }
+    catch (error) {
+        return { pages: [], note: `Playwright could not start a browser, so the pages were not read (npx playwright install chromium): ${String(error instanceof Error ? error.message : error).split('\n')[0]}` };
+    }
+    try {
+        const page = await browser.newPage();
+        const pages = [];
+        for (const url of urls) {
+            await page.goto(url, { waitUntil: 'networkidle', timeout: 30_000 });
+            const aria = await page.locator('body').ariaSnapshot();
+            pages.push({ url, title: await page.title(), aria: aria.length > maxAria ? `${aria.slice(0, maxAria)}\n... (cut)` : aria });
+        }
+        return { pages, note: null };
+    }
+    catch (error) {
+        return { pages: [], note: `The pages could not be read: ${String(error instanceof Error ? error.message : error).split('\n')[0]}` };
+    }
+    finally {
+        await browser.close();
+    }
+}
+/** The source files (not tests) most related to a feature: what it does and what its comments promise. */
+export const relatedCodeSources = (root, feature) => relatedTestSources(root, feature, 2, 6_000, 'code');

package/dist/engine/quality/model.js

@@ -0,0 +1,17 @@
+// The model Tewip writes with. Triage uses a small, fast model because the deterministic rules do
+// most of that work; planning and writing tests are open-ended, so they use a stronger one.
+// Settings: TEWIP_WRITE_MODEL (default below), TEWIP_WRITE_REASONING (default medium).
+import { join } from 'node:path';
+import { cachedClient, loadDotEnv } from '../llm/client.js';
+import { clientFor, modelChoiceFromEnv } from '../llm/providers.js';
+export const DEFAULT_WRITE_MODEL = 'gpt-5.5';
+/** The writing client, or null when no model is configured (writing needs one; triage does not). */
+export function writerFromEnv(projectRoot) {
+    loadDotEnv();
+    const choice = modelChoiceFromEnv('write');
+    if (!choice)
+        return null;
+    const client = clientFor(choice);
+    // Same request, same answer, no second charge: kept with the project like the rest of .tewip.
+    return cachedClient(client, join(projectRoot, '.tewip', 'writer-cache.jsonl'));
+}

package/dist/engine/quality/plan-command.js

@@ -0,0 +1,34 @@
+// `tewip plan`: gather the facts, ask the writing model for a plan, render it, and keep it in
+// .tewip/plans (Markdown to review, JSON for `tewip write` to build tests from). The same function
+// serves the command line and the MCP server, so an editor's assistant gets the same plan.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { noModelHelp } from '../llm/providers.js';
+import { usageLine } from '../llm/usage.js';
+import { writerFromEnv } from './model.js';
+import { gatherPlanFacts, writePlan } from './plan.js';
+import { renderPlan } from './plan-render.js';
+const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 60) || 'plan';
+/** Writes the plan into the project's .tewip/plans and returns it as Markdown, with where it went. */
+export async function planProject(cmd, progress = () => { }) {
+    const model = writerFromEnv(cmd.root);
+    if (!model)
+        throw new Error(`writing a plan needs a model.
+${noModelHelp()}`);
+    progress('Tewip is reading the project...');
+    const facts = await gatherPlanFacts(cmd);
+    progress(`  ${facts.tests.tests.length} existing test(s), ${facts.pages.length} page(s) read${facts.change ? `, ${facts.change.files.length} changed file(s)` : ''}${facts.history.length ? `, ${facts.history.length} past failure(s)` : ''}. Writing the plan...`);
+    const plan = await writePlan(facts, model);
+    const markdown = renderPlan(plan, facts, model.model);
+    const out = cmd.out ?? join(cmd.root, '.tewip', 'plans', `${slug(plan.title)}.md`);
+    mkdirSync(join(out, '..'), { recursive: true });
+    writeFileSync(out, markdown, 'utf8');
+    // The same plan as data, for `tewip write`: its scenarios, and the pages it read.
+    writeFileSync(out.replace(/\.md$/, '') + '.json', JSON.stringify({ plan, feature: facts.feature, urls: facts.pages.map((p) => p.url), model: model.model }, null, 2), 'utf8');
+    return { markdown, out };
+}
+export async function runPlan(cmd) {
+    const { markdown, out } = await planProject(cmd, (line) => console.error(line));
+    console.log(markdown);
+    console.error(`\nSaved to ${out}\n${usageLine()}`);
+}

package/dist/engine/quality/plan-render.js

@@ -0,0 +1,38 @@
+const cell = (s) => s.replaceAll('|', '/').replace(/\s+/g, ' ').trim();
+export function renderPlan(plan, facts, model) {
+    const byPriority = (p) => plan.scenarios.filter((s) => s.priority === p);
+    const lines = [
+        `# Test plan: ${plan.title}`,
+        '',
+        `> Draft by Tewip (${model}). Review before use: every scenario says what it is grounded on.`,
+        '',
+        plan.summary,
+        '',
+        '## Scope',
+        ...plan.scope.map((s) => `- ${s}`),
+        ...(plan.out_of_scope.length ? ['', '**Out of scope:**', ...plan.out_of_scope.map((s) => `- ${s}`)] : []),
+        '',
+        '## Risks',
+        '',
+        '| Severity | Risk | Why |',
+        '|---|---|---|',
+        ...plan.risks.map((r) => `| ${r.severity} | ${cell(r.risk)} | ${cell(r.why)} |`),
+        '',
+        '## Scenarios',
+    ];
+    for (const p of ['P0', 'P1', 'P2']) {
+        const xs = byPriority(p);
+        if (xs.length === 0)
+            continue;
+        lines.push('', `### ${p} (${xs.length})`);
+        for (const s of xs) {
+            lines.push('', `**${s.id}. ${s.title}** — ${s.type}${s.automate ? ', automate' : ', manual'}${s.covered_by ? ` · already covered by \`${s.covered_by}\`` : ''}`, ...(s.preconditions ? [`- Given: ${s.preconditions}`] : []), ...s.steps.map((step, i) => `${i + 1}. ${step}`), `- Expected: ${s.expected}`, `- Grounded on: ${s.grounded_on}`);
+        }
+    }
+    const automate = plan.scenarios.filter((s) => s.automate && !s.covered_by);
+    lines.push('', '## To automate next', '', automate.length ? automate.map((s) => `- ${s.id} ${s.title} (${s.priority})`).join('\n') : 'Nothing new: existing tests cover the automatable scenarios.');
+    if (plan.open_questions.length)
+        lines.push('', '## Open questions', ...plan.open_questions.map((q) => `- ${q}`));
+    lines.push('', '## What this plan was built from', `- Feature description: ${facts.feature.length > 200 ? `${facts.feature.slice(0, 200)}…` : facts.feature}`, `- Change: ${facts.change ? `${facts.change.range}, ${facts.change.files.length} file(s)` : 'none given'}`, `- Pages read: ${facts.pages.length ? facts.pages.map((p) => p.url).join(', ') : facts.pagesNote ?? 'none given'}`, `- Existing tests: ${facts.tests.tests.length} named in ${facts.tests.files} file(s)${facts.testSources?.length ? `; read in full: ${facts.testSources.map((t) => t.file).join(', ')}` : ''}`, `- Failure history: ${facts.history.length ? `${facts.history.length} test(s) Tewip diagnosed before` : 'none recorded yet'}`, '');
+    return lines.join('\n');
+}

package/dist/engine/quality/plan.js

@@ -0,0 +1,119 @@
+// Phase 6: test plans. Tewip writes a plan from facts it reads, not from imagination: the feature
+// as described, what a change touched, the pages of the running app, the tests that already exist,
+// and - what general agents do not have - the project's own failure history, so the plan weighs
+// the areas that broke or flaked before. The model proposes; everything it may rely on is listed
+// with the plan, and scenarios say what they are grounded on.
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { readJsonl } from '../../reporters/store.js';
+import { changeSummary, existingTests, readPages, relatedCodeSources, relatedTestSources } from './grounding.js';
+export const PLAN_PROMPT_VERSION = 'plan-4';
+/** Failures Tewip already diagnosed in this project (from `tewip explain` runs kept in .tewip). */
+function failureHistory(root, cap = 60) {
+    const dir = join(root, '.tewip', 'history');
+    if (!existsSync(dir))
+        return [];
+    const seen = new Map();
+    for (const project of readdirSync(dir)) {
+        for (const r of readJsonl(join(dir, project, 'triage.jsonl'))) {
+            seen.set(r.testId, r.diagnosis?.category ?? 'UNKNOWN');
+        }
+    }
+    return [...seen].slice(-cap).map(([test, category]) => `${test}: ${category}`);
+}
+export async function gatherPlanFacts(input) {
+    const { pages, note } = await readPages(input.urls ?? [], input.root);
+    return {
+        feature: input.feature,
+        change: input.diffRange ? changeSummary(input.root, input.diffRange) : null,
+        pages,
+        pagesNote: note,
+        tests: existingTests(input.root),
+        testSources: relatedTestSources(input.root, input.feature),
+        codeSources: relatedCodeSources(input.root, input.feature),
+        history: failureHistory(input.root),
+    };
+}
+const SYSTEM = `You are Tewip's test planner, a senior QA lead. Write a test plan for the feature described.
+
+Use only the facts given: the feature description, the change (files and diff), the pages of the running app (accessibility snapshots: the roles and names a user sees), the tests that already exist, and the project's failure history.
+- Name page elements only as they appear in a snapshot. If a scenario needs something no snapshot shows, say so in grounded_on ("not seen on the pages read; confirm").
+- Do not plan what an existing test already covers. Read existingTests.relatedSources: a table-driven test (a list of cases, test.each, parametrize) covers every case in its table. covered_by is either an entry copied exactly from existingTests.names, or a file from relatedSources followed by ": " and the exact case that covers the scenario (e.g. "test/query.test.ts: { input: '/?foo=1', query: { foo: undefined }, out: '/' }"), or an empty string. Partial or related coverage goes in grounded_on, never in covered_by.
+- Read the code: do not expect behaviour that contradicts what the code documents (a comment saying keys are ignored, a value is clamped...). If the intended behaviour is unclear, ask in open_questions instead of assuming.
+- Weigh the failure history: an area whose tests failed or flaked before deserves a scenario for that risk.
+- Cover more than the happy path: negative cases, boundaries, accessibility, and security where the feature touches input, access or data.
+- Prioritise: P0 breaks the feature for everyone, P1 breaks it for some or corrupts data, P2 is a lesser problem.
+- Keep steps concrete and short, as a tester would run them. Mark automate true when a stable automated check is realistic.`;
+const SCENARIO = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['id', 'title', 'type', 'priority', 'preconditions', 'steps', 'expected', 'automate', 'covered_by', 'grounded_on'],
+    properties: {
+        id: { type: 'string' },
+        title: { type: 'string' },
+        type: { type: 'string', enum: ['functional', 'negative', 'boundary', 'accessibility', 'security', 'performance', 'compatibility'] },
+        priority: { type: 'string', enum: ['P0', 'P1', 'P2'] },
+        preconditions: { type: 'string' },
+        steps: { type: 'array', items: { type: 'string' } },
+        expected: { type: 'string' },
+        automate: { type: 'boolean' },
+        covered_by: { type: 'string' },
+        grounded_on: { type: 'string' },
+    },
+};
+const SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['title', 'summary', 'scope', 'out_of_scope', 'risks', 'scenarios', 'open_questions'],
+    properties: {
+        title: { type: 'string' },
+        summary: { type: 'string' },
+        scope: { type: 'array', items: { type: 'string' } },
+        out_of_scope: { type: 'array', items: { type: 'string' } },
+        risks: {
+            type: 'array',
+            items: { type: 'object', additionalProperties: false, required: ['risk', 'why', 'severity'], properties: { risk: { type: 'string' }, why: { type: 'string' }, severity: { type: 'string', enum: ['high', 'medium', 'low'] } } },
+        },
+        scenarios: { type: 'array', items: SCENARIO },
+        open_questions: { type: 'array', items: { type: 'string' } },
+    },
+};
+function factsForModel(f) {
+    return JSON.stringify({
+        feature: f.feature,
+        change: f.change ? { range: f.change.range, files: f.change.files, diff: f.change.patch } : 'no change given',
+        pages: f.pages.length ? f.pages.map((p) => ({ url: p.url, title: p.title, accessibilitySnapshot: p.aria })) : f.pagesNote ?? 'no pages given',
+        existingTests: { files: f.tests.files, names: f.tests.tests, relatedSources: f.testSources },
+        code: f.codeSources?.length ? f.codeSources : 'not read',
+        failureHistory: f.history.length ? f.history : 'none recorded yet',
+    });
+}
+/**
+ * The model's "already covered by" claims are checked against the tests Tewip actually found: a
+ * claim naming no real test is dropped (and kept as context in grounded_on), so a scenario is never
+ * marked covered, and left out of what to automate, on the model's word alone.
+ */
+export function verifyCoverage(plan, facts) {
+    const known = new Set(facts.tests.tests);
+    const sources = facts.testSources ?? [];
+    // A cited case must appear in the file it names: its code-like parts, at least.
+    const inSource = (claim) => sources.some((src) => {
+        if (!claim.startsWith(`${src.file}: `))
+            return false;
+        const quoted = claim.slice(src.file.length + 2).match(/[A-Za-z0-9_$./?=&%+-]{3,}/g) ?? [];
+        return quoted.length > 0 && quoted.every((part) => src.content.includes(part));
+    });
+    return {
+        ...plan,
+        scenarios: plan.scenarios.map((s) => {
+            const claim = s.covered_by.trim();
+            if (!claim || known.has(claim) || inSource(claim))
+                return { ...s, covered_by: claim };
+            return { ...s, covered_by: '', grounded_on: `${s.grounded_on} (related, not a full cover: ${claim})` };
+        }),
+    };
+}
+export async function writePlan(facts, model) {
+    const raw = await model.complete({ system: SYSTEM, user: factsForModel(facts), schemaName: 'tewip_test_plan', schema: SCHEMA });
+    return verifyCoverage(JSON.parse(raw), facts);
+}