@nativele/ts-dom 0.5.4 → 0.6.0

package/dist/cli.mjs

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
-import { _ as staleGenerated, a as analyze, c as formatDiagnostics, f as isSelected, g as scanDefines, h as renderTags, i as CodegenError, l as generateDirs, m as listTs, n as checkA11y, o as checkGenerated, p as listHtml, r as CODEGEN_RULES, s as crossDirDuplicates, t as A11Y_RULES, v as watchAll } from "./a11y-CiEJj_e6.mjs";
-import { c as lintUsage, n as UNUSED_MARKUP_RULES, o as formatIssue, s as lintDataFlow, t as DATA_FLOW_RULES } from "./lint-Did4w-NL.mjs";
+import { _ as scanTags, a as analyze, c as formatDiagnostics, f as isSelected, g as scanDefines, h as renderTags, i as CodegenError, l as generateDirs, m as listTs, n as checkA11y, o as checkGenerated, p as listHtml, r as CODEGEN_RULES, s as crossDirDuplicates, t as A11Y_RULES, v as staleGenerated, y as watchAll } from "./a11y-KXbo-8o3.mjs";
+import { c as lintDataFlow, l as lintUsage, n as UNUSED_MARKUP_RULES, s as formatIssue, t as DATA_FLOW_RULES } from "./lint-DUsdDKZ-.mjs";
 import { createRequire } from "node:module";
 import { cpSync, existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 // src/lib/tsconfig.ts
 /** tsconfig is JSONC: drop comments and trailing commas before parsing. */
@@ -29,30 +30,71 @@ function resolveExtends(from, ext) {
 	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) {
+function readTsConfig(file) {
+	const config = readChain(file, 0);
+	return config.include === void 0 && config.files ? {
+		...config,
+		include: []
+	} : config;
+}
+/** include, exclude and files are each taken from the nearest config that sets it, as tsc does; the default include is decided only for the whole chain. */
+function readChain(file, depth) {
 	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);
+		const base = readChain(target, depth + 1);
 		merged = {
+			...merged,
+			...base,
 			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 ?? (Array.isArray(json.files) ? [] : void 0);
+	const own = (key) => Array.isArray(json[key]) ? json[key].map((p) => resolve(dirname(file), p).split("\\").join("/")) : merged[key];
+	const [include, exclude, files] = [
+		own("include"),
+		own("exclude"),
+		own("files")
+	];
 	return {
 		compilerOptions: {
 			...merged.compilerOptions,
 			...json.compilerOptions
 		},
-		...include ? { include } : {}
+		...include ? { include } : {},
+		...exclude ? { exclude } : {},
+		...files ? { files } : {}
+	};
+}
+/** A tsconfig include or exclude pattern (absolute, forward slashes) as tsc matches it: `**` crosses folders, `*` and `?` stay within one, a last segment without a wildcard or an extension names a folder, and an exclude also removes everything under a folder it matches. */
+function globRegExp(pattern, exclude) {
+	const last = pattern.slice(pattern.lastIndexOf("/") + 1);
+	const segments = (!exclude && !/[*?]/.test(last) && !/\.[^.]+$/.test(last) ? `${pattern.replace(/\/$/, "")}/**/*` : pattern).split("/");
+	const body = segments.map((seg, i) => {
+		const end = i === segments.length - 1;
+		if (seg === "**") return end ? ".*" : "(?:[^/]+/)*";
+		const text = seg.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]");
+		return end ? text : `${text}/`;
+	}).join("");
+	return new RegExp(`^${body}${exclude ? "(?:$|/)" : "$"}`);
+}
+/**
+* Why tsc leaves `file` out of the program of a config whose folder is `configDir`, unless another file imports it: include does not match it, or an exclude pattern removes it.
+* null when files, or include without a matching exclude, take it in.
+*/
+function leftOutBy(config, configDir, file) {
+	const f = file.split("\\").join("/");
+	if (config.files?.includes(f)) return null;
+	if (!(config.include ?? [`${configDir.split("\\").join("/")}/**/*`]).some((p) => globRegExp(p, false).test(f))) return { by: "include" };
+	const pattern = config.exclude?.find((p) => globRegExp(p, true).test(f));
+	return pattern === void 0 ? null : {
+		by: "exclude",
+		pattern
 	};
 }
 /**
@@ -81,7 +123,7 @@ const CHECK_RULES = {
 	"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",
+	"tsc-not-found": "TypeScript is not installed in the project, so types were not checked and the check fails",
 	"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"
 };
@@ -125,7 +167,7 @@ const CONTRACT = [
 	[
 		"itemComponentMissingFromTagMap",
 		"item-not-in-tag-map",
-		"run ts-dom gen so ts-dom-tags.ts lists the item component"
+		"run ts-dom gen so ts-dom-tags.ts lists the item component; if it already does, the tsconfig include or exclude leaves ts-dom-tags.ts out of the program (ts-dom doctor reports it as tsconfig-misses-tag-map): make include match it"
 	],
 	[
 		"itemComponentClassNotExported",
@@ -163,7 +205,7 @@ function mapTscErrors(errors, cwd) {
 			};
 		}
 	};
-	const brokenClasses = /* @__PURE__ */ new Set();
+	const brokenClasses = /* @__PURE__ */ new Map();
 	const brokenBodies = [];
 	for (const e of errors) {
 		if (!/missingStateKeys|conflictingKeys|reservedPropNames|nativeEventNames/.test(e.message)) continue;
@@ -171,7 +213,7 @@ function mapTscErrors(errors, cwd) {
 		const lines = text.split("\n");
 		const m = /class\s+([A-Za-z_$][\w$]*)\s+extends\s+Component\s*\(/.exec(lines[e.line - 1] ?? "");
 		if (!m?.[1]) continue;
-		brokenClasses.add(m[1]);
+		if (!brokenClasses.has(m[1])) brokenClasses.set(m[1], e);
 		const end = classBodyEnd(text, lines.slice(0, e.line - 1).join("\n").length + (e.line > 1 ? 1 : 0) + m.index + m[0].length - 1);
 		if (end !== -1) brokenBodies.push({
 			file: rel(resolve(cwd, e.file)),
@@ -179,8 +221,9 @@ function mapTscErrors(errors, cwd) {
 			to: text.slice(0, end).split("\n").length
 		});
 	}
-	const followsBroken = (i) => [...brokenClasses].some((c) => i.message.includes(`'${c}'`) || i.message.includes(`'typeof ${c}'`)) || brokenBodies.some((b) => b.file === i.file && i.line > b.from && i.line <= b.to);
+	const firstIssueOf = /* @__PURE__ */ new Map();
 	for (const e of errors) {
+		const before = out.length;
 		const file = resolve(cwd, e.file);
 		const where = `${rel(file)}:${e.line}:${e.col}`;
 		const issue = (rule, message, at) => out.push({
@@ -217,11 +260,50 @@ function mapTscErrors(errors, cwd) {
 			named = true;
 			issue(rule, `${e.message.split("\n")[0]} Fix: ${fix}.`);
 		}
-		if (named) continue;
-		if (file.endsWith(".html.ts") || file.endsWith(`${sep}ts-dom-tags.ts`)) issue("tsc", `${e.code}: ${e.message} This file is generated, so an edit to it is overwritten. Fix: run ts-dom gen for the folder that holds it; if it is left over from a template or folder that is no longer scanned, delete it.`);
+		if (named) {
+			firstIssueOf.set(e, out[before]);
+			continue;
+		}
+		const tag = /Property '"([^"]+)"' must be of type/.exec(e.message)?.[1];
+		if (e.code === "TS2717" && tag && file.endsWith(`${sep}ts-dom-tags.ts`)) issue("duplicate-define", `The tag <${tag}> is declared with another class by a second tag map in the same program (another generated ts-dom-tags.ts, from a folder that is scanned separately or from a package), so two components share one custom element name, and at runtime only the class whose define() runs first is registered: the other define() is skipped without an error (tsc ${e.code} at ${where}). Fix: rename the tag in one of the define() calls and in the templates that use it; editing this generated file does not help.`);
+		else if (file.endsWith(".html.ts") || file.endsWith(`${sep}ts-dom-tags.ts`)) issue("tsc", `${e.code}: ${e.message} This file is generated, so an edit to it is overwritten. Fix: run ts-dom gen for the folder that holds it; if it is left over from a template or folder that is no longer scanned, delete it.`);
 		else 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));
+	const brokenFiles = new Set([...brokenClasses.values()].map((e) => rel(resolve(cwd, e.file))));
+	const classIn = (message) => {
+		const types = [...message.matchAll(/'([^']*)'/g)].flatMap((m) => topLevelMembers(m[1]).map((t) => t.replace(/^typeof\s+/, "")));
+		return [...brokenClasses.keys()].find((c) => types.includes(c));
+	};
+	return out.flatMap((i) => {
+		const cls = i.rule === "tsc" ? classIn(i.message) : void 0;
+		if (i.rule === "tsc" && brokenBodies.some((b) => b.file === i.file && i.line > b.from && i.line <= b.to)) return [];
+		if (cls === void 0) return [i];
+		if (brokenFiles.has(i.file) || /(^|[\\/])node_modules[\\/]/.test(i.file)) return [];
+		const cause = brokenClasses.get(cls);
+		const first = firstIssueOf.get(cause);
+		const at = first ? `${first.file}:${first.line}:${first.col} [${first.rule}]` : `${rel(resolve(cwd, cause.file))}:${cause.line}:${cause.col}`;
+		return [{
+			...i,
+			message: `${i.message.replace(/ Fix: .*$/s, "")} This error follows from the contract error of ${cls} at ${at}, which makes tsc type ${cls} as that error instead of an element. Fix: fix that error first; this one then goes away.`
+		}];
+	});
+}
+/** The members of a union or intersection type as tsc prints it (`A & { x: number; }` gives `A` and `{ x: number; }`); any other type is its only member. */
+function topLevelMembers(type) {
+	const out = [];
+	let depth = 0;
+	let from = 0;
+	for (let i = 0; i < type.length; i++) {
+		const c = type[i];
+		if ("({[<".includes(c)) depth++;
+		else if (")}]".includes(c) || c === ">" && type[i - 1] !== "=") depth--;
+		else if (depth === 0 && (c === "&" || c === "|")) {
+			out.push(type.slice(from, i));
+			from = i + 1;
+		}
+	}
+	out.push(type.slice(from));
+	return out.map((t) => t.trim());
 }
 /** The offset of the `}` that closes a class body, given the offset of the `(` of its `extends Component(`; -1 when it cannot be found. Strings and comments are skipped. */
 function classBodyEnd(text, open) {
@@ -328,8 +410,8 @@ function runCheck(options) {
 		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."
+		severity: "error",
+		message: "TypeScript is not installed in this project, so no types were checked, and a check without them would pass with nothing looked at. Fix: npm i -D typescript (in CI, install the dev dependencies before ts-dom check)."
 	});
 	else {
 		const configs = projectConfigs(cwd, options.project);
@@ -475,10 +557,11 @@ function libraryVersion(root = skillsRoot()) {
 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-not-strict": "strict is off (set to false, or left out on TypeScript 5 or a version that cannot be determined), so tsc does not report possibly null values or implicit any",
 	"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-classic-resolution": "modules resolve the classic way (moduleResolution classic, or the TypeScript 5 default for module ES2015 to ESNext), which cannot resolve the runtime package the generated files import; TypeScript 6 deprecates it and 7 removes it",
 	"tsconfig-misses-templates": "include leaves out a folder with templates, so their generated types are not checked",
+	"tsconfig-misses-tag-map": "include or exclude leaves ts-dom-tags.ts out of the program and no file imports it, so custom element tags are typed as plain HTMLElement",
 	"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",
@@ -518,6 +601,83 @@ function scriptSteps(scripts, name, depth = 0) {
 		...scriptSteps(scripts, `post${name}`, depth + 1)
 	];
 }
+/** The version of the TypeScript the project resolves, or null when it has none. */
+function typescriptVersion(cwd) {
+	try {
+		return JSON.parse(readFileSync(createRequire(join(cwd, "package.json")).resolve("typescript/package.json"), "utf8")).version ?? null;
+	} catch {
+		return null;
+	}
+}
+const TS5_CLASSIC_MODULES = /* @__PURE__ */ new Set([
+	"es6",
+	"es2015",
+	"es2020",
+	"es2022",
+	"esnext",
+	"amd",
+	"umd",
+	"system",
+	"none"
+]);
+const implicitlyClassic = (o) => {
+	if (o.module !== void 0) return TS5_CLASSIC_MODULES.has(String(o.module).toLowerCase());
+	return ![
+		"",
+		"es3",
+		"es5"
+	].includes(String(o.target ?? "").toLowerCase());
+};
+const readPackageJson = (file) => {
+	try {
+		return JSON.parse(readFileSync(file, "utf8"));
+	} catch {
+		return {};
+	}
+};
+/** `cwd` and the folders above it up to the workspace root: the nearest folder with a package.json "workspaces" field or a pnpm-workspace.yaml, else the git root. Only `cwd` when neither is found below the home directory or the filesystem root. */
+function upToWorkspaceRoot(cwd) {
+	const start = resolve(cwd);
+	const home = homedir();
+	const chain = [];
+	for (let dir = start;; dir = dirname(dir)) {
+		if (dir === home && dir !== start) return [start];
+		chain.push(dir);
+		if (existsSync(join(dir, "pnpm-workspace.yaml")) || "workspaces" in readPackageJson(join(dir, "package.json")) || existsSync(join(dir, ".git"))) return chain;
+		if (dirname(dir) === dir) return [start];
+	}
+}
+const SCRIPT_EXTENSIONS = [
+	"js",
+	"cjs",
+	"mjs",
+	"ts",
+	"cts",
+	"mts"
+];
+const OXFMT_CONFIGS = [
+	".oxfmtrc.json",
+	".oxfmtrc.jsonc",
+	...SCRIPT_EXTENSIONS.map((e) => `oxfmt.config.${e}`)
+];
+const PRETTIER_CONFIGS = [
+	".prettierrc",
+	...[
+		"json",
+		"json5",
+		"yaml",
+		"yml",
+		"toml",
+		...SCRIPT_EXTENSIONS
+	].map((e) => `.prettierrc.${e}`),
+	...SCRIPT_EXTENSIONS.map((e) => `prettier.config.${e}`)
+];
+const MODULE_SPECIFIERS = /\b(?:from|import)\s*\(?\s*["'](\.{1,2}\/[^"']+)["']|<reference\s+path\s*=\s*["']([^"']+)["']/g;
+/** Whether `file` imports, re-exports or references `tagMap` through a relative path. */
+function importsTagMap(file, tagMap) {
+	const target = tagMap.replace(/\.ts$/, "");
+	return [...(readText(file) ?? "").matchAll(MODULE_SPECIFIERS)].some((m) => resolve(dirname(file), m[1] ?? m[2]).replace(/\.[jt]s$/, "") === target);
+}
 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. */
@@ -536,9 +696,14 @@ function runDoctor(options) {
 	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);
+	const configs = projectConfigs(cwd, options.project);
 	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\").");
+	if (!configs.length) {
+		if (options.project) add("no-tsconfig", "error", `The tsconfig ${options.project} given with --project does not exist. Fix: pass the path of the tsconfig the project type-checks with.`);
+		else add("no-tsconfig", "error", "There is no tsconfig.json. Fix: add one with \"strict\": true, \"lib\": [\"ES2022\", \"DOM\"] and \"moduleResolution\": \"bundler\" (or \"NodeNext\").");
+	}
+	const tsVersion = typescriptVersion(cwd);
+	const tsMajor = tsVersion === null ? null : Number.parseInt(tsVersion, 10);
 	const includes = [];
 	let everyConfigIncludes = true;
 	const scanned = dirs.map((dir) => ({
@@ -561,16 +726,42 @@ function runDoctor(options) {
 		if (config.include) includes.push(...config.include);
 		else everyConfigIncludes = false;
 		if (covering.length && !covering.some((r) => r.path === configPath)) continue;
-		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 lost = "so tsc does not report values that may be null (a querySelector result or an optional ref used without a check) or parameters and variables that are implicitly any (a handler parameter without a type); the names in the templates are checked either way";
+		if (o.strict === false) add("tsconfig-not-strict", "warning", `compilerOptions.strict is false, ${lost}. Fix: set "strict": true.`, { file });
+		else if (o.strict === void 0 && tsMajor === null) add("tsconfig-not-strict", "warning", `compilerOptions.strict is not set, and the TypeScript version could not be determined (typescript is not resolvable from this project): TypeScript 5 leaves strict off by default (6 and later turn it on), ${lost}. Fix: set "strict": true.`, { file });
+		else if (o.strict === void 0 && tsMajor !== null && tsMajor < 6) add("tsconfig-not-strict", "warning", `compilerOptions.strict is not set, and TypeScript ${tsVersion} leaves it off by default (6 and later turn it on), ${lost}. 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 });
+		const cannotResolve = `which cannot resolve the package "${runtime}" that every generated file imports (TS2792 Cannot find module), so no component gets its types`;
+		if (String(o.moduleResolution ?? "").toLowerCase() === "classic") add("tsconfig-classic-resolution", "error", `moduleResolution is "classic", ${tsMajor === null ? `${cannotResolve}; TypeScript 6 deprecates it (TS5107) and 7 removes it (TS5108)` : tsMajor >= 7 ? `which TypeScript ${tsVersion} no longer supports, so tsc stops with TS5108 before checking anything` : tsMajor === 6 ? `which TypeScript ${tsVersion} deprecates, so tsc stops with TS5107 before checking anything` : cannotResolve}. Fix: use "bundler" (or "NodeNext" with "module": "NodeNext").`, { file });
+		else if (o.moduleResolution === void 0 && tsMajor !== null && tsMajor < 6 && implicitlyClassic(o)) add("tsconfig-classic-resolution", "error", `${o.module !== void 0 ? `"module": ${JSON.stringify(o.module)}` : `"target": ${JSON.stringify(o.target)} (which makes module ES2015 or later)`} without "moduleResolution" makes TypeScript ${tsVersion} resolve modules the classic way, ${cannotResolve}. Fix: add "moduleResolution": "bundler" (or set "module" and "moduleResolution" to "NodeNext").`, { file });
 	}
 	if (configs.length && everyConfigIncludes) {
 		const missed = /* @__PURE__ */ new Set();
 		for (const folder of scanned.flatMap((s) => s.folders)) 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]) });
 	}
+	for (const { dir, folders } of scanned) {
+		const tags = scanTags(dir).map((t) => `<${t.tag}>`);
+		if (!tags.length) continue;
+		const tagMap = join(dir, "ts-dom-tags.ts");
+		const left = read.filter(({ config: { include } }) => !include || (folders.length ? folders : [dir]).some((t) => include.some((p) => covers(p, t)))).map(({ path, config }) => ({
+			path,
+			config,
+			why: leftOutBy(config, dirname(path), tagMap)
+		}));
+		const first = left[0];
+		if (!first?.why || left.some((l) => !l.why)) continue;
+		const configDir = dirname(first.path);
+		if ([
+			...listTs(dir),
+			...first.config.files ?? [],
+			...listTs(configDir).filter((f) => !leftOutBy(first.config, configDir, f))
+		].some((f) => importsTagMap(f, tagMap))) continue;
+		const own = (p) => relative(configDir, p).split("\\").join("/") || ".";
+		const effect = `so tsc types the tags defined in ${rel(dir)} (${tags.slice(0, 3).join(", ")}${tags.length > 3 ? ", ..." : ""}) as plain HTMLElement in document.createElement, querySelector and refs, and every list of item components fails with item-not-in-tag-map`;
+		add("tsconfig-misses-tag-map", "error", first.why.by === "include" ? `The include of ${rel(first.path)} does not match ${rel(tagMap)}, and no file imports it, ${effect}. Fix: add "${own(tagMap)}" to include.` : `The exclude pattern "${own(first.why.pattern)}" in ${rel(first.path)} removes ${rel(tagMap)} from the program, and no file imports it, ${effect}. Fix: narrow the pattern so it leaves ts-dom-tags.ts in, or add "${own(tagMap)}" to files (files are kept even when exclude matches them).`, { file: rel(first.path) });
+	}
 	let resolvable = Object.keys(paths).includes(runtime);
 	if (!resolvable) try {
 		createRequire(join(cwd, "package.json")).resolve(`${runtime}/package.json`);
@@ -615,7 +806,15 @@ function runDoctor(options) {
 	].map((ext) => join(cwd, `vitest.config.${ext}`)).find((f) => existsSync(f));
 	const vitest = vitestConfig ? readText(vitestConfig) : null;
 	if (vitestConfig && vitest !== null && !/@nativele\/ts-dom\/vite|vite-plugin(\.ts)?["']/.test(vitest) && !/["']\.\/vite\.config(\.[cm]?[jt]s)?["']/.test(vitest)) add("vite-plugin-missing", "warning", `${rel(vitestConfig)} replaces the Vite config for Vitest and does not use the ts-dom plugin, so the templates are not generated when the tests start and a clean checkout fails to resolve ./x.html.js. Fix: add tsDom() to its plugins, or merge the Vite config into it: mergeConfig(viteConfig, defineConfig({ test: { ... } })) with viteConfig imported from "./vite.config".`, { file: rel(vitestConfig) });
-	const oxlintrc = [".oxlintrc.json", "oxlintrc.json"].map((n) => join(cwd, n)).find((f) => existsSync(f));
+	const workspace = upToWorkspaceRoot(cwd);
+	const nearest = (names) => workspace.flatMap((d) => names.map((n) => join(d, n))).find((f) => existsSync(f));
+	const oxlintrc = nearest([
+		".oxlintrc.json",
+		".oxlintrc.jsonc",
+		"oxlintrc.json",
+		"oxlint.config.ts",
+		"oxlint.config.mts"
+	]);
 	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"));
@@ -624,8 +823,7 @@ function runDoctor(options) {
 		...pkg.dependencies,
 		...pkg.devDependencies
 	};
-	const scripts = Object.values(pkg.scripts ?? {});
-	if ((readText(join(cwd, ".gitignore")) ?? "").split("\n").some((l) => !l.trim().startsWith("!") && /\*\.html\.ts\s*$/.test(l)) && dirs.some(hasTemplates)) {
+	if (workspace.some((d) => (readText(join(d, ".gitignore")) ?? "").split("\n").some((l) => !l.trim().startsWith("!") && /\*\.html\.ts\s*$/.test(l))) && dirs.some(hasTemplates)) {
 		const all = pkg.scripts ?? {};
 		const checksTemplates = (step) => {
 			const project = TSC_PROJECT.exec(step)?.[1];
@@ -650,14 +848,21 @@ function runDoctor(options) {
 			});
 		}
 	}
-	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 prettierIgnore = nearest([".prettierignore"]);
+	const ignoredHtml = /(^|\n)\s*(\*\*\/)?\*\.html\s*($|\n)/.test(prettierIgnore ? readText(prettierIgnore) ?? "" : "");
+	const formatterIn = (d) => {
+		const file = join(d, "package.json");
+		const json = readPackageJson(file);
+		const ds = {
+			...json.dependencies,
+			...json.devDependencies
+		};
+		const runs = (tool) => Object.values(json.scripts ?? {}).some((c) => tool.test(c));
+		const oxfmt = OXFMT_CONFIGS.map((n) => join(d, n)).find((f) => existsSync(f)) ?? ("oxfmt" in ds || runs(/(^|[\s;&|])(oxfmt|vp fmt)(\s|$)/) ? file : void 0);
+		if (oxfmt || ignoredHtml) return oxfmt;
+		return PRETTIER_CONFIGS.map((n) => join(d, n)).find((f) => existsSync(f)) ?? ("prettier" in json || "prettier" in ds || runs(/(^|[\s;&|])prettier(\s|$)/) ? file : void 0);
+	};
+	const formatter = workspace.map(formatterIn).find((f) => f !== void 0) ?? (vite !== null && /\bfmt\s*:/.test(vite) ? viteConfig : void 0);
 	const collapseScript = Object.entries(pkg.scripts ?? {}).find(([, c]) => c.includes("--whitespace=collapse"))?.[0];
 	const collapseVite = vite !== null && /whitespace\s*:\s*["']collapse["']/.test(vite);
 	const generatedModes = dirs.flatMap(listHtml).flatMap((f) => {
@@ -674,9 +879,9 @@ function runDoctor(options) {
 		add("formatter-whitespace", "warning", `${asker} asks for whitespace "collapse", but ${preserved.length === 1 ? "this generated file was" : `${preserved.length} generated files (this one first) were`} written with "preserve" (by a gen or check run without the flag, for example), and a run without --whitespace keeps the mode a file was last written with, so the page gets the whitespace as written instead of collapsed. Fix: regenerate with the flag once: ${rerun}.`, { file: rel(preserved[0].file) });
 	}
 	const collapsed = collapseScript !== void 0 || collapseVite || generatedModes.some((g) => g.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\" })).");
+	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\" })).", { file: rel(formatter) });
 	for (const skill of listSkills(options.skillsDir ?? skillsRoot())) {
-		const copies = installedCopies(cwd, skill.name);
+		const copies = workspace.flatMap((d) => installedCopies(d, skill.name));
 		const shipped = readFileSync(join(skill.dir, "SKILL.md"), "utf8");
 		for (const copy of copies) if (readFileSync(join(copy, "SKILL.md"), "utf8") !== shipped) add("skill-outdated", "info", `${rel(copy)} differs from the ${skill.name} Skill shipped with the installed Nativele. Fix: run ts-dom skills add ${skill.name} to replace it with the shipped version.`, { file: rel(join(copy, "SKILL.md")) });
 		const found = skill.detects.filter((d) => d in deps);
@@ -887,7 +1092,7 @@ connected() { /* put the behavior in the class */ }`
 		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.",
+		why: "A custom element tag can be registered only once. define() skips a tag that is already registered, so with two classes for one tag the class whose define() runs first wins and the other is dropped without an error, and the tag map cannot say which class the tag stands for. ts-dom check also reports it when tsc finds two tag maps in one program that declare the tag with different classes (TS2717 in ts-dom-tags.ts), for example a folder scanned separately or a package that ships its own tag map.",
 		bad: `// a.ts
 define("user-card", CardA);
 // b.ts
@@ -1186,7 +1391,9 @@ Component(tpl, { props: { task: {} as Task } })`
 		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`
+		good: `npx ts-dom gen   # regenerates ts-dom-tags.ts
+// and keep ts-dom-tags.ts in the program: tsconfig.json
+{ "include": ["src"] }   // not ["src/**/*.tsx"], and no exclude that matches it`
 	},
 	"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.",
@@ -1215,7 +1422,7 @@ const n: number = 1;`
 // vite.config.ts with root: "web": tsDom({ dirs: ["src"] })`
 	},
 	"tsc-not-found": {
-		why: "ts-dom check runs the TypeScript compiler of the project. Without it installed, nothing can be type-checked.",
+		why: "ts-dom check runs the TypeScript compiler of the project. Without it installed, nothing can be type-checked, so this is an error: otherwise a CI job that omits the dev dependencies would pass without any type check.",
 		bad: `npx ts-dom check   # typescript is not installed`,
 		good: `npm i -D typescript
 npx ts-dom check`
@@ -1227,9 +1434,10 @@ npx ts-dom check`
 { "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.",
+		why: "The names in the templates are checked with or without strict, but without it tsc does not report values that may be null (a querySelector result, an optional ref) or parameters that are implicitly any (a handler parameter without a type). TypeScript 6 and later turn strict on when it is left out; TypeScript 5 leaves it off, so there it has to be set. When the project's TypeScript cannot be resolved, its version is unknown, and a missing strict is reported as on TypeScript 5.",
 		bad: `// tsconfig.json
-{ "compilerOptions": { "strict": false } }`,
+{ "compilerOptions": { "strict": false } }
+// or, with TypeScript 5, no "strict" at all`,
 		good: `// tsconfig.json
 { "compilerOptions": { "strict": true } }`
 	},
@@ -1241,9 +1449,11 @@ npx ts-dom check`
 { "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.",
+		why: "Every generated x.html.ts imports the runtime package (@nativele/ts-dom), and the classic resolution does not look in node_modules, so tsc reports TS2792 (Cannot find module) and no component gets its types. TypeScript 5 also resolves the classic way when moduleResolution is left out and module is ES2015 to ESNext (or target is ES2015 or later without module). TypeScript 6 deprecates classic (TS5107) and 7 removes it (TS5108); both stop before checking anything.",
 		bad: `// tsconfig.json
-{ "compilerOptions": { "moduleResolution": "classic" } }`,
+{ "compilerOptions": { "moduleResolution": "classic" } }
+// or, with TypeScript 5
+{ "compilerOptions": { "module": "ESNext" } }`,
 		good: `// tsconfig.json
 { "compilerOptions": { "moduleResolution": "bundler" } }`
 	},
@@ -1253,6 +1463,15 @@ npx ts-dom check`
 { "include": ["src/server"] }   // templates are in src/ui`,
 		good: `// tsconfig.json
 { "include": ["src"] }`
+	},
+	"tsconfig-misses-tag-map": {
+		why: "ts-dom-tags.ts registers the components in HTMLElementTagNameMap. Usually no file imports it, so it is in the program only when include matches it and exclude does not remove it; a file in the program that imports or re-exports it (a package entry with export type {} from \"./ts-dom-tags.js\") brings it in as well, and then nothing is reported. Left out, tags are typed as plain HTMLElement and lists of item components fail with item-not-in-tag-map. The x.html.ts files do not have this problem: their components import them. include, exclude and files are read through extends as tsc reads them: each from the nearest config that sets it.",
+		bad: `// tsconfig.json
+{ "include": ["src/**/*.tsx"] }
+{ "include": ["src"], "exclude": ["**/ts-dom-tags.ts"] }`,
+		good: `// tsconfig.json
+{ "include": ["src"] }
+{ "include": ["src/**/*.tsx", "src/ts-dom-tags.ts"] }`
 	},
 	"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.",
@@ -1295,7 +1514,7 @@ import viteConfig from "./vite.config";
 export default mergeConfig(viteConfig, defineConfig({ test: { environment: "happy-dom" } }));`
 	},
 	"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.",
+		why: "The oxlint plugin runs the template rules (unused markup, data flow, accessibility) in the editor. Without it they only run from the CLI. In a package of a workspace, the nearest lint config up to the workspace root is read.",
 		bad: `// .oxlintrc.json
 { "rules": {} }`,
 		good: `// .oxlintrc.json
@@ -1305,7 +1524,7 @@ export default mergeConfig(viteConfig, defineConfig({ test: { environment: "happ
 }`
 	},
 	"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. The same warning is given when the scripts or the Vite config ask for collapse but the generated files were written with preserve: a run without --whitespace keeps the mode a file was last written with, so one run without the flag leaves the project on preserve.",
+		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. The same warning is given when the scripts or the Vite config ask for collapse but the generated files were written with preserve: a run without --whitespace keeps the mode a file was last written with, so one run without the flag leaves the project on preserve. In a package of a workspace, the formatter's config files, the prettier key, dependencies and scripts in package.json, and .prettierignore are looked up to the workspace root, nearest first.",
 		bad: `# formatter is configured, templates keep their whitespace
 npx ts-dom gen
 # or: package.json has "gen": "ts-dom gen src --whitespace=collapse", but the files came from a plain run
@@ -1353,8 +1572,10 @@ Commands
         --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)
+        --project=<path>  tsconfig to check (default: tsconfig.json)
         --include=<glob>, --exclude=<glob>, --whitespace=collapse|preserve   as for gen (they decide which
                           generated files are stale)
+        --strict          exit with code 1 on warnings too (errors always do; info never does)
         --json            print the issues as JSON instead of text
   skills            List the Nativele Skills shipped with this version: task procedures for coding agents
                     (set-up, a complete example, known limitations, verification), with the versions verified
@@ -1389,7 +1610,7 @@ function ruleGroups() {
 		],
 		[
 			"lint: unused-markup",
-			"errors from `ts-dom lint` / oxlint rule ts-dom/unused-markup (or ts-dom/<id>)",
+			"errors from `ts-dom lint` / oxlint rule ts-dom/unused-markup (or ts-dom/<id>); no-importer only from `ts-dom lint`, as the oxlint plugin sees one file at a time and cannot tell that no file imports a template",
 			UNUSED_MARKUP_RULES
 		],
 		[
@@ -1549,13 +1770,15 @@ try {
 		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 project = args.find((a) => a.startsWith("--project="))?.slice(10);
 		const issues = runDoctor({
 			dirs,
-			generate
+			generate,
+			...project ? { project } : {}
 		});
 		if (flags.has("--json")) console.log(JSON.stringify({ issues }, null, 2));
 		else for (const i of issues) (i.severity === "error" ? console.error : i.severity === "warning" ? console.warn : console.log)(formatDoctorIssue(i));
-		if (issues.some((i) => i.severity === "error")) process.exitCode = 1;
+		if (issues.some((i) => i.severity === "error" || flags.has("--strict") && i.severity === "warning")) process.exitCode = 1;
 		if (!flags.has("--json") && !issues.some((i) => i.severity !== "info")) console.log("ts-dom doctor: the set-up looks right");
 	} else if (cmd === "lint") {
 		const files = dirs.flatMap(listTs);