@codelaw/rules-ts 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Arpit Arya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+SPDX-License-Identifier: MIT

package/NOTICE

@@ -0,0 +1,6 @@
+@codelaw/rules-ts
+
+The rules are reimplementations written for codelaw. Their `ported_from:`
+fields name the typescript-eslint rules (https://typescript-eslint.io, MIT
+License) whose documented behaviour they reproduce; no typescript-eslint code
+or documentation text is included.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @codelaw/rules-ts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+codelaw's TypeScript rules — one of codelaw's first-party rule packs
+([SR-RULE-PACKS](../../records/0101_rule-packs.md)). It ships on
+npm only, as `@codelaw/rules-ts`; PyPI has no copy (L6 decision 11).
+
+```toml
+# codelaw.toml
+extends = ["codelaw:js/recommended", "codelaw:js/typescript", "codelaw:ts/recommended"]
+preview = true   # every rule is `preview` until a corpus run promotes it
+```
+
+## Presets
+
+<!-- docs-sync:presets -->
+
+| preset | rules | ported from |
+|---|---|---|
+| `ts/recommended` | 20 | typescript-eslint `recommended` 8.71.2 (not type-checked) — all 20 rules; the four core rules its `eslint-recommended` switches on are `codelaw:js/typescript` in `@codelaw/rules-js` |
+| `ts/conventions` | 1 | codelaw's starter catalogue: `ts/type-only-imports` — opt in |
+
+<!-- /docs-sync:presets -->
+
+Every rule is **reimplemented**, not vendored: the matchers, messages and docs
+are written fresh, and each rule's `ported_from:` names the source rule.
+
+## How the ports differ
+
+Every rule matches its source's documented behaviour on the source's own
+examples. Where codelaw differs, the rule's `## Differences from the source`
+section says so. The larger ones:
+
+| rule | difference |
+|---|---|
+| `ts/no-unused-expressions` | `x satisfies T;` is a compile-time type test and is allowed |
+
+Nothing from typescript-eslint's non-type-checked `recommended` is left out.
+Every `*-type-checked` typescript-eslint config is out of scope: those rules
+need type information (L3).

package/codelaw-pack.toml

@@ -0,0 +1,6 @@
+name = "@codelaw/rules-ts"
+version = "0.2.0"
+min_codelaw = "0.1.0"
+languages = ["typescript", "tsx"]
+presets = ["ts/recommended", "ts/conventions"]
+description = "codelaw's TypeScript rules, from typescript-eslint; npm only (SR-RULE-PACKS)"

package/corpus.toml

@@ -0,0 +1,25 @@
+# `codelaw test --corpus` finding counts (SR-RULE-AUTHORING decision 4).
+# Rewrite with --update-snapshot, and review the change.
+
+[findings]
+"ts/ban-ts-comment" = 96
+"ts/no-array-constructor" = 0
+"ts/no-duplicate-enum-values" = 0
+"ts/no-empty-object-type" = 276
+"ts/no-explicit-any" = 1653
+"ts/no-extra-non-null-assertion" = 0
+"ts/no-misused-new" = 0
+"ts/no-namespace" = 1
+"ts/no-non-null-asserted-optional-chain" = 0
+"ts/no-require-imports" = 3
+"ts/no-this-alias" = 1
+"ts/no-unnecessary-type-constraint" = 0
+"ts/no-unsafe-declaration-merging" = 173
+"ts/no-unsafe-function-type" = 8
+"ts/no-unused-expressions" = 39
+"ts/no-unused-vars" = 318
+"ts/no-wrapper-object-types" = 0
+"ts/prefer-as-const" = 0
+"ts/prefer-namespace-keyword" = 0
+"ts/triple-slash-reference" = 0
+"ts/type-only-imports" = 797

package/package.json

@@ -1,6 +1,16 @@
 {
   "name": "@codelaw/rules-ts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "codelaw's TypeScript rules, from typescript-eslint; npm only (SR-RULE-PACKS)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arpitarya/codelaw.git"
+  },
+  "homepage": "https://github.com/arpitarya/codelaw",
+  "keywords": [
+    "codelaw",
+    "codelaw-pack",
+    "lint-rules"
+  ]
+}

package/presets/ts/conventions.toml

@@ -0,0 +1,4 @@
+description = "House conventions from codelaw's starter catalogue; opt in"
+
+[rules]
+"ts/type-only-imports" = "error"

package/presets/ts/recommended.toml

@@ -0,0 +1,23 @@
+description = "typescript-eslint's recommended preset (8.71.2, not type-checked), reimplemented; the core rules it switches on for TypeScript are codelaw:js/typescript"
+
+[rules]
+"ts/ban-ts-comment" = "error"
+"ts/no-array-constructor" = "error"
+"ts/no-duplicate-enum-values" = "error"
+"ts/no-empty-object-type" = "error"
+"ts/no-explicit-any" = "error"
+"ts/no-extra-non-null-assertion" = "error"
+"ts/no-misused-new" = "error"
+"ts/no-namespace" = "error"
+"ts/no-non-null-asserted-optional-chain" = "error"
+"ts/no-require-imports" = "error"
+"ts/no-this-alias" = "error"
+"ts/no-unnecessary-type-constraint" = "error"
+"ts/no-unsafe-declaration-merging" = "error"
+"ts/no-unsafe-function-type" = "error"
+"ts/no-unused-expressions" = "error"
+"ts/no-unused-vars" = "error"
+"ts/no-wrapper-object-types" = "error"
+"ts/prefer-as-const" = "error"
+"ts/prefer-namespace-keyword" = "error"
+"ts/triple-slash-reference" = "error"

package/rules/ts/ban-ts-comment.md

@@ -0,0 +1,64 @@
+---
+id: ts/ban-ts-comment
+title: "No @ts-ignore or @ts-nocheck; @ts-expect-error says why"
+languages: [typescript, tsx]
+fix: manual
+fix_reason: "the reason the error is expected has to come from the author"
+stability: preview
+ported_from: [typescript-eslint/ban-ts-comment]
+since: 0.1.0
+---
+
+Type-checking is never switched off with `@ts-ignore` or `@ts-nocheck`, and a `@ts-expect-error`
+says why the error is expected.
+
+**Why:** `@ts-ignore` hides an error for good, even after the code it excused changes; `@ts-expect-
+error` fails as soon as the error is gone.
+
+```codelaw
+match:
+  kind: comment
+  any:
+    - regex: ^(//|/\*)\s*@ts-(ignore|nocheck)\b
+    - regex: ^(//|/\*)\s*@ts-expect-error\s*(\*/)?$
+message: "Don't silence the compiler with `@ts-ignore` or `@ts-nocheck`; use `@ts-expect-error: <why>`"
+```
+
+## How to fix
+
+1. Fix the type error if you can.
+2. Otherwise replace the comment with `// @ts-expect-error: <why>`.
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+// @ts-ignore
+const n: number = "1";
+```
+
+#### Do
+
+```ts
+// @ts-expect-error: the fixture checks the compiler's message
+const n: number = "1";
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+// @ts-ignore
+const n: number = "1";
+```
+
+#### Do
+
+```tsx
+// @ts-expect-error: the fixture checks the compiler's message
+const n: number = "1";
+```

package/rules/ts/no-array-constructor.md

@@ -0,0 +1,58 @@
+---
+id: ts/no-array-constructor
+title: "No Array constructor with several arguments"
+languages: [typescript, tsx]
+fix: auto
+stability: preview
+ported_from: [typescript-eslint/no-array-constructor, eslint/no-array-constructor]
+since: 0.1.0
+---
+
+Arrays are built with literals; `new Array(n)` with one argument (a length) is allowed.
+
+**Why:** `new Array(a, b)` and `new Array(n)` mean different things, and the literal says what it
+means.
+
+```codelaw
+match:
+  any:
+    - pattern: new Array($$$ARGS)
+    - pattern: Array($$$ARGS)
+  not:
+    any:
+      - pattern: new Array($ONE)
+      - pattern: Array($ONE)
+      - has: { field: type_arguments, pattern: $T }
+message: "Use an array literal instead of the Array constructor"
+fix: "[$$$ARGS]"
+```
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+const xs = new Array(1, 2, 3);
+```
+
+#### Do
+
+```ts
+const xs = [1, 2, 3];
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+const xs = new Array(1, 2, 3);
+```
+
+#### Do
+
+```tsx
+const xs = [1, 2, 3];
+```

package/rules/ts/no-duplicate-enum-values.md

@@ -0,0 +1,65 @@
+---
+id: ts/no-duplicate-enum-values
+title: "No two enum members share a value"
+languages: [typescript, tsx]
+fix: manual
+fix_reason: "which value is right needs the author"
+stability: preview
+ported_from: [typescript-eslint/no-duplicate-enum-values]
+since: 0.1.0
+---
+
+Each member of an enum given a literal value has a different value.
+
+**Why:** Two members with one value are indistinguishable at run time, which is usually a copy-paste
+slip.
+
+```codelaw
+native: ts/no-duplicate-enum-values
+```
+
+## How to fix
+
+1. Give each member its own value.
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+enum Color {
+  Red = 1,
+  Green = 1,
+}
+```
+
+#### Do
+
+```ts
+enum Color {
+  Red = 1,
+  Green = 2,
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+enum Color {
+  Red = 1,
+  Green = 1,
+}
+```
+
+#### Do
+
+```tsx
+enum Color {
+  Red = 1,
+  Green = 2,
+}
+```

package/rules/ts/no-empty-object-type.md

@@ -0,0 +1,65 @@
+---
+id: ts/no-empty-object-type
+title: "No empty interfaces or {} types"
+languages: [typescript, tsx]
+fix: manual
+fix_reason: "the right replacement — `object`, `unknown` or `Record<string, never>` — depends on intent"
+stability: preview
+ported_from: [typescript-eslint/no-empty-object-type]
+since: 0.1.0
+---
+
+Code doesn't declare an empty interface or use the type `{}`.
+
+**Why:** `{}` accepts every value except `null` and `undefined`, which is almost never what an
+empty-looking type was meant to say.
+
+```codelaw
+match:
+  any:
+    - kind: interface_declaration
+      has: { field: body, regex: '^\{\s*\}$' }
+    - kind: object_type
+      regex: '^\{\s*\}$'
+message: "`{}` means any non-null value, not an empty object; say what you mean"
+```
+
+## How to fix
+
+1. For any object, use `object`.
+2. For any value, use `unknown`.
+3. For an object with no keys, use `Record<string, never>`.
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+interface Options {}
+type Empty = {};
+```
+
+#### Do
+
+```ts
+type Options = Record<string, never>;
+type Anything = unknown;
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+interface Options {}
+type Empty = {};
+```
+
+#### Do
+
+```tsx
+type Options = Record<string, never>;
+type Anything = unknown;
+```

package/rules/ts/no-explicit-any.md

@@ -0,0 +1,61 @@
+---
+id: ts/no-explicit-any
+title: "No explicit any"
+languages: [typescript, tsx]
+fix: suggest
+fix_reason: "`unknown` may need narrowing code where the value is used"
+stability: preview
+ported_from: [typescript-eslint/no-explicit-any]
+since: 0.1.0
+---
+
+Types are not written as `any`.
+
+**Why:** `any` silently disables checking for everything it touches; `unknown` keeps the checks and
+forces a narrowing.
+
+```codelaw
+match:
+  kind: predefined_type
+  regex: ^any$
+message: "`any` turns off type-checking here; use `unknown` and narrow it"
+fix: "unknown"
+```
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+function parse(input: any) {
+  return input;
+}
+```
+
+#### Do
+
+```ts
+function parse(input: unknown) {
+  return input;
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+function parse(input: any) {
+  return input;
+}
+```
+
+#### Do
+
+```tsx
+function parse(input: unknown) {
+  return input;
+}
+```

package/rules/ts/no-extra-non-null-assertion.md

@@ -0,0 +1,50 @@
+---
+id: ts/no-extra-non-null-assertion
+title: "No repeated non-null assertions"
+languages: [typescript, tsx]
+fix: auto
+stability: preview
+ported_from: [typescript-eslint/no-extra-non-null-assertion]
+since: 0.1.0
+---
+
+A non-null assertion `!` is not repeated.
+
+**Why:** `x!!` means the same as `x!`; the second `!` is a typo.
+
+```codelaw
+match:
+  pattern: $X!!
+message: "One `!` is enough"
+fix: "$X!"
+```
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+const n = value!!;
+```
+
+#### Do
+
+```ts
+const n = value!;
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+const n = value!!;
+```
+
+#### Do
+
+```tsx
+const n = value!;
+```

package/rules/ts/no-misused-new.md

@@ -0,0 +1,70 @@
+---
+id: ts/no-misused-new
+title: "No constructors declared in interfaces, and no `new` methods in classes"
+languages: [typescript, tsx]
+fix: manual
+fix_reason: "the intended constructor signature needs the author"
+stability: preview
+ported_from: [typescript-eslint/no-misused-new]
+since: 0.1.0
+---
+
+An interface doesn't declare a method named `constructor`, and a class doesn't declare a method
+named `new`.
+
+**Why:** Both look like constructors but are ordinary methods; constructors in types are written
+`new (): T`.
+
+```codelaw
+match:
+  any:
+    - kind: method_signature
+      has: { field: name, regex: ^constructor$ }
+      inside: { kind: interface_body, stopBy: neighbor }
+    - kind: method_definition
+      has: { field: name, regex: ^new$ }
+message: "This declares a constructor where TypeScript reads a plain method"
+```
+
+## How to fix
+
+1. In an interface, describe a constructor with `new (…): T`.
+2. In a class, use `constructor(…)`.
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+interface Point {
+  constructor(): void;
+}
+```
+
+#### Do
+
+```ts
+interface PointConstructor {
+  new (): object;
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+interface Point {
+  constructor(): void;
+}
+```
+
+#### Do
+
+```tsx
+interface PointConstructor {
+  new (): object;
+}
+```

package/rules/ts/no-namespace.md

@@ -0,0 +1,65 @@
+---
+id: ts/no-namespace
+title: "No TypeScript namespaces"
+languages: [typescript, tsx]
+fix: manual
+fix_reason: "moving a namespace's members into a module changes every import"
+stability: preview
+ported_from: [typescript-eslint/no-namespace]
+since: 0.1.0
+---
+
+Code is organised with ES modules, not `namespace` or `module` blocks; `declare module "x"` and
+`declare global` are allowed.
+
+**Why:** Namespaces predate ES modules and don't work with modern bundlers and tooling as well.
+
+```codelaw
+match:
+  any:
+    - kind: internal_module
+    - kind: module
+      has: { field: name, kind: identifier }
+  not:
+    inside: { kind: ambient_declaration, stopBy: end }
+message: "Use ES modules instead of a namespace"
+```
+
+## How to fix
+
+1. Move the namespace's members to a module of their own.
+2. Export them, and import them where the namespace was used.
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+namespace Geometry {
+  export const pi = 3.14;
+}
+```
+
+#### Do
+
+```ts
+export const pi = 3.14;
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+namespace Geometry {
+  export const pi = 3.14;
+}
+```
+
+#### Do
+
+```tsx
+export const pi = 3.14;
+```