codz-cli 0.0.0-stage → 0.1.2

package/dist/skills/setupDoctor.js

@@ -0,0 +1,226 @@
+// doctor --setup: can codz run here? Environment and configuration checks,
+// separate from the project-health checks of plain `codz doctor`. Read-only.
+//
+// Every check returns pass, warn or fail with a message and, when useful, a hint.
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { TOOL_DIR } from "../core/cache.js";
+import { CONFIG_FILE } from "../core/config.js";
+import { exists, readJson, readText, walk } from "../core/fsutil.js";
+import { dirtyFiles, isGitRepo } from "../core/git.js";
+import { PATH_KEYS, validateConfig } from "../core/validateConfig.js";
+import { runTool } from "../core/proc.js";
+// From source Node runs the TypeScript itself (22.18+); the npm build (dist/) needs 20+.
+const FROM_SOURCE = import.meta.url.endsWith('.ts');
+const MIN_NODE = FROM_SOURCE ? [22, 18] : [20, 0];
+const has = (cmd, args = ['--version']) => {
+    const r = runTool(cmd, args, { timeout: 10000 });
+    return r.status === 0 ? (r.stdout || r.stderr).trim().split('\n')[0] : null;
+};
+function pkgDeps(root) {
+    const pkg = readJson(join(root, 'package.json'));
+    return { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+}
+const pubspec = (root) => readText(join(root, 'pubspec.yaml')) ?? '';
+export const CHECKS = [
+    {
+        id: 'node_version',
+        run() {
+            const [maj, min] = process.versions.node.split('.').map(Number);
+            const ok = maj > MIN_NODE[0] || (maj === MIN_NODE[0] && min >= MIN_NODE[1]);
+            return ok
+                ? { status: 'pass', message: `v${process.versions.node}` }
+                : { status: 'fail', message: `Node v${process.versions.node} is older than ${MIN_NODE.join('.')}.`, hint: FROM_SOURCE ? 'Run from source, codz needs Node 22.18 or newer (or run npm run build to use Node 20+). Install it with nvm, fnm or from nodejs.org.' : 'codz needs Node 20 or newer. Install it with nvm, fnm or from nodejs.org.' };
+        },
+    },
+    {
+        id: 'git_present',
+        run({ root }) {
+            if (!has('git'))
+                return { status: 'warn', message: 'git is not installed.', hint: 'codz still works, but it cannot warn you about uncommitted changes before writing.' };
+            return isGitRepo(root) ? { status: 'pass', message: 'git repository' } : { status: 'warn', message: 'This project is not a git repository.', hint: 'Run git init and commit, so every codz change is a reviewable diff.' };
+        },
+    },
+    {
+        id: 'git_clean',
+        run({ root }) {
+            if (!isGitRepo(root))
+                return { status: 'pass', message: 'not a git repository (skipped)' };
+            const dirty = dirtyFiles(root).filter((f) => f !== CONFIG_FILE);
+            return dirty.length
+                ? { status: 'warn', message: `${dirty.length} uncommitted change${dirty.length === 1 ? '' : 's'} (${dirty.slice(0, 3).join(', ')}${dirty.length > 3 ? ', …' : ''}).`, hint: 'Commands that write refuse a dirty tree unless you pass --allow-dirty.' }
+                : { status: 'pass', message: 'working tree clean' };
+        },
+    },
+    {
+        id: 'config_found',
+        run({ configText }) {
+            return configText !== null ? { status: 'pass', message: CONFIG_FILE } : { status: 'fail', message: `No ${CONFIG_FILE} in this folder or above it.`, hint: 'Create it with: codz init' };
+        },
+    },
+    {
+        id: 'config_valid',
+        run({ root, configText }) {
+            if (configText === null)
+                return { status: 'fail', message: 'no config to check', hint: 'codz init' };
+            const issues = validateConfig(configText, root).filter((i) => !i.key || !PATH_KEYS.has(i.key));
+            const errors = issues.filter((i) => i.level === 'error');
+            if (errors.length)
+                return { status: 'fail', message: errors.map((e) => e.message).join(' '), hint: errors[0].hint ?? 'See every problem with: codz config check' };
+            if (issues.length)
+                return { status: 'warn', message: issues.map((e) => e.message).join(' '), hint: 'See every problem with: codz config check' };
+            return { status: 'pass', message: 'parses; known keys and values' };
+        },
+    },
+    {
+        id: 'config_paths',
+        run({ root, configText }) {
+            if (configText === null)
+                return { status: 'pass', message: 'no config (skipped)' };
+            let issues;
+            try {
+                issues = validateConfig(configText, root).filter((i) => i.key && PATH_KEYS.has(i.key));
+            }
+            catch {
+                return { status: 'pass', message: 'skipped' };
+            }
+            const errors = issues.filter((i) => i.level === 'error');
+            if (errors.length)
+                return { status: 'fail', message: errors.map((e) => e.message).join(' '), hint: errors[0].hint };
+            if (issues.length)
+                return { status: 'warn', message: issues.map((e) => e.message).join(' '), hint: issues[0].hint };
+            return { status: 'pass', message: 'every path exists inside the project' };
+        },
+    },
+    {
+        id: 'gitignore',
+        run({ root }) {
+            if (isGitRepo(root)) {
+                const r = spawnSync('git', ['check-ignore', '-q', `${TOOL_DIR}/cache/map.json`], { cwd: root });
+                return r.status === 0 ? { status: 'pass', message: `${TOOL_DIR}/ is ignored` } : { status: 'warn', message: `${TOOL_DIR}/ is not in .gitignore.`, hint: `Add a line "${TOOL_DIR}/" to .gitignore; it holds the cache, backups and history.` };
+            }
+            const gi = readText(join(root, '.gitignore')) ?? '';
+            return /^\/?\.codz\/?$/m.test(gi) ? { status: 'pass', message: `${TOOL_DIR}/ is ignored` } : { status: 'warn', message: `${TOOL_DIR}/ is not in .gitignore.`, hint: `Add a line "${TOOL_DIR}/" to .gitignore.` };
+        },
+    },
+    {
+        id: 'framework_supported',
+        run({ adapter }) {
+            return adapter.id === 'generic'
+                ? { status: 'warn', message: 'No Next.js or Flutter project was found, so only explain and doctor work.', hint: 'Run codz from the folder with package.json (Next.js) or pubspec.yaml (Flutter).' }
+                : { status: 'pass', message: `${adapter.id}@${adapter.version}` };
+        },
+    },
+    {
+        id: 'unsupported_libs',
+        run({ root, adapter }) {
+            const found = [];
+            if (adapter.id === 'nextjs') {
+                if (!exists(join(root, 'app')) && !exists(join(root, 'src/app')) && (exists(join(root, 'pages')) || exists(join(root, 'src/pages'))))
+                    found.push('Pages Router (api add and mocks expect the App Router; route add works)');
+                if (pkgDeps(root).swr)
+                    found.push('SWR (hooks are written for TanStack Query only)');
+            }
+            else if (adapter.id === 'flutter') {
+                const spec = pubspec(root);
+                if (/^\s+http:/m.test(spec) && !/^\s+dio:/m.test(spec))
+                    found.push('the http package (api add writes Dio code)');
+                if (/^\s+chopper:/m.test(spec))
+                    found.push('Chopper (api add writes Dio repositories or Retrofit clients)');
+            }
+            return found.length
+                ? { status: 'warn', message: `Not supported yet: ${found.join('; ')}.`, hint: 'codz still runs; generated code follows its own style for these.' }
+                : { status: 'pass', message: 'none found' };
+        },
+    },
+    {
+        id: 'formatter',
+        run({ root, adapter }) {
+            if (adapter.id === 'nextjs' || adapter.id === 'react-native') {
+                return exists(join(root, 'node_modules/.bin/prettier')) || exists(join(root, 'node_modules/prettier'))
+                    ? { status: 'pass', message: 'prettier' }
+                    : { status: 'warn', message: 'Prettier is not installed in this project. Code is written in the detected style but not formatted.', hint: 'npm i -D prettier' };
+            }
+            if (adapter.id === 'flutter') {
+                const v = has('dart');
+                return v ? { status: 'pass', message: v } : { status: 'warn', message: 'Dart SDK not found. Code will be written but not formatted.', hint: 'Install Flutter and make sure dart is on your PATH.' };
+            }
+            return { status: 'pass', message: 'not needed' };
+        },
+    },
+    {
+        id: 'analyzer',
+        run({ root, adapter }) {
+            if (adapter.id === 'nextjs' || adapter.id === 'react-native') {
+                return exists(join(root, 'node_modules/typescript'))
+                    ? { status: 'pass', message: 'typescript' }
+                    : { status: 'warn', message: 'typescript is not installed, so changes are not checked for compile errors after applying.', hint: 'npm install (TypeScript is in most Next.js projects already)' };
+            }
+            if (adapter.id === 'flutter') {
+                if (!has('dart'))
+                    return { status: 'warn', message: 'Dart SDK not found, so changes are not analyzed after applying.', hint: 'Install Flutter.' };
+                return exists(join(root, '.dart_tool/package_config.json'))
+                    ? { status: 'pass', message: 'dart analyze' }
+                    : { status: 'warn', message: 'flutter pub get has not been run, so dart analyze is skipped.', hint: 'flutter pub get' };
+            }
+            return { status: 'pass', message: 'not needed' };
+        },
+    },
+    {
+        id: 'scan_cache',
+        run({ root }) {
+            const path = join(root, TOOL_DIR, 'cache', 'map.json');
+            if (!exists(path))
+                return { status: 'pass', message: 'no cache yet; it is built on the next command' };
+            const cache = readJson(path);
+            if (!cache || !cache.map)
+                return { status: 'warn', message: 'The scan cache is unreadable.', hint: 'It is rebuilt automatically; to force it now: codz explain --rescan' };
+            return { status: 'pass', message: 'readable (rebuilt automatically when files or codz change)' };
+        },
+    },
+    {
+        id: 'history_state',
+        run({ root }) {
+            const leftovers = walk(root, '.', { maxFiles: 50000 }).filter((f) => f.endsWith('.codz-tmp'));
+            if (leftovers.length)
+                return { status: 'fail', message: `Half-written files from an interrupted apply: ${leftovers.slice(0, 3).join(', ')}.`, hint: 'Delete the .codz-tmp files; the real files were not replaced.' };
+            const histPath = join(root, TOOL_DIR, 'history.json');
+            if (!exists(histPath))
+                return { status: 'pass', message: 'no changes applied yet' };
+            const hist = readJson(histPath);
+            if (!Array.isArray(hist))
+                return { status: 'fail', message: `${TOOL_DIR}/history.json is unreadable, so undo cannot work.`, hint: `Move ${TOOL_DIR}/history.json aside; codz starts a new history.` };
+            const last = [...hist].reverse().find((h) => !h.undone);
+            if (last && !exists(join(root, TOOL_DIR, 'backups', last.id)))
+                return { status: 'warn', message: `The backup for the last change (${last.id}) is missing, so it cannot be undone.` };
+            return { status: 'pass', message: `${hist.length} change${hist.length === 1 ? '' : 's'} in history` };
+        },
+    },
+];
+export function runSetupDoctor(root, adapter) {
+    const ctx = { root, adapter, configText: readText(join(root, CONFIG_FILE)) };
+    const checks = CHECKS.map((c) => {
+        try {
+            return { id: c.id, ...c.run(ctx) };
+        }
+        catch (e) {
+            return { id: c.id, status: 'warn', message: `The check could not run: ${e.message}` };
+        }
+    });
+    const summary = { pass: 0, warn: 0, fail: 0 };
+    for (const c of checks)
+        summary[c.status]++;
+    return { checks, summary };
+}
+export function renderSetupDoctor(r, header, color) {
+    const paint = (s, t) => (!color ? t : s === 'fail' ? `\x1b[31m${t}\x1b[0m` : s === 'warn' ? `\x1b[33m${t}\x1b[0m` : `\x1b[32m${t}\x1b[0m`);
+    const width = Math.max(...r.checks.map((c) => c.id.length));
+    const lines = [header];
+    for (const c of r.checks) {
+        lines.push(`  ${paint(c.status, c.status.padEnd(4))}  ${c.id.padEnd(width)}  ${c.message}`);
+        if (c.hint && c.status !== 'pass')
+            lines.push(`  ${' '.repeat(4)}  ${' '.repeat(width)}  → ${c.hint}`);
+    }
+    lines.push(`Summary: ${r.summary.pass} pass, ${r.summary.warn} warn, ${r.summary.fail} fail`);
+    return lines.join('\n');
+}

package/dist/skills/templatesCmd.js

@@ -0,0 +1,32 @@
+// templates list | templates init [id...]: see which templates the project
+// customizes, and start one from a file that reproduces codz's own output.
+import { join } from 'node:path';
+import { buildChangeSet } from "../core/changeset.js";
+import { exists } from "../core/fsutil.js";
+import { TEMPLATES, templatesFolder } from "../core/templates.js";
+import { ToolError } from "../core/types.js";
+export function listTemplates(root) {
+    const folder = templatesFolder(root);
+    return { folder, templates: TEMPLATES.map((t) => ({ id: t.id, about: t.about, custom: exists(join(root, folder, `${t.id}.tmpl`)), placeholders: Object.keys(t.vars) })) };
+}
+export function planTemplatesInit(root, ids) {
+    const folder = templatesFolder(root);
+    const unknown = ids.filter((id) => !TEMPLATES.some((t) => t.id === id));
+    if (unknown.length)
+        throw new ToolError('bad_template', `Unknown template ${unknown.join(', ')}.`, `Templates: ${TEMPLATES.map((t) => t.id).join(', ')}`);
+    const chosen = TEMPLATES.filter((t) => !ids.length || ids.includes(t.id));
+    const files = new Map();
+    const summary = [];
+    for (const t of chosen) {
+        const file = `${folder}/${t.id}.tmpl`;
+        if (exists(join(root, file)))
+            continue;
+        files.set(file, t.example);
+        summary.push(`Create ${file}: ${t.about} (placeholders: ${Object.keys(t.vars).map((v) => `{{${v}}}`).join(', ')})`);
+    }
+    if (!files.size)
+        summary.push(`Every chosen template already exists in ${folder}.`);
+    else
+        summary.push('Edit them and commit them; codz uses them from the next command on. {{default}} is what codz would write.');
+    return buildChangeSet(root, 'templates init', { files, summary, warnings: [], generated: [] });
+}

package/dist/skills/testgen.js

@@ -0,0 +1,331 @@
+// test add <endpoint>... | --all: unit tests for API functions, with the
+// network faked so they run offline and fast.
+//
+//   Next.js   Vitest (or Jest when the project uses it): fetch, or the axios
+//             instance's method, is replaced with a spy that answers example
+//             data; the test checks the method, the URL and the parsed result,
+//             and (for fetch) that a failed response throws.
+//   Flutter   flutter_test: Dio gets a fake HttpClientAdapter; the test checks
+//             the method, the path and the parsed result, and that a 500 throws
+//             a DioException.
+//
+// Example data comes from the models, like mock add. One test file per API
+// file; endpoints that already have a test are skipped.
+import { join, posix } from 'node:path';
+import { loadMap } from "../core/cache.js";
+import { buildChangeSet } from "../core/changeset.js";
+import { loadConfig } from "../core/config.js";
+import { readJson, readText, walk } from "../core/fsutil.js";
+import { ToolError } from "../core/types.js";
+import { readMethod, splitParams } from "../adapters/getx.js";
+import { importPath } from "../adapters/nextjs.js";
+import { findDeclaration } from "./apiEdit.js";
+import { exampleFor, unwrapsData } from "./mock.js";
+function pick(map, opts) {
+    if (opts.all)
+        return map.endpoints;
+    if (!opts.endpoints.length)
+        throw new ToolError('bad_args', 'Which endpoints? Usage: codz test add <endpoint>... or --all');
+    return opts.endpoints.map((n) => {
+        const ep = map.endpoints.find((e) => e.name === n) ?? map.endpoints.find((e) => e.name.toLowerCase() === n.toLowerCase());
+        if (!ep)
+            throw new ToolError('no_endpoint', `No endpoint called ${n} was found.`, `Endpoints: ${map.endpoints.map((e) => e.name).join(', ')}`);
+        return ep;
+    });
+}
+export async function planTestAdd(root, adapter, opts) {
+    const { map } = await loadMap(root, adapter, loadConfig(root).conventions);
+    const eps = pick(map, opts);
+    if (!eps.length)
+        throw new ToolError('no_endpoints', 'This project has no endpoints to test yet.', 'Add one with: codz api add');
+    if (adapter.id === 'nextjs' || adapter.id === 'react-native' || adapter.id === 'react')
+        return nextTests(root, map, eps);
+    if (adapter.id === 'flutter')
+        return flutterTests(root, map, eps);
+    if (adapter.id === 'android')
+        return (await import("./androidTests.js")).androidTests(root, map, eps);
+    throw new ToolError('not_supported', `test add writes tests for Next.js, React, React Native, Flutter and Android; ${adapter.id === 'ios' ? 'iOS (XCTest) is not supported yet' : `this project uses the ${adapter.id} adapter`}.`, adapter.id === 'ios' ? 'Test the APIClient methods with XCTest and a URLProtocol stub for now; codz will write these later.' : undefined);
+}
+/** Argument values for a call: path parameters get 1 or 'abc', the body gets example data. */
+function exampleArg(type, name, map) {
+    if (/^(number|int|double)$/.test(type))
+        return 1;
+    if (/^(string|String)$/.test(type))
+        return name === 'id' || /Id$/.test(name) ? 'abc' : 'text';
+    return exampleFor(type.replace(/^Partial<(.+)>$/, '$1'), map, name);
+}
+/** A JavaScript literal in the project's quote style. */
+function tsLiteral(v, q) {
+    if (typeof v === 'string')
+        return q === "'" ? `'${v.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'` : JSON.stringify(v);
+    if (v === null || typeof v !== 'object')
+        return String(v);
+    if (Array.isArray(v))
+        return `[${v.map((x) => tsLiteral(x, q)).join(', ')}]`;
+    const IDENT = /^[A-Za-z_$][\w$]*$/;
+    return `{ ${Object.entries(v).map(([k, x]) => `${IDENT.test(k) ? k : tsLiteral(k, q)}: ${tsLiteral(x, q)}`).join(', ')} }`.replace('{  }', '{}');
+}
+const fill = (path, values) => path.replace(/\{([^/}]+)\}/g, (_m, n) => String(values.get(n) ?? values.get(n.replace(/[-_](\w)/g, (_x, ch) => ch.toUpperCase())) ?? 1));
+// ---------------- Next.js ----------------
+function nextTests(root, map, eps) {
+    const c = map.conventions;
+    const pkg = readJson(join(root, 'package.json')) ?? {};
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    // React Native apps test with Jest (jest-expo on Expo) even before it is installed; web apps default to Vitest.
+    const rn = map.framework === 'react-native';
+    const jest = !deps.vitest && (!!(deps.jest || deps['@types/jest'] || deps['jest-expo']) || rn);
+    const spy = jest ? 'jest' : 'vi';
+    const existingTests = walk(root, '.', { exts: ['.ts', '.tsx'] }).filter((f) => /\.(test|spec)\.tsx?$/.test(f));
+    const inTestsFolder = existingTests.length > 0 && existingTests.filter((f) => f.includes('/__tests__/')).length * 2 > existingTests.length;
+    const q = c.quote === 'double' ? '"' : "'";
+    const semi = c.semicolons === 'false' ? '' : ';';
+    const files = new Map();
+    const summary = [];
+    const warnings = [];
+    let warned204 = false;
+    if (!deps.vitest && !jest)
+        warnings.push('No test runner found in package.json; the tests are written for Vitest. Add it with: npm i -D vitest (then run npx vitest).');
+    if (jest && !deps.jest && !deps['jest-expo'])
+        warnings.push(c.flavor === 'expo' ? 'No test runner found in package.json; the tests are written for Jest. Add it with: npx expo install jest-expo jest (then run npx jest).' : 'No test runner found in package.json; the tests are written for Jest. Add it with: npm i -D jest (then run npx jest).');
+    const axios = c.http === 'axios';
+    const inst = (c.axiosInstance || 'axios').replace(/^default:/, '');
+    const byFile = new Map();
+    for (const ep of eps)
+        byFile.set(ep.file, [...(byFile.get(ep.file) ?? []), ep]);
+    for (const [file, list] of byFile) {
+        const dir = posix.dirname(file);
+        const base = posix.basename(file).replace(/\.(tsx?|jsx?)$/, '');
+        const testFile = inTestsFolder ? `${dir}/__tests__/${base}.test.ts` : `${dir}/${base}.test.ts`;
+        let text = files.get(testFile) ?? readText(join(root, testFile)) ?? '';
+        const src = readText(join(root, file)) ?? '';
+        const helperText = c.httpHelperFile ? readText(join(root, c.httpHelperFile)) ?? files.get(c.httpHelperFile) ?? '' : '';
+        const jsonOnly = /\.json\(\)/.test(helperText) && !/\b204\b|content-length|no content/i.test(helperText);
+        const names = [];
+        const blocks = [];
+        for (const ep of list) {
+            if (new RegExp(`describe\\(\\s*['"\`]${ep.name}['"\`]`).test(text))
+                continue;
+            const decl = findDeclaration(src, ep.name, 'ts');
+            if (!decl) {
+                warnings.push(`Could not read ${ep.name} in ${file}; no test written for it.`);
+                continue;
+            }
+            const args = splitParams(decl.params).map((p) => /^\s*(\w+)(\??)\s*:\s*([\s\S]+)$/.exec(p)).filter((m) => !!m);
+            const values = new Map();
+            const callArgs = [];
+            for (const [, name, optional, type] of args) {
+                if (optional)
+                    continue;
+                const v = exampleArg(type.trim(), name, map);
+                values.set(name, v);
+                callArgs.push(tsLiteral(v, q));
+            }
+            const type = (ep.response ?? '').replace(/^Promise<(.*)>$/, '$1');
+            const voidish = !type || /^(void|unknown)$/.test(type) || ep.method === 'DELETE';
+            const value = voidish ? null : exampleFor(type, map);
+            const body = unwrapsData(src.slice(decl.start, decl.end), c) ? { data: value } : value;
+            const url = fill(ep.path, values);
+            const call = `${ep.name}(${callArgs.join(', ')})`;
+            // A helper that always reads JSON throws on 204 No Content: test with an empty JSON reply, and say so once.
+            const no204 = voidish && !axios && jsonOnly;
+            if (no204 && !warned204) {
+                warned204 = true;
+                warnings.push(`${c.httpHelperFile}: ${c.httpHelper}() always reads the body as JSON, so a 204 No Content reply (common for DELETE) will throw "Unexpected end of JSON input". The tests reply 200 with null; to handle 204, return undefined when res.status === 204 before res.json().`);
+            }
+            const L = [`describe(${q}${ep.name}${q}, () => {`];
+            if (axios) {
+                const verb = ep.method.toLowerCase();
+                L.push(`  it(${q}calls ${ep.method} ${ep.path} through ${inst} and returns the data${q}, async () => {`, `    const body = ${tsLiteral(body, q)}${semi}`, `    const request = ${spy}.spyOn(${inst}, ${q}${verb}${q}).mockResolvedValue({ data: body } as never)${semi}`, `    const result = await ${call}${semi}`, `    expect(String(request.mock.calls[0][0])).toContain(${q}${url}${q})${semi}`, voidish ? `    expect(result).toBeUndefined()${semi}` : `    expect(result).toEqual(${unwrapsData(src.slice(decl.start, decl.end), c) ? 'body.data' : 'body'})${semi}`, '  })' + semi);
+            }
+            else {
+                L.push(`  it(${q}calls ${ep.method} ${ep.path} and returns the parsed body${q}, async () => {`, `    const body = ${tsLiteral(body, q)}${semi}`, `    const fetchMock = ${spy}.spyOn(globalThis, ${q}fetch${q}).mockResolvedValue(new Response(${voidish ? (no204 ? `${q}null${q}` : 'null') : 'JSON.stringify(body)'}, { status: ${voidish && !no204 ? 204 : 200}, headers: { ${q}Content-Type${q}: ${q}application/json${q} } }))${semi}`, `    const result = await ${call}${semi}`, `    const [url, init] = fetchMock.mock.calls[0]${semi}`, `    expect(String(url)).toContain(${q}${url}${q})${semi}`, `    expect(init?.method ?? ${q}GET${q}).toBe(${q}${ep.method}${q})${semi}`, voidish ? null : `    expect(result).toEqual(${unwrapsData(src.slice(decl.start, decl.end), c) ? 'body.data' : 'body'})${semi}`, '  })' + semi, '', `  it(${q}throws when the server answers with an error${q}, async () => {`, `    ${spy}.spyOn(globalThis, ${q}fetch${q}).mockResolvedValue(new Response(${q}nope${q}, { status: 500 }))${semi}`, `    await expect(${call}).rejects.toThrow()${semi}`, '  })' + semi);
+            }
+            L.push('})' + semi);
+            blocks.push(L.filter((l) => l !== null).join('\n'));
+            names.push(ep.name);
+        }
+        if (!names.length)
+            continue;
+        const own = inTestsFolder ? `../${base}` : `./${base}`;
+        if (!text) {
+            const header = [];
+            // Jest's globals are imported from @jest/globals (installed with Jest), so they are typed without @types/jest.
+            if (!jest || !deps['@types/jest'] || deps['@jest/globals'])
+                header.push(`import { afterEach, describe, expect, it, ${spy} } from ${q}${jest ? '@jest/globals' : 'vitest'}${q}${semi}`);
+            if (axios && inst !== 'axios' && c.axiosInstanceFile) {
+                const p = importPath(testFile, c.axiosInstanceFile, { ...c, importStyle: 'relative' });
+                header.push((c.axiosInstance ?? '').startsWith('default:') ? `import ${inst} from ${q}${p}${q}${semi}` : `import { ${inst} } from ${q}${p}${q}${semi}`);
+            }
+            else if (axios)
+                header.push(`import axios from ${q}axios${q}${semi}`);
+            header.push(`import { ${names.sort().join(', ')} } from ${q}${own}${q}${semi}`, '', `afterEach(() => {`, `  ${spy}.restoreAllMocks()${semi}`, `})${semi}`);
+            text = header.join('\n');
+        }
+        else {
+            // Add the tested functions to the import of the API file.
+            const m = new RegExp(`import \\{([^}]*)\\} from ['"]${own.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')}['"];?`).exec(text);
+            if (m) {
+                const have = m[1].split(',').map((x) => x.trim()).filter(Boolean);
+                text = text.replace(m[0], `import { ${[...new Set([...have, ...names])].sort().join(', ')} } from ${q}${own}${q}${semi}`);
+            }
+            else
+                text = `import { ${names.sort().join(', ')} } from ${q}${own}${q}${semi}\n${text}`;
+        }
+        text = `${text.replace(/\s*$/, '\n')}\n${blocks.join('\n\n')}\n`;
+        files.set(testFile, text);
+        summary.push(`${readText(join(root, testFile)) === null ? 'Create' : 'Update'} ${testFile}: tests for ${names.join(', ')}`);
+    }
+    if (!files.size)
+        summary.push('Every chosen endpoint already has a test.');
+    else
+        summary.push(`Run them with: ${jest ? 'npx jest' : 'npx vitest run'}`);
+    return buildChangeSet(root, 'test add', { files, summary, warnings, generated: [] });
+}
+// ---------------- Flutter ----------------
+function dartLiteral(v, indent = '') {
+    if (v === null || v === undefined)
+        return 'null';
+    if (typeof v === 'string')
+        return `'${v.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\$/g, '\\$')}'`;
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return String(v);
+    const inner = `${indent}  `;
+    if (Array.isArray(v))
+        return v.length ? `[\n${v.map((x) => `${inner}${dartLiteral(x, inner)},`).join('\n')}\n${indent}]` : '[]';
+    const entries = Object.entries(v);
+    return entries.length ? `{\n${entries.map(([k, x]) => `${inner}${dartLiteral(k)}: ${dartLiteral(x, inner)},`).join('\n')}\n${indent}}` : '<String, dynamic>{}';
+}
+const FAKE_ADAPTER = [
+    '/// Answers every request with [status] and [body], and remembers the request.',
+    'class _FakeAdapter implements HttpClientAdapter {',
+    '  _FakeAdapter(this.status, this.body);',
+    '',
+    '  final int status;',
+    '  final Object? body;',
+    '  RequestOptions? last;',
+    '',
+    '  @override',
+    '  Future<ResponseBody> fetch(RequestOptions options, Stream<Uint8List>? requestStream, Future<void>? cancelFuture) async {',
+    '    last = options;',
+    '    return ResponseBody.fromString(jsonEncode(body), status, headers: {',
+    '      Headers.contentTypeHeader: [Headers.jsonContentType],',
+    '    });',
+    '  }',
+    '',
+    '  @override',
+    '  void close({bool force = false}) {}',
+    '}',
+].join('\n');
+function flutterTests(root, map, eps) {
+    const c = map.conventions;
+    const pkg = c.packageName;
+    const files = new Map();
+    const summary = [];
+    const warnings = [];
+    const pubspec = readText(join(root, 'pubspec.yaml')) ?? '';
+    if (!/^\s+flutter_test:/m.test(pubspec))
+        warnings.push('flutter_test is not in dev_dependencies; add it (it ships with the Flutter SDK): dev_dependencies: flutter_test: sdk: flutter');
+    const byFile = new Map();
+    for (const ep of eps)
+        byFile.set(ep.file, [...(byFile.get(ep.file) ?? []), ep]);
+    for (const [file, list] of byFile) {
+        const testFile = `test/${file.replace(/^lib\//, '').replace(/\.dart$/, '_test.dart')}`;
+        const existing = files.get(testFile) ?? readText(join(root, testFile));
+        const src = readText(join(root, file)) ?? '';
+        const groups = [];
+        const names = [];
+        const modelFiles = new Set();
+        for (const ep of list) {
+            const sig = readMethod(src, ep.name);
+            if (!sig?.repoClass) {
+                warnings.push(`Could not read ${ep.name} in ${file}; no test written for it.`);
+                continue;
+            }
+            if (existing && new RegExp(`group\\(\\s*'${sig.repoClass}\\.${ep.name}'`).test(existing))
+                continue;
+            const ctorTakesDio = new RegExp(`\\b${sig.repoClass}\\s*\\(\\s*(?:this\\.\\w+|Dio\\s+\\w+)\\s*[,)]|factory\\s+${sig.repoClass}\\s*\\(\\s*Dio\\b`).test(src);
+            if (!ctorTakesDio) {
+                warnings.push(`${sig.repoClass} does not take its Dio in the constructor, so ${ep.name} cannot be tested with a fake adapter; no test written.`);
+                continue;
+            }
+            const values = new Map();
+            const args = [];
+            for (const part of splitParams(sig.params.replace(/@\w+(?:\([^)]*\))?\s*/g, ''))) {
+                if (part.startsWith('{') || part.startsWith('['))
+                    continue; // optional query parameters
+                const m = /^([\w<>?, ]+?)\s+(\w+)$/.exec(part.trim());
+                if (!m)
+                    continue;
+                const [type, name] = [m[1].trim(), m[2]];
+                if (name === 'body') {
+                    const model = map.models.find((x) => x.name === type.replace(/\?$/, ''));
+                    if (model) {
+                        args.push(`${model.name}.fromJson(${dartLiteral(exampleFor(model.name, map), '        ')})`);
+                        if (model.file !== file)
+                            modelFiles.add(model.file);
+                    }
+                    else
+                        args.push(dartLiteral(exampleFor(type, map, name)));
+                    continue;
+                }
+                const v = /^int\??$/.test(type) ? 1 : /^double\??$/.test(type) ? 1.5 : 'abc';
+                values.set(name, v);
+                args.push(dartLiteral(v));
+            }
+            const type = sig.returnType;
+            const voidish = /^void$/.test(type) || ep.method === 'DELETE';
+            const value = voidish ? null : exampleFor(type, map);
+            const decl = findDeclaration(src, ep.name, 'dart');
+            const body = decl && unwrapsData(src.slice(decl.start, decl.end), c) ? { data: value } : value;
+            const list2 = /^List<(.+)>$/.exec(type);
+            const model = map.models.find((m) => m.name === (list2?.[1] ?? type).replace(/\?$/, ''));
+            // Imported only when the test names it (isA<Model>); a list is checked by its length.
+            if (model && model.file !== file && !list2 && !voidish)
+                modelFiles.add(model.file);
+            const expectResult = voidish ? null : list2 ? `      expect(result, hasLength(${Array.isArray(value) ? value.length : 1}));` : model ? `      expect(result, isA<${model.name}>());` : '      expect(result, isNotNull);';
+            const call = `${sig.repoClass}(dio).${ep.name}(${args.join(', ')})`;
+            groups.push([
+                `  group('${sig.repoClass}.${ep.name}', () {`,
+                `    test('calls ${ep.method} ${ep.path} and parses the response', () async {`,
+                `      final adapter = _FakeAdapter(${voidish ? 204 : 200}, ${dartLiteral(body, '      ')});`,
+                "      final dio = Dio(BaseOptions(baseUrl: 'https://api.test'))..httpClientAdapter = adapter;",
+                `      ${voidish ? '' : 'final result = '}await ${call};`,
+                `      expect(adapter.last!.method, '${ep.method}');`,
+                `      expect(adapter.last!.uri.path, endsWith('${fill(ep.path, values).replace(/^https?:\/\/[^/]+/, '')}'));`,
+                expectResult,
+                '    });',
+                '',
+                "    test('throws when the server fails', () async {",
+                "      final dio = Dio(BaseOptions(baseUrl: 'https://api.test'))..httpClientAdapter = _FakeAdapter(500, {'error': 'nope'});",
+                `      await expectLater(${call}, throwsA(isA<DioException>()));`,
+                '    });',
+                '  });',
+            ]
+                .filter((l) => l !== null)
+                .join('\n'));
+            names.push(ep.name);
+        }
+        if (!names.length)
+            continue;
+        let text;
+        const uri = (f) => (pkg ? `package:${pkg}/${f.replace(/^lib\//, '')}` : posix.relative(posix.dirname(testFile), f));
+        if (existing) {
+            const close = existing.lastIndexOf('}');
+            text = `${existing.slice(0, close).replace(/\s*$/, '\n')}\n${groups.join('\n\n')}\n}\n`;
+            for (const f of modelFiles)
+                if (!existing.includes(uri(f)))
+                    text = text.replace(/(import 'package:flutter_test\/flutter_test.dart';\n)/, `$1import '${uri(f)}';\n`);
+        }
+        else {
+            const imports = ["import 'dart:convert';", "import 'dart:typed_data';", '', "import 'package:dio/dio.dart';", "import 'package:flutter_test/flutter_test.dart';", `import '${uri(file)}';`, ...[...modelFiles].sort().map((f) => `import '${uri(f)}';`)];
+            text = [...imports, '', FAKE_ADAPTER, '', 'void main() {', groups.join('\n\n'), '}', ''].join('\n');
+        }
+        files.set(testFile, text);
+        summary.push(`${existing ? 'Update' : 'Create'} ${testFile}: tests for ${names.join(', ')}`);
+    }
+    if (!files.size)
+        summary.push('Every chosen endpoint already has a test.');
+    else
+        summary.push('Run them with: flutter test');
+    return buildChangeSet(root, 'test add', { files, summary, warnings, generated: [] });
+}