@williamthorsen/tsconfig 0.3.0 → 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

@@ -3,13 +3,13 @@
 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 -->
-## Release notes — v0.3.0 (2026-08-07)
+## Release notes — v0.4.0 (2026-08-09)
 
 ### 🎉 Features
 
-- Support explicit resource management for consumers (#148)
+- Add a bundled readyup kit that checks tsconfig adoption and alignment (#152)
 
-  Adds `ESNext.Disposable` to the libraries recognized by TypeScript in the exported base config. This enables the use of `using` and `await using` declarations.
+  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
@@ -30,6 +30,24 @@ 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:
@@ -60,6 +78,35 @@ The base declares none of these:
 
 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
 
 ISC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/tsconfig",
-  "version": "0.3.0",
+  "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"
   }
 }