codz-cli 0.0.0-stage → 0.1.2

package/dist/skills/doctor.js

@@ -0,0 +1,304 @@
+// doctor: read-only health checks over the project map.
+//
+//   locales     missing keys (error), extra keys, untranslated texts, unused keys
+//   api         calls with no error handling, endpoints without a typed response
+//   urls        hardcoded http(s) URLs outside config / network setup
+//   models      models nothing uses
+//
+// Exit code 1 when any error is found (or any warning with --strict).
+import { join } from 'node:path';
+import { matchBrace } from "../adapters/source.js";
+import { loadMap } from "../core/cache.js";
+import { loadConfig } from "../core/config.js";
+import { readText, walk } from "../core/fsutil.js";
+import { readLocales } from "./locale.js";
+const lineOf = (text, index) => text.slice(0, index).split('\n').length;
+/** Code files with comments blanked (same length, so offsets and lines stay right). */
+function codeFiles(root, map) {
+    const exts = map.framework === 'flutter' ? ['.dart'] : map.framework === 'android' ? ['.kt'] : ['.ts', '.tsx', '.js', '.jsx', '.mjs'];
+    const start = map.framework === 'flutter' ? 'lib' : '.';
+    const out = new Map();
+    for (const f of walk(root, start, { exts, extraIgnored: ['.codz', 'test', '__tests__', 'generated', 'build', '.gradle', 'androidTest'] })) {
+        if (/\.(g|freezed|d)\.(dart|ts)$/.test(f) || /(^|\/)(next|tailwind|postcss|eslint|vitest|jest)\.config\./.test(f))
+            continue;
+        out.set(f, stripComments(readText(join(root, f)) ?? ''));
+    }
+    return out;
+}
+function stripComments(t) {
+    let out = '';
+    let i = 0;
+    while (i < t.length) {
+        const c = t[i];
+        const n = t[i + 1];
+        if (c === '/' && n === '/') {
+            const end = t.indexOf('\n', i);
+            const stop = end === -1 ? t.length : end;
+            out += ' '.repeat(stop - i);
+            i = stop;
+        }
+        else if (c === '/' && n === '*') {
+            const end = t.indexOf('*/', i + 2);
+            const stop = end === -1 ? t.length : end + 2;
+            out += t.slice(i, stop).replace(/[^\n]/g, ' ');
+            i = stop;
+        }
+        else if (c === "'" || c === '"' || c === '`') {
+            let j = i + 1;
+            while (j < t.length && t[j] !== c && !(c !== '`' && t[j] === '\n'))
+                j += t[j] === '\\' ? 2 : 1;
+            out += t.slice(i, j + 1);
+            i = j + 1;
+        }
+        else {
+            out += c;
+            i++;
+        }
+    }
+    return out;
+}
+// ---------------- locales ----------------
+function checkLocales(root, map, code, findings) {
+    let set;
+    try {
+        set = readLocales(root, map);
+    }
+    catch (e) {
+        findings.push({ check: 'locales', severity: 'error', message: e.message });
+        return;
+    }
+    if (!set || !set.files.size)
+        return;
+    const def = set.keys.get(set.defaultLang) ?? new Map();
+    for (const [lang, keys] of set.keys) {
+        if (lang === set.defaultLang)
+            continue;
+        const file = set.files.get(lang);
+        const missing = [...def.keys()].filter((k) => !keys.has(k));
+        const extra = [...keys.keys()].filter((k) => !def.has(k));
+        const same = [...keys.entries()].filter(([k, v]) => def.get(k) === v && /[A-Za-z]{3,}/.test(v) && !/^[A-Z0-9_]+$/.test(v));
+        if (missing.length) {
+            findings.push({ check: 'locales', severity: 'error', file, message: `${lang} is missing ${missing.length} key${missing.length === 1 ? '' : 's'}: ${list(missing)}`, fix: `codz doctor --fix adds them with the ${set.defaultLang} text, or: codz locale key ${missing[0]} "${(def.get(missing[0]) ?? '').replace(/"/g, '\\"')}" --value ${lang}="<${lang} text>" --force`, data: { kind: 'missingKeys', lang, keys: missing } });
+        }
+        if (extra.length)
+            findings.push({ check: 'locales', severity: 'warning', file, message: `${lang} has ${extra.length} key${extra.length === 1 ? '' : 's'} the ${set.defaultLang} file does not: ${list(extra)}` });
+        if (same.length)
+            findings.push({ check: 'locales', severity: 'info', file, message: `${same.length} ${lang} text${same.length === 1 ? ' is' : 's are'} the same as ${set.defaultLang} (not translated yet?): ${list(same.map(([k]) => k))}` });
+    }
+    // Unused keys: look for the key where the framework would use it.
+    const localeFiles = new Set(set.files.values());
+    const all = [...code.entries()].filter(([f]) => !localeFiles.has(f)).map(([, t]) => t).join('\n');
+    // next-intl / i18next: useTranslations('home') / getTranslations('home') / useTranslation('home')
+    // with t('title') in the same file uses home.title. Collected per file, so namespaces do not mix.
+    const usedViaNamespace = new Set();
+    for (const [f, t] of code) {
+        if (localeFiles.has(f))
+            continue;
+        const namespaces = [...t.matchAll(/\b(?:useTranslations|getTranslations|useTranslation)\s*\(\s*(?:\{\s*namespace\s*:\s*)?['"`]([\w.-]+)['"`]/g)].map((m) => m[1]);
+        const calls = [...t.matchAll(/\bt(?:\.rich|\.markup|\.raw)?\s*\(\s*['"`]([\w.-]+)['"`]/g)].map((m) => m[1]);
+        for (const c of calls) {
+            usedViaNamespace.add(c);
+            for (const ns of namespaces)
+                usedViaNamespace.add(`${ns}.${c}`);
+        }
+    }
+    const unused = [...def.keys()].filter((key) => {
+        const esc = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        if (set.kind === 'arb')
+            return !new RegExp(`\\.${esc}\\b`).test(all);
+        if (usedViaNamespace.has(key))
+            return false;
+        if (new RegExp(`['"\`]${esc}['"\`]`).test(all))
+            return false;
+        // A whole namespace passed on (t used for a child component's keys) counts for its keys.
+        return ![...usedViaNamespace].some((u) => key.startsWith(`${u}.`));
+    });
+    // A dynamic lookup (t(`x.${y}`), key.tr on a variable) makes "unused" unreliable.
+    const dynamic = /\bt\(\s*`[^`]*\$\{|\b\w+\.tr\b(?!['"])/.test(all.replace(/['"][^'"\n]*['"]\.tr\b/g, ''));
+    if (unused.length) {
+        findings.push({
+            check: 'locales',
+            severity: 'info',
+            file: set.files.get(set.defaultLang),
+            message: `${unused.length} key${unused.length === 1 ? ' looks' : 's look'} unused: ${list(unused)}${dynamic ? ' (some keys are looked up dynamically, so check before deleting)' : ''}`,
+        });
+    }
+}
+function list(xs, n = 6) {
+    return xs.slice(0, n).join(', ') + (xs.length > n ? `, … (${xs.length - n} more)` : '');
+}
+// ---------------- api ----------------
+function insideTry(text, index) {
+    for (const m of text.slice(0, index).matchAll(/\btry\s*\{/g)) {
+        const open = m.index + m[0].length - 1;
+        const close = matchBrace(text, open, 'dart');
+        if (close === -1 || close > index)
+            return true;
+    }
+    return false;
+}
+function enclosingFunctionHandles(text, index, framework) {
+    // Look at the statement: .catchError / .catch( / onError chained after the call.
+    const after = text.slice(index, index + 400);
+    const stmtEnd = after.search(/;\s*(\n|$)/);
+    const stmt = stmtEnd === -1 ? after : after.slice(0, stmtEnd);
+    if (framework === 'android' && /\brunCatching\s*\{/.test(text.slice(Math.max(0, index - 200), index)))
+        return true;
+    if (/\.catchError\(|\.catch\(|onError\s*:|\.then\([^)]*,\s*\(?\w*\)?\s*=>/.test(stmt))
+        return true;
+    if (framework === 'flutter') {
+        // Riverpod turns errors into AsyncValue.error; AsyncValue.guard catches too.
+        const before = text.slice(Math.max(0, index - 1500), index);
+        if (/AsyncValue\.guard\s*\(/.test(before.slice(-300)))
+            return true;
+        if (/\b(FutureProvider|StreamProvider)(\.\w+)*(<[^>]*>)?\s*\(/.test(before) || /extends\s+(_\$\w+|AsyncNotifier|FamilyAsyncNotifier|AutoDisposeAsyncNotifier)\b/.test(text))
+            return true;
+    }
+    return false;
+}
+function checkApi(root, map, code, findings) {
+    const next = map.framework === 'nextjs';
+    for (const ep of map.endpoints) {
+        for (const f of new Set(ep.calledFrom)) {
+            const t = code.get(f);
+            if (t === undefined || f === ep.file)
+                continue;
+            // Next.js: server components and route handlers fall back to error.tsx; client code must handle errors.
+            if (next && !/^\s*['"]use client['"]/.test(t))
+                continue;
+            const re = new RegExp(`\\b${ep.name}\\s*\\(`, 'g');
+            for (const m of t.matchAll(re)) {
+                const lineStart = t.lastIndexOf('\n', m.index) + 1;
+                const lineText = t.slice(lineStart, t.indexOf('\n', m.index) === -1 ? t.length : t.indexOf('\n', m.index));
+                if (/\b(import|export|function|Future<|async\s+\w+\s*\()/.test(lineText.slice(0, m.index - lineStart)) && !/await|=/.test(lineText))
+                    continue;
+                if (insideTry(t, m.index) || enclosingFunctionHandles(t, m.index, map.framework))
+                    continue;
+                // FutureBuilder / StreamBuilder put the error in snapshot.error; only a builder that ignores it is a problem.
+                const fb = /\b(FutureBuilder|StreamBuilder)\b[\s\S]{0,200}$/.exec(t.slice(Math.max(0, m.index - 200), m.index));
+                if (fb) {
+                    const rest = t.slice(m.index, m.index + 1200);
+                    if (/hasError|\.error\b|ConnectionState/.test(rest))
+                        continue;
+                    findings.push({
+                        check: 'api',
+                        severity: 'warning',
+                        file: f,
+                        line: lineOf(t, m.index),
+                        message: `${ep.name}() runs in a ${fb[1]} whose builder never checks snapshot.hasError, so a failed request shows as empty data.`,
+                        fix: 'Handle snapshot.hasError in the builder (show an error message and a retry).',
+                    });
+                    continue;
+                }
+                // useQuery / useSWR report errors through their own state.
+                if (next && /\b(useQuery|useSWR|useMutation|useSuspenseQuery)\s*\(/.test(t.slice(Math.max(0, m.index - 300), m.index)))
+                    continue;
+                findings.push({
+                    check: 'api',
+                    severity: 'warning',
+                    file: f,
+                    line: lineOf(t, m.index),
+                    message: `${ep.name}() is called without error handling; a failed request ${map.framework === 'flutter' ? 'throws a DioException' : map.framework === 'android' ? 'throws an HttpException or IOException (and crashes a coroutine without a handler)' : next ? 'throws in the browser' : 'throws'} here.`,
+                    fix: map.framework === 'flutter' ? 'Wrap the call in try { … } on DioException catch (e) { … } and show an error state.' : map.framework === 'android' ? 'Wrap the call in try { … } catch (e: Exception) { … } (or runCatching) and expose an error state.' : 'Wrap the call in try/catch (or use .catch) and show an error state.',
+                });
+            }
+        }
+        const r = (ep.response ?? '').replace(/\s/g, '');
+        if (!r || /^(dynamic|any|unknown|Object|Object\?|Map<String,dynamic>|Record<string,any>|Record<string,unknown>|Response|Response<dynamic>|Future<dynamic>|Promise<any>|Promise<unknown>)$/.test(r)) {
+            findings.push({
+                check: 'api',
+                severity: 'warning',
+                file: ep.file,
+                message: `${ep.name}() (${ep.method} ${ep.path}) returns ${r || 'an untyped value'}; callers get no type checking.`,
+                fix: `codz api update ${ep.name} --sample response.json builds a typed model from a real response.`,
+                data: { kind: 'untyped', endpoint: ep.name },
+            });
+        }
+    }
+}
+// ---------------- urls ----------------
+function checkUrls(map, code, findings) {
+    const allowedFiles = new Set([map.conventions.networkFile, map.conventions.httpHelperFile, map.conventions.diFile].filter(Boolean));
+    for (const [f, t] of code) {
+        if (allowedFiles.has(f) || /(^|\/)(env|config|constants?|app_config|environment)s?\.(ts|js|dart)$/.test(f) || /(^|\/)(ApiConfig|Config|Constants|Env)\.kt$/.test(f) || /(^|\/)(config|env)\//.test(f))
+            continue;
+        for (const m of t.matchAll(/(['"`])(https?:\/\/[^'"`\s]+)\1/g)) {
+            const url = m[2];
+            if (/^https?:\/\/(www\.)?(w3\.org|schema\.org|json-schema\.org|xmlns\.com)/.test(url))
+                continue;
+            const isAsset = /\.(png|jpe?g|gif|svg|webp|ico|mp4|woff2?)(\?|$)/i.test(url) || /(fonts\.googleapis|images\.unsplash|picsum\.photos|placehold)/.test(url);
+            const lineStart = t.lastIndexOf('\n', m.index) + 1;
+            const looksApi = /\/api\b|\/v\d+\b|localhost|127\.0\.0\.1|:\d{4}/.test(url) || /\b(fetch|axios|dio|http|get|post|put|patch|delete|baseUrl|BaseOptions)\b/i.test(t.slice(lineStart, m.index));
+            if (isAsset && !looksApi)
+                continue;
+            findings.push({
+                check: 'urls',
+                severity: looksApi ? 'warning' : 'info',
+                file: f,
+                line: lineOf(t, m.index),
+                message: `Hardcoded URL ${url}${looksApi ? ' looks like an API address' : ''}.`,
+                fix: map.framework === 'flutter' ? 'Read it from the base URL in your network setup (or --dart-define) instead.' : map.framework === 'android' ? 'Keep it in one place (ApiConfig.BASE_URL or a buildConfigField) and use that.' : `Read it from ${map.conventions.baseUrlEnv || 'an env variable such as NEXT_PUBLIC_API_URL'} instead.`,
+                data: { kind: 'url', url, index: m.index + 1 },
+            });
+        }
+    }
+}
+// ---------------- models ----------------
+function checkModels(map, code, findings) {
+    for (const model of map.models) {
+        const re = new RegExp(`\\b${model.name}\\b`);
+        const used = [...code.entries()].some(([f, t]) => {
+            if (f !== model.file)
+                return re.test(t);
+            // In its own file, count uses beyond the declaration (and fromJson/toJson of itself).
+            const n = [...t.matchAll(new RegExp(`\\b${model.name}\\b`, 'g'))].length;
+            const self = [...t.matchAll(new RegExp(`(class|interface|type|enum)\\s+${model.name}\\b|${model.name}\\.(fromJson|_)|${model.name}\\s*\\(|factory\\s+${model.name}\\b|_\\$${model.name}`, 'g'))].length;
+            return n > self;
+        });
+        if (!used)
+            findings.push({ check: 'models', severity: 'info', file: model.file, message: `The model ${model.name} is not used anywhere.`, fix: 'Delete it if it is left over from a removed endpoint (codz doctor --fix does that).', data: { kind: 'unusedModel', name: model.name } });
+    }
+}
+export async function runDoctor(root, adapter, opts = {}) {
+    const { map } = await loadMap(root, adapter, loadConfig(root).conventions, { force: true });
+    const code = codeFiles(root, map);
+    const findings = [];
+    const want = (c) => !opts.only?.length || opts.only.includes(c);
+    if (want('locales'))
+        checkLocales(root, map, code, findings);
+    if (want('api'))
+        checkApi(root, map, code, findings);
+    if (want('urls'))
+        checkUrls(map, code, findings);
+    if (want('models'))
+        checkModels(map, code, findings);
+    const order = { error: 0, warning: 1, info: 2 };
+    findings.sort((a, b) => order[a.severity] - order[b.severity] || a.check.localeCompare(b.check) || (a.file ?? '').localeCompare(b.file ?? '') || (a.line ?? 0) - (b.line ?? 0));
+    const counts = { error: 0, warning: 0, info: 0 };
+    for (const f of findings)
+        counts[f.severity]++;
+    return { findings, counts };
+}
+export function renderDoctor(r, color) {
+    const paint = (s, t) => (!color ? t : s === 'error' ? `\x1b[31m${t}\x1b[0m` : s === 'warning' ? `\x1b[33m${t}\x1b[0m` : `\x1b[2m${t}\x1b[0m`);
+    const icon = { error: '✗', warning: '!', info: 'i' };
+    if (!r.findings.length)
+        return 'No problems found.';
+    const out = [];
+    const titles = { locales: 'Locales', api: 'API calls', urls: 'Hardcoded URLs', models: 'Models' };
+    for (const check of ['locales', 'api', 'urls', 'models']) {
+        const fs = r.findings.filter((f) => f.check === check);
+        if (!fs.length)
+            continue;
+        out.push(titles[check]);
+        for (const f of fs) {
+            const where = f.file ? `${f.file}${f.line ? `:${f.line}` : ''}  ` : '';
+            out.push(paint(f.severity, `  ${icon[f.severity]} ${where}${f.message}`));
+            if (f.fix)
+                out.push(`    → ${f.fix}`);
+        }
+        out.push('');
+    }
+    out.push(`${r.counts.error} error${r.counts.error === 1 ? '' : 's'}, ${r.counts.warning} warning${r.counts.warning === 1 ? '' : 's'}, ${r.counts.info} note${r.counts.info === 1 ? '' : 's'}`);
+    return out.join('\n');
+}

package/dist/skills/doctorFix.js

@@ -0,0 +1,214 @@
+// doctor --fix: repairs what can be repaired safely, as one change set with a
+// diff (preview, apply, undo as usual). Everything else is listed with the
+// command or edit that fixes it.
+//
+//   missing locale keys   added to each language with the default language's text
+//   hardcoded URLs        Next.js: `${process.env.<baseUrlEnv>}/path` when the URL starts
+//                         with that env's value; Flutter: a relative path inside Dio calls
+//                         when it starts with the Dio base URL
+//   unused models         the declaration is removed; a file left empty is deleted, and its
+//                         barrel export goes with it
+//   untyped responses     not automatic: needs a real response (api update --sample)
+//   unhandled API errors  not automatic: needs a decision about the error UI
+import { join, posix } from 'node:path';
+import { findTsBlock } from "../adapters/nextjs.js";
+import { matchBrace } from "../adapters/source.js";
+import { loadMap } from "../core/cache.js";
+import { buildChangeSet } from "../core/changeset.js";
+import { loadConfig } from "../core/config.js";
+import { jsonSet } from "../core/jsonEdit.js";
+import { detectEol, readText, walk, withEol } from "../core/fsutil.js";
+import { runDoctor } from "./doctor.js";
+import { dartString, getxBlocks, readLocales } from "./locale.js";
+const read = (root, files, f) => files.get(f) ?? readText(join(root, f));
+// ---------------- locales ----------------
+function fixMissingKeys(root, map, finding, files, summary) {
+    const set = readLocales(root, map);
+    if (!set)
+        return false;
+    const { lang, keys } = finding.data;
+    const def = set.keys.get(set.defaultLang);
+    const file = set.files.get(lang);
+    if (!file)
+        return false;
+    if (set.kind === 'getx') {
+        const block = getxBlocks(root, set.translationsFile).find((b) => b.lang === lang);
+        if (!block)
+            return false;
+        let t = (files.get(block.file) ?? block.text).replace(/\r\n/g, '\n');
+        const close = locateBlockClose(t, block.code);
+        if (close === -1)
+            return false;
+        const closeIndent = t.slice(t.lastIndexOf('\n', close) + 1, close).match(/^[ \t]*/)[0];
+        const before = t.slice(0, close).replace(/\s*$/, '');
+        const lines = keys.map((k) => `${closeIndent}  ${dartString(k)}: ${dartString(def.get(k) ?? '')},`).join('\n');
+        t = `${before}${before.endsWith('{') || before.endsWith(',') ? '' : ','}\n${lines}\n${closeIndent}${t.slice(close)}`;
+        files.set(block.file, withEol(t, detectEol(block.text)));
+    }
+    else {
+        const raw = read(root, files, file);
+        let t = raw;
+        for (const k of keys)
+            t = jsonSet(t, set.kind === 'arb' ? [k] : k.split('.'), def.get(k) ?? '');
+        files.set(file, t);
+    }
+    summary.push(`Add ${keys.length} missing key${keys.length === 1 ? '' : 's'} to ${file} (${lang}) with the ${set.defaultLang} text: ${keys.slice(0, 5).join(', ')}${keys.length > 5 ? ', …' : ''}`);
+    return true;
+}
+/** The closing brace of a GetX language map ('en_US': { … }) in text. */
+function locateBlockClose(t, code) {
+    const m = new RegExp(`['"]${code}['"]\\s*:\\s*\\{`).exec(t);
+    if (!m)
+        return -1;
+    return matchBrace(t, m.index + m[0].length - 1, 'dart');
+}
+// ---------------- URLs ----------------
+function envValue(root, name) {
+    for (const f of ['.env.local', '.env.development', '.env', '.env.example', '.env.development.local']) {
+        const m = new RegExp(`^\\s*${name}\\s*=\\s*['"]?([^'"\\n#]+)`, 'm').exec(readText(join(root, f)) ?? '');
+        if (m && /^https?:\/\//.test(m[1].trim()))
+            return m[1].trim().replace(/\/$/, '');
+    }
+    return undefined;
+}
+function fixUrl(root, map, finding, files, summary) {
+    const file = finding.file;
+    const { url } = finding.data;
+    const t = read(root, files, file);
+    const c = map.conventions;
+    if (map.framework === 'nextjs') {
+        const env = c.baseUrlEnv;
+        const base = env ? envValue(root, env) : undefined;
+        if (!env || !base || !url.startsWith(base)) {
+            finding.fix = `It is not under ${env ? `${env} (${base ?? 'not set in any .env file'})` : 'a configured base URL'}; move it to an env variable by hand.`;
+            return false;
+        }
+        const rest = url.slice(base.length);
+        let next = t;
+        for (const q of ["'", '"', '`'])
+            next = next.split(`${q}${url}${q}`).join(`\`\${process.env.${env}}${rest}\``);
+        if (next === t)
+            return false;
+        files.set(file, next);
+        summary.push(`${file}: ${url} → \`\${process.env.${env}}${rest}\``);
+        return true;
+    }
+    if (map.framework === 'react-native') {
+        finding.fix = `Move it to API_URL in ${c.configFile || 'src/config/env.ts'} and call it through your API client.`;
+        return false;
+    }
+    // Flutter: only inside Dio calls, where a relative path resolves against BaseOptions.baseUrl.
+    const base = (c.baseUrl ?? '').replace(/\/$/, '');
+    if (!base || !url.startsWith(base)) {
+        finding.fix = `It does not start with the Dio base URL${base ? ` (${base})` : ''}; move it to your network setup by hand.`;
+        return false;
+    }
+    const rest = url.slice(base.length) || '/';
+    let changed = false;
+    const next = t.replace(/(\b\w*[dD]io\w*\s*\.\s*(?:get|post|put|patch|delete|head|request|download)\s*(?:<[^>]*>)?\s*\(\s*)(['"])([^'"]+)\2/g, (m, pre, q, u) => {
+        if (u !== url)
+            return m;
+        changed = true;
+        return `${pre}${q}${rest}${q}`;
+    });
+    if (!changed) {
+        finding.fix = 'It is not passed straight to a Dio call; move it to your network setup by hand.';
+        return false;
+    }
+    files.set(file, next);
+    summary.push(`${file}: ${url} → '${rest}' (Dio adds its base URL)`);
+    return true;
+}
+// ---------------- models ----------------
+function dartClassBlock(text, name) {
+    const m = new RegExp(`(^|\\n)((?:[ \\t]*(?:///[^\\n]*|@\\w+(?:\\([^)]*\\))?)\\n)*)[ \\t]*(?:@\\w+(?:\\([^)]*\\))?\\s+)*class\\s+${name}\\b[^{]*\\{`).exec(text);
+    if (!m)
+        return null;
+    const close = matchBrace(text, m.index + m[0].length - 1, 'dart');
+    return close === -1 ? null : { start: m.index + m[1].length, end: close + 1 };
+}
+function fixUnusedModel(root, map, finding, files, deletes, summary, notes) {
+    const model = map.models.find((m) => m.name === finding.data.name);
+    if (!model || deletes.has(model.file))
+        return false;
+    const text = read(root, files, model.file);
+    if (text === null)
+        return false;
+    const lang = model.file.endsWith('.dart') ? 'dart' : 'ts';
+    const block = lang === 'dart' ? dartClassBlock(text, model.name) : findTsBlock(text, model.name);
+    if (!block) {
+        notes.push(`${model.file}: could not find the declaration of ${model.name}; delete it by hand.`);
+        return false;
+    }
+    let rest = (text.slice(0, block.start) + text.slice(block.end)).replace(/\n{3,}/g, '\n\n');
+    // Generated json_serializable glue for this class.
+    if (lang === 'dart')
+        rest = rest.replace(new RegExp(`^part '[^']*\\.g\\.dart';\\n?`, 'm'), (p) => (/\bclass\s+\w+/.test(rest) ? p : ''));
+    const onlyImports = rest.replace(/^\s*(import|export)\b[^\n]*\n?/gm, '').replace(/^\s*part\b[^\n]*\n?/gm, '').trim() === '';
+    if (onlyImports) {
+        deletes.add(model.file);
+        files.delete(model.file);
+        summary.push(`Delete ${model.file}: ${model.name} was its only declaration and nothing uses it`);
+        removeBarrelExport(root, model.file, files, summary);
+    }
+    else {
+        files.set(model.file, rest.replace(/^\n+/, '').replace(/\n*$/, '\n'));
+        summary.push(`Remove ${model.name} from ${model.file}: nothing uses it`);
+    }
+    return true;
+}
+function removeBarrelExport(root, deleted, files, summary) {
+    const dir = posix.dirname(deleted);
+    const base = posix.basename(deleted).replace(/\.(ts|tsx|dart)$/, '');
+    const candidates = deleted.endsWith('.dart') ? walk(root, dir, { exts: ['.dart'] }).filter((f) => posix.dirname(f) === dir) : [`${dir}/index.ts`];
+    for (const f of candidates) {
+        if (f === deleted)
+            continue;
+        const t = read(root, files, f);
+        if (t === null)
+            continue;
+        const re = deleted.endsWith('.dart') ? new RegExp(`^export\\s+'(?:\\./)?${base}\\.dart';[ \\t]*\\n?`, 'gm') : new RegExp(`^export\\s+(?:\\*|(?:type\\s+)?\\{[^}]*\\})\\s+from\\s+['"]\\./${base}(?:\\.js)?['"];?[ \\t]*\\n?`, 'gm');
+        const next = t.replace(re, '');
+        if (next !== t) {
+            files.set(f, next);
+            summary.push(`Update ${f}: drop the export of ${posix.basename(deleted)}`);
+        }
+    }
+}
+// ---------------- entry ----------------
+export async function planDoctorFix(root, adapter, opts = {}) {
+    const report = await runDoctor(root, adapter, opts);
+    const { map } = await loadMap(root, adapter, loadConfig(root).conventions);
+    const files = new Map();
+    const deletes = new Set();
+    const summary = [];
+    const notes = [];
+    const manual = [];
+    let fixed = 0;
+    // URLs from the end of each file first, so earlier offsets stay valid (replacements are by value anyway).
+    for (const f of report.findings) {
+        let ok = false;
+        const d = f.data;
+        if (d?.kind === 'missingKeys')
+            ok = fixMissingKeys(root, map, f, files, summary);
+        else if (d?.kind === 'url' && f.severity !== 'info')
+            ok = fixUrl(root, map, f, files, summary);
+        else if (d?.kind === 'unusedModel')
+            ok = fixUnusedModel(root, map, f, files, deletes, summary, notes);
+        if (ok)
+            fixed++;
+        else if (f.severity !== 'info')
+            manual.push(f);
+    }
+    const warnings = [];
+    if (fixed && report.findings.some((f) => f.data?.kind === 'missingKeys'))
+        warnings.push('The added locale keys hold the default-language text; translate them (doctor lists them as untranslated).');
+    warnings.push(...notes);
+    if (manual.length) {
+        warnings.push(`Still needs you (${manual.length}):\n${manual.map((m) => `    ${m.file ? `${m.file}${m.line ? `:${m.line}` : ''}  ` : ''}${m.message}${m.fix ? `\n      → ${m.fix}` : ''}`).join('\n')}`);
+    }
+    if (!summary.length)
+        summary.push(report.findings.length ? 'Nothing here can be fixed automatically.' : 'No problems found.');
+    const changeSet = buildChangeSet(root, 'doctor fix', { files, deletes, summary, warnings, generated: [] });
+    return { changeSet, fixed, manual };
+}

package/dist/skills/explain.js

@@ -0,0 +1,61 @@
+// explain: prints how the project is put together, from the project map.
+const pad = (s, n) => (s.length >= n ? s + ' ' : s + ' '.repeat(n - s.length));
+export function renderExplain(map, adapter, color) {
+    const b = (s) => (color ? `\x1b[1m${s}\x1b[0m` : s);
+    const dim = (s) => (color ? `\x1b[2m${s}\x1b[0m` : s);
+    const names = { nextjs: 'Next.js', flutter: 'Flutter', generic: 'Generic' };
+    const out = [];
+    out.push(b(`${names[map.framework] ?? map.framework} project`) + dim(`  (adapter ${map.adapter})`));
+    out.push(dim(`Supported setup: ${adapter.supportedSetup}`));
+    const conv = Object.entries(map.conventions).filter(([, v]) => v !== '');
+    if (conv.length) {
+        out.push('', b('Conventions'));
+        const w = Math.max(...conv.map(([k]) => k.length)) + 2;
+        for (const [k, v] of conv)
+            out.push(`  ${pad(k, w)}${v}`);
+    }
+    out.push('', b(`Routes (${map.routes.length})`));
+    if (!map.routes.length)
+        out.push(dim('  none found'));
+    const rw = Math.max(0, ...map.routes.map((r) => r.path.length)) + 2;
+    for (const r of map.routes)
+        out.push(`  ${pad(r.path, rw)}${dim(r.file)}`);
+    out.push('', b(`Endpoints (${map.endpoints.length})`));
+    if (!map.endpoints.length)
+        out.push(dim('  none found'));
+    const pw = Math.max(0, ...map.endpoints.map((e) => e.path.length)) + 2;
+    const nw = Math.max(0, ...map.endpoints.map((e) => e.name.length + (e.response ? e.response.length + 3 : 0))) + 2;
+    for (const e of map.endpoints) {
+        const used = e.calledFrom.length ? `  used in ${e.calledFrom.join(', ')}` : '  not called anywhere yet';
+        out.push(`  ${pad(e.method, 7)}${pad(e.path, pw)}${pad(e.name + (e.response ? ` → ${e.response}` : ''), nw)}${dim(e.file + used)}`);
+    }
+    out.push('', b(`Models (${map.models.length})`));
+    if (!map.models.length)
+        out.push(dim('  none found'));
+    const mw = Math.max(0, ...map.models.map((m) => m.name.length)) + 2;
+    for (const m of map.models) {
+        const fields = m.fields.map((f) => `${f.name}${f.nullable ? '?' : ''}`).join(', ');
+        out.push(`  ${pad(m.name, mw)}${fields.length > 70 ? fields.slice(0, 67) + '...' : fields}  ${dim(m.file)}`);
+    }
+    out.push('', b('Locales'));
+    if (map.locales.languages.length) {
+        out.push(`  ${map.locales.languages.map((l) => (l === map.locales.default ? `${l} (default)` : l)).join(', ')}, ${map.locales.keyCount} keys`);
+        out.push(dim(`  ${map.locales.files.join(', ')}`));
+    }
+    else
+        out.push(dim('  none found'));
+    out.push('', b('Base URLs'));
+    if (map.baseUrls.length)
+        for (const u of map.baseUrls)
+            out.push(`  ${u.name} = ${u.value}  ${dim(u.file)}`);
+    else
+        out.push(dim('  none found in .env files'));
+    const ext = Object.entries(map.stats.byExtension).slice(0, 6).map(([e, n]) => `${e} ${n}`).join(', ');
+    out.push('', b('Files') + `  ${map.stats.files} (${ext})`);
+    if (map.notes.length) {
+        out.push('', b('Notes'));
+        for (const n of map.notes)
+            out.push(`  - ${n}`);
+    }
+    return out.join('\n');
+}