@codelaw/rules-js 0.0.0-stage → 0.1.0

package/presets/react/recommended.toml

@@ -0,0 +1,22 @@
+description = "eslint-plugin-react 7.37.5 recommended with jsx-runtime, and eslint-plugin-react-hooks 7.1.1 rules-of-hooks and exhaustive-deps, reimplemented"
+
+[rules]
+"react/display-name" = "error"
+"react/exhaustive-deps" = "error"
+"react/jsx-key" = "error"
+"react/jsx-no-comment-textnodes" = "error"
+"react/jsx-no-duplicate-props" = "error"
+"react/jsx-no-target-blank" = "error"
+"react/jsx-no-undef" = "error"
+"react/no-children-prop" = "error"
+"react/no-danger-with-children" = "error"
+"react/no-deprecated" = "error"
+"react/no-direct-mutation-state" = "error"
+"react/no-find-dom-node" = "error"
+"react/no-is-mounted" = "error"
+"react/no-render-return-value" = "error"
+"react/no-string-refs" = "error"
+"react/no-unescaped-entities" = "error"
+"react/no-unknown-property" = "error"
+"react/require-render-return" = "error"
+"react/rules-of-hooks" = "error"

package/presets/stencil/recommended.toml

@@ -0,0 +1,18 @@
+description = "@stencil/eslint-plugin 1.4.0 recommended without its type-checked rules, reimplemented"
+
+[rules]
+"stencil/ban-default-true" = "error"
+"stencil/ban-exported-const-enums" = "error"
+"stencil/ban-prefix" = "error"
+"stencil/decorators-context" = "error"
+"stencil/host-data-deprecated" = "error"
+"stencil/methods-must-be-public" = "error"
+"stencil/no-unused-watch" = "error"
+"stencil/own-methods-must-be-private" = "error"
+"stencil/own-props-must-be-private" = "error"
+"stencil/prefer-vdom-listener" = "error"
+"stencil/prop-readonly" = "error"
+"stencil/props-must-be-public" = "error"
+"stencil/required-jsdoc" = "error"
+"stencil/reserved-member-names" = "error"
+"stencil/strict-mutable" = "error"

package/presets/ts/recommended.toml

@@ -0,0 +1,27 @@
+description = "typescript-eslint's recommended preset (8.71.2, not type-checked), reimplemented, with the core rules it switches on for 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"
+"js/no-var" = "error"
+"js/prefer-const" = "error"
+"js/prefer-rest-params" = "error"
+"js/prefer-spread" = "error"

package/rules/graph/no-unused-exports.md

@@ -0,0 +1,135 @@
+---
+id: graph/no-unused-exports
+title: Exported symbols must be used somewhere
+languages: [javascript, jsx, typescript, tsx]
+scope: project
+severity: error
+fix: suggest
+fix_reason: "Static analysis can't rule out reflective or external use, so removal needs a human or agent to accept the diff."
+stability: preview
+ported_from: [knip/exports, knip/types]
+since: 0.1.0
+---
+
+Every exported symbol is imported by another module, is reachable from an entry point, or is marked `@public` / `@keep`.
+
+**Why:** an export nothing imports is dead code that still looks like API: readers keep it, refactors carry it, and it hides what a module is really for.
+
+```codelaw
+graph:
+  symbol:
+    exported: true
+    kind: [function, class, variable, type, interface, enum]
+  unless:
+    - reachable_from: entry
+    - tagged: [public, keep]
+  when:
+    external_references: 0
+  certainty_from: module.dynamic
+message: "`$SYMBOL` is exported but never used outside `$FILE`"
+fix:
+  - when: { local_references: ">0" }
+    do: [strip-export-keyword]
+  - else:
+    do: [remove-declaration]
+```
+
+## How to fix
+
+1. Run `codelaw graph why-unused <symbol>` (`<file>#<export>` or `<module>:<name>`) to see each entry, keep and import clause.
+2. If something outside the repo uses it, add the file to `[graph] entry` or `[graph] keep`, add its decorator to `[graph] registrars`, or tag it `/** @public */` / `# codelaw: keep`.
+3. Otherwise delete the declaration (and its `__all__` or `export { … }` entry), or drop `export` if its own file still uses it.
+
+## Examples
+
+### JavaScript
+
+#### Don't
+
+```js files
+// src/date.js
+export function formatDate(d) { return d.toISOString(); }
+export function parseDate(s) { return new Date(s); }
+// src/app.js
+import { formatDate } from "./date";
+console.log(formatDate(new Date()));
+```
+
+#### Do
+
+```js files
+// src/date.js
+export function formatDate(d) { return d.toISOString(); }
+// src/app.js
+import { formatDate } from "./date";
+console.log(formatDate(new Date()));
+```
+
+### JSX
+
+#### Don't
+
+```jsx files
+// src/Button.jsx
+export function Button() { return <button />; }
+export function Unused() { return <span />; }
+// src/App.jsx
+import { Button } from "./Button";
+console.log(<Button />);
+```
+
+#### Do
+
+```jsx files
+// src/Button.jsx
+export function Button() { return <button />; }
+// src/App.jsx
+import { Button } from "./Button";
+console.log(<Button />);
+```
+
+### TypeScript
+
+#### Don't
+
+```ts files
+// packages/utils/src/date.ts
+export function formatDate(d: Date) { return d.toISOString(); }
+export function parseDate(s: string) { return new Date(s); }
+// packages/web/src/app.ts
+import { formatDate } from "../../utils/src/date";
+console.log(formatDate(new Date()));
+```
+
+#### Do
+
+```ts files
+// packages/utils/src/date.ts
+export function formatDate(d: Date) { return d.toISOString(); }
+// packages/web/src/app.ts
+import { formatDate } from "../../utils/src/date";
+console.log(formatDate(new Date()));
+```
+
+### TSX
+
+#### Don't
+
+```tsx files
+// src/theme.tsx
+export const theme = { dark: false };
+export const unusedTheme = { dark: true };
+// src/main.tsx
+import { theme } from "./theme";
+console.log(theme);
+```
+
+#### Do
+
+```tsx files
+// src/theme.tsx
+export const theme = { dark: false };
+// src/main.tsx
+import { theme } from "./theme";
+console.log(theme);
+```

package/rules/js/constructor-super.md

@@ -0,0 +1,77 @@
+---
+id: js/constructor-super
+title: "A derived class's constructor calls super(); a base class's does not"
+languages: [javascript, jsx]
+fix: manual
+fix_reason: "what `super()` must receive depends on the base class"
+stability: preview
+ported_from: [eslint/constructor-super]
+since: 0.1.0
+---
+
+A class that extends another must call `super()` in its constructor before it returns, and a class
+that extends nothing must not call `super()` at all.
+
+**Why:** Without `super()` the instance is never initialised and the constructor throws; in a base
+class `super()` is a syntax error.
+
+```codelaw
+native: js/constructor-super
+```
+
+## How to fix
+
+1. In a class with `extends`, call `super(...)` with the arguments the base class expects, before any use of `this`.
+2. In a class without `extends`, remove the `super()` call.
+
+## Examples
+
+### JavaScript
+
+#### Don't
+
+```js
+class Cat extends Animal {
+  constructor() {
+    this.lives = 9;
+  }
+}
+```
+
+#### Do
+
+```js
+class Cat extends Animal {
+  constructor() {
+    super();
+    this.lives = 9;
+  }
+}
+```
+
+### JSX
+
+#### Don't
+
+```jsx
+class Cat extends Animal {
+  constructor() {
+    this.lives = 9;
+  }
+}
+```
+
+#### Do
+
+```jsx
+class Cat extends Animal {
+  constructor() {
+    super();
+    this.lives = 9;
+  }
+}
+```
+
+## Differences from the source
+
+Paths are followed in straight-line order: a `super()` on any branch counts as called.

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.