fix(plugin-map): drop the maplibre-gl@6 default import + gate type-check in CI (#2911) (#2915)

os-zhuang · claude · web-flow · commit 5b9cf963afa3 · 2026-07-28T19:39:54.000+08:00
* fix(plugin-map): drop the maplibre-gl@6 default import + gate type-check in CI (#2911) maplibre-gl@6.0.0 removed its default export (#2848), so ObjectMap.tsx's `import maplibregl from 'maplibre-gl'` has been a TS1192 error on main. The binding was never used — the map comes from react-map-gl/maplibre and the CSS from the side-effect import on the next line — so it is deleted outright. Runtime-neutral: @vis.gl/react-maplibre does `Promise.resolve(mapLib || import('maplibre-gl'))`, so it self-loads the library. Browser-verified against the store-locator-map catalog schema — maplibre-gl fetched as its own lazy chunk, canvas 800x600, all 3 markers mounted, identical with and without the static import. The error survived a day of green CI because no workflow ran type-check, and `turbo build` only checks types where a package's build happens to invoke tsc (the 22 vite-build packages do not). A sweep of all 45 packages found ten with broken types. `pnpm type-check` alone is not a gate: turbo silently skips packages with no type-check script, so with plugin-map fixed it reports 63/63 green while nine packages remain broken. Therefore: - plugin-ai / plugin-report gain the tsconfig `paths` override their type-checked peers already carry (and their own vite dts program already applies), which is the sole cause of the TS6059 rootDir floods. - Seven packages gain "type-check": "tsc --noEmit"; coverage 28 -> 35 of 45. - scripts/check-type-check-coverage.mjs requires every uncovered package to be declared with a reason and only lets the lists shrink. - New "Type Check" CI job runs the coverage guard, then pnpm type-check. Both halves were proven red before being trusted: the guard in all four of its failure modes, and the job against both the re-introduced maplibre-gl import and a fresh error injected into plugin-ai — which had no type checking at all before this change. Refs #2911, #2848 Co-Authored-By: Claude <noreply@anthropic.com> * chore(type-check): link each DEBT entry to its follow-up issue Corrects two notes while wiring the links. The plugin-grid TS2367 pair is not a logic bug: `reason` is mutated only inside the `bump` closure, which TS's control-flow analysis does not track, so it stays narrowed to its initialiser. Runtime is correct and deleting the branch would silently disable the type gate. And the layout error is a half-landed feature, not a dead branch — nav type `component` is fully implemented in the renderer but absent from both `NavigationItemType` and its zod enum, so the schema rejects it and authors cannot declare one. Refs #2911, #2916, #2917, #2918, #2919 Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/.changeset/type-check-gate-2911.md b/.changeset/type-check-gate-2911.md
@@ -0,0 +1,59 @@
+---
+"@object-ui/plugin-map": patch
+"@object-ui/plugin-ai": patch
+"@object-ui/plugin-report": patch
+"@object-ui/plugin-dashboard": patch
+"@object-ui/create-plugin": patch
+"@object-ui/console": patch
+---
+
+fix(plugin-map): drop the `maplibre-gl@6` default import, and put type-check behind a CI gate that cannot be silently skipped (#2911)
+
+`maplibre-gl@6.0.0` removed its default export (arrived via #2848, dependabot),
+so `ObjectMap.tsx`'s `import maplibregl from 'maplibre-gl'` has been a TS1192
+error on `main` for a day. The binding was never used — the map instance comes
+from `react-map-gl/maplibre`, and the stylesheet from the side-effect import on
+the next line — so the import is simply deleted rather than rewritten to
+`import * as`.
+
+Removing it is runtime-neutral, which the issue had explicitly left unverified.
+`@vis.gl/react-maplibre` (what `react-map-gl/maplibre` re-exports) does
+`Promise.resolve(mapLib || import('maplibre-gl'))` in `components/map.js`, so it
+loads the library itself when no `mapLib` prop is passed. Verified in a browser
+against the `store-locator-map` catalog schema: `maplibre-gl` is fetched as its
+own lazy chunk, the WebGL canvas comes up 800x600, and all three markers mount —
+byte-identical probe output with and without the static import. That also matches
+what `apps/console/src/main.tsx` already intends, where the plugin is registered
+lazily specifically to keep `maplibre-gl` out of the initial bundle.
+
+**The reason it survived a day of green CI is the part worth fixing.** No
+workflow ran `type-check` at all, and `turbo build` only checks types for
+packages whose `build` script happens to invoke `tsc` — the 22 `vite build`
+packages transpile without checking. A sweep of all 45 packages found ten with
+broken types, `plugin-map` merely being the one that had a script to notice it.
+
+Adding a `pnpm type-check` job alone would not have been a gate: **turbo silently
+skips any package with no `type-check` script**, so 17 packages read as passing
+because nothing ran. With `plugin-map` fixed, `pnpm type-check` reports 63/63
+green while nine packages are still broken. So:
+
+- `plugin-ai` and `plugin-report` gain the `paths` override their type-checked
+  peers already carry, which detaches workspace deps from sibling *source* and
+  resolves them through built `.d.ts` — the sole cause of the 104-error TS6059
+  `rootDir` floods, and the same trick their own `vite.config.ts` already applies
+  to the dts program.
+- Seven packages gain `"type-check": "tsc --noEmit"` (`plugin-ai`,
+  `plugin-report`, `plugin-dashboard`, `create-plugin`, `console`, and the two
+  console examples). Coverage goes 28 -> 35 of 45.
+- New `scripts/check-type-check-coverage.mjs` makes the invisibility impossible:
+  a package with no `type-check` script must be declared, with a reason, and the
+  lists only shrink — gaining a script without deleting the entry fails the
+  guard. The nine known-broken packages are recorded there with error counts
+  (`@object-ui/runner` has no `tsconfig.json` at all), tracked as follow-ups.
+- New `Type Check` CI job runs the coverage guard first (instant, no install),
+  then `pnpm type-check`.
+
+Both halves were proven to fail before being trusted: the guard was exercised in
+all four of its failure modes, and re-introducing the `maplibre-gl` import turns
+the job red again, as does a fresh error injected into `plugin-ai` — a package
+that had no type checking whatsoever before this change.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -35,6 +35,60 @@ jobs:
       - name: Verify all packages are in changeset fixed group
         run: node scripts/check-changeset-fixed.mjs
 
+  # Types were entirely unguarded until #2911: no job ran `type-check`, and
+  # `turbo build` only checks types for packages whose build script happens to
+  # invoke `tsc` — the 22 `vite build` packages transpile without checking. A
+  # `maplibre-gl@6` breakage therefore sat on `main` for a day behind a green CI.
+  #
+  # Note that `pnpm type-check` alone is not a sufficient gate: turbo silently
+  # skips any package with no `type-check` script, so a package without one
+  # reads as passing. The coverage guard is what makes that impossible, and it
+  # runs first because it is instant and catches the structural mistake.
+  type-check:
+    name: Type Check
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+        with:
+          submodules: true
+
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Verify pnpm version
+        run: pnpm --version
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version: '20.x'
+          cache: 'pnpm'
+
+      # Every package must be either type-checked or explicitly declared as a
+      # known gap. Runs before install: it only reads package.json files.
+      - name: Verify type-check coverage
+        run: node scripts/check-type-check-coverage.mjs
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Turbo Cache
+        uses: actions/cache@v6
+        with:
+          path: node_modules/.cache/turbo
+          key: turbo-${{ runner.os }}-type-check-${{ github.sha }}
+          restore-keys: |
+            turbo-${{ runner.os }}-type-check-
+            turbo-${{ runner.os }}-
+
+      # `type-check` dependsOn `^build`, so this builds workspace dependencies
+      # first: the checked packages resolve their deps through built `.d.ts`.
+      - name: Run type-check
+        run: pnpm type-check
+
   # PRs run the suite split across 4 runners. The suite is dominated by fixed
   # per-file cost rather than by the assertions: a PR run reported 495s wall
   # clock of which only 178s was `tests` — the rest was `setup` (831s
diff --git a/apps/console/package.json b/apps/console/package.json
@@ -45,6 +45,7 @@
     "dev": "vite",
     "build:plugin": "tsc -p tsconfig.plugin.json",
     "build": "tsc && vite build && pnpm build:plugin",
+    "type-check": "tsc --noEmit",
     "build:analyze": "pnpm build && echo 'Bundle analysis available at dist/stats.html'",
     "preview": "vite preview",
     "test": "vitest run",
diff --git a/examples/byo-backend-console/package.json b/examples/byo-backend-console/package.json
@@ -7,6 +7,7 @@
   "scripts": {
     "dev": "vite",
     "build": "tsc && vite build",
+    "type-check": "tsc --noEmit",
     "preview": "vite preview"
   },
   "dependencies": {
diff --git a/examples/console-starter/package.json b/examples/console-starter/package.json
@@ -7,6 +7,7 @@
   "scripts": {
     "dev": "vite",
     "build": "tsc && vite build",
+    "type-check": "tsc --noEmit",
     "preview": "vite preview"
   },
   "dependencies": {
diff --git a/package.json b/package.json
@@ -31,6 +31,7 @@
     "test:coverage": "vitest run --coverage",
     "lint": "turbo run lint",
     "type-check": "turbo run type-check",
+    "type-check:coverage": "node scripts/check-type-check-coverage.mjs",
     "cli": "node packages/cli/dist/cli.js",
     "objectui": "node packages/cli/dist/cli.js",
     "create-plugin": "node packages/create-plugin/dist/index.js",
diff --git a/packages/create-plugin/package.json b/packages/create-plugin/package.json
@@ -16,6 +16,7 @@
   ],
   "scripts": {
     "build": "tsup",
+    "type-check": "tsc --noEmit",
     "dev": "tsup --watch",
     "test": "vitest run",
     "lint": "eslint ."
diff --git a/packages/plugin-ai/package.json b/packages/plugin-ai/package.json
@@ -20,6 +20,7 @@
   ],
   "scripts": {
     "build": "vite build",
+    "type-check": "tsc --noEmit",
     "clean": "rm -rf dist",
     "test": "vitest run --passWithNoTests",
     "lint": "eslint ."
diff --git a/packages/plugin-ai/tsconfig.json b/packages/plugin-ai/tsconfig.json
@@ -2,7 +2,16 @@
   "extends": "../../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
-    "jsx": "react-jsx"
+    "jsx": "react-jsx",
+    "baseUrl": ".",
+    // Overriding `paths` drops the root config's `@object-ui/* -> packages/*/src`
+    // mappings, so workspace deps resolve through their built `.d.ts` instead of
+    // pulling sibling sources into this program (which would be outside rootDir).
+    // vite.config.ts already does the same for the dts program.
+    "paths": {
+      "@/*": ["src/*"]
+    },
+    "skipLibCheck": true
   },
   "include": ["src"],
   "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.test.tsx"]
diff --git a/packages/plugin-dashboard/package.json b/packages/plugin-dashboard/package.json
@@ -16,6 +16,7 @@
   },
   "scripts": {
     "build": "vite build",
+    "type-check": "tsc --noEmit",
     "test": "vitest run",
     "lint": "eslint ."
   },
diff --git a/packages/plugin-map/src/ObjectMap.tsx b/packages/plugin-map/src/ObjectMap.tsx
@@ -28,7 +28,6 @@ import { extractRecords, buildExpandFields } from '@object-ui/core';
 import { z } from 'zod';
 import MapGL, { NavigationControl, Marker, Popup } from 'react-map-gl/maplibre';
 import type { MapRef } from 'react-map-gl/maplibre';
-import maplibregl from 'maplibre-gl';
 import 'maplibre-gl/dist/maplibre-gl.css';
 
 const MapConfigSchema = z.object({
diff --git a/packages/plugin-report/package.json b/packages/plugin-report/package.json
@@ -20,6 +20,7 @@
   ],
   "scripts": {
     "build": "vite build",
+    "type-check": "tsc --noEmit",
     "clean": "rm -rf dist",
     "test": "vitest run",
     "lint": "eslint ."
diff --git a/packages/plugin-report/tsconfig.json b/packages/plugin-report/tsconfig.json
@@ -3,6 +3,14 @@
   "compilerOptions": {
     "outDir": "dist",
     "jsx": "react-jsx",
+    "baseUrl": ".",
+    // Overriding `paths` drops the root config's `@object-ui/* -> packages/*/src`
+    // mappings, so workspace deps resolve through their built `.d.ts` instead of
+    // pulling sibling sources into this program (which would be outside rootDir).
+    // vite.config.ts already does the same for the dts program.
+    "paths": {
+      "@/*": ["src/*"]
+    },
     "skipLibCheck": true
   },
   "include": ["src"],
diff --git a/scripts/check-type-check-coverage.mjs b/scripts/check-type-check-coverage.mjs
@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * Validates that every workspace package's types are actually checked by CI.
+ *
+ * `pnpm type-check` runs `turbo run type-check`, and turbo silently skips any
+ * package that has no `type-check` script — so a package without one is not
+ * "passing", it is unchecked. That is how #2911 happened: `plugin-map` sat
+ * broken on `main` for a day while build and tests were green.
+ *
+ * This guard makes that invisibility impossible. A package with no
+ * `type-check` script must be declared below, with a reason, and the lists can
+ * only shrink: once a package gains the script, its entry has to be deleted or
+ * this guard fails.
+ *
+ * Run:  node scripts/check-type-check-coverage.mjs
+ * Exit: 0 = OK, 1 = coverage regressed or the lists are stale
+ */
+
+import { readFileSync, readdirSync, statSync } from "fs";
+import { resolve, dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+// ── Known gaps ───────────────────────────────────────────────────────────────
+// Packages whose types do NOT currently compile, so they cannot carry a
+// `type-check` script yet. Every entry is real debt: fix the errors, add
+// `"type-check": "tsc --noEmit"`, then delete the entry. Counts are from the
+// #2911 sweep (bare `tsc --noEmit` with the `paths` override its type-checked
+// peers already carry, so the TS6059 rootDir noise is excluded).
+const DEBT = {
+  "@object-ui/runner": { errors: 14, issue: 2917, note: "no tsconfig.json at all; also imports two exports @object-ui/core does not have" },
+  "@object-ui/plugin-form": { errors: 10, issue: 2919, note: "6x t() fallback-signature mismatch, 2x undefined index, 2x string|number" },
+  "@object-ui/site": { errors: 7, issue: 2919, note: "TS2304 on Next's generated LayoutProps/PageProps; needs .next/types from a prior next build" },
+  "@object-ui/plugin-grid": { errors: 4, issue: 2919, note: "2x t() call signature + 2x TS2367 that are closure-mutation narrowing artifacts, NOT a logic bug" },
+  "@object-ui/cli": { errors: 4, issue: 2919, note: "tsup dts:true does not fail on these" },
+  "@object-ui/plugin-view": { errors: 3, issue: 2916, note: "Record<ViewType,...> missing the 'chart' key" },
+  "@object-ui/layout": { errors: 2, issue: 2918, note: "nav type 'component' is implemented but absent from NavigationItemType and its zod enum" },
+  "@object-ui/plugin-designer": { errors: 1, issue: 2919, note: "unused parameter" },
+  "object-ui": { errors: 1, issue: 2919, note: "TS5107: moduleResolution=node10 deprecated, stops working in TS 7" },
+};
+
+// Packages that are not compiled at all: documentation snippets with no build
+// script and no tsconfig, whose sources are read rather than run. Re-validated
+// on every run — the moment one gains a build script or a tsconfig it is a real
+// package, the exemption dies, and the guard fails.
+const NOT_COMPILED = ["@object-ui/example-hello-world"];
+
+// ── Collect workspace packages ───────────────────────────────────────────────
+const GROUPS = ["packages", "apps", "examples"];
+
+function collect() {
+  const out = [];
+  for (const group of GROUPS) {
+    let entries;
+    try {
+      entries = readdirSync(resolve(root, group));
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const dir = join(group, entry);
+      const manifest = resolve(root, dir, "package.json");
+      try {
+        statSync(manifest);
+      } catch {
+        continue;
+      }
+      const pkg = JSON.parse(readFileSync(manifest, "utf8"));
+      if (!pkg.name) continue;
+      let hasTsconfig = true;
+      try {
+        statSync(resolve(root, dir, "tsconfig.json"));
+      } catch {
+        hasTsconfig = false;
+      }
+      out.push({
+        name: pkg.name,
+        dir,
+        hasScript: Boolean(pkg.scripts?.["type-check"]),
+        hasBuild: Boolean(pkg.scripts?.build),
+        hasTsconfig,
+      });
+    }
+  }
+  return out;
+}
+
+const packages = collect();
+const byName = new Map(packages.map((p) => [p.name, p]));
+
+const errors = [];
+
+// 1. Undeclared gap — a package born without a type-check script.
+for (const pkg of packages) {
+  if (pkg.hasScript) continue;
+  if (DEBT[pkg.name] || NOT_COMPILED.includes(pkg.name)) continue;
+  errors.push(
+    `${pkg.name} (${pkg.dir}) has no "type-check" script, so \`pnpm type-check\` skips it entirely.\n` +
+      `      Add  "type-check": "tsc --noEmit"  to its package.json. If its types do not compile\n` +
+      `      yet, add it to DEBT in scripts/check-type-check-coverage.mjs with an error count.`
+  );
+}
+
+// 2. Ratchet — a declared gap that has been closed must leave the list.
+for (const name of Object.keys(DEBT)) {
+  const pkg = byName.get(name);
+  if (!pkg) {
+    errors.push(`${name} is listed in DEBT but is not a workspace package any more — delete the entry.`);
+  } else if (pkg.hasScript) {
+    errors.push(
+      `${name} now has a "type-check" script — delete its DEBT entry so the gap cannot reopen` +
+        `${DEBT[name].issue ? ` (and close #${DEBT[name].issue} if it is done)` : ""}.`
+    );
+  }
+}
+
+// 3. Ratchet — an exemption only holds while the package really is not compiled.
+for (const name of NOT_COMPILED) {
+  const pkg = byName.get(name);
+  if (!pkg) {
+    errors.push(`${name} is listed in NOT_COMPILED but is not a workspace package any more — delete the entry.`);
+    continue;
+  }
+  if (pkg.hasScript) {
+    errors.push(`${name} now has a "type-check" script — delete its NOT_COMPILED entry.`);
+    continue;
+  }
+  const acquired = [pkg.hasBuild && "a build script", pkg.hasTsconfig && "a tsconfig.json"].filter(Boolean);
+  if (acquired.length > 0) {
+    errors.push(
+      `${name} is listed in NOT_COMPILED but has gained ${acquired.join(" and ")} — it is a real package now.\n` +
+        `      Add  "type-check": "tsc --noEmit"  and remove the exemption.`
+    );
+  }
+}
+
+// ── Report ───────────────────────────────────────────────────────────────────
+const checked = packages.filter((p) => p.hasScript).length;
+const debtCount = Object.keys(DEBT).length;
+const debtErrors = Object.values(DEBT).reduce((sum, d) => sum + d.errors, 0);
+
+if (errors.length === 0) {
+  console.log(
+    `✅  type-check coverage: ${checked}/${packages.length} packages checked, ` +
+      `${debtCount} known-broken (${debtErrors} errors outstanding), ` +
+      `${NOT_COMPILED.length} not compiled.`
+  );
+  process.exit(0);
+}
+
+console.error("❌  type-check coverage regressed:\n");
+for (const message of errors) {
+  console.error(`    • ${message}`);
+}
+console.error(
+  "\nA package with no `type-check` script is not passing — turbo skips it and CI sees nothing.\n" +
+    "See https://github.com/objectstack-ai/objectui/issues/2911 for why this guard exists."
+);
+process.exit(1);
