@nativele/ts-dom 0.3.0 → 0.4.6

package/dist/cli.mjs

@@ -1,74 +1,1173 @@
 #!/usr/bin/env node
-import { d as listHtml, i as CodegenError, n as checkA11y, p as watchAll, r as CODEGEN_RULES, s as generateAll, t as A11Y_RULES } from "./a11y-CeZcA10z.mjs";
-import { c as lintUsage, n as UNUSED_MARKUP_RULES, o as formatIssue, s as lintDataFlow, t as DATA_FLOW_RULES } from "./lint-DS-IOjkf.mjs";
-import { readFileSync, readdirSync, statSync } from "node:fs";
-import { join, relative } from "node:path";
+import { _ as watchAll, a as analyze, c as generateAll, d as isSelected, f as listHtml, g as staleGenerated, i as CodegenError, m as renderTags, n as checkA11y, o as checkGenerated, p as listTs, r as CODEGEN_RULES, t as A11Y_RULES } from "./a11y-wWL9rie7.mjs";
+import { c as lintUsage, n as UNUSED_MARKUP_RULES, o as formatIssue, s as lintDataFlow, t as DATA_FLOW_RULES } from "./lint-CP_i4VPA.mjs";
+import { createRequire } from "node:module";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+// src/lib/tsconfig.ts
+/** tsconfig is JSONC: drop comments and trailing commas before parsing. */
+function parseJsonc(text) {
+	const noComments = text.replace(/("(?:\\.|[^"\\])*")|\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (m, str) => str ?? "");
+	return JSON.parse(noComments.replace(/,(\s*[}\]])/g, "$1"));
+}
+function resolveExtends(from, ext) {
+	const dir = dirname(from);
+	if (ext.startsWith(".")) {
+		const target = resolve(dir, ext);
+		return existsSync(target) ? target : existsSync(`${target}.json`) ? `${target}.json` : null;
+	}
+	const req = createRequire(from);
+	for (const spec of [
+		ext,
+		`${ext}.json`,
+		`${ext}/tsconfig.json`
+	]) try {
+		return req.resolve(spec);
+	} catch {}
+	return null;
+}
+/** Read a tsconfig and the ones it extends (a relative path, a package, or an array of them), the later and nearer one winning. */
+function readTsConfig(file, depth = 0) {
+	const json = parseJsonc(readFileSync(file, "utf8"));
+	let merged = { compilerOptions: {} };
+	const exts = typeof json.extends === "string" ? [json.extends] : Array.isArray(json.extends) ? json.extends : [];
+	for (const ext of depth < 5 ? exts : []) {
+		const target = resolveExtends(file, ext);
+		if (!target) continue;
+		const base = readTsConfig(target, depth + 1);
+		merged = {
+			compilerOptions: {
+				...merged.compilerOptions,
+				...base.compilerOptions
+			},
+			...base.include ?? merged.include ? { include: base.include ?? merged.include } : {}
+		};
+	}
+	const own = json.include;
+	const include = own ? own.map((p) => resolve(dirname(file), p).split("\\").join("/")) : merged.include;
+	return {
+		compilerOptions: {
+			...merged.compilerOptions,
+			...json.compilerOptions
+		},
+		...include ? { include } : {}
+	};
+}
+/**
+* The tsconfig files tsc would check for a project: `project`, or tsconfig.json in `cwd`.
+* A solution-style config (`"files": []` with `references`) checks nothing itself, so its referenced projects are returned instead.
+*/
+function projectConfigs(cwd, project) {
+	const root = resolve(cwd, project ?? "tsconfig.json");
+	if (!existsSync(root)) return [];
+	const json = parseJsonc(readFileSync(root, "utf8"));
+	const refs = Array.isArray(json.references) ? json.references.map((r) => r.path).filter((p) => typeof p === "string") : [];
+	if (!(refs.length > 0 && Array.isArray(json.files) && json.files.length === 0 && json.include === void 0)) return [root];
+	return refs.map((ref) => {
+		const abs = resolve(dirname(root), ref);
+		return existsSync(abs) && statSync(abs).isDirectory() ? join(abs, "tsconfig.json") : abs;
+	}).filter((f) => existsSync(f));
+}
+// src/lib/check.ts
+const CHECK_RULES = {
+	"stale-generated": "a generated file is missing, outdated or orphaned, so the type errors may not match the templates",
+	"missing-binding": "a {{ hole }} or data-if names nothing in state, props or derive (found by tsc)",
+	"conflicting-keys": "the same name is declared in more than one of state, props and derive (found by tsc)",
+	"reserved-prop": "a prop is named like a member of HTMLElement or ts-dom (found by tsc)",
+	"native-event-name": "an emitted event is named like a native DOM event (found by tsc)",
+	"item-prop-missing": "the data-prop of a list is not a prop of its item component (found by tsc)",
+	"item-not-in-tag-map": "the item component is defined in a scanned folder but missing from ts-dom-tags.ts (found by tsc)",
+	"item-class-not-exported": "the item component class passed to define() is not exported (found by tsc)",
+	tsc: "any other TypeScript error, as tsc reports it",
+	"tsc-not-found": "TypeScript is not installed in the project, so types were not checked",
+	"dir-not-found": "a folder given on the command line does not exist, so nothing in it was checked",
+	"tsc-failed": "tsc did not run to completion (no tsconfig, a bad option, a crash), so types were not checked"
+};
+/** Parse `tsc --pretty false` output; indented lines continue the previous message. */
+function parseTscOutput(out) {
+	const errors = [];
+	for (const line of out.split(/\r?\n/)) {
+		const m = /^(.+?)\((\d+),(\d+)\): error (TS\d+): (.*)$/.exec(line);
+		if (m) errors.push({
+			file: m[1],
+			line: Number(m[2]),
+			col: Number(m[3]),
+			code: m[4],
+			message: m[5]
+		});
+		else if (/^\s+\S/.test(line) && errors.length) errors.at(-1).message += `\n${line.trim()}`;
+	}
+	return errors;
+}
+const CONTRACT = [
+	[
+		"conflictingKeys",
+		"conflicting-keys",
+		"keep each name in only one of state, props and derive"
+	],
+	[
+		"reservedPropNames",
+		"reserved-prop",
+		"rename the prop (for example title -> titleText)"
+	],
+	[
+		"nativeEventNames",
+		"native-event-name",
+		"rename the event, for example with a prefix such as item-"
+	],
+	[
+		"dataPropNotOnItemComponent",
+		"item-prop-missing",
+		"declare the property in the item component's props, or change data-prop"
+	],
+	[
+		"itemComponentMissingFromTagMap",
+		"item-not-in-tag-map",
+		"run ts-dom gen so ts-dom-tags.ts lists the item component"
+	],
+	[
+		"itemComponentClassNotExported",
+		"item-class-not-exported",
+		"export the class passed to define() so its prop types can be read"
+	]
+];
+const namesAfter = (message, key) => {
+	const m = new RegExp(`${key}: ((?:"[^"]+"(?:\\s*\\|\\s*)?)+)`).exec(message);
+	return m ? [...m[1].matchAll(/"([^"]+)"/g)].map((x) => x[1]) : [];
+};
+const templatesOf = (tsFile) => {
+	if (!existsSync(tsFile)) return [];
+	return [...readFileSync(tsFile, "utf8").matchAll(/from\s+["'](\.{1,2}\/[^"']+\.html)\.js["']/g)].map((m) => resolve(dirname(tsFile), m[1])).filter((f) => existsSync(f));
+};
+/**
+* Turn the tsc errors that come from the template contract into issues that point at the template, or at the line to change, with a Fix hint.
+* Other errors are kept as `tsc` issues.
+*/
+function mapTscErrors(errors, cwd) {
+	const rel = (f) => relative(cwd, f);
+	const out = [];
+	const analyses = /* @__PURE__ */ new Map();
+	const analysisOf = (html) => {
+		let a = analyses.get(html);
+		if (!a) analyses.set(html, a = analyze(readFileSync(html, "utf8")));
+		return a;
+	};
+	const locate = (tsFile, keys) => {
+		for (const html of templatesOf(tsFile)) for (const key of keys) {
+			const loc = analysisOf(html).locs.get(key);
+			if (loc) return {
+				file: html,
+				...loc
+			};
+		}
+	};
+	const brokenClasses = /* @__PURE__ */ new Set();
+	for (const e of errors) {
+		if (!/missingStateKeys|conflictingKeys|reservedPropNames|nativeEventNames/.test(e.message)) continue;
+		const line = readFileSync(resolve(cwd, e.file), "utf8").split("\n")[e.line - 1] ?? "";
+		const name = /class\s+([A-Za-z_$][\w$]*)\s+extends\s+Component\s*\(/.exec(line)?.[1];
+		if (name) brokenClasses.add(name);
+	}
+	const followsBroken = (message) => [...brokenClasses].some((c) => message.includes(`'${c}'`) || message.includes(`'typeof ${c}'`));
+	for (const e of errors) {
+		const file = resolve(cwd, e.file);
+		const where = `${rel(file)}:${e.line}:${e.col}`;
+		const issue = (rule, message, at) => out.push({
+			...at ?? {
+				file: rel(file),
+				line: e.line,
+				col: e.col
+			},
+			rule,
+			severity: "error",
+			message
+		});
+		let named = false;
+		for (const name of namesAfter(e.message, "missingStateKeys")) {
+			named = true;
+			const found = locate(file, [`text:${name}`, `if:${name}`]);
+			issue("missing-binding", `"${name}" is used by {{ ${name} }} or data-if="${name}" but the component declares no state, prop or derived value of that name (tsc at ${where}). Fix: add "${name}" to state, props or derive, or remove it from the template.`, found && {
+				file: rel(found.file),
+				line: found.line,
+				col: found.col
+			});
+		}
+		for (const name of namesAfter(e.message, "missingHandlers")) {
+			named = true;
+			const found = locate(file, [`event:${name}`]);
+			issue("missing-handler", `data-on-*="${name}" refers to a method the component class does not define (tsc at ${where}). Fix: add a public method \`${name}(e: Event, hit: EventHit)\` to the class.`, found && {
+				file: rel(found.file),
+				line: found.line,
+				col: found.col
+			});
+		}
+		for (const [key, rule, fix] of CONTRACT) {
+			if (!e.message.includes(key)) continue;
+			named = true;
+			issue(rule, `${e.message.split("\n")[0]} Fix: ${fix}.`);
+		}
+		if (!named) issue("tsc", `${e.code}: ${e.message} Fix: change the TypeScript at this location so the types agree; ts-dom rules --explain=tsc.`);
+	}
+	return out.filter((i) => i.rule !== "tsc" || !followsBroken(i.message));
+}
+function findTsc(cwd) {
+	try {
+		const pkgPath = createRequire(join(cwd, "package.json")).resolve("typescript/package.json");
+		const bin = JSON.parse(readFileSync(pkgPath, "utf8")).bin?.tsc;
+		return bin ? resolve(dirname(pkgPath), bin) : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Everything an agent needs in one pass: template diagnostics, generated files, TypeScript errors mapped back to the templates, and the lint rules.
+* Returns the issues sorted by file and position.
+*/
+function runCheck(options) {
+	const cwd = options.cwd ?? process.cwd();
+	const generate = options.generate ?? {};
+	const issues = [];
+	const rel = (f) => relative(cwd, f);
+	const dirs = [];
+	for (const d of options.dirs.map((x) => resolve(cwd, x))) if (existsSync(d)) dirs.push(d);
+	else issues.push({
+		file: rel(d) || ".",
+		line: 1,
+		col: 1,
+		rule: "dir-not-found",
+		severity: "error",
+		message: `The folder ${rel(d) || "."} does not exist, so nothing in it was checked. Fix: pass the folder that holds the templates and components (default: src).`
+	});
+	for (const dir of dirs) for (const f of listHtml(dir)) {
+		if (!isSelected(dir, f, generate)) continue;
+		for (const d of analyze(readFileSync(f, "utf8")).diagnostics) issues.push({
+			file: rel(f),
+			...d
+		});
+	}
+	for (const dir of dirs) try {
+		renderTags(dir);
+	} catch (e) {
+		if (!(e instanceof CodegenError)) throw e;
+		issues.push({
+			file: rel(dir),
+			line: 1,
+			col: 1,
+			rule: "duplicate-define",
+			severity: "error",
+			message: e.message.replace(/^[^[]*\[duplicate-define\]\s*/, "")
+		});
+	}
+	if (options.write === false) for (const dir of dirs) for (const s of staleGenerated(dir, generate)) issues.push({
+		file: rel(s.file),
+		line: 1,
+		col: 1,
+		rule: "stale-generated",
+		severity: "error",
+		message: `The generated file is ${s.reason}, so the type errors below may not match the templates. Fix: run ts-dom gen (or ts-dom check without --no-write).`
+	});
+	else for (const dir of dirs) try {
+		generateAll(dir, generate);
+	} catch (e) {
+		if (!(e instanceof CodegenError)) throw e;
+	}
+	const tsc = findTsc(cwd);
+	if (!tsc) issues.push({
+		file: ".",
+		line: 1,
+		col: 1,
+		rule: "tsc-not-found",
+		severity: "warning",
+		message: "TypeScript is not installed in this project, so types were not checked. Fix: npm i -D typescript."
+	});
+	else {
+		const configs = projectConfigs(cwd, options.project);
+		const runs = configs.length ? configs.map((c) => ["-p", c]) : [options.project ? ["-p", options.project] : []];
+		const parsed = [];
+		for (const extra of runs) {
+			const run = spawnSync(process.execPath, [
+				tsc,
+				"--noEmit",
+				"--pretty",
+				"false",
+				...extra
+			], {
+				cwd,
+				encoding: "utf8",
+				maxBuffer: 268435456
+			});
+			const output = `${run.stdout ?? ""}\n${run.stderr ?? ""}`;
+			const errors = parseTscOutput(output);
+			parsed.push(...errors);
+			if (run.error || run.status !== 0 && !errors.length) {
+				const detail = run.error ? String(run.error.message) : output.trim().split("\n").slice(0, 5).join(" ");
+				issues.push({
+					file: extra[1] ? rel(extra[1]) : ".",
+					line: 1,
+					col: 1,
+					rule: "tsc-failed",
+					severity: "error",
+					message: `tsc did not check the types: ${detail} Fix: make \`npx tsc --noEmit\` run in this folder (a tsconfig.json, or --project=<path>).`
+				});
+			}
+		}
+		issues.push(...mapTscErrors(parsed, cwd));
+	}
+	const tsFiles = dirs.flatMap(listTs);
+	const lint = [...lintUsage(dirs, tsFiles), ...lintDataFlow(dirs, tsFiles)].map((i) => ({
+		...i,
+		file: rel(resolve(cwd, i.file))
+	}));
+	for (const i of lint) {
+		if (i.rule === "missing-handler" && issues.some((x) => x.rule === "missing-handler" && x.file === i.file && x.line === i.line && x.col === i.col)) continue;
+		issues.push(i);
+	}
+	if (options.a11y) for (const dir of dirs) for (const f of listHtml(dir)) for (const d of checkA11y(readFileSync(f, "utf8"))) issues.push({
+		file: rel(f),
+		...d
+	});
+	const seen = /* @__PURE__ */ new Set();
+	return issues.filter((i) => {
+		const k = `${i.file}:${i.line}:${i.col}:${i.rule}:${i.message}`;
+		return !seen.has(k) && seen.add(k) !== void 0;
+	}).sort((x, y) => x.file.localeCompare(y.file) || x.line - y.line || x.col - y.col);
+}
+// src/lib/doctor.ts
+const DOCTOR_RULES = {
+	"dir-not-found": "a folder given on the command line does not exist, so nothing in it was checked",
+	"no-tsconfig": "there is no tsconfig.json, so tsc cannot check the templates against the components",
+	"tsconfig-not-strict": "strict is off, so tsc lets wrong names and null values through",
+	"tsconfig-no-dom-lib": "lib leaves out DOM, so element types are missing",
+	"tsconfig-classic-resolution": "moduleResolution classic cannot resolve ./x.html.js to the generated x.html.ts",
+	"tsconfig-misses-templates": "include leaves out a folder with templates, so their generated types are not checked",
+	"runtime-not-installed": "the runtime package the generated files import cannot be resolved",
+	"template-import-without-js": "a template is imported as ./x.html instead of ./x.html.js",
+	"stale-generated": "a generated file is missing, outdated or orphaned",
+	"vite-plugin-missing": "the Vite config does not use the ts-dom plugin, so templates are not regenerated while the dev server runs",
+	"oxlint-plugin-missing": "the lint config does not load the ts-dom oxlint plugin, so the template rules do not run in the editor",
+	"formatter-whitespace": "a formatter is set up while templates keep their whitespace, so reformatting can change the rendered spacing"
+};
+const readText = (file) => existsSync(file) ? readFileSync(file, "utf8") : null;
+/** Whether an include pattern (absolute, forward slashes) makes tsc read the files directly in `dir`. */
+function covers(pattern, dir) {
+	const d = dir.split("\\").join("/");
+	const star = pattern.indexOf("*");
+	if (star === -1) return /\.[cm]?tsx?$/.test(pattern) ? false : d === pattern || d.startsWith(`${pattern}/`);
+	const prefix = pattern.slice(0, star).replace(/\/$/, "");
+	if (pattern.slice(star).startsWith("**")) return d === prefix || d.startsWith(`${prefix}/`);
+	return d === prefix;
+}
+const templateFolders = (dir) => [...new Set(listHtml(dir).map((f) => dirname(f)))];
+const hasTemplates = (dir) => listHtml(dir).length > 0;
+/** Check the project set-up an agent or a developer could get wrong; every issue names its rule and ends with a Fix hint. */
+function runDoctor(options) {
+	const cwd = options.cwd ?? process.cwd();
+	const generate = options.generate ?? {};
+	const runtime = generate.runtime ?? "@nativele/ts-dom";
+	const rel = (f) => relative(cwd, f) || ".";
+	const issues = [];
+	const add = (rule, severity, message, at = {}) => issues.push({
+		rule,
+		severity,
+		message,
+		...at
+	});
+	const dirs = [];
+	for (const d of options.dirs.map((x) => resolve(cwd, x))) if (existsSync(d)) dirs.push(d);
+	else add("dir-not-found", "error", `The folder ${rel(d)} does not exist, so nothing in it was checked. Fix: pass the folder that holds the templates and components (default: src).`, { file: rel(d) });
+	const configs = projectConfigs(cwd);
+	let paths = {};
+	if (!configs.length) add("no-tsconfig", "error", "There is no tsconfig.json. Fix: add one with \"strict\": true, \"lib\": [\"ES2022\", \"DOM\"] and \"moduleResolution\": \"bundler\" (or \"NodeNext\").");
+	const includes = [];
+	let everyConfigIncludes = true;
+	for (const configPath of configs) {
+		const config = readTsConfig(configPath);
+		const o = config.compilerOptions;
+		const file = rel(configPath);
+		paths = {
+			...paths,
+			...o.paths
+		};
+		if (o.strict !== true) add("tsconfig-not-strict", "warning", "compilerOptions.strict is not true, so tsc lets wrong names and null values through. Fix: set \"strict\": true.", { file });
+		const lib = o.lib;
+		if (lib && !lib.some((l) => l.toLowerCase() === "dom")) add("tsconfig-no-dom-lib", "error", "compilerOptions.lib leaves out DOM, so element types such as HTMLButtonElement are missing. Fix: add \"DOM\" to lib.", { file });
+		if (String(o.moduleResolution ?? "").toLowerCase() === "classic") add("tsconfig-classic-resolution", "error", "moduleResolution \"classic\" cannot resolve ./x.html.js to the generated x.html.ts. Fix: use \"bundler\" or \"NodeNext\".", { file });
+		if (config.include) includes.push(...config.include);
+		else everyConfigIncludes = false;
+	}
+	if (configs.length && everyConfigIncludes) {
+		const missed = /* @__PURE__ */ new Set();
+		for (const d of dirs) for (const folder of templateFolders(d)) if (!includes.some((p) => covers(p, folder))) missed.add(rel(folder));
+		for (const folder of missed) add("tsconfig-misses-templates", "error", `No tsconfig include covers ${folder}, which has templates, so their generated types are never checked. Fix: add "${folder === "." ? "**/*" : `${folder}/**/*`}" to include.`, { file: rel(configs[0]) });
+	}
+	let resolvable = Object.keys(paths).includes(runtime);
+	if (!resolvable) try {
+		createRequire(join(cwd, "package.json")).resolve(`${runtime}/package.json`);
+		resolvable = true;
+	} catch {
+		resolvable = false;
+	}
+	if (!resolvable) add("runtime-not-installed", "error", `The generated files import "${runtime}", which cannot be resolved from this project. Fix: npm i ${runtime}.`);
+	for (const d of dirs) {
+		for (const f of listTs(d)) readFileSync(f, "utf8").split("\n").forEach((text, i) => {
+			const m = /from\s+["'](\.{1,2}\/[^"']+\.html)["']/.exec(text);
+			if (m) add("template-import-without-js", "error", `${m[1]} is imported without .js, which works only through a bundler plugin that Nativele does not provide. Fix: import "${m[1]}.js" (TypeScript maps it to the generated ${m[1]}.ts).`, {
+				file: rel(f),
+				line: i + 1
+			});
+		});
+		for (const s of staleGenerated(d, generate)) add("stale-generated", "warning", `The generated file is ${s.reason}. Fix: run ts-dom gen (or ts-dom check, which regenerates).`, { file: rel(s.file) });
+	}
+	const viteConfig = [
+		"vite.config.ts",
+		"vite.config.mts",
+		"vite.config.js",
+		"vite.config.mjs"
+	].map((n) => join(cwd, n)).find((f) => existsSync(f));
+	const vite = viteConfig ? readText(viteConfig) : null;
+	if (viteConfig && vite !== null && !/@nativele\/ts-dom\/vite|vite-plugin(\.ts)?["']/.test(vite)) add("vite-plugin-missing", "warning", "The Vite config does not use the ts-dom plugin, so templates are not regenerated while the dev server runs. Fix: import { tsDom } from \"@nativele/ts-dom/vite\" and add tsDom() to plugins.", { file: rel(viteConfig) });
+	const oxlintrc = [".oxlintrc.json", "oxlintrc.json"].map((n) => join(cwd, n)).find((f) => existsSync(f));
+	const lintConfigs = [oxlintrc ? readText(oxlintrc) : null, vite && /\blint\s*:/.test(vite) ? vite : null].filter((t) => t !== null);
+	if (lintConfigs.length && !lintConfigs.some((t) => /@nativele\/ts-dom\/oxlint|oxlint-plugin(\.ts)?["']/.test(t))) add("oxlint-plugin-missing", "warning", "The lint config does not load the ts-dom oxlint plugin, so unused markup, data flow and accessibility rules do not run in the editor. Fix: add { name: \"ts-dom\", specifier: \"@nativele/ts-dom/oxlint\" } to jsPlugins and enable \"ts-dom/unused-markup\".", { file: rel(oxlintrc ?? viteConfig) });
+	const pkgText = readText(join(cwd, "package.json"));
+	const pkg = pkgText ? JSON.parse(pkgText) : {};
+	const deps = {
+		...pkg.dependencies,
+		...pkg.devDependencies
+	};
+	const scripts = Object.values(pkg.scripts ?? {});
+	const ignoredHtml = /(^|\n)\s*(\*\*\/)?\*\.html\s*($|\n)/.test(readText(join(cwd, ".prettierignore")) ?? "");
+	const formatter = [".oxfmtrc.json", ".oxfmtrc.jsonc"].some((n) => existsSync(join(cwd, n))) || "oxfmt" in deps || scripts.some((c) => /(^|[\s;&|])(oxfmt|vp fmt)(\s|$)/.test(c)) || vite !== null && /\bfmt\s*:/.test(vite) || !ignoredHtml && ([
+		".prettierrc",
+		".prettierrc.json",
+		".prettierrc.js",
+		"prettier.config.js",
+		"prettier.config.mjs"
+	].some((n) => existsSync(join(cwd, n))) || "prettier" in deps || scripts.some((c) => /(^|[\s;&|])prettier(\s|$)/.test(c)));
+	const collapsed = scripts.some((c) => c.includes("--whitespace=collapse")) || vite !== null && /whitespace\s*:\s*["']collapse["']/.test(vite) || dirs.some((d) => listHtml(d).some((f) => (readText(`${f}.ts`) ?? "").split("\n", 3).includes("// whitespace: collapse")));
+	if (formatter && !collapsed && dirs.some(hasTemplates)) add("formatter-whitespace", "warning", "A formatter (oxfmt or Prettier) is set up, and templates keep their whitespace as written, so reformatting a template can change the spacing on the page. Fix: generate with whitespace \"collapse\" (ts-dom gen --whitespace=collapse, or tsDom({ whitespace: \"collapse\" })).");
+	return issues;
+}
+function formatDoctorIssue(i) {
+	return `${i.file ?? "."}:${i.line ?? 1}:1 ${i.severity} [${i.rule}] ${i.message}`;
+}
+// src/lib/rule-docs.ts
+const RULE_DOCS = {
+	"invalid-hole": {
+		why: "HTML only names things: a hole is a single identifier that TypeScript fills in. Paths and expressions would turn the template into a language, and codegen could not derive a field name from them.",
+		bad: `<!-- card.html -->
+<h2>{{ user.name }}</h2>
+<p>{{ count + 1 }}</p>`,
+		good: `<!-- card.html -->
+<h2>{{ userName }}</h2>
+<p>{{ nextCount }}</p>
+// card.ts: compute the value in TypeScript, then fill the named hole
+this.set({ userName: user.name, nextCount: count + 1 });`
+	},
+	"attr-hole": {
+		why: "Holes are only text slots. An attribute value is not a text node, so it cannot be filled the same way and would be left as literal braces.",
+		bad: `<!-- card.html -->
+<a href="/user/{{ id }}">profile</a>`,
+		good: `<!-- card.html -->
+<a data-ref="link">profile</a>
+// card.ts
+this.refs.link.href = "/user/" + id;`
+	},
+	"invalid-event-name": {
+		why: "The part after data-on- becomes the name of a DOM event listener, so it must be a plain event name. Modifiers or other characters (as other frameworks allow) would make it listen for an event that never fires.",
+		bad: `<form data-on-submit.prevent="save">...</form>`,
+		good: `<!-- form.html -->
+<form data-on-submit="save">...</form>
+// form.ts
+save(e: Event): void { e.preventDefault(); }`
+	},
+	"invalid-handler": {
+		why: "data-on-* only names a method; HTML holds no expressions or calls. A call such as save(1) would not be run, and the type of the method could not be checked.",
+		bad: `<button data-on-click="removeItem(item.id)">x</button>`,
+		good: `<button data-on-click="removeItem">x</button>
+// card.ts: inside a list, hit.key is the item's key
+removeItem(_e: Event, hit: EventHit) { this.set((s) => ({ rows: s.rows.filter((r) => r.id !== hit.key) })); }`
+	},
+	"reserved-handler": {
+		why: "A handler becomes a method on the component class. A name such as render, click or remove would override a member of HTMLElement or ts-dom and break the component in ways tsc cannot always see.",
+		bad: `<button data-on-click="render">refresh</button>`,
+		good: `<button data-on-click="refresh">refresh</button>`
+	},
+	"empty-ref": {
+		why: "data-ref names an element so TypeScript can reach it through this.refs. An empty name gives codegen nothing to generate.",
+		bad: `<input data-ref="">`,
+		good: `<input data-ref="name">
+// card.ts
+this.refs.name.focus();`
+	},
+	"duplicate-ref": {
+		why: "Each data-ref becomes one field of this.refs, so two elements with the same name would be indistinguishable and one would be unreachable.",
+		bad: `<button data-ref="btn">ok</button>
+<button data-ref="btn">cancel</button>`,
+		good: `<button data-ref="ok">ok</button>
+<button data-ref="cancel">cancel</button>`
+	},
+	"empty-if": {
+		why: "data-if names a condition that TypeScript toggles through this.set. Without a name there is nothing to toggle.",
+		bad: `<p data-if="">Saved</p>`,
+		good: `<p data-if="saved">Saved</p>
+// card.ts
+this.set({ saved: true });`
+	},
+	"if-on-item-root": {
+		why: "The root element of a data-each item is the item itself, created and removed by the list. A data-if on it would fight the list over whether the item exists.",
+		bad: `<template data-each="rows">
+  <li data-if="visible">{{ label }}</li>
+</template>`,
+		good: `<template data-each="rows">
+  <li><span data-if="visible">{{ label }}</span></li>
+</template>`
+	},
+	"slot-in-list": {
+		why: "A slot is filled once by the light DOM of the component, but a data-each template is cloned for every item, so the same slot would appear many times.",
+		bad: `<template data-each="rows">
+  <li><slot></slot></li>
+</template>`,
+		good: `<slot></slot>
+<template data-each="rows">
+  <li>{{ label }}</li>
+</template>`
+	},
+	"style-not-top-level": {
+		why: "The component collects its styles from the top level of the template and applies them once. A style nested inside other markup would not be picked up.",
+		bad: `<div>
+  <style>p { color: red; }</style>
+  <p>hi</p>
+</div>`,
+		good: `<style>p { color: red; }</style>
+<div>
+  <p>hi</p>
+</div>`
+	},
+	"duplicate-slot": {
+		why: "Two slots with the same name receive the same light DOM, and the browser shows it in only one of them. This is a warning because it is sometimes a mistake of copying markup.",
+		bad: `<slot name="actions"></slot>
+<slot name="actions"></slot>`,
+		good: `<slot name="actions"></slot>
+<slot name="footer"></slot>`
+	},
+	"each-not-template": {
+		why: "A list needs an inert prototype that is cloned for each item. Only a <template> provides that without being rendered itself.",
+		bad: `<ul data-each="todos">
+  <li>{{ title }}</li>
+</ul>`,
+		good: `<ul>
+  <template data-each="todos">
+    <li>{{ title }}</li>
+  </template>
+</ul>`
+	},
+	"empty-each": {
+		why: "The data-each name becomes this.lists.<name>. An empty name gives codegen no list to generate.",
+		bad: `<template data-each="">
+  <li>{{ title }}</li>
+</template>`,
+		good: `<template data-each="todos">
+  <li>{{ title }}</li>
+</template>`
+	},
+	"nested-each": {
+		why: "Updates are explicit and local; nested lists would need a tree of lists to keep in step. Give the inner list to a child component instead.",
+		bad: `<template data-each="groups">
+  <li>
+    <template data-each="items"><span>{{ label }}</span></template>
+  </li>
+</template>`,
+		good: `<template data-each="groups" data-key="id" data-prop="group">
+  <group-row></group-row>
+</template>
+<!-- group-row.html has its own data-each="items" -->`
+	},
+	"duplicate-each": {
+		why: "Each data-each name becomes one entry of this.lists, so two lists with one name would be the same list in TypeScript.",
+		bad: `<template data-each="rows"><li>{{ a }}</li></template>
+<template data-each="rows"><li>{{ b }}</li></template>`,
+		good: `<template data-each="rows"><li>{{ a }}</li></template>
+<template data-each="extras"><li>{{ b }}</li></template>`
+	},
+	"each-binding-incomplete": {
+		why: "A list of components needs both the field that identifies an item (data-key) and the prop that receives it (data-prop). With only one, codegen cannot type the items assignment.",
+		bad: `<template data-each="tasks" data-key="id">
+  <task-row></task-row>
+</template>`,
+		good: `<template data-each="tasks" data-key="id" data-prop="task">
+  <task-row></task-row>
+</template>`
+	},
+	"invalid-each-binding": {
+		why: "data-key and data-prop are names, not paths: the key is a field of the item and the prop is a property of the item component. Both must be single identifiers so tsc can check them.",
+		bad: `<template data-each="tasks" data-key="meta.id" data-prop="the-task">
+  <task-row></task-row>
+</template>`,
+		good: `<template data-each="tasks" data-key="id" data-prop="task">
+  <task-row></task-row>
+</template>`
+	},
+	"each-binding-root": {
+		why: "With data-key and data-prop the item is a component that receives the data through its prop, so the item root must be exactly one custom element.",
+		bad: `<template data-each="tasks" data-key="id" data-prop="task">
+  <li>{{ title }}</li>
+</template>`,
+		good: `<template data-each="tasks" data-key="id" data-prop="task">
+  <task-row></task-row>
+</template>`
+	},
+	"each-root-count": {
+		why: "Each item is cloned as one element so the list can move and remove it as a unit. Zero or several roots would leave no single element to key.",
+		bad: `<template data-each="rows">
+  <dt>{{ term }}</dt>
+  <dd>{{ detail }}</dd>
+</template>`,
+		good: `<template data-each="rows">
+  <div><dt>{{ term }}</dt><dd>{{ detail }}</dd></div>
+</template>`
+	},
+	"document-tag": {
+		why: "A template is parsed as a fragment, and the browser drops <html>, <head> and <body> from fragments, so the markup would silently vanish.",
+		bad: `<body>
+  <h1>{{ title }}</h1>
+</body>`,
+		good: `<h1>{{ title }}</h1>`
+	},
+	"forbidden-tag": {
+		why: "A script in a template would run code from markup. Behavior belongs to TypeScript, and pages with Trusted Types enabled would block it.",
+		bad: `<script>alert(1)<\/script>`,
+		good: `// card.ts
+connected() { /* put the behavior in the class */ }`
+	},
+	"forbidden-attribute": {
+		why: "on* attributes and srcdoc run code from markup or are blocked by Trusted Types. Events are attached by data-on-* to a named method instead.",
+		bad: `<button onclick="save()">save</button>`,
+		good: `<button data-on-click="save">save</button>`
+	},
+	"unsafe-url": {
+		why: "A javascript: URL in href, src, action or formaction runs code when followed, and Trusted Types pages block it. Use a handler for behavior.",
+		bad: `<a href="javascript:void(0)">more</a>`,
+		good: `<button data-on-click="more">more</button>`
+	},
+	"duplicate-define": {
+		why: "A custom element tag can be registered only once, so two define() calls with one tag in the scanned directories would make the second fail at runtime and make the generated tag map ambiguous.",
+		bad: `// a.ts
+define("user-card", CardA);
+// b.ts
+define("user-card", CardB);`,
+		good: `// a.ts
+define("user-card", CardA);
+// b.ts
+define("user-badge", CardB);`
+	},
+	"unused-ref": {
+		why: "A data-ref that no code reads is dead markup, and it often means the code that was meant to use the element was removed or misspelled.",
+		bad: `<!-- card.html -->
+<input data-ref="name">
+// card.ts does not use this.refs.name`,
+		good: `<input data-ref="name">
+// card.ts
+this.refs.name.focus();`
+	},
+	"unused-if": {
+		why: "A data-if that is never toggled stays in its initial state forever, which usually means the condition was never wired up.",
+		bad: `<p data-if="error">Failed</p>
+// card.ts never sets "error"`,
+		good: `<p data-if="error">Failed</p>
+// card.ts
+this.set({ error: true });`
+	},
+	"unused-text": {
+		why: "A hole that no code fills renders empty, so the page shows nothing where a value was expected.",
+		bad: `<h2>{{ title }}</h2>
+// card.ts never sets "title"`,
+		good: `<h2>{{ title }}</h2>
+// card.ts
+this.set({ title: "Hello" });`
+	},
+	"unused-list": {
+		why: "A data-each that the class never assigns or fills always renders an empty list.",
+		bad: `<template data-each="rows"><li>{{ label }}</li></template>
+// card.ts never uses this.lists.rows`,
+		good: `<template data-each="rows"><li>{{ label }}</li></template>
+// card.ts
+this.lists.rows.replace(rows, (r) => r.id, (r, { text }) => (text.label = r.label));`
+	},
+	"unused-item-name": {
+		why: "A name inside a list item that no code fills or reads is dead markup, usually left over after the item shape changed.",
+		bad: `<template data-each="rows"><li>{{ label }} {{ note }}</li></template>
+// card.ts
+this.lists.rows.replace(rows, (r) => r.id, (r, { text }) => (text.label = r.label));`,
+		good: `<template data-each="rows"><li>{{ label }}</li></template>
+// card.ts
+this.lists.rows.replace(rows, (r) => r.id, (r, { text }) => (text.label = r.label));`
+	},
+	"missing-handler": {
+		why: "data-on-* names a method, and a missing method means the event does nothing. The same check runs in tsc through the generated types and in lint on the class text.",
+		bad: `<button data-on-click="save">save</button>
+// card.ts defines no save()`,
+		good: `<button data-on-click="save">save</button>
+// card.ts
+save() { /* ... */ }`
+	},
+	"no-importer": {
+		why: "A template that no TypeScript file imports never becomes a component, so it is dead code or an import that was forgotten.",
+		bad: `// card.html exists, but no .ts file contains
+// import tpl from "./card.html.js"`,
+		good: `// card.ts
+import tpl from "./card.html.js";`
+	},
+	"prop-forwarding": {
+		why: "Props go down one level. Handing your own prop straight to a child is prop drilling and hides where the data really comes from; use a shared store or have the parent that owns the data set the child.",
+		bad: `// panel.ts (props: { name: string })
+render(view) { this.refs.kid.name = view.name; }`,
+		good: `// panel.ts: fill the child from data this component owns
+render(view) { this.refs.kid.name = this.state.label; }`
+	},
+	"emit-forwarding": {
+		why: "Events go up, one level at a time, and a parent that only re-emits a child's event builds an implicit chain across layers. Handle the event where it matters, or use a shared store.",
+		bad: `// panel.ts
+onChange(e) { this.emit("change", e.detail); }`,
+		good: `// panel.ts
+onChange(e) { this.set({ value: e.detail.value }); }`
+	},
+	"props-mutation": {
+		why: "Props are read-only inside the component: the parent owns them and sets them. Assigning one here would be overwritten at the next parent update and breaks one-way data flow.",
+		bad: `// counter.ts (props: { count: number })
+inc() { this.count = this.count + 1; }`,
+		good: `// counter.ts
+inc() { this.emit("count-change", { value: this.props.count + 1 }); }`
+	},
+	"custom-event-on-native": {
+		why: "A child's custom event does not bubble, so a handler on a native element would never receive it. Events are handled on the tag of the component that emits them.",
+		bad: `<div data-on-quantity-change="update">
+  <qty-input></qty-input>
+</div>`,
+		good: `<div>
+  <qty-input data-on-quantity-change="update"></qty-input>
+</div>`
+	},
+	"unknown-prop": {
+		why: "An attribute on a child tag that the child does not declare in props is ignored at runtime, so a typo silently sets nothing.",
+		bad: `<x-kid lable="hi"></x-kid>`,
+		good: `<x-kid label="hi"></x-kid>
+// x-kid.ts: Component(tpl, { props: { label: "" } })`
+	},
+	"invalid-prop-value": {
+		why: "An attribute is always a string, so it can only set string, number or boolean props. Other types can only be passed as JS properties.",
+		bad: `<x-list items="a,b"></x-list>
+// x-list.ts: props: { items: [] as string[] }`,
+		good: `<x-list data-ref="list"></x-list>
+// panel.ts
+this.refs.list.items = ["a", "b"];`
+	},
+	"unknown-event": {
+		why: "The child does not declare this event in emits and it is not a native event, so the handler could never run. The check catches typos and removed events.",
+		bad: `<qty-input data-on-quantity-chnage="update"></qty-input>`,
+		good: `<qty-input data-on-quantity-change="update"></qty-input>
+// qty-input.ts: emits: { "quantity-change": event<{ value: number }>() }`
+	},
+	"img-alt": {
+		why: "Without alt, screen readers cannot describe the image, or read out its file name.",
+		bad: `<img src="logo.png">`,
+		good: `<img src="logo.png" alt="Nativele logo">
+<img src="divider.png" alt="">`
+	},
+	"control-name": {
+		why: "A button or link with no text, hole, slot or aria-label has no accessible name, so assistive technology announces it as an unnamed control.",
+		bad: `<button data-on-click="close"><svg></svg></button>`,
+		good: `<button data-on-click="close" aria-label="Close"><svg></svg></button>`
+	},
+	"form-label": {
+		why: "A form control without a label cannot be identified by screen readers, and clicking the label text will not focus it.",
+		bad: `<input data-ref="email">`,
+		good: `<label>Email <input data-ref="email"></label>`
+	},
+	"iframe-title": {
+		why: "A screen reader announces an iframe by its title. Without one the user cannot tell what it contains.",
+		bad: `<iframe src="/map"></iframe>`,
+		good: `<iframe src="/map" title="Office location map"></iframe>`
+	},
+	"dialog-name": {
+		why: "A dialog without a name is announced with no context when it opens.",
+		bad: `<dialog><p>Delete?</p></dialog>`,
+		good: `<dialog aria-label="Confirm delete"><p>Delete?</p></dialog>`
+	},
+	"heading-empty": {
+		why: "An empty heading adds an empty stop to the heading navigation of assistive technology.",
+		bad: `<h2></h2>`,
+		good: `<h2>{{ title }}</h2>`
+	},
+	"aria-role": {
+		why: "An invalid role is ignored by browsers, so the element loses the meaning you meant to give it. This is almost always a misspelling.",
+		bad: `<div role="buton">save</div>`,
+		good: `<div role="button" tabindex="0">save</div>`
+	},
+	"aria-attr": {
+		why: "An unknown aria-* attribute is ignored by assistive technology, so the state you meant to expose is lost. This is almost always a misspelling.",
+		bad: `<button aria-pressd="true">bold</button>`,
+		good: `<button aria-pressed="true">bold</button>`
+	},
+	"role-tabindex": {
+		why: "An element with an interactive role promises keyboard use, but a non-focusable element cannot be reached with the keyboard.",
+		bad: `<div role="button" data-on-click="save">save</div>`,
+		good: `<button data-on-click="save">save</button>`
+	},
+	"tabindex-positive": {
+		why: "A positive tabindex pulls an element ahead of the natural order and makes the focus order differ from the reading order.",
+		bad: `<button tabindex="3">save</button>`,
+		good: `<button tabindex="0">save</button>`
+	},
+	"hidden-focusable": {
+		why: "A focusable element inside aria-hidden=\"true\" can be reached by keyboard but is invisible to screen readers.",
+		bad: `<div aria-hidden="true"><button>save</button></div>`,
+		good: `<div><button>save</button></div>`
+	},
+	"label-for": {
+		why: "A <label for> that points to a missing id labels nothing, so the control stays unnamed.",
+		bad: `<label for="email">Email</label>
+<input id="mail">`,
+		good: `<label for="email">Email</label>
+<input id="email">`
+	},
+	"id-in-list": {
+		why: "A data-each template is cloned for every item, so an id inside it is repeated and no longer unique in the document.",
+		bad: `<template data-each="rows">
+  <li id="row">{{ label }}</li>
+</template>`,
+		good: `<template data-each="rows">
+  <li data-ref="row">{{ label }}</li>
+</template>`
+	},
+	"duplicate-id": {
+		why: "Ids must be unique, or label, aria-labelledby and similar references point at the wrong element.",
+		bad: `<input id="name">
+<input id="name">`,
+		good: `<input id="first-name">
+<input id="last-name">`
+	},
+	"aria-idref": {
+		why: "An ARIA attribute such as aria-labelledby refers to an id that is not in this template, so the reference is dead. If the id lives outside the component, ignore the rule for that file.",
+		bad: `<section aria-labelledby="heading">
+  <h2 id="title">{{ title }}</h2>
+</section>`,
+		good: `<section aria-labelledby="title">
+  <h2 id="title">{{ title }}</h2>
+</section>`
+	},
+	"heading-order": {
+		why: "Skipping heading levels breaks the outline that screen reader users navigate by.",
+		bad: `<h1>{{ title }}</h1>
+<h3>{{ subtitle }}</h3>`,
+		good: `<h1>{{ title }}</h1>
+<h2>{{ subtitle }}</h2>`
+	},
+	"table-header": {
+		why: "Without header cells, a screen reader cannot tell which column or row a data cell belongs to.",
+		bad: `<table><tr><td>Name</td><td>Age</td></tr></table>`,
+		good: `<table><tr><th>Name</th><th>Age</th></tr></table>`
+	},
+	"list-structure": {
+		why: "Screen readers announce lists by counting their items, which only works when <ul>/<ol> contain <li> and <li> sits inside a list.",
+		bad: `<ul><div>one</div></ul>`,
+		good: `<ul><li>one</li></ul>`
+	},
+	"landmark-label": {
+		why: "When several landmarks of one kind exist, users navigating by landmark hear identical names and cannot tell them apart.",
+		bad: `<nav>...</nav>
+<nav>...</nav>`,
+		good: `<nav aria-label="Main">...</nav>
+<nav aria-label="Footer">...</nav>`
+	},
+	"redundant-role": {
+		why: "A role that repeats the native role adds nothing and can drift from the element if it is changed later.",
+		bad: `<button role="button">save</button>`,
+		good: `<button>save</button>`
+	},
+	"click-semantics": {
+		why: "A div or span with data-on-click cannot be focused or activated by keyboard, and assistive technology does not know it is clickable.",
+		bad: `<div data-on-click="open">open</div>`,
+		good: `<button data-on-click="open">open</button>`
+	},
+	"stale-generated": {
+		why: "Types come from the generated *.html.ts files. If one is missing, outdated or orphaned, tsc checks against old templates and its errors may not match the HTML. ts-dom doctor reports the same condition as a warning.",
+		bad: `# card.html was edited, card.html.ts was not regenerated
+npx ts-dom check --no-write`,
+		good: `npx ts-dom gen
+# or: npx ts-dom check (it regenerates first)`
+	},
+	"missing-binding": {
+		why: "Every {{ hole }} and data-if must be backed by a field in state, props or derive. tsc finds the ones that are not, which usually means a typo or a forgotten declaration.",
+		bad: `<!-- card.html -->
+<h2>{{ title }}</h2>
+// card.ts
+Component(tpl, { state: { name: "" } })`,
+		good: `// card.ts
+Component(tpl, { state: { title: "" } })`
+	},
+	"conflicting-keys": {
+		why: "state, props and derive share one namespace in the view. The same name in two of them would make it unclear who owns the value, against one-way data flow.",
+		bad: `Component(tpl, {
+  state: { total: 0 },
+  derive: { total: (s) => s.count * 2 },
+})`,
+		good: `Component(tpl, {
+  state: { count: 0 },
+  derive: { total: (s) => s.count * 2 },
+})`
+	},
+	"reserved-prop": {
+		why: "A prop becomes a property on the element, and names such as title, hidden or render already belong to HTMLElement or ts-dom.",
+		bad: `Component(tpl, { props: { title: "" } })`,
+		good: `Component(tpl, { props: { heading: "" } })`
+	},
+	"native-event-name": {
+		why: "An emitted event with a native name such as click or input would be confused with the native event and handled by the wrong listeners.",
+		bad: `Component(tpl, { emits: { click: event() } })`,
+		good: `Component(tpl, { emits: { "item-select": event() } })`
+	},
+	"item-prop-missing": {
+		why: "A list with data-prop assigns each item to that property of the item component. If the component does not declare it, the items go nowhere.",
+		bad: `<template data-each="tasks" data-key="id" data-prop="task"><task-row></task-row></template>
+// task-row.ts
+Component(tpl, { props: { item: {} as Task } })`,
+		good: `// task-row.ts
+Component(tpl, { props: { task: {} as Task } })`
+	},
+	"item-not-in-tag-map": {
+		why: "tsc learns which class a tag stands for from ts-dom-tags.ts. If the item component is missing there, its items cannot be typed.",
+		bad: `// task-row.ts defines the tag, but ts-dom-tags.ts is out of date
+define("task-row", TaskRow);`,
+		good: `npx ts-dom gen   # regenerates ts-dom-tags.ts`
+	},
+	"item-class-not-exported": {
+		why: "The tag map imports the class from the file that calls define(), so the class must be exported or tsc cannot see its props.",
+		bad: `class TaskRow extends Component(tpl, {}) {}
+define("task-row", TaskRow);`,
+		good: `export class TaskRow extends Component(tpl, {}) {}
+define("task-row", TaskRow);`
+	},
+	tsc: {
+		why: "Any TypeScript error that none of the specific rules recognizes is passed through as tsc prints it, at its TypeScript location, so one command shows every problem.",
+		bad: `// card.ts
+const n: number = "1";`,
+		good: `// card.ts
+const n: number = 1;`
+	},
+	"tsc-failed": {
+		why: "When tsc stops before checking (no tsconfig, a bad option, a crash), a check that only looked for type errors would pass with none. This rule makes that visible.",
+		bad: `npx ts-dom check --project=tsconfig.app.json   # the file does not exist`,
+		good: `npx ts-dom check --project=tsconfig.json`
+	},
+	"dir-not-found": {
+		why: "A folder given to ts-dom check or doctor that does not exist would otherwise be skipped silently, and a clean result would only mean that nothing was looked at.",
+		bad: `npx ts-dom check ap   # the templates live in app/`,
+		good: `npx ts-dom check app`
+	},
+	"tsc-not-found": {
+		why: "ts-dom check runs the TypeScript compiler of the project. Without it installed, nothing can be type-checked.",
+		bad: `npx ts-dom check   # typescript is not installed`,
+		good: `npm i -D typescript
+npx ts-dom check`
+	},
+	"no-tsconfig": {
+		why: "The core value of the library is that tsc checks HTML against TypeScript, and tsc needs a tsconfig.json to know what to check.",
+		bad: `# project root has no tsconfig.json`,
+		good: `// tsconfig.json
+{ "compilerOptions": { "strict": true, "lib": ["ES2022", "DOM"] }, "include": ["src"] }`
+	},
+	"tsconfig-not-strict": {
+		why: "Without strict, tsc lets wrong names and null values through, which removes most of what the generated types are for.",
+		bad: `// tsconfig.json
+{ "compilerOptions": { "strict": false } }`,
+		good: `// tsconfig.json
+{ "compilerOptions": { "strict": true } }`
+	},
+	"tsconfig-no-dom-lib": {
+		why: "Components extend HTMLElement and refs are element types. Without the DOM lib those types do not exist.",
+		bad: `// tsconfig.json
+{ "compilerOptions": { "lib": ["ES2022"] } }`,
+		good: `// tsconfig.json
+{ "compilerOptions": { "lib": ["ES2022", "DOM"] } }`
+	},
+	"tsconfig-classic-resolution": {
+		why: "Templates are imported as ./x.html.js and TypeScript must map that to the generated x.html.ts. The classic resolution does not do that mapping.",
+		bad: `// tsconfig.json
+{ "compilerOptions": { "moduleResolution": "classic" } }`,
+		good: `// tsconfig.json
+{ "compilerOptions": { "moduleResolution": "bundler" } }`
+	},
+	"tsconfig-misses-templates": {
+		why: "tsc only checks files under include. A template folder left out means its generated types are never checked against the components.",
+		bad: `// tsconfig.json
+{ "include": ["src/server"] }   // templates are in src/ui`,
+		good: `// tsconfig.json
+{ "include": ["src"] }`
+	},
+	"runtime-not-installed": {
+		why: "Generated files import the runtime package. If it cannot be resolved from the project, they fail to compile and to run.",
+		bad: `// card.html.ts imports "@nativele/ts-dom", which is not installed`,
+		good: `npm i @nativele/ts-dom`
+	},
+	"template-import-without-js": {
+		why: "Without a bundler plugin, ./x.html is not a module. ./x.html.js is what TypeScript maps to the generated x.html.ts, and it works with or without Vite.",
+		bad: `import tpl from "./card.html";`,
+		good: `import tpl from "./card.html.js";`
+	},
+	"vite-plugin-missing": {
+		why: "The Vite plugin regenerates the .html.ts files while the dev server runs. Without it, edits to a template are not reflected until gen is run by hand.",
+		bad: `// vite.config.ts
+export default defineConfig({ plugins: [] });`,
+		good: `// vite.config.ts
+import { tsDom } from "@nativele/ts-dom/vite";
+export default defineConfig({ plugins: [tsDom()] });`
+	},
+	"oxlint-plugin-missing": {
+		why: "The oxlint plugin runs the template rules (unused markup, data flow, accessibility) in the editor. Without it they only run from the CLI.",
+		bad: `// .oxlintrc.json
+{ "rules": {} }`,
+		good: `// .oxlintrc.json
+{
+  "jsPlugins": [{ "name": "ts-dom", "specifier": "@nativele/ts-dom/oxlint" }],
+  "rules": { "ts-dom/unused-markup": "warn" }
+}`
+	},
+	"formatter-whitespace": {
+		why: "Text whitespace in a template is kept as written. A formatter that re-indents the HTML can then change the spaces rendered on the page.",
+		bad: `# formatter is configured, templates keep their whitespace
+npx ts-dom gen`,
+		good: `npx ts-dom gen --whitespace=collapse
+// or in vite.config.ts: tsDom({ whitespace: "collapse" })`
+	}
+};
 // src/cli.ts
 const HELP = `ts-dom <command> [dirs...] [flags]
 
 Commands
   gen   [dirs...]   Generate x.html.ts for every x.html, plus ts-dom-tags.ts (default dir: src)
         --watch           keep watching and regenerate on change
+        --check           write nothing; list generated files that are missing, outdated or orphaned, exit 1 if any
         --include=<glob>  only these templates (repeatable; relative to each dir, ** crosses folders)
         --exclude=<glob>  leave these templates out (repeatable)
         --whitespace=collapse   collapse whitespace in text and drop line-break-only text between tags
+        --whitespace=preserve   keep whitespace as written; without either, the mode the generated files were
+                                last written with is kept (gen, gen --check, check and doctor all follow it)
   lint  [dirs...]   Check templates against the code that uses them (default dir: src)
+        --a11y            also check ARIA / accessibility (warnings)
+        --strict          exit with code 1 on warnings too (errors always do)
+        --json            print the issues as JSON instead of text (also for gen --check)
+  check [dirs...]   One pass for agents and CI: template diagnostics, generated files, tsc errors mapped back
+                    to the templates, and the lint rules (default dir: src)
+        --no-write        do not regenerate; report stale generated files instead
+        --project=<path>  tsconfig for tsc (default: tsc's own lookup)
         --a11y            also check ARIA / accessibility (warnings)
         --strict          exit with code 1 on warnings too (errors always do)
         --json            print the issues as JSON instead of text
+  doctor [dirs...]  Check the project set-up: tsconfig, template imports, generated files, the runtime package,
+                    and the Vite, oxlint and formatter configuration (default dir: src)
+        --json            print the issues as JSON instead of text
   rules             List every rule id with its description
+        --explain=<id>    why the rule exists, a wrong example and the fix (the id as printed in [brackets])
+        --json            print every rule as JSON: { id, group, description, why, bad, good }
 
 Output format: file:line:col severity [rule-id] message. Each message says what is wrong and how to fix it.
 Exit code: 0 = clean, 1 = errors found (or warnings with --strict).
 `;
-function tsFiles(dir) {
-	return readdirSync(dir).flatMap((n) => {
-		if (n === "node_modules") return [];
-		const f = join(dir, n);
-		if (statSync(f).isDirectory()) return tsFiles(f);
-		return n.endsWith(".ts") && !n.endsWith(".d.ts") && !n.endsWith(".html.ts") && n !== "ts-dom-tags.ts" ? [f] : [];
-	});
-}
-function printRules() {
-	const groups = [
+function ruleGroups() {
+	return [
 		[
 			"gen",
 			"reported by `ts-dom gen` while analyzing a template (errors stop code generation)",
 			CODEGEN_RULES
 		],
+		[
+			"check",
+			"reported by `ts-dom check` (tsc errors mapped back to the templates, and generated file state)",
+			CHECK_RULES
+		],
+		[
+			"doctor",
+			"reported by `ts-dom doctor` (project set-up)",
+			DOCTOR_RULES
+		],
 		[
 			"lint: unused-markup",
-			"errors from `ts-dom lint` / oxlint rule ts-dom/unused-markup",
+			"errors from `ts-dom lint` / oxlint rule ts-dom/unused-markup (or ts-dom/<id>)",
 			UNUSED_MARKUP_RULES
 		],
 		[
 			"lint: data-flow",
-			"warnings from `ts-dom lint` / oxlint rule ts-dom/data-flow",
+			"warnings from `ts-dom lint` / oxlint rule ts-dom/data-flow (or ts-dom/<id>)",
 			DATA_FLOW_RULES
 		],
 		[
 			"lint: a11y",
-			"warnings from `ts-dom lint --a11y` / oxlint rule ts-dom/a11y",
+			"warnings from `ts-dom lint --a11y` / oxlint rule ts-dom/a11y (or ts-dom/<id>)",
 			Object.fromEntries(Object.entries(A11Y_RULES).map(([k, v]) => [k, v.split(". Fix:")[0]]))
 		]
 	];
-	for (const [name, note, rules] of groups) {
+}
+function printRules() {
+	const explain = args.find((a) => a.startsWith("--explain="))?.slice(10);
+	if (explain !== void 0) {
+		const doc = RULE_DOCS[explain];
+		const where = ruleGroups().filter(([, , rules]) => explain in rules);
+		if (!doc || !where.length) {
+			console.error(`Unknown rule id "${explain}". Fix: run ts-dom rules to see every id.`);
+			process.exitCode = 1;
+			return;
+		}
+		console.log(`[${explain}] ${where.map(([g, , r]) => `${g}: ${r[explain]}`).join("; ")}\n\nWhy: ${doc.why}\n\nWrong:\n${doc.bad}\n\nRight:\n${doc.good}`);
+		return;
+	}
+	if (flags.has("--json")) {
+		const rules = ruleGroups().flatMap(([group, , rules]) => Object.entries(rules).map(([id, description]) => ({
+			id,
+			group,
+			description,
+			...RULE_DOCS[id]
+		})));
+		console.log(JSON.stringify({ rules }, null, 2));
+		return;
+	}
+	for (const [name, note, rules] of ruleGroups()) {
 		console.log(`\n${name}: ${note}`);
-		for (const [id, desc] of Object.entries(rules)) console.log(`  ${id.padEnd(24)} ${desc}`);
+		for (const [id, desc] of Object.entries(rules)) console.log(`  ${id.padEnd(28)} ${desc}`);
 	}
+	console.log("\nts-dom rules --explain=<id> shows why a rule exists, with a wrong and a right example.");
 }
 const [cmd, ...args] = process.argv.slice(2);
 const flags = new Set(args.filter((a) => a.startsWith("--")));
 const globs = (name) => args.filter((a) => a.startsWith(`--${name}=`)).map((a) => a.slice(name.length + 3));
+const whitespace = flags.has("--whitespace=collapse") ? "collapse" : flags.has("--whitespace=preserve") ? "preserve" : void 0;
 const generate = {
 	include: globs("include"),
 	exclude: globs("exclude"),
-	whitespace: flags.has("--whitespace=collapse") ? "collapse" : "preserve"
+	...whitespace ? { whitespace } : {}
 };
 const dirs = args.filter((a) => !a.startsWith("--"));
 if (!dirs.length) dirs.push("src");
 try {
-	if (cmd === "gen") {
+	if (cmd === "gen" && flags.has("--check")) {
+		const results = dirs.map((d) => checkGenerated(d, generate));
+		const stale = results.flatMap((r) => r.stale);
+		const errors = results.flatMap((r) => r.errors);
+		if (flags.has("--json")) console.log(JSON.stringify({
+			stale: stale.map((s) => ({
+				...s,
+				file: relative(process.cwd(), s.file)
+			})),
+			errors
+		}, null, 2));
+		else {
+			for (const s of stale) console.error(`${relative(process.cwd(), s.file)}:1:1 error [stale-generated] The generated file is ${s.reason}. Fix: run ts-dom gen.`);
+			for (const e of errors) console.error(e);
+			if (!stale.length && !errors.length) console.log("ts-dom gen --check: generated files are up to date");
+		}
+		if (stale.length || errors.length) process.exitCode = 1;
+	} else if (cmd === "gen") {
 		let failed = false;
 		for (const d of dirs) try {
 			generateAll(d, generate);
@@ -86,8 +1185,30 @@ try {
 			});
 			await new Promise(() => {});
 		}
+	} else if (cmd === "check") {
+		const project = args.find((a) => a.startsWith("--project="))?.slice(10);
+		const issues = runCheck({
+			dirs,
+			generate,
+			write: !flags.has("--no-write"),
+			a11y: flags.has("--a11y"),
+			...project ? { project } : {}
+		});
+		if (flags.has("--json")) console.log(JSON.stringify({ issues }, null, 2));
+		else for (const i of issues) (i.severity === "error" ? console.error : console.warn)(formatIssue(i));
+		if (issues.filter((i) => i.severity === "error").length || flags.has("--strict") && issues.length) process.exitCode = 1;
+		if (!flags.has("--json") && !issues.length) console.log("ts-dom check: no issues");
+	} else if (cmd === "doctor") {
+		const issues = runDoctor({
+			dirs,
+			generate
+		});
+		if (flags.has("--json")) console.log(JSON.stringify({ issues }, null, 2));
+		else for (const i of issues) (i.severity === "error" ? console.error : console.warn)(formatDoctorIssue(i));
+		if (issues.some((i) => i.severity === "error")) process.exitCode = 1;
+		if (!flags.has("--json") && !issues.length) console.log("ts-dom doctor: the set-up looks right");
 	} else if (cmd === "lint") {
-		const files = dirs.flatMap(tsFiles);
+		const files = dirs.flatMap(listTs);
 		const issues = [...lintUsage(dirs, files), ...lintDataFlow(dirs, files)];
 		if (flags.has("--a11y")) for (const dir of dirs) for (const f of listHtml(dir)) for (const d of checkA11y(readFileSync(f, "utf8"))) issues.push({
 			file: relative(process.cwd(), f),