ts-builds 4.0.2 → 4.2.0

package/README.md

@@ -132,6 +132,25 @@ If your project uses ESLint plugins not bundled with ts-builds (e.g., `eslint-pl
 
 This tells ts-builds to use your project's ESLint installation instead of the bundled version.
 
+### Linting Tests
+
+`ts-builds lint` covers `srcDir`. Set `lint.includeTests` to cover `testDir` as well:
+
+```json
+{
+  "testDir": "./test",
+  "lint": {
+    "includeTests": true
+  }
+}
+```
+
+- It's off by default in 4.x, because turning it on can fail `validate` in a repo whose tests were never linted. 5.0 turns it on.
+- A `testDir` that doesn't exist is skipped. One with nothing ESLint can lint, such as only JSON fixtures, stops `lint` with exit code 2, the same as an empty `srcDir`.
+- `.ts-builds/lint-report.json` and `lint:summary` count both directories.
+- The fp and functype configs turn off the rules that misread a test's shape, for test files only: `@typescript-eslint/require-await` and `@typescript-eslint/no-unnecessary-condition`, plus `functype/prefer-option`, `prefer-either` and `prefer-try` in the functype config. The rule lists come from functype's `test-overrides` and `tests` configs. The base config enables none of these, so it has no override.
+- The fp and functype configs use type-aware rules, so every test file has to be in a tsconfig. Add `test/**/*` to `include`, or point `parserOptions.project` at a `tsconfig.eslint.json` that has it. On the bundled path, test files outside any tsconfig count as errors and print as one message naming this fix. With `lint.useProjectEslint`, your ESLint reports each one itself.
+
 ### For SPAs/React Apps (Vite)
 
 Use Vite instead of tsdown for SPA builds:
@@ -235,6 +254,99 @@ Wire-up:
 aggregate a different root. Finding zero sidecars exits nonzero — an empty sweep
 must not silently pass CI.
 
+The sidecar also has a `rules` field with per-rule counts: errors, warnings, findings
+silenced by an `eslint-disable` comment.
+
+### Lint telemetry (opt-in)
+
+`ts-builds lint` can send each run's per-rule counts to an endpoint you run. That shows which
+rules fire, which ones people silence, and how both change between releases. It's off unless you
+turn it on. ts-builds reads these settings from the environment only, so `ts-builds.config.json`
+has no switch for it. A committed script, workflow or config command that sets them still turns it
+on for everyone who runs it, so set them only where you mean to, such as your own CI.
+
+| Env var                       | Effect                                                                                                                     |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `TS_BUILDS_TELEMETRY=1`       | Turns it on.                                                                                                               |
+| `TS_BUILDS_TELEMETRY_URL`     | Where to POST. Must be `https`, or `http` to localhost. With telemetry on and no URL, `lint` warns once and sends nothing. |
+| `TS_BUILDS_TELEMETRY_DEBUG=1` | Prints the payload to stderr and sends nothing, whether or not telemetry is on.                                            |
+| `DO_NOT_TRACK=1`              | Turns it off, whatever else is set.                                                                                        |
+
+Each run sends one JSON object:
+
+```json
+{
+  "schema": 1,
+  "package": "@acme/api",
+  "project": "3f9c2a1b7d4e6f80",
+  "ci": true,
+  "agent": "claude-code",
+  "fix": false,
+  "durationMs": 1840,
+  "files": 212,
+  "fatal": 0,
+  "versions": {
+    "node": "24.20.0",
+    "ts-builds": "4.2.0",
+    "eslint": "10.14.0",
+    "typescript": "6.0.3",
+    "eslint-plugin-functype": "2.125.1"
+  },
+  "enabled": { "functype/no-let": "error", "functype/prefer-option": "warn" },
+  "rules": { "functype/prefer-option": { "errors": 0, "warnings": 3, "silenced": 2 } }
+}
+```
+
+- **Never sent:** file paths, source code or message text.
+- **Sent as-is:** the `package.json` name, left out when there isn't one, and rule ids as your config
+  names them. Plugin names and versions are sent only when they look like an npm package name and a
+  semver version.
+- **`project`:** a salted hash of the git remote, so one repo's packages group together. It's a
+  stable pseudonym, not anonymity: anyone who knows the remote URL can compute it. It's left out
+  when there's no remote.
+- **`agent`:** set when a coding agent runs the lint. Today that's Claude Code, from `CLAUDECODE=1`.
+- **`versions`:** Node, ts-builds, ESLint, TypeScript, and each configured plugin. A plugin's
+  installed version wins over the `meta.version` it declares, which is hand-written and can go stale.
+  When the installed package can't be found, the `meta.version` is used.
+- **`enabled`:** the plugin rules that are on, with their severity, read from the first linted file's
+  config. It tells a rule with no findings apart from a rule that's off. Core rules are left out.
+
+It never changes a run's result. It sends after lint finishes and its output is printed, waits at
+most 2 seconds, and ignores every error, so the exit code and output stay the same. A run that
+fails before linting, such as one with a broken config, sends nothing.
+
+It doesn't cover `lint.useProjectEslint`, which spawns your own ESLint so ts-builds never sees the
+results. It also doesn't cover scripts that call `eslint` directly instead of `ts-builds lint`.
+
+To turn it on in GitHub Actions, set both variables on the job:
+
+```yaml
+env:
+  TS_BUILDS_TELEMETRY: "1"
+  TS_BUILDS_TELEMETRY_URL: ${{ vars.TS_BUILDS_TELEMETRY_URL }}
+```
+
+Under Turbo's strict env mode, a task only sees the variables Turbo is told about, plus a built-in
+set that includes `CI`. List these so `ts-builds lint` sees them. Adding `globalPassThroughEnv` also
+turns on strict mode for every task, so check that your other tasks still get the variables they need:
+
+```jsonc
+// turbo.json
+{
+  "globalPassThroughEnv": [
+    "TS_BUILDS_TELEMETRY",
+    "TS_BUILDS_TELEMETRY_URL",
+    "TS_BUILDS_TELEMETRY_DEBUG",
+    "DO_NOT_TRACK",
+    "GITHUB_ACTIONS",
+    "CLAUDECODE",
+  ],
+}
+```
+
+Pass-through variables don't change Turbo's cache key. A cached lint task doesn't run, so it sends
+nothing.
+
 ## Extendable Configs
 
 ts-builds exports base configurations you can extend:

package/dist/cli.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { mkdir, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
-import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { $, Do, List, Map, Option, Set, Try } from "functype";
 import { Fs, Process } from "functype-os";
-import { spawn, spawnSync } from "node:child_process";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { createInterface } from "node:readline";
 import { gzipSync } from "node:zlib";
 
@@ -57,7 +58,10 @@ function loadConfig() {
 		srcDir: userConfig.srcDir ?? "./src",
 		testDir: userConfig.testDir ?? "./test",
 		buildMode: userConfig.buildMode ?? "tsdown",
-		lint: { useProjectEslint: userConfig.lint?.useProjectEslint ?? false },
+		lint: {
+			useProjectEslint: userConfig.lint?.useProjectEslint ?? false,
+			includeTests: userConfig.lint?.includeTests ?? false
+		},
 		size: userConfig.size ?? {},
 		changelog: userConfig.changelog ?? {},
 		commands,
@@ -65,6 +69,270 @@ function loadConfig() {
 	};
 }
 
+// src/cli/telemetry.ts
+/**
+* Opt-in lint telemetry: per-rule counts from a `ts-builds lint` run, sent to an endpoint you
+* choose so you can see which rules fire, which get silenced, and whether that changes over time.
+*
+* Off unless `TS_BUILDS_TELEMETRY=1` is set, and `DO_NOT_TRACK=1` always turns it off. ts-builds
+* reads these from the environment only. A committed script, workflow or config command that sets
+* them still turns it on for everyone who runs it. It never sends file paths, source or messages,
+* the send waits at most `TELEMETRY_TIMEOUT_MS`, and it never changes the run's exit code.
+*/
+/** Bump when the payload's shape changes incompatibly, so the receiver can tell versions apart. */
+const TELEMETRY_SCHEMA_VERSION = 1;
+/** The most a send can add to a lint run. A send that takes longer is dropped. */
+const TELEMETRY_TIMEOUT_MS = 2e3;
+/** A fixed salt, so the repo id is a stable pseudonym. Anyone who knows the remote URL can recompute it. */
+const PROJECT_SALT = "ts-builds-telemetry-v1";
+const LOG_PREFIX = "[ts-builds telemetry]";
+const NO_COUNTS = {
+	errors: 0,
+	warnings: 0,
+	silenced: 0
+};
+const isOn = (value) => value !== void 0 && /^(1|true|yes)$/i.test(value.trim());
+/** One hit per message that has a rule id. Messages without one are fatal, and counted apart. */
+function hits(result) {
+	const reported = result.messages.flatMap((m) => m.ruleId === null ? [] : [{
+		ruleId: m.ruleId,
+		field: m.severity === 2 ? "errors" : "warnings"
+	}]);
+	const suppressed = result.suppressedMessages.flatMap((m) => m.ruleId === null ? [] : [{
+		ruleId: m.ruleId,
+		field: "silenced"
+	}]);
+	return [...reported, ...suppressed];
+}
+/** Per-rule counts for a lint run. Pure: the same results always give the same, key-sorted output. */
+function ruleStats(results) {
+	const unsorted = results.flatMap(hits).reduce((acc, h) => {
+		const current = acc[h.ruleId] ?? NO_COUNTS;
+		return {
+			...acc,
+			[h.ruleId]: {
+				...current,
+				[h.field]: current[h.field] + 1
+			}
+		};
+	}, {});
+	return {
+		rules: Object.fromEntries(Object.keys(unsorted).toSorted().map((id) => [id, unsorted[id] ?? NO_COUNTS])),
+		fatal: results.reduce((n, r) => n + r.messages.filter((m) => m.ruleId === null).length, 0)
+	};
+}
+const LOCAL_HOSTS = [
+	"localhost",
+	"127.0.0.1",
+	"[::1]"
+];
+/** An https URL, or http only to this machine (for tests and a local receiver). */
+function isAllowedEndpoint(endpoint) {
+	return Try(() => new URL(endpoint)).map((url) => url.protocol === "https:" || url.protocol === "http:" && LOCAL_HOSTS.includes(url.hostname)).orElse(false);
+}
+/**
+* What to do with this run's telemetry, from the environment alone. `DO_NOT_TRACK` wins over
+* everything. `TS_BUILDS_TELEMETRY_DEBUG` prints the payload and sends nothing, so you can see
+* exactly what would go out before turning it on.
+*/
+function telemetryMode(env) {
+	if (isOn(env.DO_NOT_TRACK)) return { kind: "off" };
+	if (isOn(env.TS_BUILDS_TELEMETRY_DEBUG)) return { kind: "debug" };
+	if (!isOn(env.TS_BUILDS_TELEMETRY)) return { kind: "off" };
+	const endpoint = env.TS_BUILDS_TELEMETRY_URL?.trim() ?? "";
+	if (endpoint === "") return {
+		kind: "off",
+		warning: "TS_BUILDS_TELEMETRY is on but TS_BUILDS_TELEMETRY_URL isn't set, so nothing was sent."
+	};
+	if (!isAllowedEndpoint(endpoint)) return {
+		kind: "off",
+		warning: "TS_BUILDS_TELEMETRY_URL must be an https URL (http only to localhost), so nothing was sent."
+	};
+	return {
+		kind: "send",
+		endpoint
+	};
+}
+/**
+* A git remote reduced to `host/owner/repo`, lowercase: no protocol, credentials, port or `.git`.
+* `git@github.com:a/b.git`, `https://user:token@github.com/a/b` and `ssh://git@github.com/a/b`
+* all give `github.com/a/b`.
+*/
+function normalizeRemote(remote) {
+	const trimmed = remote.trim().replace(/\/+$/, "").replace(/\.git$/i, "");
+	const scp = /^[^@/\s]+@([^:/\s]+):(.+)$/.exec(trimmed);
+	if (scp) return `${scp[1]}/${scp[2]}`.replace(/^\/+/, "").toLowerCase();
+	return Try(() => new URL(trimmed)).map((url) => `${url.hostname}${url.pathname}`.replace(/\/+$/, "")).orElse(trimmed).toLowerCase();
+}
+/** The salted id for a remote. Stable across machines and clones, so one repo's packages group together. */
+function projectId(remote) {
+	return createHash("sha256").update(`${PROJECT_SALT}:${normalizeRemote(remote)}`).digest("hex").slice(0, 16);
+}
+/** The coding agent driving this run, when its env marker is set. */
+function detectAgent(env) {
+	return env.CLAUDECODE === "1" ? Option("claude-code") : Option.none();
+}
+function isCi(env) {
+	return isOn(env.CI) || env.GITHUB_ACTIONS === "true";
+}
+/**
+* The npm package that provides a rule's plugin, splitting the rule id the way ESLint does: at the
+* first slash, or the second for a scoped plugin. `functype/x` is `eslint-plugin-functype`,
+* `@typescript-eslint/x` is `@typescript-eslint/eslint-plugin`, `@scope/name/x` is
+* `@scope/eslint-plugin-name`, and `a/b/c` is `eslint-plugin-a`. Core rules have no plugin.
+*/
+function pluginPackage(ruleId) {
+	const parts = ruleId.split("/");
+	const first = parts.at(0) ?? "";
+	if (parts.length < 2 || first === "") return Option.none();
+	if (!first.startsWith("@")) return Option(`eslint-plugin-${first}`);
+	const name = parts.length > 2 ? parts.at(1) : void 0;
+	return Option(name === void 0 ? `${first}/eslint-plugin` : `${first}/eslint-plugin-${name}`);
+}
+/** An npm package name, so a plugin's `meta.name` can't carry a path or other free text. */
+const NPM_NAME = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+/** A semver version, so a plugin's `meta.version` can't carry free text. */
+const SEMVER = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/;
+const ancestors = (dir) => {
+	const parent = dirname(dir);
+	return parent === dir ? [dir] : [dir, ...ancestors(parent)];
+};
+const readJson = (path) => Try(() => JSON.parse(readFileSync(path, "utf-8"))).toOption();
+const versionIn = (path) => readJson(path).flatMap((pkg) => typeof pkg.version === "string" ? Option(pkg.version) : Option.none());
+/**
+* A package's installed version, found the way Node finds it: `node_modules/<name>` in `fromDir` or
+* any ancestor. Inside a `node_modules` folder it also checks `<name>` beside it, which is where pnpm
+* puts a package's dependencies (`.pnpm/ts-builds@x/node_modules/eslint-plugin-x`).
+*/
+function installedVersion(name, fromDir) {
+	const found = ancestors(fromDir).flatMap((dir) => [join(dir, "node_modules", name, "package.json"), ...basename(dir) === "node_modules" ? [join(dir, name, "package.json")] : []]).find((path) => existsSync(path));
+	return found === void 0 ? Option.none() : versionIn(found);
+}
+/** ts-builds' own root: the nearest ancestor of this module whose `package.json` is ts-builds. */
+function tsBuildsRoot() {
+	const here = dirname(fileURLToPath(import.meta.url));
+	const root = ancestors(here).find((dir) => readJson(join(dir, "package.json")).map((pkg) => pkg.name === "ts-builds").orElse(false));
+	return root === void 0 ? Option.none() : Option(root);
+}
+/** The git remote of the repo holding `dir`, if there is one. */
+function gitRemote(dir) {
+	return Try(() => execFileSync("git", [
+		"config",
+		"--get",
+		"remote.origin.url"
+	], {
+		cwd: dir,
+		encoding: "utf-8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"ignore"
+		],
+		timeout: 2e3
+	}).trim()).toOption().filter((out) => out !== "");
+}
+const severityOf = (entry) => {
+	const level = Array.isArray(entry) ? entry[0] : entry;
+	if (level === 2 || level === "error") return Option("error");
+	if (level === 1 || level === "warn") return Option("warn");
+	return Option.none();
+};
+const asRecord = (value) => typeof value === "object" && value !== null ? value : {};
+const asString = (value) => typeof value === "string" && value !== "" ? Option(value) : Option.none();
+/**
+* The plugins and the plugin rules that are on, from `eslint.calculateConfigForFile(...)`. Core
+* rules are left out, and so is ESLint's own `@` namespace.
+*/
+function activeConfig(calculated) {
+	const config = asRecord(calculated);
+	return {
+		plugins: Object.entries(asRecord(config.plugins)).filter(([namespace]) => namespace !== "@").flatMap(([namespace, plugin]) => {
+			const meta = asRecord(asRecord(plugin).meta);
+			return asString(meta.name).filter((name) => name.length <= 214 && NPM_NAME.test(name)).or(pluginPackage(`${namespace}/rule`)).map((name) => ({
+				name,
+				metaVersion: asString(meta.version).filter((v) => SEMVER.test(v))
+			})).toArray();
+		}),
+		enabled: Object.fromEntries(Object.entries(asRecord(config.rules)).filter(([id]) => id.includes("/")).flatMap(([id, entry]) => severityOf(entry).map((severity) => [id, severity]).toArray()).toSorted(([a], [b]) => a.localeCompare(b)))
+	};
+}
+/**
+* Versions worth comparing across runs: the toolchain, plus every configured plugin and every plugin
+* whose rules reported. A plugin's installed version wins over the one its `meta` claims, because a
+* hand-written `meta.version` can go stale.
+*/
+function versionsFor(run, rules, active) {
+	const root = tsBuildsRoot();
+	const lookup = (name) => installedVersion(name, run.dir).or(root.flatMap((dir) => installedVersion(name, dir)));
+	const configured = active.map((a) => a.plugins).orElse([]);
+	const claimed = (name) => Option(configured.find((p) => p.name === name)).flatMap((p) => p.metaVersion);
+	const plugins = [...configured.map((p) => p.name), ...Object.keys(rules).flatMap((id) => pluginPackage(id).toArray())].filter((name, i, all) => all.indexOf(name) === i).toSorted();
+	const typescript = lookup("typescript").map((v) => [["typescript", v]]).orElse([]);
+	const pluginVersions = plugins.flatMap((name) => lookup(name).or(claimed(name)).map((v) => [name, v]).toArray());
+	return {
+		node: process.versions.node,
+		"ts-builds": root.flatMap((dir) => versionIn(join(dir, "package.json"))).orElse("unknown"),
+		eslint: run.eslintVersion,
+		...Object.fromEntries([...typescript, ...pluginVersions])
+	};
+}
+/** The payload for one lint run. Holds counts and versions only: no file paths, source or messages. */
+function buildTelemetryPayload(run, env, active = Option.none()) {
+	const stats = ruleStats(run.results);
+	const project = gitRemote(run.dir).map(projectId);
+	const agent = detectAgent(env);
+	return {
+		schema: 1,
+		...run.packageName.map((name) => ({ package: name })).orElse({}),
+		...project.map((id) => ({ project: id })).orElse({}),
+		ci: isCi(env),
+		...agent.map((name) => ({ agent: name })).orElse({}),
+		fix: run.fix,
+		durationMs: Math.round(run.durationMs),
+		files: run.results.length,
+		fatal: stats.fatal,
+		versions: versionsFor(run, stats.rules, active),
+		...active.map((a) => ({ enabled: a.enabled })).orElse({}),
+		rules: stats.rules
+	};
+}
+/**
+* POST the payload. Resolves `true` on a 2xx and `false` otherwise; never rejects. The send is
+* awaited rather than left in flight, so the run's exit can't cut it off or be held open by it.
+*/
+async function sendTelemetry(payload, endpoint, timeoutMs = TELEMETRY_TIMEOUT_MS) {
+	return (await Try.async(async () => {
+		const res = await fetch(endpoint, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify(payload),
+			signal: AbortSignal.timeout(timeoutMs)
+		});
+		await res.body?.cancel();
+		return res.ok;
+	})).orElse(false);
+}
+/**
+* Report one lint run, as the environment asks. Never throws and never changes the run's result:
+* a failure anywhere in here is dropped.
+*/
+async function reportLintTelemetry(run, env = process.env, log = (line) => process.stderr.write(`${line}\n`)) {
+	await Try.async(async () => {
+		const mode = telemetryMode(env);
+		if (mode.kind === "off") {
+			if (mode.warning !== void 0) log(`${LOG_PREFIX} ${mode.warning}`);
+			return;
+		}
+		const payload = buildTelemetryPayload(run, env, (run.configFor === void 0 ? Option.none() : (await Try.async(run.configFor)).toOption()).map(activeConfig));
+		if (mode.kind === "debug") {
+			log(`${LOG_PREFIX} TS_BUILDS_TELEMETRY_DEBUG is set, so this was printed and not sent:`);
+			log(JSON.stringify(payload, null, 2));
+			return;
+		}
+		await sendTelemetry(payload, mode.endpoint);
+	});
+}
+
 // src/cli/lint-report.ts
 /**
 * Current sidecar schema version. Bump when the shape changes incompatibly so
@@ -75,14 +343,15 @@ const LINT_REPORT_VERSION = 1;
 function lintReportPath(dir = targetDir) {
 	return join(dir, ".ts-builds", "lint-report.json");
 }
-/** Package name from `<dir>/package.json`, falling back to the directory name. */
-function readPackageName(dir = targetDir) {
+/** The `name` in `<dir>/package.json`, when the file exists, parses and has a non-empty name. */
+function packageJsonName(dir = targetDir) {
 	const pkgPath = join(dir, "package.json");
-	if (existsSync(pkgPath)) try {
-		const { name } = JSON.parse(readFileSync(pkgPath, "utf-8"));
-		if (typeof name === "string" && name.length > 0) return name;
-	} catch {}
-	return basename(dir);
+	if (!existsSync(pkgPath)) return Option.none();
+	return Try(() => JSON.parse(readFileSync(pkgPath, "utf-8")).name).toOption().flatMap((name) => typeof name === "string" && name.length > 0 ? Option(name) : Option.none());
+}
+/** Package name from `<dir>/package.json`, falling back to the directory name. For local use only. */
+function readPackageName(dir = targetDir) {
+	return packageJsonName(dir).orElse(basename(dir));
 }
 /** Build a report from ESLint results. */
 function buildLintReport(results, fix, pkg) {
@@ -108,7 +377,8 @@ function buildLintReport(results, fix, pkg) {
 			filePath: r.filePath,
 			errorCount: r.errorCount,
 			warningCount: r.warningCount
-		}))
+		})),
+		rules: ruleStats(results).rules
 	};
 }
 /** Build a fatal report for a run that threw before producing results. */
@@ -379,8 +649,20 @@ function writeAll(stream, data) {
 		stream.write(data, (err) => err ? reject(err) : resolve());
 	});
 }
+/** What `lint` covers: `srcDir`, plus `testDir` when `lint.includeTests` is on and it exists. */
+function lintTargets(config, dir) {
+	return config.lint.includeTests && existsSync(resolve(dir, config.testDir)) ? [config.srcDir, config.testDir] : [config.srcDir];
+}
+const isInside = (file, directory) => {
+	const path = relative(directory, file);
+	return path !== "" && path !== ".." && !path.startsWith(`..${sep}`);
+};
+const notInTsconfig = (result) => result.messages.some((message) => message.fatal === true && message.message.includes("was not found by the project service"));
 /**
-* Lint `srcDir`.
+* Lint `srcDir`, and `testDir` with `lint.includeTests`.
+*
+* Test files no tsconfig includes each fail to parse under a type-aware config. They still
+* count as errors, but print as one message that names the fix, not one parse error per file.
 *
 * Bundled path (default, `useProjectEslint: false`): runs ESLint through its Node
 * API in a single pass, so we get the familiar stylish output AND exact issue
@@ -409,8 +691,8 @@ function writeAll(stream, data) {
 async function runLint(check = false) {
 	const config = loadConfig();
 	if (config.lint.useProjectEslint) {
-		const args = check ? [config.srcDir] : ["--fix", config.srcDir];
-		return runCommand("npx eslint", args);
+		const targets = lintTargets(config, targetDir);
+		return runCommand("npx eslint", check ? targets : ["--fix", ...targets]);
 	}
 	const fix = !check;
 	const pkg = readPackageName(targetDir);
@@ -420,14 +702,29 @@ async function runLint(check = false) {
 			fix,
 			cwd: targetDir
 		});
-		const results = await eslint.lintFiles([config.srcDir]);
+		const startedAt = performance.now();
+		const results = await eslint.lintFiles(lintTargets(config, targetDir));
 		if (fix) await ESLint.outputFixes(results);
+		const durationMs = performance.now() - startedAt;
 		const report = buildLintReport(results, fix, pkg);
 		await writeLintReport(report, targetDir);
 		try {
-			const output = await (await eslint.loadFormatter("stylish")).format(results);
+			const testDir = resolve(targetDir, config.testDir);
+			const unparsed = config.lint.includeTests ? results.filter((result) => isInside(result.filePath, testDir) && notInTsconfig(result)) : [];
+			const output = await (await eslint.loadFormatter("stylish")).format(results.filter((result) => !unparsed.includes(result)));
 			if (output) await writeAll(process.stdout, output);
+			if (unparsed.length > 0) await writeAll(process.stdout, `\n✗ ${unparsed.length} file(s) in ${config.testDir} aren't in a tsconfig, so type-aware rules can't read them.\n  Add "${relative(targetDir, testDir).split(sep).join("/")}/**/*" to "include" in tsconfig.json, or point parserOptions.project at a tsconfig.eslint.json that has it.\n`);
 		} catch {}
+		const firstFile = results.at(0)?.filePath;
+		await reportLintTelemetry({
+			results,
+			fix,
+			durationMs,
+			packageName: packageJsonName(targetDir),
+			eslintVersion: ESLint.version,
+			dir: targetDir,
+			configFor: () => firstFile === void 0 ? Promise.resolve(void 0) : eslint.calculateConfigForFile(firstFile)
+		});
 		return report.errorCount > 0 ? 1 : 0;
 	} catch (err) {
 		console.error(err.message);
@@ -983,6 +1280,81 @@ function findWorkspaceRoot(dir) {
 	const parent = dirname(dir);
 	return parent === dir ? Option.none() : findWorkspaceRoot(parent);
 }
+/** The `packages:` globs of a `pnpm-workspace.yaml`, quotes stripped. */
+function readWorkspacePackageGlobs(yaml) {
+	return readListBlock(yaml, /^packages:/);
+}
+const GLOB_TOKEN = /\*\*\/|\/\*\*$|\*\*|\*|\?|[^*?]/g;
+const GLOB_TOKEN_REGEX = {
+	"**/": "(?:.*/)?",
+	"/**": "(?:/.*)?",
+	"**": ".*",
+	"*": "[^/]*",
+	"?": "[^/]"
+};
+const normalizeGlobPath = (path) => path.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+function globRegExp(glob) {
+	const body = normalizeGlobPath(glob).replace(GLOB_TOKEN, (token) => GLOB_TOKEN_REGEX[token] ?? token.replace(/[.+^${}()|[\]\\]/g, "\\$&"));
+	return new RegExp(`^${body}$`);
+}
+/**
+* Pure matcher: whether pnpm's `packages:` globs list `relDir`, a directory path
+* relative to the workspace root. Covers the forms pnpm documents: `*` (within one
+* path segment), `**` (any depth, including none), `?`, and a leading `!` to exclude.
+* Listed means some include matches and no exclude does.
+*/
+function isListedPackage(relDir, globs) {
+	const path = normalizeGlobPath(relDir);
+	const matches = (glob) => globRegExp(glob).test(path);
+	const includes = globs.filter((glob) => !glob.startsWith("!"));
+	const excludes = globs.filter((glob) => glob.startsWith("!")).map((glob) => glob.slice(1));
+	return includes.some(matches) && !excludes.some(matches);
+}
+/** The workspace root strictly above `dir` whose `packages:` globs list it, if any. */
+function findListingRoot(dir) {
+	const parent = dirname(dir);
+	if (parent === dir) return Option.none();
+	return findWorkspaceRoot(parent).filter((root) => isListedPackage(relative(root, dir), readWorkspacePackageGlobs(readFileSync(join(root, "pnpm-workspace.yaml"), "utf-8"))));
+}
+/**
+* For a package with its own `pnpm-workspace.yaml` that a workspace root above
+* lists, that root. pnpm treats only a directory with a `package.json` as a
+* workspace package, and a nested file in an unlisted directory is a legitimate
+* separate workspace (pnpm 12 creates one there itself), so both are required.
+*/
+function strayWorkspaceRoot(dir) {
+	return isFile(join(dir, "pnpm-workspace.yaml")) && existsSync(join(dir, "package.json")) ? findListingRoot(dir) : Option.none();
+}
+/**
+* Directories below `dir` holding their own `pnpm-workspace.yaml`, without
+* descending into one once found. Skips hidden directories, `node_modules` and
+* symlinks, like the lint-report walk; an unreadable directory counts as empty.
+*/
+function nestedWorkspaceDirs(dir) {
+	return Try(() => readdirSync(dir, { withFileTypes: true })).orElse([]).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules").map((entry) => join(dir, entry.name)).flatMap((sub) => isFile(join(sub, "pnpm-workspace.yaml")) ? [sub] : nestedWorkspaceDirs(sub));
+}
+/**
+* Every stray file `doctor` should report from `dir`: `dir` itself when it is a
+* stray package, and, when `dir` is a workspace root, each package below it that
+* its globs list and that has its own `pnpm-workspace.yaml`. Returned as
+* `[root, packageDir]` pairs.
+*/
+function findStrayWorkspaceFiles(dir) {
+	const asPackage = strayWorkspaceRoot(dir).fold(() => [], (root) => [[root, dir]]);
+	const wsPath = join(dir, "pnpm-workspace.yaml");
+	const globs = isFile(wsPath) ? readWorkspacePackageGlobs(readFileSync(wsPath, "utf-8")) : [];
+	const asRoot = globs.length === 0 ? [] : nestedWorkspaceDirs(dir).filter((sub) => existsSync(join(sub, "package.json")) && isListedPackage(relative(dir, sub), globs)).map((sub) => [dir, sub]);
+	return [...asPackage, ...asRoot];
+}
+function detectStrayWorkspaceFiles(dir) {
+	return findStrayWorkspaceFiles(dir).map(([root, pkgDir]) => {
+		const rel = relative(root, pkgDir).split(sep).join("/");
+		return {
+			severity: "warning",
+			message: `${rel}/pnpm-workspace.yaml sits inside a package that the workspace root (${root}) lists. Its settings don't apply to the workspace, and pnpm run from ${rel} treats it as a separate workspace: it ignores the root's settings and packageManager pin and writes its own pnpm-lock.yaml. Move any settings it holds to the root's pnpm-workspace.yaml and delete it, or add "!${rel}" to the root's packages to keep it a separate workspace`
+		};
+	});
+}
 function snapshotFile(path) {
 	return {
 		path,
@@ -1091,7 +1463,8 @@ function detectPnpm11Issues(dir = targetDir, releaseAgeProbe = defaultReleaseAge
 		...hoistIssues,
 		...pnpmFieldIssues,
 		...detectAllowBuildsIssues(dir),
-		...detectReleaseAgeIssues(dir, releaseAgeProbe)
+		...detectReleaseAgeIssues(dir, releaseAgeProbe),
+		...detectStrayWorkspaceFiles(dir)
 	];
 	return List(results.length > 0 ? results : [{
 		severity: "info",
@@ -1173,8 +1546,12 @@ function renderExcludeEntry(entry) {
 * the next top-level key.
 */
 function readReleaseAgeExcludeEntries(yaml) {
-	const entryLine = /^\s*-\s*(["']?)([^"'\s#]+)\1\s*(?:#.*)?$/;
-	return Set(blockLines(yaml, /^minimumReleaseAgeExclude:/).map((line) => entryLine.exec(line)?.[2]).filter((entry) => entry !== void 0));
+	return Set(readListBlock(yaml, /^minimumReleaseAgeExclude:/));
+}
+const YAML_LIST_ENTRY = /^\s*-\s*(["']?)([^"'\s#]+)\1\s*(?:#.*)?$/;
+/** The unquoted items of the top-level list block whose header matches `header`. */
+function readListBlock(yaml, header) {
+	return blockLines(yaml, header).map((line) => YAML_LIST_ENTRY.exec(line)?.[2]).filter((entry) => entry !== void 0);
 }
 /**
 * Insert YAML list entries (already rendered as `  - x` lines) into an existing
@@ -1360,15 +1737,6 @@ function migrateReleaseAgeExcludes(dir, ws, probe) {
 		}],
 		sourceMutations: []
 	}));
-	const outerRoot = findWorkspaceRoot(dir).filter((root) => root !== dir);
-	if (outerRoot.isSome()) return outerRoot.fold(() => noChange(ws), (root) => ({
-		ws,
-		actions: [{
-			kind: "manual",
-			message: `${violations.length} package(s) are newer than the minimumReleaseAge cutoff, but this is a workspace package — run 'ts-builds doctor --fix' from the workspace root (${root}) to add them to its pnpm-workspace.yaml`
-		}],
-		sourceMutations: []
-	}));
 	const covered = readReleaseAgeExcludeEntries(ws).map(releaseAgeExcludeEntry);
 	const newEntries = List(violations.map(releaseAgeExcludeEntry)).filter((entry) => !covered.has(entry)).distinct().toArray();
 	if (newEntries.length === 0) return noChange(ws);
@@ -1400,6 +1768,37 @@ function migrateAllowBuilds(ws, lockfile) {
 		sourceMutations: []
 	};
 }
+/**
+* The refusal `--fix` reports from inside a workspace package. pnpm reads
+* pnpm-workspace.yaml settings only from the workspace root: writing them into the
+* package's own file would do nothing, and a stray pnpm-workspace.yaml can make pnpm
+* treat the package as its own workspace root. Moving the package's settings to the
+* root is not automated, because it could switch on settings that are inert today
+* (a package's `pnpm.overrides`, say).
+*/
+function workspacePackageAction(root) {
+	return {
+		kind: "manual",
+		message: `Nothing changed: this is a workspace package, and pnpm reads these settings only from the workspace root (${root}). Run 'ts-builds doctor --fix' there, and move any settings in this package's .npmrc or package.json "pnpm" field to the root's pnpm-workspace.yaml by hand`
+	};
+}
+/**
+* The refusal `--fix` reports from a stray package: one with its own
+* `pnpm-workspace.yaml` that a workspace root lists. pnpm run from here does read
+* that file, which is the problem, so writing more into it would entrench it.
+*/
+function strayPackageAction(root) {
+	return {
+		kind: "manual",
+		message: `Nothing changed: this package's own pnpm-workspace.yaml sits inside the workspace rooted at ${root} (see the warning above). Move its settings to the root's pnpm-workspace.yaml and delete it, then run 'ts-builds doctor --fix' from the root`
+	};
+}
+/** Why `--fix` must not write from `dir`, if it must not: a stray or ordinary workspace package. */
+function workspaceRefusal(dir) {
+	const stray = strayWorkspaceRoot(dir).map(strayPackageAction);
+	if (stray.isSome()) return stray;
+	return findWorkspaceRoot(dir).filter((root) => root !== dir).map(workspacePackageAction);
+}
 function migratePnpm11(dir = targetDir, releaseAgeProbe = defaultReleaseAgeProbe) {
 	const wsPath = join(dir, "pnpm-workspace.yaml");
 	const originalWs = existsSync(wsPath) && statSync(wsPath).isFile() ? readFileSync(wsPath, "utf-8") : "";
@@ -1417,6 +1816,11 @@ function migratePnpm11(dir = targetDir, releaseAgeProbe = defaultReleaseAgeProbe
 	];
 	const { ws } = allowBuilds;
 	const actions = steps.flatMap((step) => step.actions);
+	const refusal = ws !== originalWs || steps.some((step) => step.sourceMutations.length > 0) ? workspaceRefusal(dir) : Option.none();
+	if (refusal.isSome()) return {
+		actions: [refusal.orThrow()],
+		errors: 0
+	};
 	if (ws !== originalWs && !safeWrite(wsPath, ws)) return {
 		actions: [...actions, {
 			kind: "manual",
@@ -1702,9 +2106,9 @@ function createConfig(force = false) {
 	console.log(`
 Configuration options:
   srcDir         Source directory for linting (default: "./src")
-  testDir        Test directory (default: "./test")
+  testDir        Test directory (default: "./test"); linted with lint.includeTests
   buildMode      "tsdown" (default, libraries) or "vite" (SPAs/React apps)
-  lint           Lint settings: { "useProjectEslint": true }
+  lint           Lint settings: { "useProjectEslint": true, "includeTests": true }
   validateChain  Commands to run for validate (default shown above)
   commands       Custom commands: { "name": "shell command" }
   chains         Named chains: { "validate:fast": ["format", "lint"] }

package/eslint.config.fp.js

@@ -41,4 +41,6 @@ export default [
       ...functypeConfig.configs.recommended.rules,
     },
   },
+  // Last, so it wins over the rules above, and a consumer's own blocks after it win over it.
+  functypeConfig.configs.testOverrides,
 ]

package/eslint.config.functype.js

@@ -45,4 +45,7 @@ export default [
       ...functypePlugin.configs.recommended.rules,
     },
   },
+  // Last, so they win over the rules above, and a consumer's own blocks after them win over them.
+  functypeConfig.configs.testOverrides,
+  functypePlugin.configs.tests,
 ]

package/package-scripts.json

@@ -17,12 +17,12 @@
       "required": true
     },
     "lint": {
-      "command": "eslint ./src --fix",
+      "command": "ts-builds lint",
       "description": "Lint and auto-fix with ESLint",
       "required": true
     },
     "lint:check": {
-      "command": "eslint ./src",
+      "command": "ts-builds lint:check",
       "description": "Check ESLint without fixing",
       "required": true
     },
@@ -87,7 +87,7 @@
       "scripts": {
         "validate": "pnpm format && pnpm lint && pnpm test && pnpm build",
         "format": "prettier --write .",
-        "lint": "eslint ./src --fix",
+        "lint": "ts-builds lint",
         "test": "vitest run",
         "build": "ts-builds build"
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-builds",
-  "version": "4.0.2",
+  "version": "4.2.0",
   "description": "Shared TypeScript configuration files for library templates. Provides standardized ESLint, Prettier, Vitest, TypeScript, and build configs.",
   "keywords": [
     "typescript",
@@ -66,9 +66,9 @@
     "@vitest/coverage-v8": "^5.0.3",
     "@vitest/ui": "^5.0.3",
     "eslint": "^10.10.0",
-    "eslint-config-functype": "^2.111.0",
+    "eslint-config-functype": "^2.124.1",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-functype": "^2.111.0",
+    "eslint-plugin-functype": "^2.124.1",
     "eslint-plugin-prettier": "^5.5.6",
     "eslint-plugin-simple-import-sort": "^14.0.0",
     "functype": "^1.11.0",