ts-builds 4.1.0 → 4.2.0

package/README.md

@@ -254,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

@@ -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,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) {
@@ -111,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. */
@@ -435,8 +702,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 +715,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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-builds",
-  "version": "4.1.0",
+  "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.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",