biome-typescript-best-practices-plugin 1.0.0

package/CHANGELOG.md

@@ -0,0 +1 @@
+# biome-typescript-best-practices-plugin

package/README.md

@@ -0,0 +1,243 @@
+# biome-typescript-best-practices-plugin
+
+A [Biome](https://biomejs.dev) plugin (written in [GritQL](https://biomejs.dev/blog/gritql-biome)) that
+enforces TypeScript best practices **not covered by Biome's recommended linter** — catching the patterns
+that quietly bypass the type checker, walk the prototype chain, or sort your numbers wrong.
+
+```ts
+// flagged
+const el = getEl() as HTMLInputElement;          // `as` bypasses the type checker
+if ("id" in obj) {}                              // `in` walks the prototype chain
+items.reduce((acc, x) => acc, {});               // `{}` accumulator leaks prototype keys
+enum Color { Red, Green }                        // enum emits runtime code
+delete obj[key];                                 // dynamic delete deoptimises shape
+[3, 20, 100].sort();                             // lexicographic → [100, 20, 3]
+
+// safe
+const el = getEl();                              // narrow with a type guard, or `satisfies`
+if (Object.hasOwn(obj, "id")) {}
+items.reduce((acc, x) => acc.set(x.k, x.v), new Map());
+const Color = { Red: "red", Green: "green" } as const;
+delete obj.prop;                                 // static key is fine
+[3, 20, 100].sort((a, b) => a - b);
+```
+
+## Rules
+
+| Rule | Flags | Why |
+| --- | --- | --- |
+| `ts/no-as-cast` | `expr as T` type assertions (except `as const`) | `as` silences the type checker and can mask real type errors. |
+| `ts/no-in-operator` | the `in` operator and `for...in` | `in` walks the prototype chain, matching inherited/polluted keys. |
+| `ts/no-empty-object-accumulator` | `reduce(…, {})` / `reduceRight(…, {})` | A `{}` accumulator carries `Object.prototype`, so dynamic keys like `"__proto__"` leak in. |
+| `ts/no-enum` | `enum` and `const enum` declarations | Enums emit runtime code with surprising semantics; `const enum` breaks `isolatedModules`. |
+| `ts/no-dynamic-delete` | `delete obj[expr]` with a computed, non-literal key | Deleting a dynamic key deoptimises the object shape and usually means a `Map` was wanted. |
+| `ts/require-array-sort-compare` | `.sort()` / `.toSorted()` with no comparator | Default sort is by UTF-16 code unit, so numbers come out in the wrong order. |
+
+All rules report a diagnostic only (severity `warn`, category `plugin`); none apply an auto-fix, because the
+correct repair is context-specific — the plugin flags the hazard and leaves the fix to you.
+
+These rules are intentionally **not** duplicates of Biome's recommended set (which already covers
+`noExplicitAny`, `noNonNullAssertion`, `noDoubleEquals`, and similar). They fill gaps that otherwise need
+`typescript-eslint`.
+
+### ts/no-as-cast
+
+```ts
+// flagged
+const el = getEl() as HTMLInputElement;
+const rec = (obj as Record<string, unknown>).key;
+const twice = value as unknown as Target;   // double assertion — flagged twice
+
+// safe
+const val = input as const;                 // `as const` narrows a literal, allowed
+const ok = value satisfies Target;          // `satisfies` validates without asserting
+```
+
+A type assertion tells the compiler "trust me" and switches off the very check you installed TypeScript
+for. Only `as const` (literal narrowing) is exempt — every other `as T` is flagged. A double assertion
+(`x as unknown as T`) is two `TsAsExpression` nodes, so it reports twice. Inspired by
+[`biome-plugin-no-type-assertion`](https://github.com/albertodeago/biome-plugin-no-type-assertion).
+
+### ts/no-in-operator
+
+```ts
+// flagged
+if ("id" in obj) {}
+for (const k in obj) {}
+
+// safe
+if (Object.hasOwn(obj, "id")) {}
+for (const k of Object.keys(obj)) {}
+```
+
+The `in` operator and `for...in` both consult the prototype chain, so inherited or prototype-polluted keys
+match. `Object.hasOwn` is an own-property check; `Object.keys`/`Object.entries` with `for...of` iterate only
+own enumerable keys. Inspired by
+[felixarntz/biome's `no-in-operator`](https://github.com/felixarntz/biome/blob/main/rules/no-in-operator.grit).
+
+### ts/no-empty-object-accumulator
+
+```ts
+// flagged
+items.reduce((acc, x) => { acc[x.k] = x.v; return acc; }, {});
+items.reduceRight((acc, x) => acc, {});
+
+// safe
+items.reduce((acc, x) => acc.set(x.k, x.v), new Map());
+items.reduce((acc, x) => acc + x, 0);
+items.reduce((acc, x) => acc, { total: 0 });   // seeded object, not empty
+```
+
+Only an **empty** `{}` seed is flagged — that is the shape used for dynamic-key aggregation, where a key like
+`"__proto__"` or `"constructor"` can collide with `Object.prototype`. A `new Map()` or `Object.create(null)`
+has no such surface. Inspired by
+[felixarntz/biome's `no-empty-object-accumulator`](https://github.com/felixarntz/biome/blob/main/rules/no-empty-object-accumulator.grit).
+
+### ts/no-enum
+
+```ts
+// flagged
+enum Color { Red, Green }
+const enum Dir { Up, Down }
+
+// safe
+const Color = { Red: "red", Green: "green" } as const;
+type Color = (typeof Color)[keyof typeof Color];
+```
+
+`enum` is one of the few TypeScript features that emits runtime code, and it has surprising semantics (numeric
+enums are bidirectional maps; a value can be assigned any number). `const enum` is erased but breaks under
+`isolatedModules` / Babel / esbuild. A `const` object with `as const` plus a derived union is fully erasable
+and behaves predictably.
+
+### ts/no-dynamic-delete
+
+```ts
+// flagged
+delete obj[key];
+delete cache[getId()];
+delete registry[user.id];
+
+// safe
+delete obj.prop;        // static member
+delete obj["literal"];  // literal key
+delete arr[0];          // literal index
+```
+
+Deleting a computed, non-literal key forces the engine to change the object's hidden shape, deoptimising it,
+and usually signals that a `Map` (with `.delete(key)`) was the right structure — or that the field should be
+modelled as optional (`v?: T`). Static members and literal keys are left alone.
+
+### ts/require-array-sort-compare
+
+```ts
+// flagged
+[3, 20, 100].sort();      // → [100, 20, 3]
+numbers.toSorted();
+
+// safe
+[3, 20, 100].sort((a, b) => a - b);
+strings.sort();           // NOTE: also flagged — see limitations
+```
+
+`Array#sort` and `Array#toSorted` with no comparator coerce elements to strings and compare by UTF-16 code
+unit, so `[3, 20, 100]` sorts to `[100, 20, 3]`. Passing an explicit comparator makes the order intentional
+and correct.
+
+## Limitations
+
+The plugin matches **structure, not types** — it keys off method and operator shapes, not the static type of
+the receiver. Practical consequences:
+
+- `ts/require-array-sort-compare` flags every argument-less `.sort()` / `.toSorted()`, including on
+  `string[]` where the default order is fine. Add a comparator (`(a, b) => a.localeCompare(b)`) or suppress
+  the line if the lexicographic default is intended.
+- `ts/no-empty-object-accumulator` matches any `.reduce(fn, {})` regardless of receiver, and
+  `ts/no-dynamic-delete` matches any `delete x[expr]`.
+- Biome's GritQL plugins cannot yet take per-rule configuration, so the matches are intentionally broad. Scope
+  the plugin with Biome's `includes` / `overrides` if false positives are a problem, or disable an individual
+  rule by editing your copy of the `.grit` file.
+
+## Usage
+
+Install the plugin as a dev dependency:
+
+```sh
+npm install -D biome-typescript-best-practices-plugin
+```
+
+Reference it from your Biome configuration:
+
+```jsonc
+{
+  "plugins": ["biome-typescript-best-practices-plugin/typescript.grit"],
+  "linter": {
+    "rules": { "recommended": true }
+  }
+}
+```
+
+Then run the linter:
+
+```sh
+npx @biomejs/biome lint <files>
+```
+
+Requires Biome **2.0+** (GritQL plugins landed in v2.0). Developed and tested against Biome 2.5.
+
+> Using it directly from this repo instead? Set `"plugins": ["./typescript.grit"]` and point the path at the
+> checked-out file.
+
+## Try it
+
+```sh
+npm install
+npx @biomejs/biome lint example.ts
+```
+
+## Tests
+
+Snapshot tests live in [tests/](tests/). Each case is a pair: `tests/fixtures/<name>.ts` (the source to lint)
+and `<name>.expected.json` (the diagnostics it should produce, as an order-independent array of
+`{ "line": <number>, "rule": "<slug>" }`). The runner ([scripts/run-tests.mjs](scripts/run-tests.mjs)) runs
+`biome lint --reporter=json` on each fixture with only the plugin enabled and compares the extracted
+diagnostics against the expectation.
+
+```sh
+npm test
+```
+
+Every rule has a flagged fixture and a safe counterpart, covering the exempt cases (`as const`,
+`Object.hasOwn`, seeded/`Map` accumulators, `const`-object enums, literal-key deletes, and comparator sorts).
+
+## How it works
+
+The plugin is one Biome GritQL file, [typescript.grit](typescript.grit).
+
+- `no-as-cast` matches `TsAsExpression(ty = $type)` and excludes `$type <: TsReferenceType(name = \`const\`)`
+  so `as const` passes.
+- `no-in-operator` matches `JsInExpression` and `JsForInStatement`.
+- `no-empty-object-accumulator` matches a `reduce`/`reduceRight` call whose second argument is a
+  `JsObjectExpression` with an empty member list (`$members <: []`).
+- `no-enum` matches `TsEnumDeclaration` (covers both `enum` and `const enum`).
+- `no-dynamic-delete` matches `delete $target` where `$target` is a `JsComputedMemberExpression` whose key is
+  not a string or number literal.
+- `require-array-sort-compare` matches a `sort`/`toSorted` call with an empty argument list (`$args <: []`).
+
+## Releasing
+
+Versions and the changelog are managed with [Changesets](https://github.com/changesets/changesets).
+
+1. Add a changeset describing a change: `npx changeset`.
+2. Commit the changeset to your branch.
+3. On merge to `main`, the [Release workflow](.github/workflows/release.yml) opens a "Version Packages" pull
+   request that bumps the version and updates `CHANGELOG.md`.
+4. Merge that PR and the workflow publishes the new version to npm.
+
+The workflow needs an `NPM_TOKEN` secret in the repo. CI runs the test suite on every push and pull request
+([.github/workflows/ci.yml](.github/workflows/ci.yml)).
+
+---
+
+Inspired by [`biome-plugin-no-type-assertion`](https://github.com/albertodeago/biome-plugin-no-type-assertion)
+and the GritQL rules in [felixarntz/biome](https://github.com/felixarntz/biome).

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "biome-typescript-best-practices-plugin",
+  "version": "1.0.0",
+  "description": "Biome plugin that enforces TypeScript best practices — no `as` assertions, no `in` operator, no empty-object reduce accumulators, no enums, no dynamic delete, and safe array sorting.",
+  "license": "ISC",
+  "author": "Ivan Stepanian <iv.stpn@gmail.com>",
+  "type": "commonjs",
+  "keywords": [
+    "biome",
+    "biome-plugin",
+    "gritql",
+    "lint",
+    "typescript",
+    "best-practices",
+    "type-safety"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iv-stpn/biome-typescript-best-practices-plugin.git"
+  },
+  "homepage": "https://github.com/iv-stpn/biome-typescript-best-practices-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/iv-stpn/biome-typescript-best-practices-plugin/issues"
+  },
+  "files": [
+    "typescript.grit",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node scripts/run-tests.mjs",
+    "typecheck": "tsc --noEmit",
+    "version": "changeset version",
+    "release": "changeset publish"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.2",
+    "@changesets/cli": "2.31.0",
+    "@types/node": "^26",
+    "typescript": "^6"
+  }
+}

package/typescript.grit

@@ -0,0 +1,131 @@
+engine biome(1.0)
+language js
+
+// biome-typescript-best-practices-plugin: TypeScript safety & clarity rules.
+//
+// A set of best-practice checks that are NOT part of Biome's default/recommended
+// linter but that push TypeScript towards safer, clearer code. Every rule reports
+// a diagnostic only (no auto-fix): the correct rewrite is context-specific, so the
+// plugin flags the hazard and leaves the fix to the author.
+//
+// Rules:
+//   ts/no-as-cast                 — `expr as T` type assertions (bypasses the checker).
+//   ts/no-in-operator             — the `in` operator and `for...in` (prototype-chain traps).
+//   ts/no-empty-object-accumulator — `reduce(..., {})` with a plain-object accumulator.
+//   ts/no-enum                    — `enum` / `const enum` declarations.
+//   ts/no-dynamic-delete          — `delete obj[expr]` with a computed, non-literal key.
+//   ts/require-array-sort-compare — `.sort()` / `.toSorted()` with no comparator.
+//
+// Inspired by biome-plugin-no-type-assertion and felixarntz/biome's GritQL rules.
+
+// A `.sort` / `.toSorted` member name.
+pattern sort_method_name() {
+    or { `sort`, `toSorted` }
+}
+
+or {
+    // Rule: ts/no-as-cast
+    // Bad:  const el = document.getElementById("x") as HTMLInputElement;
+    // Good: use a type guard, a runtime check, or `satisfies` for validation.
+    // `as` assertions silence the type checker and can mask real bugs. `as const`
+    // is a legitimate literal-narrowing form and is left alone.
+    TsAsExpression(ty = $type) as $node where {
+        not $type <: TsReferenceType(name = `const`),
+        register_diagnostic(
+            span = $node,
+            message = "[ts/no-as-cast] Avoid `as` type assertions — they bypass the type checker and can hide real type errors. Use a type guard, a runtime check, or `satisfies` to validate a value. (`as const` is allowed.)",
+            severity = "warn"
+        )
+    },
+
+    // Rule: ts/no-in-operator
+    // Bad:  if ("id" in obj) { ... }        for (const k in obj) { ... }
+    // Good: if (Object.hasOwn(obj, "id"))   for (const k of Object.keys(obj))
+    // `in` walks the prototype chain, so inherited/polluted keys match too, and it
+    // gives no type narrowing you can rely on across shapes.
+    or {
+        JsInExpression() as $node where {
+            register_diagnostic(
+                span = $node,
+                message = "[ts/no-in-operator] Avoid the `in` operator — it walks the prototype chain and matches inherited keys. Use Object.hasOwn(obj, key) for an own-property check.",
+                severity = "warn"
+            )
+        },
+        JsForInStatement() as $node where {
+            register_diagnostic(
+                span = $node,
+                message = "[ts/no-in-operator] Avoid `for...in` — it iterates inherited enumerable keys. Use `for (const k of Object.keys(obj))` (or Object.entries) instead.",
+                severity = "warn"
+            )
+        }
+    },
+
+    // Rule: ts/no-empty-object-accumulator
+    // Bad:  items.reduce((acc, x) => { acc[x.k] = x.v; return acc; }, {})
+    // Good: new Map(items.map((x) => [x.k, x.v]))   or   Object.create(null)
+    // A plain `{}` accumulator carries Object.prototype, so dynamic keys like
+    // "__proto__" / "constructor" leak into aggregation. A Map (or a null-proto
+    // object) has no such surface.
+    JsCallExpression(
+        callee = JsStaticMemberExpression(member = $method),
+        arguments = JsCallArguments(args = $args)
+    ) as $call where {
+        $method <: or { `reduce`, `reduceRight` },
+        $args <: [$_, $init],
+        $init <: JsObjectExpression(members = $members),
+        $members <: [],
+        register_diagnostic(
+            span = $call,
+            message = "[ts/no-empty-object-accumulator] Avoid a `{}` accumulator in reduce — its prototype chain lets keys like \"__proto__\" leak into dynamic-key aggregation. Use `new Map()` or `Object.create(null)`.",
+            severity = "warn"
+        )
+    },
+
+    // Rule: ts/no-enum
+    // Bad:  enum Color { Red, Green }        const enum Dir { Up, Down }
+    // Good: const Color = { Red: "red", Green: "green" } as const;
+    //       type Color = (typeof Color)[keyof typeof Color];
+    // `enum` emits runtime code, has surprising numeric/string semantics, and
+    // `const enum` breaks under isolatedModules. A `const` object + union type is
+    // safer and erasable.
+    TsEnumDeclaration() as $node where {
+        register_diagnostic(
+            span = $node,
+            message = "[ts/no-enum] Avoid `enum` — it emits runtime code and has surprising semantics (and `const enum` breaks isolatedModules). Prefer a `const` object with `as const` plus a derived union type.",
+            severity = "warn"
+        )
+    },
+
+    // Rule: ts/no-dynamic-delete
+    // Bad:  delete obj[key];   delete obj[getKey()];
+    // Good: model the field as optional (`v?: T`) or use a Map and `.delete(key)`.
+    // Deleting a computed, non-literal key deoptimises the object's shape and often
+    // signals that a Map was the right structure. Literal keys are left alone.
+    `delete $target` as $node where {
+        $target <: JsComputedMemberExpression(member = $key),
+        not $key <: or { JsStringLiteralExpression(), JsNumberLiteralExpression() },
+        register_diagnostic(
+            span = $node,
+            message = "[ts/no-dynamic-delete] Avoid `delete` with a computed key — it deoptimises the object shape. Model the property as optional, or use a Map with `.delete(key)`.",
+            severity = "warn"
+        )
+    },
+
+    // Rule: ts/require-array-sort-compare
+    // Bad:  [3, 20, 100].sort()   // → [100, 20, 3] (lexicographic!)
+    // Good: [3, 20, 100].sort((a, b) => a - b)
+    // `Array#sort` / `toSorted` with no comparator sorts by UTF-16 code unit, so
+    // numbers come out in the wrong order. Always pass an explicit comparator.
+    JsCallExpression(
+        callee = JsStaticMemberExpression(member = $method),
+        arguments = JsCallArguments(args = $args)
+    ) as $call where {
+        $method <: sort_method_name(),
+        $args <: [],
+        register_diagnostic(
+            span = $call,
+            message = "[ts/require-array-sort-compare] `.sort()` / `.toSorted()` with no comparator sorts lexicographically, so numbers sort wrong (e.g. [3,20,100] → [100,20,3]). Pass a compare function, e.g. .sort((a, b) => a - b).",
+            severity = "warn"
+        )
+    }
+}