@codelaw/rules-js 0.0.0-stage → 0.1.0

package/rules/js/prefer-rest-params.md

@@ -0,0 +1,103 @@
+---
+id: js/prefer-rest-params
+title: "Rest parameters instead of arguments"
+languages: [javascript, jsx, typescript, tsx]
+fix: manual
+fix_reason: "the parameter list has to be rewritten by hand"
+stability: preview
+ported_from: [eslint/prefer-rest-params]
+since: 0.1.0
+---
+
+Functions take a rest parameter `...args` instead of reading `arguments`.
+
+**Why:** `arguments` is not a real array, isn't available in arrow functions, and hides how many
+arguments a function takes.
+
+```codelaw
+match:
+  kind: identifier
+  regex: ^arguments$
+where:
+  $$MATCH: builtin
+message: "Use a rest parameter (`...args`) instead of `arguments`"
+```
+
+## How to fix
+
+1. Add a rest parameter `...args` to the function.
+2. Replace each use of `arguments` with it.
+
+## Examples
+
+### JavaScript
+
+#### Don't
+
+```js
+function sum() {
+  return Array.from(arguments).reduce(add, 0);
+}
+```
+
+#### Do
+
+```js
+function sum(...numbers) {
+  return numbers.reduce(add, 0);
+}
+```
+
+### JSX
+
+#### Don't
+
+```jsx
+function sum() {
+  return Array.from(arguments).reduce(add, 0);
+}
+```
+
+#### Do
+
+```jsx
+function sum(...numbers) {
+  return numbers.reduce(add, 0);
+}
+```
+
+### TypeScript
+
+#### Don't
+
+```ts
+function sum() {
+  return Array.from(arguments).reduce(add, 0);
+}
+```
+
+#### Do
+
+```ts
+function sum(...numbers) {
+  return numbers.reduce(add, 0);
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+function sum() {
+  return Array.from(arguments).reduce(add, 0);
+}
+```
+
+#### Do
+
+```tsx
+function sum(...numbers) {
+  return numbers.reduce(add, 0);
+}
+```

package/rules/js/prefer-spread.md

@@ -0,0 +1,95 @@
+---
+id: js/prefer-spread
+title: "Spread instead of .apply()"
+languages: [javascript, jsx, typescript, tsx]
+fix: auto
+stability: preview
+ported_from: [eslint/prefer-spread]
+since: 0.1.0
+---
+
+A function is called with spread arguments, `f(...args)`, instead of `f.apply(null, args)`.
+
+**Why:** Spread says the same thing more directly, and doesn't need a `this` value.
+
+```codelaw
+match:
+  any:
+    - pattern: $F.apply(null, $ARGS)
+    - pattern: $F.apply(undefined, $ARGS)
+constraints:
+  F: { kind: identifier }
+message: "Use spread: `$F(...$ARGS)`"
+fix: "$F(...$ARGS)"
+```
+
+## Examples
+
+### JavaScript
+
+#### Don't
+
+```js
+const max = Math.max.apply(null, values);
+const min = least.apply(null, values);
+```
+
+#### Do
+
+```js
+const max = Math.max.apply(null, values);
+const min = least(...values);
+```
+
+### JSX
+
+#### Don't
+
+```jsx
+const max = Math.max.apply(null, values);
+const min = least.apply(null, values);
+```
+
+#### Do
+
+```jsx
+const max = Math.max.apply(null, values);
+const min = least(...values);
+```
+
+### TypeScript
+
+#### Don't
+
+```ts
+const max = Math.max.apply(null, values);
+const min = least.apply(null, values);
+```
+
+#### Do
+
+```ts
+const max = Math.max.apply(null, values);
+const min = least(...values);
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+const max = Math.max.apply(null, values);
+const min = least.apply(null, values);
+```
+
+#### Do
+
+```tsx
+const max = Math.max.apply(null, values);
+const min = least(...values);
+```
+
+## Differences from the source
+
+Only `f.apply(null, args)` and `f.apply(undefined, args)` on a plain function name are checked;
+method calls are left alone.

package/rules/js/preserve-caught-error.md

@@ -0,0 +1,122 @@
+---
+id: js/preserve-caught-error
+title: "A rethrown error keeps the caught one as its cause"
+languages: [javascript, jsx, typescript, tsx]
+fix: suggest
+fix_reason: "the new error class must accept an options argument"
+stability: preview
+ported_from: [eslint/preserve-caught-error]
+since: 0.1.0
+---
+
+A built-in error (`Error`, `TypeError` and the rest) thrown from a `catch` block passes the caught
+error as `{ cause }`.
+
+**Why:** Without the cause, the original error and its stack are lost.
+
+```codelaw
+match:
+  pattern: throw new $C($MSG);
+  inside:
+    kind: catch_clause
+    has: { field: parameter, pattern: $E }
+    stopBy:
+      any: [{kind: function_declaration}, {kind: function_expression}, {kind: arrow_function}, {kind: method_definition}, {kind: generator_function_declaration}, {kind: generator_function}]
+constraints:
+  C: { regex: ^(Error|TypeError|RangeError|ReferenceError|SyntaxError|URIError|EvalError)$ }
+  MSG: { not: { kind: object } }
+where:
+  $C: builtin
+message: "Pass the caught error as the cause: `new $C($MSG, { cause: $E })`"
+fix: "throw new $C($MSG, { cause: $E });"
+```
+
+## Examples
+
+### JavaScript
+
+#### Don't
+
+```js
+try {
+  load();
+} catch (err) {
+  throw new Error("Load failed");
+}
+```
+
+#### Do
+
+```js
+try {
+  load();
+} catch (err) {
+  throw new Error("Load failed", { cause: err });
+}
+```
+
+### JSX
+
+#### Don't
+
+```jsx
+try {
+  load();
+} catch (err) {
+  throw new Error("Load failed");
+}
+```
+
+#### Do
+
+```jsx
+try {
+  load();
+} catch (err) {
+  throw new Error("Load failed", { cause: err });
+}
+```
+
+### TypeScript
+
+#### Don't
+
+```ts
+try {
+  load();
+} catch (err) {
+  throw new Error("Load failed");
+}
+```
+
+#### Do
+
+```ts
+try {
+  load();
+} catch (err) {
+  throw new Error("Load failed", { cause: err });
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+try {
+  load();
+} catch (err) {
+  throw new Error("Load failed");
+}
+```
+
+#### Do
+
+```tsx
+try {
+  load();
+} catch (err) {
+  throw new Error("Load failed", { cause: err });
+}
+```

package/rules/js/require-yield.md

@@ -0,0 +1,107 @@
+---
+id: js/require-yield
+title: "A generator function yields"
+languages: [javascript, jsx, typescript, tsx]
+fix: manual
+fix_reason: "whether to yield or to drop the `*` needs the author"
+stability: preview
+ported_from: [eslint/require-yield]
+since: 0.1.0
+---
+
+A non-empty generator function contains at least one `yield`.
+
+**Why:** A generator without `yield` is either unfinished or should be a plain function.
+
+```codelaw
+match:
+  any:
+    - kind: generator_function_declaration
+    - kind: generator_function
+  not:
+    any:
+      - has: { field: body, regex: '^\{\s*\}$' }
+      - has:
+          kind: yield_expression
+          stopBy:
+            any: [{kind: function_declaration}, {kind: function_expression}, {kind: arrow_function}, {kind: method_definition}, {kind: generator_function_declaration}, {kind: generator_function}]
+message: "A generator that never yields is a plain function"
+```
+
+## How to fix
+
+1. Add the `yield` the generator was meant to have, or remove the `*`.
+
+## Examples
+
+### JavaScript
+
+#### Don't
+
+```js
+function* ids() {
+  return 1;
+}
+```
+
+#### Do
+
+```js
+function* ids() {
+  yield 1;
+}
+```
+
+### JSX
+
+#### Don't
+
+```jsx
+function* ids() {
+  return 1;
+}
+```
+
+#### Do
+
+```jsx
+function* ids() {
+  yield 1;
+}
+```
+
+### TypeScript
+
+#### Don't
+
+```ts
+function* ids() {
+  return 1;
+}
+```
+
+#### Do
+
+```ts
+function* ids() {
+  yield 1;
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+function* ids() {
+  return 1;
+}
+```
+
+#### Do
+
+```tsx
+function* ids() {
+  yield 1;
+}
+```

package/rules/js/use-isnan.md

@@ -0,0 +1,105 @@
+---
+id: js/use-isnan
+title: "Test for NaN with Number.isNaN"
+languages: [javascript, jsx, typescript, tsx]
+fix: manual
+fix_reason: "the comparison's operator decides whether to negate"
+stability: preview
+ported_from: [eslint/use-isnan]
+since: 0.1.0
+---
+
+Code tests for `NaN` with `Number.isNaN(x)`, never by comparing with `NaN`.
+
+**Why:** `NaN` is not equal to anything, itself included, so `x === NaN` is always false.
+
+```codelaw
+match:
+  kind: binary_expression
+  has:
+    field: operator
+    regex: ^(==|===|!=|!==|<|>|<=|>=)$
+  any:
+    - has: { field: left, regex: '^(Number\.)?NaN$' }
+    - has: { field: right, regex: '^(Number\.)?NaN$' }
+message: "Nothing equals NaN, not even NaN; use Number.isNaN(x)"
+```
+
+## How to fix
+
+1. Replace `x === NaN` or `x == NaN` with `Number.isNaN(x)`.
+2. Replace `x !== NaN` or `x != NaN` with `!Number.isNaN(x)`.
+
+## Examples
+
+### JavaScript
+
+#### Don't
+
+```js
+if (price === NaN) {
+  reset();
+}
+```
+
+#### Do
+
+```js
+if (Number.isNaN(price)) {
+  reset();
+}
+```
+
+### JSX
+
+#### Don't
+
+```jsx
+if (price === NaN) {
+  reset();
+}
+```
+
+#### Do
+
+```jsx
+if (Number.isNaN(price)) {
+  reset();
+}
+```
+
+### TypeScript
+
+#### Don't
+
+```ts
+if (price === NaN) {
+  reset();
+}
+```
+
+#### Do
+
+```ts
+if (Number.isNaN(price)) {
+  reset();
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+if (price === NaN) {
+  reset();
+}
+```
+
+#### Do
+
+```tsx
+if (Number.isNaN(price)) {
+  reset();
+}
+```

package/rules/js/valid-typeof.md

@@ -0,0 +1,111 @@
+---
+id: js/valid-typeof
+title: "typeof is compared with a type it can return"
+languages: [javascript, jsx, typescript, tsx]
+fix: manual
+fix_reason: "which type was meant needs the author"
+stability: preview
+ported_from: [eslint/valid-typeof]
+since: 0.1.0
+---
+
+`typeof x` is compared only with a string it can return: `"undefined"`, `"object"`, `"boolean"`,
+`"number"`, `"string"`, `"function"`, `"symbol"` or `"bigint"`.
+
+**Why:** A misspelled type such as `"strnig"` makes the comparison always false.
+
+```codelaw
+match:
+  any:
+    - pattern: typeof $X == $S
+    - pattern: typeof $X === $S
+    - pattern: typeof $X != $S
+    - pattern: typeof $X !== $S
+    - pattern: $S == typeof $X
+    - pattern: $S === typeof $X
+    - pattern: $S != typeof $X
+    - pattern: $S !== typeof $X
+constraints:
+  S:
+    kind: string
+    not: { regex: "^[\"'](undefined|object|boolean|number|string|function|symbol|bigint)[\"']$" }
+message: "`typeof` never returns $S"
+```
+
+## How to fix
+
+1. Correct the string to the type that was meant.
+
+## Examples
+
+### JavaScript
+
+#### Don't
+
+```js
+if (typeof name === "strnig") {
+  greet(name);
+}
+```
+
+#### Do
+
+```js
+if (typeof name === "string") {
+  greet(name);
+}
+```
+
+### JSX
+
+#### Don't
+
+```jsx
+if (typeof name === "strnig") {
+  greet(name);
+}
+```
+
+#### Do
+
+```jsx
+if (typeof name === "string") {
+  greet(name);
+}
+```
+
+### TypeScript
+
+#### Don't
+
+```ts
+if (typeof name === "strnig") {
+  greet(name);
+}
+```
+
+#### Do
+
+```ts
+if (typeof name === "string") {
+  greet(name);
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+if (typeof name === "strnig") {
+  greet(name);
+}
+```
+
+#### Do
+
+```tsx
+if (typeof name === "string") {
+  greet(name);
+}
+```

package/rules/node/hashbang.md

@@ -0,0 +1,71 @@
+---
+id: node/hashbang
+title: "Commands start with a Node.js hashbang, and nothing else has one"
+languages: [javascript, jsx]
+fix: suggest
+fix_reason: "removing the hashbang of a script someone runs directly (`./tool.js`) stops it running"
+stability: preview
+ported_from: [eslint-plugin-n/hashbang]
+since: 0.1.0
+---
+
+A file the nearest `package.json` names in `bin` starts with `#!/usr/bin/env node`; a file it doesn't name has no hashbang. Without a `package.json` above the file, nothing is checked.
+
+**Why:** npm links a `bin` entry as an executable, which the shell runs through its hashbang: without one the command fails, or runs under the wrong interpreter. A hashbang on a library file is noise that suggests it is a command.
+
+```codelaw
+native: node/hashbang
+```
+
+## How to fix
+
+1. On a command `bin` names, make the first line `#!/usr/bin/env node`.
+2. On any other file, remove the hashbang, or add the file to `bin` if it is a command.
+
+## Examples
+
+### JavaScript
+
+#### Don't
+
+```js
+// package.json
+{ "name": "tool", "bin": { "tool": "./bin/tool.js" } }
+// bin/tool.js
+console.log("hello");
+```
+
+#### Do
+
+```js
+// package.json
+{ "name": "tool", "bin": { "tool": "./bin/tool.js" } }
+// bin/tool.js
+#!/usr/bin/env node
+console.log("hello");
+```
+
+### JSX
+
+#### Don't
+
+```jsx
+// package.json
+{ "name": "tool", "bin": "./cli.jsx" }
+// lib/view.jsx
+#!/usr/bin/env node
+export const View = () => <p>hello</p>;
+```
+
+#### Do
+
+```jsx
+// package.json
+{ "name": "tool", "bin": "./cli.jsx" }
+// lib/view.jsx
+export const View = () => <p>hello</p>;
+```
+
+## Differences from the source
+
+TypeScript sources are not checked: eslint-plugin-n maps them to their built JavaScript through `convertPath`, which this rule has no option for yet. The source's checks for a byte-order mark and CRLF line endings in a command are not ported, and there is no `additionalExecutables` or `executableMap` option.