ci: dedup redundant tsc compilation in build/CI

The full source type graph was being recompiled ~8x per CI run. Root causes,
all confirmed against the files:

- Makefile: build-lib and build-web both declared 'clean' as a normal
  prerequisite, so under 'make -j4' clean could run mid-write (rm -rf build
  racing tsup/webpack output) and ran once per leaf target. Switch to a single
  order-only prereq (| clean): make now runs clean exactly once and both
  builders wait for it before starting. Verified via 'make -j4 -n build'.

- tsup.config.ts: clean:true re-wiped build/cjs even though the canonical
  'yarn build' (= make clean build) already wipes the whole build/ tree first.
  Set clean:false; standalone yarn build still cleans via make.

- test/typeCompat.test.ts: each run shells out to two full 'tsc' compiles of
  the source type graph. CI runs 'yarn test' across a [20,22,24] Node matrix,
  so this identical, Node-version-independent compile ran 3x. Gate the suite
  behind SKIP_TSC_TYPE_COMPAT, which CI sets on every non-primary matrix node;
  it runs once on Node 20 and always runs locally.

- ci.yml: the standalone 'typecheck' job (tsc --noEmit + tsc -p typings) was a
  full second compile of work already done by 'make lint' in the lint job.
  Removed it; lint is now the single owner of type-checking. Build step gated
  to Node 20 (declaration emit is byte-identical across Node versions).

Net: full-graph tsc/dts compiles per CI run drop from ~8 to ~3 with no loss of
coverage. Verified: yarn build, yarn test (198 passed; 196+2 skipped with the
gate), yarn typecheck, yarn lint all green.

Author: STRML

.github/workflows/ci.yml

@@ -41,10 +41,20 @@ jobs:
       - name: Install dependencies
         run: yarn install --frozen-lockfile
 
+      # The typeCompat tsc compile is Node-version-independent; skip it on every
+      # non-primary matrix node so the full source type graph is compiled once,
+      # not three times. All other unit tests still run on every Node version.
       - name: Run unit tests
+        env:
+          SKIP_TSC_TYPE_COMPAT: ${{ matrix.node-version != 20 && '1' || '' }}
         run: yarn test
 
+      # The build (tsup --dts + webpack) recompiles the full type graph for
+      # declaration emit; that output is byte-identical across Node versions, so
+      # building on every matrix entry just recompiles the same type graph N times.
+      # Gate it to the primary Node version. Unit tests still run on all versions.
       - name: Build
+        if: matrix.node-version == 20
         run: yarn build
 
   test-browser:
@@ -84,22 +94,9 @@ jobs:
       - name: Run tests with coverage
         run: yarn test:coverage
 
-  typecheck:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          cache: 'yarn'
-
-      - name: Install dependencies
-        run: yarn install --frozen-lockfile
-
-      - name: TypeScript check (source)
-        run: yarn tsc --noEmit
-
-      - name: TypeScript check (public typings)
-        run: yarn tsc -p typings
+  # NOTE: the standalone TypeScript checks (`tsc --noEmit` for source and
+  # `tsc -p typings` for the public .d.ts) are already run by `make lint` in the
+  # `lint` job above. Running them again here recompiled the full type graph a
+  # second time every CI run for no added coverage, so this job was removed and
+  # `lint` is the single owner of type-checking. Re-add a dedicated job only if
+  # `make lint` ever stops invoking tsc.

Makefile

@@ -18,16 +18,19 @@ lint:
 
 # tsup emits cjs + esm + dts into build/cjs (and rewrites build/cjs/cjs.js to the
 # legacy module.exports === Draggable shape). webpack emits the UMD global bundle.
-# Both depend on `clean` so the dir is reset first even under parallel make (-j).
-# The recipe runs after both prerequisites complete and verifies the published
-# CJS/UMD contracts (see scripts/verify-build.cjs).
+# `clean` is an ORDER-ONLY prerequisite (after the `|`) on both leaf targets: make
+# guarantees it runs exactly once and that both tsup and webpack wait for it before
+# starting, so under parallel make (-j) we get one clean instead of a per-target
+# race that could `rm -rf build` mid-write. The recipe runs after both
+# prerequisites complete and verifies the published CJS/UMD contracts (see
+# scripts/verify-build.cjs).
 build: build-lib build-web
 	@node scripts/verify-build.cjs
 
-build-lib: clean $(BIN)
+build-lib: $(BIN) | clean
 	$(BIN)/tsup
 
-build-web: clean $(BIN)
+build-web: $(BIN) | clean
 	$(BIN)/webpack --mode=production
 
 # Allows usage of `make install`, `make link`

test/typeCompat.test.ts

@@ -50,7 +50,18 @@ function runTsc(projectDir: string): {ok: boolean; output: string} {
 // can take several seconds on slower CI runners — well past vitest's 5s default.
 const TSC_TIMEOUT_MS = 60_000;
 
-describe('public type-surface compatibility', () => {
+// These cases spawn `tsc` against the source type graph. The result is purely a
+// function of the TypeScript dependency + source — it does NOT depend on the Node
+// runtime version. CI runs `yarn test` across a Node version matrix, so without a
+// guard this full-graph compile would run once per matrix entry, recompiling the
+// identical type graph N times for zero added coverage. CI sets
+// SKIP_TSC_TYPE_COMPAT=1 on every non-primary matrix node so the compile happens
+// exactly once. Locally (env unset) it always runs.
+const describeTypeCompat = process.env.SKIP_TSC_TYPE_COMPAT
+  ? describe.skip
+  : describe;
+
+describeTypeCompat('public type-surface compatibility', () => {
   it('public surface is API-compatible with the old hand-written surface', () => {
     const {ok, output} = runTsc(resolve(__dirname, 'typeCompat'));
     expect(output, output).toBe('');

tsup.config.ts

@@ -45,7 +45,10 @@ export default defineConfig({
   format: ['cjs', 'esm'],
   dts: true,
   sourcemap: true,
-  clean: true,
+  // The Makefile's `clean` target (an order-only prereq of build-lib) wipes the
+  // whole build/ tree once before tsup runs, so tsup re-cleaning its own outDir
+  // here is redundant in the canonical `yarn build` (= `make clean build`) path.
+  clean: false,
   target: 'es2019',
   external,
   // ESM output -> .mjs, CJS output -> .js (so package "main" stays build/cjs/cjs.js).