chore(lint): warn on type-erasing assertions via a Biome GritQL plugin

Adds `biome-plugins/no-type-erasing-assertions.grit`, wired into biome.json,
that warns on `as any` / `as never` / `as unknown` in source — assertions that
punch through the type system instead of narrowing (a real mismatch can hide
behind them). `as const`, plain `as SpecificType`, and `never` as a type
annotation are NOT flagged. `as unknown` also catches the inner half of an
`as unknown as T` double-cast.

- severity `warn`: Biome is not a CI gate here (only local `code:fix`), and
  there's a small existing backlog (~17 in src) — this is a ratchet to keep NEW
  erasures visible, not a hard block. Warnings don't change `biome check`'s exit
  code (verified).
- test/integration/*.test-d.ts files are exempt via an `overrides` entry — test
  doubles legitimately force-cast; suppress a deliberate src case with
  `// biome-ignore lint/plugin: <reason>`.
- Known limitation (documented in the plugin): matches only the bare forms, not
  compound casts like `as never[]`.

Claude-Session: https://claude.ai/code/session_01MxTTPaPP16m6br7Hoab94w

Author: coderdan

AGENTS.md

@@ -177,6 +177,12 @@ Three rules to remember when editing CI or pnpm config:
 pnpm run code:fix
 ```
 
+  A Biome GritQL plugin (`biome-plugins/no-type-erasing-assertions.grit`) warns
+  on `as any` / `as never` / `as unknown` in `src` — type-erasing assertions that
+  silence the checker instead of narrowing. Fix the type or use a specific
+  assertion; suppress a deliberate case with `// biome-ignore lint/plugin:
+  <reason>`. Test/integration files are exempt (see `overrides` in `biome.json`).
+
 - **Build**: `pnpm run build` (Turborepo + tsup per package)
 - **Test**: `pnpm --filter <pkg> test` for targeted iterations
 - **Releases**: Use Changesets

biome-plugins/no-type-erasing-assertions.grit

@@ -0,0 +1,26 @@
+// Flags type-erasing assertions: `x as any`, `x as never`, `x as unknown`
+// (the last also catches the inner half of `x as unknown as T` double-casts).
+//
+// These punch a hole through the type system rather than narrowing a value, so
+// a real type mismatch can hide behind them (e.g. passing the wrong shape to a
+// function whose signature you've silenced). Prefer fixing the underlying type,
+// narrowing with a guard, or a precise `as SpecificType`.
+//
+// NOT flagged: `as const` (a widening-freeze, not an erasure), a plain
+// `as SpecificType`, or `never` used as a *type annotation* (e.g. a contravariant
+// `param: never`) — those are legitimate.
+//
+// Warning, not error: the repo has a large existing backlog, and this is a
+// ratchet to keep NEW erasures visible. Intentional cases take a
+// `// biome-ignore lint/plugin: <reason>` suppression.
+or {
+  `$e as any`,
+  `$e as never`,
+  `$e as unknown`
+} where {
+  register_diagnostic(
+    span = $e,
+    message = "Avoid type-erasing assertions (`as any` / `as never` / `as unknown`) — they silence the checker instead of narrowing. Fix the underlying type, use a type guard, or assert a specific type. Suppress an intentional case with `// biome-ignore lint/plugin: <reason>`.",
+    severity = "warn"
+  )
+}

biome.json

@@ -30,5 +30,19 @@
         "noThenProperty": "off"
       }
     }
-  }
+  },
+  "plugins": ["./biome-plugins/no-type-erasing-assertions.grit"],
+  "overrides": [
+    {
+      "includes": [
+        "**/__tests__/**",
+        "**/*.test.ts",
+        "**/*.test-d.ts",
+        "**/integration/**",
+        "**/tests/**",
+        "**/*.spec.ts"
+      ],
+      "plugins": []
+    }
+  ]
 }