@williamthorsen/tsconfig 0.2.1 → 0.4.0

package/.readyup/kits/default.js

@@ -0,0 +1,308 @@
+/** @noformat — @generated. Do not edit. Compiled by rdy. */
+/* eslint-disable */
+export const __readyupVersion = "0.25.0";
+
+
+// .readyup/kits/default.ts
+import { defineRdyKit } from "readyup";
+import {
+  discoverWorkspaces,
+  esYearForNodeMajor,
+  fileExists,
+  readEnginesNodeFloor,
+  readJsonFile,
+  readToolVersionsNode,
+  readTsconfigChain
+} from "readyup/check-utils";
+
+// src/readiness/base-chain.ts
+var BASE_PACKAGE = "@williamthorsen/tsconfig";
+var PATH_SPECIFIER = /^(?:\.{1,2}(?:[/\\]|$)|[/\\]|[A-Za-z]:)/;
+function findBaseIndex(entries) {
+  const index = entries.findIndex((entry) => entry.specifier !== void 0 && isBaseSpecifier(entry.specifier));
+  return index === -1 ? void 0 : index;
+}
+function hasExternalBase(entries) {
+  return entries.some((entry) => isExternalBase(entry));
+}
+function isBaseSpecifier(specifier) {
+  return specifier === BASE_PACKAGE || specifier.startsWith(`${BASE_PACKAGE}/`);
+}
+function isConsumerOwnedConfig(path) {
+  return !path.startsWith("../") && !path.split("/").includes("node_modules");
+}
+function isExternalBase(entry) {
+  const { specifier } = entry;
+  if (specifier === void 0) return false;
+  return !PATH_SPECIFIER.test(specifier) && !isBaseSpecifier(specifier);
+}
+
+// src/readiness/classifyChain.ts
+function classifyChain(chain) {
+  if (chain.unresolvedExtends.some((unresolved) => isBaseSpecifier(unresolved.specifier))) {
+    return { kind: "uninstalled" };
+  }
+  const baseIndex = findBaseIndex(chain.entries);
+  if (baseIndex !== void 0) return { baseIndex, kind: "adopted" };
+  return hasExternalBase(chain.entries) ? { kind: "external-base" } : { kind: "unadopted" };
+}
+
+// src/readiness/es-year.ts
+var ES_YEAR = /^es\d{4}$/;
+function isEsYearAtLeast(candidate, floor) {
+  return candidate >= floor;
+}
+function parseEsYear(value) {
+  const normalized = value.trim().toLowerCase();
+  return ES_YEAR.test(normalized) ? normalized : void 0;
+}
+function readDeclaredEsYear(compilerOptions) {
+  const target = compilerOptions["target"];
+  const targetYear = typeof target === "string" ? parseEsYear(target) : void 0;
+  if (targetYear !== void 0) return targetYear;
+  const libYears = toStringArray(compilerOptions["lib"]).flatMap((entry) => {
+    const year = parseEsYear(entry);
+    return year === void 0 ? [] : [year];
+  });
+  return libYears.toSorted().at(-1);
+}
+function toStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry) => typeof entry === "string");
+}
+
+// src/readiness/findRedundantOptions.ts
+import { isDeepStrictEqual } from "node:util";
+function findRedundantOptions(entries, baseIndex) {
+  const baseOptions = entries[baseIndex]?.compilerOptions;
+  if (baseOptions === void 0) return [];
+  const exempt = dependencyDeclaredKeys(entries, baseIndex);
+  const redundant = [];
+  for (const entry of entries.slice(0, baseIndex)) {
+    if (!isConsumerOwnedConfig(entry.path)) continue;
+    for (const [key, value] of Object.entries(entry.compilerOptions)) {
+      if (exempt.has(key) || !Object.hasOwn(baseOptions, key)) continue;
+      if (isDeepStrictEqual(value, baseOptions[key])) redundant.push({ key, path: entry.path });
+    }
+  }
+  return redundant;
+}
+function dependencyDeclaredKeys(entries, baseIndex) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const [index, entry] of entries.entries()) {
+    if (index === baseIndex || isConsumerOwnedConfig(entry.path)) continue;
+    for (const key of Object.keys(entry.compilerOptions)) keys.add(key);
+  }
+  return keys;
+}
+
+// src/readiness/node-floor.ts
+var NODE_MAJOR = /^v?(\d+)(?:[.\s]|$)/;
+var NODE_MAJOR_CEILING = 99;
+function classifyNodeEsYear(major, esYearForMajor) {
+  const esYear = esYearForMajor(major);
+  if (esYear !== void 0) return { esYear, kind: "exact" };
+  const lowestKnown = findLowestKnownMajor(esYearForMajor);
+  if (lowestKnown === void 0 || major > lowestKnown) return { kind: "unknown" };
+  const lowestEsYear = esYearForMajor(lowestKnown);
+  return lowestEsYear === void 0 ? { kind: "unknown" } : { esYear: lowestEsYear, kind: "under" };
+}
+function lowestNodeMajor(floors) {
+  const majors = floors.flatMap((floor) => {
+    const major = readNodeMajor(floor);
+    return major === void 0 ? [] : [major];
+  });
+  return majors.length === 0 ? void 0 : Math.min(...majors);
+}
+function readNodeMajor(floor) {
+  const major = NODE_MAJOR.exec(floor.trim())?.[1];
+  return major === void 0 ? void 0 : Number(major);
+}
+function findLowestKnownMajor(esYearForMajor) {
+  for (let candidate = 1; candidate <= NODE_MAJOR_CEILING; candidate += 1) {
+    if (esYearForMajor(candidate) !== void 0) return candidate;
+  }
+  return void 0;
+}
+
+// .readyup/kits/default.ts
+var PACKAGE_NAME = "@williamthorsen/tsconfig";
+var BASE_SPECIFIER = `${PACKAGE_NAME}/tsconfig.base.json`;
+var ADOPTION_URL = "https://github.com/williamthorsen/eslint-config/tree/main/packages/tsconfig#adopting-the-base";
+var NO_BASE_ES_YEAR = `no tsconfig reaches a ${PACKAGE_NAME} base declaring an ES year`;
+var NO_NODE_ES_YEAR = "no ES year is known for the declared Node floor";
+var cache = {
+  chains: /* @__PURE__ */ new Map()
+};
+var default_default = defineRdyKit({
+  description: `Adoption and alignment checks for a project consuming ${PACKAGE_NAME}`,
+  defaultSeverity: "warn",
+  checklists: [
+    {
+      name: "adoption",
+      checks: [
+        {
+          name: `Every workspace tsconfig extends ${PACKAGE_NAME}`,
+          skip: skipUnlessSomeTsconfigIsAccountable,
+          check: everyTsconfigAdoptsTheBase,
+          fix: `Extend ${BASE_SPECIFIER} from each tsconfig named above, and declare ${PACKAGE_NAME} as a devDependency of each package that names it but cannot resolve it. Adoption: ${ADOPTION_URL}`
+        },
+        {
+          name: "No tsconfig re-declares an option the base already supplies",
+          severity: "recommend",
+          check: noRedundantOptions,
+          fix: "Delete each option named above: the base already supplies it with the same value"
+        }
+      ]
+    },
+    {
+      name: "alignment",
+      checks: [
+        {
+          name: `No tsconfig declares an ES year other than the one ${PACKAGE_NAME} sets`,
+          skip: skipUnlessBaseEsYearKnown,
+          check: everyEsYearMatchesTheBase,
+          fix: "Delete the target or lib declaration named above, so the ES year the base sets applies"
+        },
+        {
+          name: "The declared Node floor supports the base's ES year",
+          severity: "error",
+          skip: skipUnlessNodeFloorComparable,
+          check: nodeFloorSupportsBaseEsYear,
+          fix: "Raise engines.node to a major implementing the base's ES year: below it, code that typechecks fails at runtime"
+        }
+      ]
+    }
+  ]
+});
+function adoptedTsconfigs() {
+  return classifyAdoptions().filter((adoption) => adoption.kind === "adopted");
+}
+function classifyAdoptions() {
+  cache.adoptions ??= findTsconfigs().map((path) => classifyTsconfig(path));
+  return cache.adoptions;
+}
+function classifyTsconfig(path) {
+  const chain = readChain(path);
+  if (chain === void 0) return { kind: "unadopted", path };
+  const classification = classifyChain(chain);
+  return classification.kind === "adopted" ? { baseIndex: classification.baseIndex, chain, kind: "adopted", path } : { kind: classification.kind, path };
+}
+function declaredNodeFloors() {
+  const engineFloors = tsconfigSearchDirs().flatMap((dir) => {
+    const manifest = readJsonFile(dirPath(dir, "package.json"));
+    if (manifest === void 0) return [];
+    const floor = readEnginesNodeFloor(manifest);
+    return floor.kind === "found" ? [floor.floor] : [];
+  });
+  if (engineFloors.length > 0) return engineFloors;
+  const toolVersionsFloor = readToolVersionsNode();
+  return toolVersionsFloor === void 0 ? [] : [toolVersionsFloor];
+}
+function dedupe(values) {
+  return [...new Set(values)];
+}
+function dirPath(dir, basename) {
+  return dir === "." ? basename : `${dir}/${basename}`;
+}
+function everyEsYearMatchesTheBase() {
+  const baseEsYear = readBaseEsYear();
+  if (baseEsYear === void 0) return true;
+  const offenders = [];
+  for (const adoption of adoptedTsconfigs()) {
+    for (const entry of adoption.chain.entries.slice(0, adoption.baseIndex)) {
+      if (!isConsumerOwnedConfig(entry.path)) continue;
+      const declared = readDeclaredEsYear(entry.compilerOptions);
+      if (declared !== void 0 && declared !== baseEsYear) offenders.push(`${entry.path} (${declared})`);
+    }
+  }
+  if (offenders.length === 0) return { ok: true, detail: `every tsconfig extending the base is at ${baseEsYear}` };
+  return {
+    ok: false,
+    detail: `the base sets ${baseEsYear}; declared otherwise in: ${dedupe(offenders).join(", ")}`
+  };
+}
+function everyTsconfigAdoptsTheBase() {
+  const accountable = classifyAdoptions().filter((adoption) => adoption.kind !== "external-base");
+  const adopted = accountable.filter((adoption) => adoption.kind === "adopted");
+  const progress = { type: "fraction", passedCount: adopted.length, count: accountable.length };
+  const uninstalled = pathsOfKind(accountable, "uninstalled");
+  const unadopted = pathsOfKind(accountable, "unadopted");
+  if (uninstalled.length === 0 && unadopted.length === 0) return { ok: true, progress };
+  const details = [
+    uninstalled.length > 0 ? `${PACKAGE_NAME} is named but not installed in: ${uninstalled.join(", ")}` : void 0,
+    unadopted.length > 0 ? `no extends chain reaches the base from: ${unadopted.join(", ")}` : void 0
+  ].filter((detail) => detail !== void 0);
+  return { ok: false, detail: details.join("; "), progress };
+}
+function findTsconfigs() {
+  return tsconfigSearchDirs().map((dir) => dirPath(dir, "tsconfig.json")).filter((path) => fileExists(path));
+}
+function judgeNodeFloor() {
+  const baseEsYear = readBaseEsYear();
+  if (baseEsYear === void 0) return { kind: "skip", reason: NO_BASE_ES_YEAR };
+  const nodeEsYear = readNodeEsYear();
+  if (nodeEsYear === void 0) return { kind: "skip", reason: "no declared Node floor names a major" };
+  if (nodeEsYear.kind === "unknown") return { kind: "skip", reason: NO_NODE_ES_YEAR };
+  if (nodeEsYear.kind === "under") {
+    return isEsYearAtLeast(baseEsYear, nodeEsYear.esYear) ? {
+      detail: `the declared Node floor implements less than ${nodeEsYear.esYear}, below the base's ${baseEsYear}`,
+      kind: "fail"
+    } : { kind: "skip", reason: NO_NODE_ES_YEAR };
+  }
+  return isEsYearAtLeast(nodeEsYear.esYear, baseEsYear) ? { detail: `the declared Node floor implements ${nodeEsYear.esYear}`, kind: "pass" } : {
+    detail: `the declared Node floor implements only ${nodeEsYear.esYear}, below the base's ${baseEsYear}`,
+    kind: "fail"
+  };
+}
+function nodeFloorSupportsBaseEsYear() {
+  const verdict = judgeNodeFloor();
+  return verdict.kind === "skip" ? true : { ok: verdict.kind === "pass", detail: verdict.detail };
+}
+function noRedundantOptions() {
+  const offenders = adoptedTsconfigs().flatMap(
+    (adoption) => findRedundantOptions(adoption.chain.entries, adoption.baseIndex).map(
+      (redundant) => `${redundant.path} (${redundant.key})`
+    )
+  );
+  if (offenders.length === 0) return true;
+  return { ok: false, detail: `the base already supplies: ${dedupe(offenders).join(", ")}` };
+}
+function pathsOfKind(classified, kind) {
+  return classified.filter((adoption) => adoption.kind === kind).map((adoption) => adoption.path);
+}
+function readBaseEsYear() {
+  for (const adoption of adoptedTsconfigs()) {
+    const baseOptions = adoption.chain.entries[adoption.baseIndex]?.compilerOptions;
+    const esYear = baseOptions === void 0 ? void 0 : readDeclaredEsYear(baseOptions);
+    if (esYear !== void 0) return esYear;
+  }
+  return void 0;
+}
+function readChain(path) {
+  if (!cache.chains.has(path)) cache.chains.set(path, readTsconfigChain(path));
+  return cache.chains.get(path);
+}
+function readNodeEsYear() {
+  const major = lowestNodeMajor(declaredNodeFloors());
+  return major === void 0 ? void 0 : classifyNodeEsYear(major, esYearForNodeMajor);
+}
+function skipUnlessBaseEsYearKnown() {
+  return readBaseEsYear() === void 0 ? NO_BASE_ES_YEAR : false;
+}
+function skipUnlessNodeFloorComparable() {
+  const verdict = judgeNodeFloor();
+  return verdict.kind === "skip" ? verdict.reason : false;
+}
+function skipUnlessSomeTsconfigIsAccountable() {
+  const classified = classifyAdoptions();
+  if (classified.length === 0) return "no workspace tsconfig was found";
+  return classified.some((adoption) => adoption.kind !== "external-base") ? false : "every workspace tsconfig extends a base belonging to another package";
+}
+function tsconfigSearchDirs() {
+  cache.searchDirs ??= [.../* @__PURE__ */ new Set([".", ...discoverWorkspaces().map((workspace) => workspace.dir)])];
+  return cache.searchDirs;
+}
+export {
+  default_default as default
+};

package/.readyup/manifest.json

@@ -0,0 +1,18 @@
+{
+  "version": 1,
+  "kits": [
+    {
+      "checklists": [
+        "adoption",
+        "alignment"
+      ],
+      "description": "Adoption and alignment checks for a project consuming @williamthorsen/tsconfig",
+      "name": "default",
+      "path": "kits/default.js",
+      "readyupVersion": "0.25.0",
+      "source": "kits/default.ts",
+      "sourceHash": "4d0a555c",
+      "targetHash": "4c59a48d"
+    }
+  ]
+}

package/README.md

@@ -2,7 +2,15 @@
 
 Shared TypeScript base config for Node-only projects. Inlines the settings of [`@tsconfig/strictest`](https://www.npmjs.com/package/@tsconfig/strictest) and adds the Node and build options it leaves out, so a consuming repo declares only what is genuinely its own.
 
-<!-- section:release-notes --><!-- /section:release-notes -->
+<!-- section:release-notes -->
+## Release notes — v0.4.0 (2026-08-09)
+
+### 🎉 Features
+
+- Add a bundled readyup kit that checks tsconfig adoption and alignment (#152)
+
+  Adds a readiness check to `@williamthorsen/tsconfig` that reports, package by package, whether a repo has adopted the base config and stayed aligned with it. A package that extends a framework's own base is reported as having opted out. The Node floor is the only finding that fails the check; the rest is advisory. The check is run with `pnpm exec rdy run --from npm:@williamthorsen/tsconfig`.
+<!-- /section:release-notes -->
 
 ## Installation
 
@@ -22,35 +30,82 @@ pnpm add -D @williamthorsen/tsconfig
 }
 ```
 
+## Adopting the base
+
+Extend the base from every tsconfig in the repo, not from the root alone. A workspace config reaches it either directly or through a config that does:
+
+```jsonc
+// packages/api/tsconfig.json
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/"],
+}
+```
+
+Every package whose tsconfig names the base by package specifier must also declare it as a devDependency: TypeScript resolves `extends` from the directory of the config that declares it, so a workspace naming a package it does not depend on resolves nothing.
+
+Once the base is in the chain, delete the options it already supplies with the same value. The inherited value applies either way, and the copy left behind stops tracking the base the next time it changes. An option set to a _different_ value is an override and stays.
+
+A package that extends a framework base such as `astro/tsconfigs/base` or `@tsconfig/svelte` has opted out of this one, which is a supported choice.
+
 ## What the base sets
 
 Everything `@tsconfig/strictest` sets, plus the Node and build options it omits:
 
-| Option                       | Value        |
-| ---------------------------- | ------------ |
-| `allowImportingTsExtensions` | `true`       |
-| `lib`                        | `["ES2025"]` |
-| `module`                     | `"NodeNext"` |
-| `moduleDetection`            | `"force"`    |
-| `noEmit`                     | `true`       |
-| `removeComments`             | `true`       |
-| `target`                     | `"ES2025"`   |
+| Option                       | Value                             |
+| ---------------------------- | --------------------------------- |
+| `allowImportingTsExtensions` | `true`                            |
+| `lib`                        | `["ES2025", "ESNext.Disposable"]` |
+| `module`                     | `"NodeNext"`                      |
+| `moduleDetection`            | `"force"`                         |
+| `noEmit`                     | `true`                            |
+| `removeComments`             | `true`                            |
+| `target`                     | `"ES2025"`                        |
 
-`target` and `lib` are pinned to a Node 24 floor.
+`target` and `lib` are pinned to a Node 24 floor. `ESNext.Disposable` supplies the explicit-resource-management declarations (`using`, `Disposable`, `DisposableStack`), which Node 24 implements and no numbered lib yet carries.
 
 ## What the consumer owns
 
 The base declares none of these:
 
-- **`types`** — the ambient type packages in scope. Most Node projects want `["node"]`; declaring it narrows the default, which would otherwise pull in every `@types/*` package installed.
-- **`paths`** — TypeScript resolves `baseUrl`-less `paths` relative to the file that _declares_ them, so a path alias set in this package would resolve inside `node_modules`. Aliases must be declared by the config that owns the source tree.
-- **`jsx`** — meaningless for the many consumers with no JSX at all.
+- **`types`**: The ambient type packages in scope. Most Node projects want `["node"]`; declaring it narrows the default, which would otherwise pull in every `@types/*` package installed.
+- **`paths`**: TypeScript resolves `baseUrl`-less `paths` relative to the file that _declares_ them, so a path alias set in this package would resolve inside `node_modules`. Aliases must be declared by the config that owns the source tree.
+- **`jsx`**: Meaningless for the many consumers with no JSX at all.
 
 `include` and `exclude` are likewise the consumer's, since only it knows its own layout.
 
 ## Emitting
 
-The base sets `noEmit: true`, on the assumption that a separate build step owns emit. A consumer that builds with this config directly must override `noEmit` — and, if it keeps `allowImportingTsExtensions`, pair that with `rewriteRelativeImportExtensions` so `./foo.ts` specifiers survive the rewrite.
+The base sets `noEmit: true`, on the assumption that a separate build step owns emit. A consumer that builds with this config directly must override `noEmit` and, if it keeps `allowImportingTsExtensions`, pair that with `rewriteRelativeImportExtensions` so `./foo.ts` specifiers survive the rewrite.
+
+## Checking your configuration
+
+This package ships a [ReadyUp](https://www.npmjs.com/package/readyup) kit that checks whether your tsconfigs are wired for the version you have installed. It is a migration aid rather than a CI gate: only a Node floor too old to run the base's ES year is reported as an error, and everything else caps at a warning.
+
+Run it once:
+
+```shell
+pnpm exec rdy run --from npm:@williamthorsen/tsconfig
+```
+
+Or list it in `.config/readyup.config.ts` to include it whenever you run `rdy run --packages`:
+
+```ts
+import { defineRdyConfig } from 'readyup';
+
+export default defineRdyConfig({
+  packages: ['@williamthorsen/tsconfig'],
+});
+```
+
+The kit walks each workspace tsconfig's `extends` chain and reports four things:
+
+- **Adoption**: a tsconfig reaching neither this base nor a framework base. A tsconfig naming this base through a specifier that does not resolve is reported separately, as declared but not installed.
+- **Re-declaration**: an option restated with the base's own value. A key that a framework base in the same chain also declares is exempt, since restating it is how a config wins against that base.
+- **ES year**: a `target` or `lib` declaring a year other than the base's, read from the base you extend rather than from a constant compiled into the kit.
+- **Node floor**: an `engines.node` below the major that implements that ES year. This is the one failure `tsc` cannot surface on its own, which is why it alone is an error.
+
+The kit runs at the version resolved from your `node_modules`, so it reports whether your configuration matches that version. It never reports whether that version is current.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/tsconfig",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Shared TypeScript base config for Node-only projects",
   "keywords": [
     "tsconfig",
@@ -23,10 +23,14 @@
     "./tsconfig.base.json": "./tsconfig.base.json"
   },
   "files": [
+    ".readyup/kits/*.js",
+    ".readyup/manifest.json",
     "tsconfig.base.json"
   ],
   "devDependencies": {
-    "@tsconfig/strictest": "2.0.8"
+    "@tsconfig/strictest": "2.0.8",
+    "esbuild": "0.28.1",
+    "readyup": "0.25.0"
   },
   "engines": {
     "node": ">=24"
@@ -37,8 +41,6 @@
   },
   "scripts": {
     "build": ":",
-    "check": "nmr lint:strict",
-    "test": ":",
-    "test:coverage": ":"
+    "check": "nmr lint:strict"
   }
 }

package/tsconfig.base.json

@@ -29,7 +29,8 @@
     // Permit `./foo.ts` specifiers; the build step rewrites them on emit.
     "allowImportingTsExtensions": true,
     // Without this, `lib` follows `target` into the `.full` variant, admitting DOM globals.
-    "lib": ["ES2025"],
+    // `ESNext.Disposable` carries the explicit-resource-management declarations; no numbered lib has them.
+    "lib": ["ES2025", "ESNext.Disposable"],
     // Default is `ES2022` with `Bundler` resolution — wrong for published Node packages.
     "module": "NodeNext",
     // Files with no import or export would otherwise be scripts sharing global scope.