ci(typecheck): every package type-checks or is ledgered — the tsup hole becomes a ratchet (#4311)

claude · claude · commit 7dbb3314677b · 2026-07-31T06:03:19.000Z
66 of 77 workspace packages build with tsup (esbuild transpile, no type check), vitest never type-checks, and the CI typecheck job covered four targets — so for most packages nothing read src/ or the tests with tsc at all. #4311 measured the hole: 380 code-tier errors across 18 packages, 241 of them driver-sql tests feeding authored-shape literals into the freshly narrowed QueryAST. Re-measured per-package `tsc --noEmit` on main @ e5a4d26; aggregates match the issue exactly (48 clean / 29 failing / 1 no-tsconfig): - The 48 clean packages (42 new scripts + 6 pre-existing) now declare `typecheck`, run by a new `turbo run typecheck` task (dependsOn ^build) wired into lint.yml's typecheck job after the workspace build. The clean set is locked against regression from today. - The 29 failing ones (858 raw errors) are frozen in a DEBT ledger in scripts/check-type-check-coverage.mjs, each entry carrying its measured count and the issue's code/config/noise triage so a config-tier pile (types: 107, core: 91-with-3-real) is never mistaken for real breakage or the reverse (driver-sql: 241, all real). @objectstack/console is EXEMPT: no TypeScript sources. - The coverage gate (self-tested, reconciled in both directions) fails when a package is neither covered nor ledgered, when a ledger entry goes stale, or when the turbo task / root aggregator / CI step is deleted — the ledger can only shrink. Root `pnpm typecheck` aggregates the task locally; AGENTS.md documents the ratchet. Empty changeset: dev scripts and CI only, releases nothing. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011m13wbaZziPveBdtQthrXd
diff --git a/.changeset/per-package-typecheck-coverage.md b/.changeset/per-package-typecheck-coverage.md
@@ -0,0 +1,4 @@
+---
+---
+
+ci(dx): every workspace package now either declares a `typecheck` script (`tsc --noEmit`, run by the new `turbo run typecheck` task in the lint workflow) or carries a measured DEBT/EXEMPT entry in `scripts/check-type-check-coverage.mjs`, whose coverage ratchet runs in CI (#4311). 66 of 77 packages build with tsup, which transpiles without type-checking, and `vitest run` does not type-check either — 48 packages were already clean and are locked in; the 29 failing ones are frozen in the ledger with their raw error counts and the issue's code/config/noise triage. Dev scripts and CI only; releases nothing.
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -236,6 +236,18 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      # Coverage meta-gate (#4311): 66 of 77 workspace packages build with tsup
+      # (esbuild transpile, no type check) and `vitest run` does not type-check
+      # either, so a package without a `typecheck` script has NO tsc reading its
+      # src/ or its tests at all — 380 real errors had accumulated that way,
+      # invisible to every green build. This gate makes the hole itself the
+      # failure: every package either declares `typecheck` (run by the turbo
+      # step below) or carries a measured DEBT/EXEMPT entry in the script's
+      # ledger, reconciled in both directions so the ledger can only shrink.
+      # Reads package.json files only; no build, sub-second.
+      - name: Check every package is type-check covered or ledgered
+        run: pnpm check:type-check-coverage
+
       - name: Type check (@objectstack/spec)
         run: pnpm --filter @objectstack/spec exec tsc --noEmit
 
@@ -351,6 +363,19 @@ jobs:
       - name: Build workspace packages
         run: pnpm exec turbo run build --filter='./packages/*' --filter='./examples/*^...'
 
+      # The per-package `typecheck` scripts the coverage gate above requires
+      # (#4311). tsc resolves workspace imports through each dependency's built
+      # dist/*.d.ts, so the task carries `dependsOn: ^build` in turbo.json —
+      # which also builds the handful of nested packages (packages/plugins/*,
+      # packages/services/*, …) the build step's direct-children glob misses
+      # when no example depends on them. Three filters because the bare
+      # `./packages/*` glob only matches direct children (see the build step's
+      # comment): the nested group dirs and apps/ (docs) need their own globs.
+      # Examples and the downstream contract keep their dedicated steps below —
+      # they are distinct gates, not bulk coverage.
+      - name: Type check workspace packages
+        run: pnpm exec turbo run typecheck --filter='./packages/*' --filter='./packages/*/*' --filter='./apps/*'
+
       - name: Type check example apps
         run: pnpm --filter './examples/*' run typecheck
 
diff --git a/AGENTS.md b/AGENTS.md
@@ -20,9 +20,15 @@ pnpm install          # deps
 pnpm setup            # first-time: install + build spec
 pnpm build            # turbo build (excludes docs)
 pnpm test             # turbo test
+pnpm typecheck        # turbo typecheck — per-package `tsc --noEmit`; tsup/vitest never type-check (#4311)
 pnpm docs:dev         # docs site
 ```
 
+Type-check coverage is ratcheted (`pnpm check:type-check-coverage`, CI-gated): every
+workspace package declares a `typecheck` script or carries a measured DEBT/EXEMPT entry
+in `scripts/check-type-check-coverage.mjs`. New packages must arrive covered; a package
+that graduates deletes its ledger entry in the same PR.
+
 ### Running the dev server
 
 | Scenario | Command | Notes |
@@ -408,7 +414,7 @@ composition with its real services, or do not claim an answer.
 
 ## Post-Task Checklist
 
-1. `pnpm test` — verify nothing broke.
+1. `pnpm test` — verify nothing broke. Touched a type-check-covered package? `pnpm typecheck` too.
 2. **Land it — don't leave passing work in the working tree.** Once tests pass,
    create a feature branch, commit, push, open a PR, and merge it after remote
    CI is fully green (see Multi-agent discipline: never straight to `main`,
diff --git a/apps/docs/package.json b/apps/docs/package.json
@@ -10,7 +10,8 @@
     "site:start": "next start",
     "site:lint": "next lint",
     "types:check": "fumadocs-mdx && next typegen && tsc --noEmit",
-    "postinstall": "fumadocs-mdx"
+    "postinstall": "fumadocs-mdx",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "fumadocs-core": "16.12.1",
diff --git a/package.json b/package.json
@@ -12,6 +12,7 @@
     "spec:rebuild": "turbo run build --filter=...@objectstack/spec",
     "test": "turbo run test",
     "test:e2e": "turbo run test:e2e",
+    "typecheck": "turbo run typecheck",
     "clean": "turbo run clean && rm -rf dist",
     "setup": "pnpm install && pnpm --filter @objectstack/spec build",
     "version": "changeset version && node scripts/sync-protocol-version.mjs && node scripts/sync-template-versions.mjs",
@@ -41,7 +42,8 @@
     "check:console-sha": "node scripts/check-console-sha.mjs",
     "check:release-notes": "node scripts/check-release-notes.mjs",
     "check:node-version": "node scripts/check-node-version.mjs",
-    "check:published-files": "node scripts/check-published-files.mjs --self-test && node scripts/check-published-files.mjs"
+    "check:published-files": "node scripts/check-published-files.mjs --self-test && node scripts/check-published-files.mjs",
+    "check:type-check-coverage": "node scripts/check-type-check-coverage.mjs --self-test && node scripts/check-type-check-coverage.mjs"
   },
   "keywords": [
     "objectstack",
diff --git a/packages/apps/account/package.json b/packages/apps/account/package.json
@@ -13,7 +13,8 @@
     }
   },
   "scripts": {
-    "build": "tsup"
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@objectstack/platform-objects": "workspace:*",
diff --git a/packages/apps/setup/package.json b/packages/apps/setup/package.json
@@ -13,7 +13,8 @@
     }
   },
   "scripts": {
-    "build": "tsup"
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@objectstack/platform-objects": "workspace:*",
diff --git a/packages/apps/studio/package.json b/packages/apps/studio/package.json
@@ -13,7 +13,8 @@
     }
   },
   "scripts": {
-    "build": "tsup"
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@objectstack/platform-objects": "workspace:*",
diff --git a/packages/cli/package.json b/packages/cli/package.json
@@ -11,7 +11,8 @@
   "scripts": {
     "build": "if [ -n \"$OS_SKIP_DTS\" ]; then tsc -p tsconfig.build.json --noCheck --declaration false --declarationMap false; else tsc -p tsconfig.build.json; fi",
     "dev": "tsc -p tsconfig.build.json --watch",
-    "test": "vitest run"
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   },
   "keywords": [
     "objectstack",
diff --git a/packages/client-react/package.json b/packages/client-react/package.json
@@ -13,7 +13,8 @@
     }
   },
   "scripts": {
-    "build": "tsup src/index.tsx --config ../../tsup.config.ts"
+    "build": "tsup src/index.tsx --config ../../tsup.config.ts",
+    "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
     "react": ">=18.0.0"
diff --git a/packages/client/package.json b/packages/client/package.json
@@ -15,7 +15,8 @@
   "scripts": {
     "build": "tsup --config ../../tsup.config.ts",
     "test": "vitest run",
-    "test:integration": "vitest run --config vitest.integration.config.ts"
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@objectstack/core": "workspace:*",
diff --git a/packages/connectors/connector-mcp/package.json b/packages/connectors/connector-mcp/package.json
@@ -14,7 +14,8 @@
   },
   "scripts": {
     "build": "tsup --config ../../../tsup.config.ts",
-    "test": "vitest run --passWithNoTests"
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
diff --git a/packages/connectors/connector-openapi/package.json b/packages/connectors/connector-openapi/package.json
@@ -14,7 +14,8 @@
     },
     "scripts": {
         "build": "tsup --config ../../../tsup.config.ts",
-        "test": "vitest run --passWithNoTests"
+        "test": "vitest run --passWithNoTests",
+        "typecheck": "tsc --noEmit"
     },
     "dependencies": {
         "@objectstack/core": "workspace:*",
diff --git a/packages/connectors/connector-rest/package.json b/packages/connectors/connector-rest/package.json
@@ -14,7 +14,8 @@
   },
   "scripts": {
     "build": "tsup --config ../../../tsup.config.ts",
-    "test": "vitest run --passWithNoTests"
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@objectstack/core": "workspace:*",
diff --git a/packages/connectors/connector-slack/package.json b/packages/connectors/connector-slack/package.json
@@ -14,7 +14,8 @@
   },
   "scripts": {
     "build": "tsup --config ../../../tsup.config.ts",
-    "test": "vitest run --passWithNoTests"
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@objectstack/core": "workspace:*",
diff --git a/packages/formula/package.json b/packages/formula/package.json
@@ -14,7 +14,8 @@
   },
   "scripts": {
     "build": "tsup --config ../../tsup.config.ts",
-    "test": "vitest run"
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@marcbachmann/cel-js": "^8.0.0",
diff --git a/packages/lint/package.json b/packages/lint/package.json
@@ -16,7 +16,8 @@
   "scripts": {
     "build": "tsup --config ../../tsup.config.ts",
     "dev": "tsc -w",
-    "test": "vitest run"
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@objectstack/formula": "workspace:*",
diff --git a/packages/mcp/package.json b/packages/mcp/package.json
@@ -15,7 +15,8 @@
   },
   "scripts": {
     "build": "tsup --config ../../tsup.config.ts",
-    "test": "vitest run"
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
diff --git a/packages/metadata-core/package.json b/packages/metadata-core/package.json
@@ -28,7 +28,8 @@
     "dev": "tsc --watch",
     "clean": "rm -rf dist",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
   },
   "keywords": [
     "objectstack",
diff --git a/packages/metadata-fs/package.json b/packages/metadata-fs/package.json
@@ -23,7 +23,8 @@
     "dev": "tsc --watch",
     "clean": "rm -rf dist",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
   },
   "keywords": [
     "objectstack",
diff --git a/packages/objectql/package.json b/packages/objectql/package.json
@@ -19,7 +19,8 @@
   },
   "scripts": {
     "build": "tsup",
-    "test": "vitest run"
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@objectstack/core": "workspace:*",
diff --git a/packages/platform-objects/package.json b/packages/platform-objects/package.json
@@ -64,7 +64,8 @@
   },
   "scripts": {
     "build": "tsup",
-    "test": "vitest run --passWithNoTests"
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@objectstack/metadata-core": "workspace:*",
diff --git a/packages/plugins/driver-mongodb/package.json b/packages/plugins/driver-mongodb/package.json
@@ -15,7 +15,8 @@
   "scripts": {
     "build": "tsup --config ../../../tsup.config.ts",
     "dev": "tsc -w",
-    "test": "vitest run"
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@objectstack/core": "workspace:*",
diff --git a/packages/plugins/embedder-openai/package.json b/packages/plugins/embedder-openai/package.json
@@ -15,7 +15,8 @@
   "scripts": {
     "build": "tsup --config ../../../tsup.config.ts",
     "dev": "tsc -w",
-    "test": "vitest run"
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@objectstack/spec": "workspace:*"
diff --git a/packages/plugins/knowledge-memory/package.json b/packages/plugins/knowledge-memory/package.json
@@ -15,7 +15,8 @@
   "scripts": {
     "build": "tsup --config ../../../tsup.config.ts",
     "dev": "tsc -w",
-    "test": "vitest run"
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@objectstack/core": "workspace:*",
diff --git a/packages/plugins/plugin-audit/package.json b/packages/plugins/plugin-audit/package.json
@@ -14,7 +14,8 @@
   },
   "scripts": {
     "build": "tsup --config ../../../tsup.config.ts",
-    "test": "vitest run --passWithNoTests"
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@objectstack/core": "workspace:*",
diff --git a/packages/plugins/plugin-auth/package.json b/packages/plugins/plugin-auth/package.json
@@ -15,7 +15,8 @@
   },
   "scripts": {
     "build": "tsup --config ../../../tsup.config.ts",
-    "test": "vitest run"
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@better-auth/core": "1.7.0-rc.2",
diff --git a/packages/plugins/plugin-dev/package.json b/packages/plugins/plugin-dev/package.json
@@ -14,7 +14,8 @@
   },
   "scripts": {
     "build": "tsup --config ../../../tsup.config.ts",
-    "test": "vitest run"
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@objectstack/account": "workspace:^",
diff --git a/packages/plugins/plugin-email/package.json b/packages/plugins/plugin-email/package.json
@@ -14,7 +14,8 @@
   },
   "scripts": {
     "build": "tsup --config ../../../tsup.config.ts",
-    "test": "vitest run --passWithNoTests"
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@objectstack/core": "workspace:*",
diff --git a/packages/plugins/plugin-hono-server/package.json b/packages/plugins/plugin-hono-server/package.json
@@ -7,7 +7,8 @@
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsup --config ../../../tsup.config.ts",
-    "test": "vitest run"
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@hono/node-server": "^2.0.12",
diff --git a/packages/plugins/plugin-pinyin-search/package.json b/packages/plugins/plugin-pinyin-search/package.json
@@ -14,7 +14,8 @@
   },
   "scripts": {
     "build": "tsup --config ../../../tsup.config.ts",
-    "test": "vitest run --passWithNoTests"
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@objectstack/core": "workspace:*",
diff --git a/packages/plugins/plugin-reports/package.json b/packages/plugins/plugin-reports/package.json
@@ -14,7 +14,8 @@
   },
   "scripts": {
     "build": "tsup --config ../../../tsup.config.ts",
-    "test": "vitest run --passWithNoTests"
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@objectstack/core": "workspace:*",
diff --git a/packages/plugins/plugin-security/package.json b/packages/plugins/plugin-security/package.json
@@ -14,7 +14,8 @@
   },
   "scripts": {
     "build": "tsup --config ../../../tsup.config.ts",
-    "test": "vitest run"
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@objectstack/core": "workspace:*",
diff --git a/packages/plugins/plugin-sharing/package.json b/packages/plugins/plugin-sharing/package.json
@@ -14,7 +14,8 @@
   },
   "scripts": {
     "build": "tsup --config ../../../tsup.config.ts",
-    "test": "vitest run --passWithNoTests"
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@objectstack/core": "workspace:*",
diff --git a/packages/plugins/plugin-webhooks/package.json b/packages/plugins/plugin-webhooks/package.json
@@ -20,7 +20,8 @@
   },
   "scripts": {
     "build": "tsup",
-    "test": "vitest run"
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@objectstack/core": "workspace:*",
diff --git a/packages/qa/http-conformance/package.json b/packages/qa/http-conformance/package.json
diff --git a/packages/sdui-parser/package.json b/packages/sdui-parser/package.json
diff --git a/packages/services/service-cluster-redis/package.json b/packages/services/service-cluster-redis/package.json
diff --git a/packages/services/service-package/package.json b/packages/services/service-package/package.json
diff --git a/packages/services/service-sms/package.json b/packages/services/service-sms/package.json
diff --git a/packages/spec/package.json b/packages/spec/package.json
diff --git a/packages/triggers/trigger-api/package.json b/packages/triggers/trigger-api/package.json
diff --git a/packages/triggers/trigger-record-change/package.json b/packages/triggers/trigger-record-change/package.json
diff --git a/packages/triggers/trigger-schedule/package.json b/packages/triggers/trigger-schedule/package.json
diff --git a/packages/verify/package.json b/packages/verify/package.json
diff --git a/packages/vscode-objectstack/package.json b/packages/vscode-objectstack/package.json
diff --git a/scripts/check-type-check-coverage.mjs b/scripts/check-type-check-coverage.mjs
diff --git a/turbo.json b/turbo.json

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +---
 +---
++
 +ci(dx): every workspace package now either declares a `typecheck` script (`tsc --noEmit`, run by the new `turbo run typecheck` task in the lint workflow) or carries a measured DEBT/EXEMPT entry in `scripts/check-type-check-coverage.mjs`, whose coverage ratchet runs in CI (#4311). 66 of 77 packages build with tsup, which transpiles without type-checking, and `vitest run` does not type-check either — 48 packages were already clean and are locked in; the 29 failing ones are frozen in the ledger with their raw error counts and the issue's code/config/noise triage. Dev scripts and CI only; releases nothing.