ts-builds 4.1.0 → 4.3.0

package/README.md

@@ -221,6 +221,23 @@ npx ts-builds validate:core
 npx ts-builds validate:landing
 ```
 
+A `commands` entry named after a built-in step (`format`, `format:check`, `lint`, `lint:check`, `typecheck`,
+`ts-types`, `test`, `test:watch`, `test:coverage`, `test:ui`, `build`, `build:watch`, `dev`, `preview`) replaces
+that step everywhere: inside a chain, and when you run it directly (`ts-builds lint:check`, or
+`ts-builds lint check`). A chain with one of those names takes precedence over both, as it does inside a chain.
+`compile` can be overridden too, but only runs inside a chain. An override runs your command instead of
+ts-builds' lint, so it sends no lint telemetry, and an override of `lint` or `lint:check` removes any old
+`.ts-builds/lint-report.json`, so `lint:summary` can't read stale counts.
+
+```json
+{
+  "commands": {
+    "lint": "eslint ./src ./test --fix --max-warnings=0",
+    "lint:check": "eslint ./src ./test --max-warnings=0"
+  }
+}
+```
+
 ### Aggregating lint results across a monorepo
 
 Under a task runner, `ts-builds` runs per-package, so each package's ESLint output
@@ -254,6 +271,100 @@ 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. A plugin's declared name is used only when it looks like an npm package name, and
+  otherwise is replaced by the name derived from its rule prefix, such as `eslint-plugin-<prefix>`. Its
+  declared version is used only when it's semver.
+- **`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, the send
+waits at most 2 seconds, and it 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

@@ -5,7 +5,8 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "nod
 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";
 
@@ -68,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
@@ -78,14 +343,22 @@ 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) {
+/**
+* Remove the sidecar. When a `commands` override replaces `lint` or `lint:check`, ts-builds' own lint
+* doesn't run and writes no report, so an old one would leave `lint:summary` reading stale counts.
+*/
+function forgetLintReport(dir = targetDir) {
+	rmSync(lintReportPath(dir), { force: true });
+}
+/** 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) {
@@ -111,7 +384,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. */
@@ -159,9 +433,10 @@ function resolveEnv(env) {
 		...env
 	} : process.env;
 }
-function runCommand(command, args, options = {}) {
+/** Spawn one shell command line; resolves with its exit code, or 1 if it can't start */
+function spawnShell(commandLine, label, options) {
 	return new Promise((resolve) => {
-		const child = spawn(command, args, {
+		const child = spawn(commandLine, {
 			cwd: resolveCwd(options.cwd),
 			env: resolveEnv(options.env),
 			stdio: "inherit",
@@ -171,27 +446,24 @@ function runCommand(command, args, options = {}) {
 			resolve(code ?? 1);
 		});
 		child.on("error", (err) => {
-			console.error(`Failed to run ${command}: ${err.message}`);
+			console.error(`Failed to run${label}: ${err.message}`);
 			resolve(1);
 		});
 	});
 }
+/**
+* Run `command` with `args` through the shell, so `.bin` shims (including
+* Windows `.cmd` files) and commands such as `npx eslint` resolve. `args` are
+* joined into the command line as given, not escaped: quote any argument that
+* holds spaces or shell characters, as `prettierFormatArgs` does. Joining here
+* rather than passing `args` to `spawn` gives the same command line Node built
+* before, without its DEP0190 warning, which flags exactly that unescaped join.
+*/
+function runCommand(command, args, options = {}) {
+	return spawnShell([command, ...args].join(" "), ` ${command}`, options);
+}
 function runShellCommand(shellCmd, options = {}) {
-	return new Promise((resolve) => {
-		const child = spawn(shellCmd, {
-			cwd: resolveCwd(options.cwd),
-			env: resolveEnv(options.env),
-			stdio: "inherit",
-			shell: true
-		});
-		child.on("close", (code) => {
-			resolve(code ?? 1);
-		});
-		child.on("error", (err) => {
-			console.error(`Failed to run: ${err.message}`);
-			resolve(1);
-		});
-	});
+	return spawnShell(shellCmd, "", options);
 }
 
 // src/cli/commands/build.ts
@@ -339,7 +611,7 @@ function prettierConfigArg() {
 * no prettier config of their own (see `prettierConfigArg`), so we fill the gap without ever
 * overriding a config they wrote.
 *
-* Bundled paths are quoted because `runCommand` spawns with `shell: true` (the shell strips the
+* Bundled paths are quoted because `runCommand` runs one shell command line (the shell strips the
 * quotes), keeping them correct when the install path contains spaces.
 */
 function prettierFormatArgs(check, bundledIgnore = bundledPrettierIgnorePath(), bundledConfig = prettierConfigArg()) {
@@ -435,8 +707,10 @@ async function runLint(check = false) {
 			fix,
 			cwd: targetDir
 		});
+		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 {
@@ -446,6 +720,16 @@ async function runLint(check = false) {
 			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);
@@ -2126,6 +2410,53 @@ function runSize(args) {
 function isRunFnCommand(cmd) {
 	return "runFn" in cmd;
 }
+/** The built-in chain steps. A `commands` entry with one of these names replaces it, in a chain or run directly. */
+const BUILTIN_STEP_NAMES = [
+	"format",
+	"format:check",
+	"lint",
+	"lint:check",
+	"typecheck",
+	"ts-types",
+	"test",
+	"test:watch",
+	"test:coverage",
+	"test:ui",
+	"build",
+	"build:watch",
+	"dev",
+	"preview",
+	"compile"
+];
+const isBuiltinStepName = (name) => BUILTIN_STEP_NAMES.includes(name);
+/** The step a top-level command runs: `lint check` is `lint:check`, `test watch` is `test:watch`, `test run` is `test` */
+function stepName(command, subCommand) {
+	if ((command === "lint" || command === "format") && subCommand === "check") return `${command}:check`;
+	if (command === "build" && subCommand === "watch") return "build:watch";
+	if (command === "test" && (subCommand === "watch" || subCommand === "coverage" || subCommand === "ui")) return `test:${subCommand}`;
+	return command;
+}
+/**
+* The user's replacement for a built-in step, if their config has one. Run directly, a built-in
+* resolves the same way it does inside a chain (`runStep`): `config.commands[step] ?? builtin`.
+*/
+function builtinOverride(step, config) {
+	return Option(config.commands[step]).filter(() => isBuiltinStepName(step));
+}
+/** An override of `lint` or `lint:check` replaces ts-builds' lint, so its old report must go */
+function forgetLintReportIfLint(step) {
+	if (step === "lint" || step === "lint:check") forgetLintReport();
+}
+/** Run a `commands` entry on its own: check its cwd, then run it through the shell */
+async function runConfiguredCommand(name, cmdDef) {
+	const cwdError = escapingValidateCwdError(name, cmdDef);
+	if (cwdError) {
+		console.error(cwdError);
+		return 1;
+	}
+	forgetLintReportIfLint(name);
+	return runShellCommand(cmdDef.run, { cwd: cmdDef.cwd });
+}
 function getBuiltinCommands(config) {
 	return {
 		format: { runFn: () => runFormat(false) },
@@ -2176,6 +2507,7 @@ async function runStep(step, config, builtins, path) {
 		console.error(cwdError);
 		return 1;
 	}
+	if (Object.hasOwn(config.commands, step)) forgetLintReportIfLint(step);
 	const cwdLabel = "cwd" in cmdDef && cmdDef.cwd ? ` (in ${cmdDef.cwd})` : "";
 	console.log(`\n▶ Running ${step}...${cwdLabel}`);
 	const code = isRunFnCommand(cmdDef) ? await cmdDef.runFn() : await runShellCommand(cmdDef.run, { cwd: cmdDef.cwd });
@@ -2193,6 +2525,12 @@ async function runValidate(chainName = "validate") {
 // src/cli.ts
 const command = process.argv[2] || "init";
 const subCommand = process.argv[3];
+const step = stepName(command, subCommand);
+if (isBuiltinStepName(step)) {
+	const config = loadConfig();
+	if (Object.hasOwn(config.chains, step)) process.exit(await runValidate(step));
+	await builtinOverride(step, config).fold(() => Promise.resolve(), async (cmd) => process.exit(await runConfiguredCommand(step, cmd)));
+}
 switch (command) {
 	case "help":
 	case "--help":
@@ -2271,16 +2609,8 @@ switch (command) {
 	default: {
 		const config = loadConfig();
 		if (config.chains[command]) process.exit(await runValidate(command));
-		else if (config.commands[command]) {
-			const cmdDef = config.commands[command];
-			const cwdError = escapingValidateCwdError(command, cmdDef);
-			if (cwdError) {
-				console.error(cwdError);
-				process.exit(1);
-			}
-			const code = await runShellCommand(cmdDef.run, { cwd: cmdDef.cwd });
-			process.exit(code);
-		} else {
+		else if (config.commands[command]) process.exit(await runConfiguredCommand(command, config.commands[command]));
+		else {
 			console.error(`Unknown command: ${command}`);
 			console.log("Run 'ts-builds help' for usage information.");
 			process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-builds",
-  "version": "4.1.0",
+  "version": "4.3.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.124.0",
+    "eslint-config-functype": "^2.124.1",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-functype": "^2.124.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",