@less-unsound/eslint-plugin 0.0.1

package/docs/rules/no-object-as-map.md

@@ -0,0 +1,49 @@
+# `no-object-as-map`
+
+Disallow using plain objects as dynamic maps.
+
+## Rule details
+
+Objects have a set of quirks: numeric keys get listed before string keys, key order is not guaranteed, keys can be inherited from `Object.prototype`, and the `__proto__` key can be used for prototype pollution exploits. Unless a high performance of hashmap is needed, or an object is statically defined, use `Map`.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+const map = {};
+const value = map[key];
+```
+
+```ts
+const map = {};
+map[key] = value;
+```
+
+```ts
+const map = Object.create(null);
+const value = map[key];
+```
+
+```ts
+({})[key];
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+const map = {};
+const value = map.foo;
+```
+
+```ts
+const map = {};
+const value = map["foo"];
+```
+
+```ts
+const map = new Map<string, number>();
+const value = map.get(key);
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-object-spread.md

@@ -0,0 +1,31 @@
+# `no-object-spread`
+
+Disallow object spread in object literals.
+
+## Rule details
+
+It will require intersection types or inheritance to type. Prefer aggregation: `{ ...a, b }` → `{ a, b }`.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+const value = { ...values };
+```
+
+```ts
+const value = { a: 1, ...values, b: 2 };
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+const value = [...values];
+```
+
+```ts
+const value = { a: 1, b: 2 };
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-object-stringification-hook.md

@@ -0,0 +1,49 @@
+# `no-object-stringification-hook`
+
+Disallow runtime `.toString` and `.toJSON`, and defining `toString` and `toJSON` hooks on objects and classes.
+
+## Rule details
+
+These obfuscate results of `console.log`, making objects different depending on how they're logged (`util.inspect` wouldn't use them). Worse, they might cause `JSON.stringify` to return unexpected results, and it will be very hard to trace to the source.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+const value = { toString: () => "x" };
+```
+
+```ts
+class Value {
+  toJSON() {
+    return "x";
+  }
+}
+```
+
+```ts
+value["toString"] = () => "x";
+```
+
+```ts
+value.toString();
+```
+
+```ts
+const stringify = value.toString;
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+interface Value {
+  toString(): string;
+}
+```
+
+```ts
+const value = { name: "x" };
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-optional-parameter.md

@@ -0,0 +1,39 @@
+# `no-optional-parameter`
+
+Disallow optional parameters marked with `?` in functions and constructor parameter properties.
+
+## Rule details
+
+TypeScript has a quirk that allows passing the function with fewer arguments to a parameter list that requires more. Eventually, this leads to passing unexpected values to optional parameters. Prefer decomposing the function into two, where one takes a full set of parameters, and the other one is a simpler version that takes less.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+function value(value?: number) {
+  return value;
+}
+```
+
+```ts
+class Value {
+  constructor(private value?: number) {}
+}
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+function value(value: number) {
+  return value;
+}
+```
+
+```ts
+class Value {
+  constructor(private value: number) {}
+}
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-optional-property.md

@@ -0,0 +1,33 @@
+# `no-optional-property`
+
+Disallow optional object fields marked with `?`.
+
+## Rule details
+
+Every `?` doubles the number of cases that should be tested. Eventually, some combination of non-defined and undefined fields will be non-semantic. Prefer at least an explicit `foo: Bar | undefined`, or better, create a type with a descriptive name to make it a tagged union.
+
+In JS, there is a distinction between a field that is not defined and a field that is `undefined` (sic). `'a' in {} === false`, `'a' in { a: undefined } === true`. TypeScript doesn't handle this properly in its type system.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+type Value = { name?: string };
+```
+
+```ts
+interface Value { name?: string; }
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+type Value = { name: string };
+```
+
+```ts
+interface Value { name: string; }
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-overload.md

@@ -0,0 +1,29 @@
+# `no-overload`
+
+Disallow function and method overloads.
+
+## Rule details
+
+It's almost the same as intersection types, which are broken.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+function f(x: string): string;
+function f(x: number): number;
+function f(x: string | number) {
+  return x;
+}
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+function f(x: string | number) {
+  return x;
+}
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-param-assign.md

@@ -0,0 +1,30 @@
+# `no-param-assign`
+
+Disallow assigning to function parameters unless mutability is required for performance.
+
+## Rule details
+
+This is essentially a `let`, except it's ever present and hidden.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+const setValue = (value: number): number => {
+  value = value + 1;
+  return value;
+};
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+const setValue = (value: number): number => value + 1;
+```
+
+## Options
+
+This rule does not accept options.
+
+## When not to use it
+
+Disable this rule when an algorithm requires parameter mutation for performance.

package/docs/rules/no-prototype-access.md

@@ -0,0 +1,43 @@
+# `no-prototype-access`
+
+Disallow runtime access to `prototype` and `__proto__`.
+
+## Rule details
+
+Don't use a legacy form of OOP. It's even worse than just using OOP.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+const value = foo.prototype;
+```
+
+```ts
+const value = foo["__proto__"];
+```
+
+```ts
+const value = { prototype: 1 };
+```
+
+```ts
+class Value { __proto__() {} }
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+const prototype = createPrototype();
+```
+
+```ts
+type Value = { prototype: string };
+```
+
+```ts
+const value = foo[prototype];
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-proxy-reflect.md

@@ -0,0 +1,39 @@
+# `no-proxy-reflect`
+
+Disallow the `Proxy` and `Reflect` global objects.
+
+## Rule details
+
+These break the type safety, are incorrectly handled in debuggers, and lead to unexpected heisenbugs.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+const value = Proxy;
+```
+
+```ts
+const value = Reflect.apply(fn, thisArg, args);
+```
+
+```ts
+const value = new Proxy(target, handler);
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+const Proxy = createProxy();
+```
+
+```ts
+const Reflect = createReflect();
+```
+
+```ts
+const value = foo.Proxy;
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-reexport-outside-entrypoint.md

@@ -0,0 +1,35 @@
+# `no-reexport-outside-entrypoint`
+
+Disallow reexports outside files explicitly mentioned in `package.json` as entrypoints.
+
+## Rule details
+
+Do not use `index.ts` files to reexport, unless it's a root `index.ts` file of some library. IDEs still don't have proper support for this, and it just adds one more file to edit on every rename.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+export * from "./foo";
+```
+
+```ts
+export { foo } from "./foo";
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+export * from "./foo";
+```
+
+This is only correct when the file is explicitly mentioned in `package.json` as an entrypoint.
+
+```ts
+const foo = 1;
+
+export { foo };
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-regular-expression.md

@@ -0,0 +1,36 @@
+# `no-regular-expression`
+
+Disallow regular-expression literals and global `RegExp()` constructor usage.
+
+## Rule details
+
+The only available engine is worst-case exponential, is different between user-agents and their versions. Regexps are extremely brittle.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+const value = /x/;
+```
+
+```ts
+RegExp("x");
+```
+
+```ts
+new RegExp("x");
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+const RegExp = (value: string): string => value;
+RegExp("x");
+```
+
+```ts
+const value = "x";
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-require.md

@@ -0,0 +1,29 @@
+# `no-require`
+
+Disallow `require()` and Node `createRequire()`.
+
+## Rule details
+
+Use `import`. It's (current year) now.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+require("node:fs");
+```
+
+```ts
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+import { readFile } from "node:fs/promises";
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-rest-parameter.md

@@ -0,0 +1,23 @@
+# `no-rest-parameter`
+
+Disallow rest parameters.
+
+## Rule details
+
+TypeScript doesn't have "mapped tuple types", so typing these will be problematic. In most cases, passing an array would suffice and would only take two more characters to type.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+const join = (...values: string[]): string => values.join(",");
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+const join = (values: readonly string[]): string => values.join(",");
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-switch.md

@@ -0,0 +1,32 @@
+# `no-switch`
+
+Disallow `switch` statements.
+
+## Rule details
+
+Switch statements require extra considerations for unexpected passthrough, are bulky, and take an extra function to make exhaustive checks work.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+switch (value) {
+  case "a":
+    return 1;
+  default:
+    return 2;
+}
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+if (value === "a") {
+  return 1;
+}
+
+return 2;
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-symbol.md

@@ -0,0 +1,31 @@
+# `no-symbol`
+
+Disallow `symbol` and `unique symbol` types.
+
+## Rule details
+
+These are very good for opaque/branded types, but have to be sandboxed in their own files and `eslint-ignore`d. The rule is here to ensure the rest of the code doesn't use them, and doesn't break opaque/branded type guarantees.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+type Value = symbol;
+```
+
+```ts
+declare const key: unique symbol;
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+type Value = string;
+```
+
+```ts
+declare const key: string;
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-try-catch.md

@@ -0,0 +1,37 @@
+# `no-try-catch`
+
+Disallow `try ... catch`.
+
+## Rule details
+
+`catch` is untyped: you get an `unknown`. Worse, most of the uses accidentally try to handle exceptions that they mustn't.
+
+Every custom FooError must have its own `handleFooError()` exported next to it, that takes 2 functions corresponding to two `{}` of `try...catch`. The two functions must be `() => T` and `(error: FooError) => U`, and the result must be `T | U`. It handles errors of that type, and passes the rest through.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+try {
+  return readFoo();
+} catch (error) {
+  if (error instanceof FooError) {
+    return recoverFoo(error);
+  }
+  throw error;
+}
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+export const handleFooError = createErrorHandler(FooError);
+
+const value = handleFooError(
+  () => readFoo(),
+  error => recoverFoo(error),
+);
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-ts-comment-directive.md

@@ -0,0 +1,25 @@
+# `no-ts-comment-directive`
+
+Disallow TypeScript comment directives.
+
+## Rule details
+
+It's a worse version of `as` that can cause the TS compiler to enter an arbitrary incorrect state.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+// @ts-ignore
+const value = foo;
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+// regular comment
+const value = foo;
+```
+
+## Options
+
+This rule does not accept options.

package/docs/rules/no-tuple.md

@@ -0,0 +1,29 @@
+# `no-tuple`
+
+Disallow tuple types.
+
+## Rule details
+
+Tuples are supposed to be used in a very generic code where individual elements of tuples bear no meaning at all. For the rest of the code, use objects.
+
+TS gives them minimal distinction from arrays, and the type system is broken around them. Occasionally, for performance reasons, tuples might be a better option than objects.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+type Pair = [string, number];
+```
+
+```ts
+type Pair = readonly [string, number];
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+type Pair = { left: string; right: number };
+```
+
+## Options
+
+This rule does not accept options.

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

@@ -0,0 +1,23 @@
+# `no-type-guard`
+
+Disallow TypeScript type guards.
+
+## Rule details
+
+These are just `as` in disguise: `const foo = (x: 1 | 2): x is 1 => x === 2;`. It might be used in straightforward cases, such as ADT boilerplate.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+const isFoo = (value: string): value is Foo => true;
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+const isFoo = (value: string): boolean => value.length > 0;
+```
+
+## Options
+
+This rule does not accept options.

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

@@ -0,0 +1,23 @@
+# `no-typeof-operator`
+
+Disallow the runtime `typeof` operator.
+
+## Rule details
+
+`<T>(x: T) => typeof x === 'number'`. Properly designed languages do not allow this.
+
+Examples of **incorrect** code for this rule:
+
+```ts
+const kind = typeof foo;
+```
+
+Examples of **correct** code for this rule:
+
+```ts
+const value = foo;
+```
+
+## Options
+
+This rule does not accept options.