@codelaw/rules-js 0.0.0-stage → 0.2.0

package/rules/js/exports-at-end.md

@@ -0,0 +1,134 @@
+---
+id: js/exports-at-end
+title: "Exports are gathered at the end of the file"
+languages: [javascript, jsx, typescript, tsx]
+fix: auto
+stability: preview
+invariant: exports-unchanged
+since: 0.1.0
+---
+
+Declarations are written without `export`, and the module's exports are listed in one `export { … }`
+(and `export type { … }`) block at the end of the file.
+
+**Why:** A reader or an agent sees the module's whole public API in one place.
+
+```codelaw
+match:
+  kind: export_statement
+  has: { field: declaration, pattern: $DECL }
+  not:
+    any:
+      - has: { regex: ^default$ }
+      - has: { field: declaration, kind: internal_module }
+      - has: { field: declaration, kind: ambient_declaration }
+      - has: { field: declaration, kind: module }
+message: "Export at the end of the file, in one `export { … }` block"
+fix:
+  - strip-export-keyword: $DECL
+  - collect-into-block:
+      target: $DECL
+      block: "export { $$$NAMES };"
+      type_block: "export type { $$$TYPE_NAMES };"
+      position: end-of-file
+```
+
+## Examples
+
+### JavaScript
+
+#### Don't
+
+```js
+export function add(a, b) {
+  return a + b;
+}
+export const zero = 0;
+```
+
+#### Do
+
+```js
+function add(a, b) {
+  return a + b;
+}
+const zero = 0;
+export { add, zero };
+```
+
+### JSX
+
+#### Don't
+
+```jsx
+export function add(a, b) {
+  return a + b;
+}
+export const zero = 0;
+```
+
+#### Do
+
+```jsx
+function add(a, b) {
+  return a + b;
+}
+const zero = 0;
+export { add, zero };
+```
+
+### TypeScript
+
+#### Don't
+
+```ts
+export function add(a: number, b: number) {
+  return a + b;
+}
+export interface Point {
+  x: number;
+}
+```
+
+#### Do
+
+```ts
+function add(a: number, b: number) {
+  return a + b;
+}
+interface Point {
+  x: number;
+}
+export { add };
+export type { Point };
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+export function add(a: number, b: number) {
+  return a + b;
+}
+export interface Point {
+  x: number;
+}
+```
+
+#### Do
+
+```tsx
+function add(a: number, b: number) {
+  return a + b;
+}
+interface Point {
+  x: number;
+}
+export { add };
+export type { Point };
+```
+
+## Differences from the source
+
+`export default`, namespaces and `declare` blocks are left alone.

package/rules/js/for-direction.md

@@ -0,0 +1,106 @@
+---
+id: js/for-direction
+title: "A for loop's counter moves toward its end condition"
+languages: [javascript, jsx, typescript, tsx]
+fix: manual
+fix_reason: "whether the condition or the update is wrong needs the author"
+stability: preview
+ported_from: [eslint/for-direction]
+since: 0.1.0
+---
+
+A `for` loop whose condition tests `i < n` counts up, and one that tests `i > n` counts down.
+
+**Why:** A counter that moves the wrong way never meets its end condition, so the loop never ends.
+
+```codelaw
+match:
+  kind: for_statement
+  any:
+    - all:
+        - has: { field: condition, any: [{ pattern: $I < $END }, { pattern: $I <= $END }] }
+        - has: { field: increment, any: [{ pattern: $I-- }, { pattern: --$I }] }
+    - all:
+        - has: { field: condition, any: [{ pattern: $I > $END }, { pattern: $I >= $END }] }
+        - has: { field: increment, any: [{ pattern: $I++ }, { pattern: ++$I }] }
+message: "The counter `$I` moves away from the condition that ends this loop"
+```
+
+## How to fix
+
+1. Decide which way the loop should count.
+2. Fix the update (`i++` or `i--`) or the comparison to match.
+
+## Examples
+
+### JavaScript
+
+#### Don't
+
+```js
+for (let i = 0; i < 10; i--) {
+  draw(i);
+}
+```
+
+#### Do
+
+```js
+for (let i = 0; i < 10; i++) {
+  draw(i);
+}
+```
+
+### JSX
+
+#### Don't
+
+```jsx
+for (let i = 0; i < 10; i--) {
+  draw(i);
+}
+```
+
+#### Do
+
+```jsx
+for (let i = 0; i < 10; i++) {
+  draw(i);
+}
+```
+
+### TypeScript
+
+#### Don't
+
+```ts
+for (let i = 0; i < 10; i--) {
+  draw(i);
+}
+```
+
+#### Do
+
+```ts
+for (let i = 0; i < 10; i++) {
+  draw(i);
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+for (let i = 0; i < 10; i--) {
+  draw(i);
+}
+```
+
+#### Do
+
+```tsx
+for (let i = 0; i < 10; i++) {
+  draw(i);
+}
+```

package/rules/js/getter-return.md

@@ -0,0 +1,74 @@
+---
+id: js/getter-return
+title: "A getter returns a value on every path"
+languages: [javascript, jsx]
+fix: manual
+fix_reason: "the value a getter should return is the author's decision"
+stability: preview
+ported_from: [eslint/getter-return]
+since: 0.1.0
+---
+
+Every path through a getter ends in `return <value>` or a `throw`.
+
+**Why:** A getter that falls off its end returns `undefined`, which is almost always a forgotten
+`return`.
+
+```codelaw
+native: js/getter-return
+```
+
+## How to fix
+
+1. Find the path that ends without a `return`.
+2. Return the value the property should have there, or throw.
+
+## Examples
+
+### JavaScript
+
+#### Don't
+
+```js
+const box = {
+  get size() {
+    if (this.items) {
+      return this.items.length;
+    }
+  },
+};
+```
+
+#### Do
+
+```js
+const box = {
+  get size() {
+    return this.items ? this.items.length : 0;
+  },
+};
+```
+
+### JSX
+
+#### Don't
+
+```jsx
+const box = {
+  get size() {
+    if (this.items) {
+      return this.items.length;
+    }
+  },
+};
+```
+
+#### Do
+
+```jsx
+const box = {
+  get size() {
+    return this.items ? this.items.length : 0;
+  },
+};
+```

package/rules/js/import-groups.md

@@ -0,0 +1,117 @@
+---
+id: js/import-groups
+title: "Imports are grouped builtin, external, internal, relative"
+languages: [javascript, jsx, typescript, tsx]
+fix: auto
+stability: preview
+options:
+  internal: { type: "string[]", default: ["@/", "~/"], description: "prefixes of internal imports" }
+since: 0.1.0
+---
+
+The file's leading imports come in four groups, in order — Node.js built-ins, packages, internal
+aliases (the `internal` option, `@/` and `~/` by default), relative paths — with a blank line
+between groups.
+
+**Why:** Grouped imports show at a glance what a module depends on, and keep diffs of the import
+block small.
+
+```codelaw
+native: js/import-groups
+```
+
+## Examples
+
+### JavaScript
+
+#### Don't
+
+```js
+import { helper } from "./helper";
+import fs from "node:fs";
+import React from "react";
+helper(fs, React);
+```
+
+#### Do
+
+```js
+import fs from "node:fs";
+
+import React from "react";
+
+import { helper } from "./helper";
+helper(fs, React);
+```
+
+### JSX
+
+#### Don't
+
+```jsx
+import { helper } from "./helper";
+import fs from "node:fs";
+import React from "react";
+helper(fs, React);
+```
+
+#### Do
+
+```jsx
+import fs from "node:fs";
+
+import React from "react";
+
+import { helper } from "./helper";
+helper(fs, React);
+```
+
+### TypeScript
+
+#### Don't
+
+```ts
+import { helper } from "./helper";
+import fs from "node:fs";
+import React from "react";
+helper(fs, React);
+```
+
+#### Do
+
+```ts
+import fs from "node:fs";
+
+import React from "react";
+
+import { helper } from "./helper";
+helper(fs, React);
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+import { helper } from "./helper";
+import fs from "node:fs";
+import React from "react";
+helper(fs, React);
+```
+
+#### Do
+
+```tsx
+import fs from "node:fs";
+
+import React from "react";
+
+import { helper } from "./helper";
+helper(fs, React);
+```
+
+## Differences from the source
+
+A block of imports with a comment inside is left alone, so no comment is moved away from the import
+it describes. A side-effect import (`import './polyfills'`, a stylesheet) stays where it is, since moving it
+changes what runs first; only the imports between two of them are ordered.

package/rules/js/no-async-promise-executor.md

@@ -0,0 +1,95 @@
+---
+id: js/no-async-promise-executor
+title: "A Promise executor is not an async function"
+languages: [javascript, jsx, typescript, tsx]
+fix: manual
+fix_reason: "the rewrite depends on what the executor does"
+stability: preview
+ported_from: [eslint/no-async-promise-executor]
+since: 0.1.0
+---
+
+The function passed to `new Promise(...)` is not `async`.
+
+**Why:** An error thrown in an async executor doesn't reject the promise, and an executor that needs
+`await` doesn't need the `Promise` wrapper.
+
+```codelaw
+match:
+  any:
+    - pattern: new Promise(async ($$$P) => $$$B)
+    - pattern: new Promise(async function ($$$P) { $$$B })
+    - pattern: new Promise(async $P => $$$B)
+message: "An async Promise executor loses its errors; await inside a plain async function instead"
+```
+
+## How to fix
+
+1. If the executor only awaits and resolves, use the awaited promise directly.
+2. Otherwise make the executor a plain function and handle errors with `reject`.
+
+## Examples
+
+### JavaScript
+
+#### Don't
+
+```js
+const data = new Promise(async (resolve) => {
+  resolve(await load());
+});
+```
+
+#### Do
+
+```js
+const data = load();
+```
+
+### JSX
+
+#### Don't
+
+```jsx
+const data = new Promise(async (resolve) => {
+  resolve(await load());
+});
+```
+
+#### Do
+
+```jsx
+const data = load();
+```
+
+### TypeScript
+
+#### Don't
+
+```ts
+const data = new Promise(async (resolve) => {
+  resolve(await load());
+});
+```
+
+#### Do
+
+```ts
+const data = load();
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+const data = new Promise(async (resolve) => {
+  resolve(await load());
+});
+```
+
+#### Do
+
+```tsx
+const data = load();
+```

package/rules/js/no-case-declarations.md

@@ -0,0 +1,134 @@
+---
+id: js/no-case-declarations
+title: "No let, const, function or class directly in a case"
+languages: [javascript, jsx, typescript, tsx]
+fix: manual
+fix_reason: "another case may rely on the shared declaration"
+stability: preview
+ported_from: [eslint/no-case-declarations]
+since: 0.1.0
+---
+
+A `let`, `const`, `function` or `class` inside a `case` sits in a block `{ … }` of its own.
+
+**Why:** Declarations in a case are scoped to the whole `switch`, so another case can see them
+uninitialised.
+
+```codelaw
+match:
+  any:
+    - kind: lexical_declaration
+    - kind: class_declaration
+    - kind: function_declaration
+  inside:
+    stopBy: neighbor
+    any: [{ kind: switch_case }, { kind: switch_default }]
+message: "A declaration in a case is visible to the whole switch; wrap the case in braces"
+```
+
+## How to fix
+
+1. Wrap the case's statements in `{ … }`.
+2. If another case uses the declaration, move it above the `switch`.
+
+## Examples
+
+### JavaScript
+
+#### Don't
+
+```js
+switch (kind) {
+  case "a":
+    const n = 1;
+    use(n);
+    break;
+}
+```
+
+#### Do
+
+```js
+switch (kind) {
+  case "a": {
+    const n = 1;
+    use(n);
+    break;
+  }
+}
+```
+
+### JSX
+
+#### Don't
+
+```jsx
+switch (kind) {
+  case "a":
+    const n = 1;
+    use(n);
+    break;
+}
+```
+
+#### Do
+
+```jsx
+switch (kind) {
+  case "a": {
+    const n = 1;
+    use(n);
+    break;
+  }
+}
+```
+
+### TypeScript
+
+#### Don't
+
+```ts
+switch (kind) {
+  case "a":
+    const n = 1;
+    use(n);
+    break;
+}
+```
+
+#### Do
+
+```ts
+switch (kind) {
+  case "a": {
+    const n = 1;
+    use(n);
+    break;
+  }
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+switch (kind) {
+  case "a":
+    const n = 1;
+    use(n);
+    break;
+}
+```
+
+#### Do
+
+```tsx
+switch (kind) {
+  case "a": {
+    const n = 1;
+    use(n);
+    break;
+  }
+}
+```

package/rules/js/no-class-assign.md

@@ -0,0 +1,61 @@
+---
+id: js/no-class-assign
+title: "A class name is not reassigned"
+languages: [javascript, jsx]
+fix: manual
+fix_reason: "what the assignment was for is the author's call"
+stability: preview
+ported_from: [eslint/no-class-assign]
+since: 0.1.0
+---
+
+Code doesn't assign a new value to the name a class declaration binds.
+
+**Why:** Reassigning a class name is almost always a mistake, and makes every later use mean
+something else.
+
+```codelaw
+match:
+  kind: identifier
+where:
+  $$MATCH: [write, { binding: class }]
+message: "`$$MATCH` is a class; don't assign to it"
+```
+
+## How to fix
+
+1. Assign to a new variable instead of the class name.
+
+## Examples
+
+### JavaScript
+
+#### Don't
+
+```js
+class Point {}
+Point = null;
+```
+
+#### Do
+
+```js
+class Point {}
+const origin = null;
+```
+
+### JSX
+
+#### Don't
+
+```jsx
+class Point {}
+Point = null;
+```
+
+#### Do
+
+```jsx
+class Point {}
+const origin = null;
+```