@less-unsound/eslint-plugin 0.0.1

package/docs/rules/no-typeof-type.md

@@ -0,0 +1,23 @@
+# `no-typeof-type`
+
+Disallow `typeof` in type context.
+
+## Rule details
+
+TypeScript has bugs around `typeof` types. For example, sometimes you might get a red underline in the editor and spend half an hour debugging, just to find that "Reload TS server" makes an error go away.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+type Value = typeof foo;
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+type Value = string;
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-undefined-type.md

@@ -0,0 +1,30 @@
+# `no-undefined-type`
+
+Disallow the `undefined` type keyword in type positions.
+
+## Rule details
+
+It usually appears in `Foo | undefined` context.
+- `string | undefined` has `""` that sometimes will clash with `undefined` in `if ()` and boolean checks.
+- `number | undefined` will cause this with `0`.
+- `boolean | undefined`... well, you get the pattern.
+- `T | undefined` where `T` is generic is a bug, because `T` might be `undefined` on its own, and in that case code is almost guaranteed to work incorrectly.
+
+Use a proper `Option<T>` type. For example, `Option<T> = [T] | undefined`, or `{ $: 'Some', value: T } | { $: 'None' }`.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+type Value = undefined;
+type Value = string | undefined;
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+type Value = string;
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-unknown.md

@@ -0,0 +1,23 @@
+# `no-unknown`
+
+Disallow the `unknown` type.
+
+## Rule details
+
+All `unknown` must immediately go through some kind of schema parser, such as `zod`. If you have to store an `unknown` somewhere and had to write this type, this caught you on not using that kind of parser immediately.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+type Value = unknown;
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+type Value = string;
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-untagged-object-union.md

@@ -0,0 +1,25 @@
+# `no-untagged-object-union`
+
+Disallow unions of inline object types unless they share a literal tag field.
+
+## Rule details
+
+These will require an `in`-condition for narrowing to select either of the branches, and `in` typing is broken.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+type Value = { a: 1 } | { b: 2 };
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+type Value = 1 | 2;
+type Value = "a" | "b";
+type Value = { readonly kind: "a"; a: number } | { readonly kind: "b"; b: number };
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-utility-type.md

@@ -0,0 +1,35 @@
+# `no-utility-type`
+
+Disallow built-in TypeScript utility types.
+
+## Rule details
+
+These are conditional types in disguise.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+type Value = Omit<Foo, "bar">;
+```
+
+```ts
+type Value = Exclude<Foo, Bar>;
+```
+
+```ts
+type Value = Readonly<Foo>;
+```
+
+```ts
+type Value = ReturnType<() => Foo>;
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+type Value = Foo;
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-var.md

@@ -0,0 +1,27 @@
+# `no-var`
+
+Disallow `var` declarations unless mutability is required for performance.
+
+## Rule details
+
+They're hoisted up to the function or module scope. `for (var i = 0; i < n; ++i) a.push(() => i)` creates an array of functions referencing the same value of `i === n`.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+var value = 1;
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+const value = 1;
+```
+
+## Options
+
+This rule does not accept options.
+
+## When not to use it
+
+Disable this rule when an algorithm requires mutable declarations for performance.

package/docs/rules/no-void-operator.md

@@ -0,0 +1,27 @@
+# `no-void-operator`
+
+Disallow the runtime `void` operator.
+
+## Rule details
+
+What for?
+
+Examples of **incorrect** code for this rule:
+
+```ts
+void foo();
+```
+
+```ts
+const value = void foo();
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+foo();
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-while.md

@@ -0,0 +1,33 @@
+# `no-while`
+
+Disallow `while` loops and `do ... while` loops.
+
+## Rule details
+
+Every iteration must have at least an explicit "fuel" check. `while` _always_ eventually leads to infinite loops in production. Do you want the whole server or browser to hang on your code?
+
+Examples of **incorrect** code for this rule:
+
+```ts
+while (value < 1) {
+  value += 1;
+}
+```
+
+```ts
+do {
+  value += 1;
+} while (value < 1);
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+for (const value of values) {
+  console.log(value);
+}
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/require-boolean-prefix.md

@@ -0,0 +1,31 @@
+# `require-boolean-prefix`
+
+Require boolean variables and fields to start with an allowed boolean prefix.
+
+## Rule details
+
+Boolean variables and fields must start with `is`, `are`, `was`, `were`, `has`, `have`, `can`, `may`, `should`, `must`, `will`, `would`, `did`, `does`, `do`, `needs`, `need`, `requires`, `supports`, `allows`, `contains`, `includes`, `matches`, or `exists`.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+const ready: boolean = true;
+```
+
+```ts
+type Value = { ready: boolean };
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+const isReady: boolean = true;
+```
+
+```ts
+type Value = { hasItems: boolean };
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/require-disjoint-union.md

@@ -0,0 +1,58 @@
+# `require-disjoint-union`
+
+Require unions to stay literal-only or to use a shared literal tag field on each local object branch.
+
+## Rule details
+
+All unions must be disjoint or string literal unions.
+
+The tag field defaults to `$`.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+type A = { readonly $: "a"; a: number };
+type B = { readonly $: "a"; b: number };
+type Value = A | B;
+```
+
+```ts
+type A = string;
+type B = number;
+type Value = A | B;
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+type Value = 1 | 2;
+type Value = "a" | "b";
+```
+
+```ts
+type A = { readonly $: "a"; a: number };
+type B = { readonly $: "b"; b: number };
+type Value = A | B;
+```
+
+```ts
+interface A { readonly kind: "a"; a: number }
+interface B { readonly kind: "b"; b: number }
+type Value = A | B;
+```
+
+```ts
+type Value = { readonly $: "a"; a: number } | { readonly $: "b"; b: number };
+```
+
+## Options
+
+```json
+[
+  {
+    "tagName": "kind"
+  }
+]
+```
+
+Use `tagName` to change the shared literal tag field that disjoint object unions must use.

package/docs/rules/require-function-verb.md

@@ -0,0 +1,83 @@
+# `require-function-verb`
+
+Require camelCase function variable names to start with an allowed verb prefix.
+
+## Rule details
+
+Names of variables that store a function must start with a verb, that store an object, string, number - with a noun.
+Predicate functions must start with `check`.
+Use `to` instead of `convert`.
+Event handlers must start with `on*`.
+The allowlist includes short established prefixes such as `assign`, `collect`, `emit`, `conv`, `elab`, `eq`, `neq`, `expect`, `extend`, `guard`, `main`, and `with`.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+const value = () => 1;
+```
+
+```ts
+const convertValue = (value: string): number => Number(value);
+```
+
+```ts
+const isReady = () => true;
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+const getValue = () => 1;
+```
+
+```ts
+const collectItems = () => [];
+```
+
+```ts
+const assignNode = () => 1;
+```
+
+```ts
+const emitNode = (): string => "node";
+```
+
+```ts
+const main = () => 1;
+```
+
+```ts
+const guardNode = () => 1;
+```
+
+```ts
+const toNumber = (value: string): number => Number(value);
+```
+
+```ts
+const checkReady = () => true;
+```
+
+```ts
+const eq = () => true;
+```
+
+```ts
+const expectValue = (): void => undefined;
+```
+
+```ts
+const extendEnv = () => 1;
+```
+
+```ts
+const withStd = () => 1;
+```
+
+```ts
+const onClick = () => undefined;
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/require-identifier-case.md

@@ -0,0 +1,54 @@
+# `require-identifier-case`
+
+Require identifiers to use camelCase, PascalCase, `_camelCase`, or short `$` names.
+
+## Rule details
+
+All names must be in `camelCase`, except for React components and type-like values (for example, zod schema) that must be in `PascalCase`.
+
+This rule also allows identifiers that start with `_` and continue in `camelCase` (for unused variables), and identifiers that start with `$` and have up to 2 letters after it (for codegen name clash reasons).
+
+Examples of **incorrect** code for this rule:
+
+```ts
+const foo_bar = 1;
+```
+
+```ts
+type foo_type = { foo_bar: number };
+```
+
+```ts
+const $abc = 1;
+```
+
+```ts
+const _FooBar = 1;
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+const fooBar = 1;
+```
+
+```ts
+type FooBar = { fooBar: number };
+```
+
+```ts
+const _fooBar = 1;
+```
+
+```ts
+const $ = 0;
+```
+
+```ts
+const $x = 1;
+const $Ab = 2;
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/require-kebab-case-filename.md

@@ -0,0 +1,37 @@
+# `require-kebab-case-filename`
+
+Require filenames to be in kebab-case.
+
+## Rule details
+
+All filenames must be in kebab-case. It's Node's standard, meant to make the code safe to run on all operating systems (ahem, Windows that doesn't distinguish case in file names).
+
+Yes, even source code of TypeScript doesn't use kebab case. Yes, they've already made their repo impossible to `git clone` on Windows with these. Wait, doesn't MS use their own OS for development?
+
+Examples of **incorrect** code for this rule:
+
+```ts
+// filename: fooBar.ts
+const value = 1;
+```
+
+```ts
+// filename: foo_bar.ts
+const value = 1;
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+// filename: foo-bar.ts
+const value = 1;
+```
+
+```ts
+// filename: foo-bar.test.ts
+const value = 1;
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/require-named-union-branch.md

@@ -0,0 +1,35 @@
+# `require-named-union-branch`
+
+Require every object-shaped union branch to be defined through its own name.
+
+## Rule details
+
+Every branch of the union type must have its own name, i.e. `{ ... } | { ... }` is invalid, and there must be two `type Foo` for each of the branches.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+type Value = { readonly kind: "a"; readonly a: number } | { readonly kind: "b"; readonly b: number };
+```
+
+```ts
+type Value = Foo | { readonly kind: "b"; readonly b: number };
+type Foo = { readonly kind: "a"; readonly a: number };
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+type A = { readonly kind: "a"; readonly a: number };
+type B = { readonly kind: "b"; readonly b: number };
+type Value = A | B;
+```
+
+```ts
+type Value = 1 | 2;
+type Value = "a" | "b";
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/require-readonly-array.md

@@ -0,0 +1,35 @@
+# `require-readonly-array`
+
+Require array types to use `readonly T[]` unless mutability is required for performance.
+
+## Rule details
+
+Arrays should be readonly: `readonly string[]`
+
+Examples of **incorrect** code for this rule:
+
+```ts
+type Value = string[];
+```
+
+```ts
+type Value = Array<string>;
+```
+
+```ts
+type Value = ReadonlyArray<string>;
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+type Value = readonly string[];
+```
+
+## Options
+
+This rule does not accept options.
+
+## When not to use it
+
+Disable this rule when an algorithm requires mutable arrays for performance.

package/docs/rules/require-readonly-collections.md

@@ -0,0 +1,35 @@
+# `require-readonly-collections`
+
+Require `ReadonlySet` and `ReadonlyMap` in types unless mutability is required for performance.
+
+## Rule details
+
+`Set` and `Map` should be readonly: `env: ReadonlyMap<string, Type>`
+
+Examples of **incorrect** code for this rule:
+
+```ts
+type Value = Set<string>;
+```
+
+```ts
+type Value = Map<string, number>;
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+type Value = ReadonlySet<string>;
+```
+
+```ts
+type Value = ReadonlyMap<string, number>;
+```
+
+## Options
+
+This rule does not accept options.
+
+## When not to use it
+
+Disable this rule when an algorithm requires mutable collections for performance.

package/docs/rules/require-readonly-object-fields.md

@@ -0,0 +1,46 @@
+# `require-readonly-object-fields`
+
+Require `readonly` on all object type fields unless mutability is required for performance.
+
+## Rule details
+
+All object fields must be `readonly`: `{ readonly foo: string }`.
+
+By assigning into a tag field of an `A | B` union, we can narrow it to an `A` type while it will have `B` (or some arbitrary combination of `A` and `B`) at runtime.
+
+If data are not immutable, it's possible to create loopy data with assignment, and cause infinite loops/recursion trying to walk that data.
+
+```typescript
+type A = { value: number, foo: A | undefined }
+const a: A = { value: 1, foo: undefined };
+a.foo = a;
+// best luck walking or serializing it now
+```
+
+Examples of **incorrect** code for this rule:
+
+```ts
+type Value = { name: string };
+```
+
+```ts
+type Value = { kind: "a"; readonly name: string } | { readonly kind: "b"; readonly name: string };
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+type Value = { readonly name: string };
+```
+
+```ts
+type Value = { readonly kind: "a"; readonly name: string } | { readonly kind: "b"; readonly name: string };
+```
+
+## Options
+
+This rule does not accept options.
+
+## When not to use it
+
+Disable this rule when an algorithm requires mutable object fields, including tag fields, for performance.

package/docs/rules/require-readonly-tuple.md

@@ -0,0 +1,27 @@
+# `require-readonly-tuple`
+
+Require tuple types to use `readonly [...]` unless mutability is required for performance.
+
+## Rule details
+
+Tuples should be readonly: `readonly [string, number]`
+
+Examples of **incorrect** code for this rule:
+
+```ts
+type Value = [string, number];
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+type Value = readonly [string, number];
+```
+
+## Options
+
+This rule does not accept options.
+
+## When not to use it
+
+Disable this rule when an algorithm requires mutable tuples for performance.