eslint-plugin-lube 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.8.0
+
+### Breaking
+
+- **The strict config moves inline parameter types into `@param` tags** with the new
+  `prefer-param-tag`: `function f(/** @type {T} */ a) {}` becomes `@param {T} a` in the JSDoc block of
+  the declaration. It has a fix, so run `eslint --fix` once; a destructured parameter is left to you.
+
+### Added
+
+- `prefer-param-tag`, in the strict config: reports a function declaration whose parameters are typed
+  with inline comments, `function f(/** @type {T} */ a) {}`, and fixes it into `@param {T} a` tags in the
+  JSDoc block of the declaration, creating the block if there is none, each tag at the position of its
+  parameter among the existing `@param` tags. Arrow functions and function expressions stay, and a
+  destructured parameter is reported without a fix.
+
+## 0.7.0
+
+### Breaking
+
+- **The strict config requires braces on every block** with `lube/curly` (`all`): `if`, `else`, `for`,
+  `while` and `do` bodies are wrapped in `{ }`. It has a fix, so run `eslint --fix` once.
+- **The strict config no longer reports `await` in a loop:** `no-await-in-loop` is gone from it.
+- **The strict config moves the type cast of a declaration's value into a `@type` tag** with the new
+  `prefer-type-tag`, in a project linted with type information: `const a = /** @type {T} */(b)/**/`
+  becomes `/** @type {T} */` on the line before `const a = b`. Run `eslint --fix` once.
+
+### Added
+
+- `prefer-type-tag`, in the strict config: reports the cast of the whole value of a declaration,
+  `const a = /** @type {T} */(b)/**/`, when TypeScript would accept a `/** @type {T} */` tag on the
+  declaration instead, and fixes it into one. A cast that narrows, such as `/** @type {T} */(list[0])/**/`
+  under `noUncheckedIndexedAccess`, one that widens to a union, such as `/** @type {T | null} */(null)/**/`,
+  one through `unknown` and `/** @type {const} */` stay. It reads types from the program of
+  `@typescript-eslint/parser` with `projectService` and checks nothing without one.
+- `curly`, ESLint's own rule with the same options, whose fix puts the braces around a comment in
+  front of the body: `if (a) /** @type {A} */(b).c = 1` becomes `if (a) {/** @type {A} */(b).c = 1}`,
+  where ESLint's fix turned the cast into a comment before the brace, `if (a) /** @type {A} */{(b).c = 1}`.
+
 ## 0.6.0
 
 ### Breaking

package/README.md

@@ -89,10 +89,12 @@ Both configs are flat config objects with `plugins` and `rules`, and differ in h
 
 **`configs.strict`** is the house style of this repository, and several of its rules cannot be fixed. It is everything in `recommended` plus:
 - `svelte-naming-convention`, which renames declarations to snake_case.
+- `prefer-param-tag`, which moves the inline `/** @type {T} */` comments of a function declaration's parameters into `@param` tags on the declaration ([prefer-param-tag](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/prefer-param-tag.md)).
+- `prefer-type-tag`, which moves the cast of a declaration's value into a `@type` tag on the declaration, in a project linted with type information ([prefer-type-tag](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/prefer-type-tag.md) shows the parser options).
 - `ascii-order` for import statements, object keys, function declarations and test cases too (see below).
 - `pretty-sequence` and `pretty-imports` at 30 characters.
 - No blank lines, no line break at the end of a file and one statement per line.
-- Core rules such as `func-style` (declarations), `no-shadow`, `prefer-const`, `one-var` (never), `no-console` and `no-await-in-loop`.
+- `curly` (braces on every block) and core rules such as `func-style` (declarations), `no-shadow`, `prefer-const`, `one-var` (never) and `no-console`.
 
 In `strict`, `ascii-order` fixes import order assuming modules can run in any order, and key order assuming nothing reads it: sorted keys change `Object.keys`, `JSON.stringify` and `for...in`.
 - Import a module that has to run first without names, `import "./setup.js"`, which is never moved.
@@ -109,6 +111,9 @@ Override a rule after the spread: `rules: { ...lube.configs.recommended.rules, "
 | Rule | Enforces | `recommended` |
 | --- | --- | --- |
 | [ascii-order](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/ascii-order.md) | ASCII order of import statements, import and export names, object keys, function declarations and test cases | names only |
+| [curly](https://eslint.org/docs/latest/rules/curly) | Braces around the bodies of `if`, `else`, `for`, `while` and `do`, as ESLint's own rule does, with a fix that keeps a comment in front of the body, such as a JSDoc cast, inside the braces | no |
+| [prefer-param-tag](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/prefer-param-tag.md) | JSDoc `@param` tags on a function declaration instead of inline `/** @type {T} */` comments in its parameter list | no |
+| [prefer-type-tag](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/prefer-type-tag.md) | A JSDoc `@type` tag on a declaration instead of a cast of its value, wherever the tag would type check (needs type information) | no |
 | [pretty-imports](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/pretty-imports.md) | Import and export names on one line when they fit, or one per line | yes |
 | [pretty-jsdoc-casting](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/pretty-jsdoc-casting.md) | JSDoc type casts written as `/** @type {T} */(value)/**/` | yes |
 | [pretty-sequence](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/pretty-sequence.md) | Items of arrays, objects, calls and parameters on one line when they fit, or one per line | yes |

package/docs/prefer-param-tag.md

@@ -0,0 +1,25 @@
+# prefer-param-tag
+Enforces JSDoc `@param` tags on a function declaration, instead of inline `/** @type {T} */` comments inside its parameter list.
+
+- Only function declarations are checked, `export` and `export default` ones too. Arrow functions and function expressions, such as `items.map((/** @type {string} */ x) => x)`, have no declaration to carry a tag and are left alone, and so are casts in a body.
+- The fix removes the inline comments and adds one `@param {T} name` line per parameter to the JSDoc block above the declaration, in parameter order, after the existing `@param` tags and before `@returns` and the like. It creates the block when there is none, and keeps the indentation of the declaration. A `@param` tag that already names the parameter is not repeated.
+- A default value, `/** @type {number} */ n = 1`, is typed by `@param {number} n` too.
+- A destructured or rest parameter has no simple name to write in a tag and is reported without a fix. So is a declaration that does not start its line, where a block cannot be added.
+
+## options
+None.
+
+## Valid
+```js
+/**
+ * @param {string} tx
+ */
+function use(tx) {}
+items.map((/** @type {string} */ x) => x)
+```
+
+## Invalid
+```js
+function use(/** @type {string} */ tx) {}
+async function source(/** @type {unknown} */ n, /** @type {number} */ m = 1) {}
+```

package/docs/prefer-type-tag.md

@@ -0,0 +1,45 @@
+# prefer-type-tag
+Enforces a JSDoc type tag on a declaration, `/** @type {T} */` on the line before it, instead of a type cast of its whole value, `const v = /** @type {T} */(value)/**/`, wherever the value is assignable to `T` and the tag says the same.
+
+The rule needs type information: it reads the types of the value and of the cast from the TypeScript program of `@typescript-eslint/parser`, and checks nothing without one. Turn it on with `projectService`, for files that a `tsconfig.json` with `checkJs` includes:
+```js
+// eslint.config.js
+import tsParser from "@typescript-eslint/parser"
+import lube from "eslint-plugin-lube"
+
+export default [
+    {
+        ...lube.configs.strict,
+        files: ["**/*.js"],
+        languageOptions: {
+            parser: tsParser,
+            parserOptions: { projectService: true, tsconfigRootDir: import.meta.dirname }
+        }
+    }
+]
+```
+
+- TypeScript files, `.ts`, `.tsx`, `.mts` and `.cts`, are not checked, since TypeScript reads no type from a JSDoc cast there.
+- A cast the value is not assignable to is kept: it narrows, as `/** @type {T} */(list[0])/**/` drops the `undefined` that `noUncheckedIndexedAccess` adds, and a tag would fail type checking. So is a cast through `unknown`, `/** @type {T} */(/** @type {unknown} */(value))/**/`, and an object literal with a property the type lacks.
+- `/** @type {const} */` is kept, since a tag cannot make a value constant.
+- A cast that widens the value to a union, `let found = /** @type {Item | null} */(null)/**/`, is kept: TypeScript narrows a variable typed by a union tag to the type of its value, so `found` would read as `null` even after a callback assigned an item, and a comparison with another member of the union would fail type checking.
+- Only a cast of the whole value of a declaration with one variable is checked, and not one in the head of a `for` loop, where a tag has nowhere to go. A declaration that already has a `@type` tag is left alone.
+- The tag goes on its own line before the declaration and any `eslint-disable-next-line`, `@ts-expect-error` or `@ts-ignore` comment above it. A declaration with a JSDoc comment of its own is reported without a fix: add the type to that comment by hand.
+
+## options
+None.
+
+## Valid
+```js
+/** @type {string[]} */
+const names = JSON.parse(text)
+const first = /** @type {string} */(names[0])/**/
+const units = /** @type {const} */([ "s", "m" ])/**/
+let found = /** @type {Item | null} */(null)/**/
+```
+
+## Invalid
+```js
+const names = /** @type {string[]} */(JSON.parse(text))/**/
+const empty = /** @type {string[]} */([])/**/
+```

package/package.json

@@ -10,7 +10,7 @@
   "devDependencies": {
     "@types/estree": "^1.0.9",
     "@typescript/native": "npm:typescript@^7.0.2",
-    "eslint": "^10.10.0"
+    "eslint": "^10.12.0"
   },
   "engines": {
     "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
@@ -53,10 +53,10 @@
   },
   "type": "module",
   "types": "types/index.d.ts",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "scripts": {
     "dts": "node ../../scripts/tsc_with_clean.js eslint-plugin-lube",
     "lint": "pnpm -w lint",
-    "test": "pnpm -w exec vitest run --coverage test/eslint-plugin-lube"
+    "test": "pnpm -w exec vitest run --coverage --coverage.include=packages/eslint-plugin-lube/src/** test/eslint-plugin-lube"
   }
 }

package/src/index.js

@@ -1,9 +1,12 @@
 import ascii_order from "./rules/ascii-order.js"
+import prefer_param_tag from "./rules/prefer-param-tag.js"
+import prefer_type_tag from "./rules/prefer-type-tag.js"
 import pretty_imports from "./rules/pretty-imports.js"
 import pretty_jsdoc_casting from "./rules/pretty-jsdoc-casting.js"
 import pretty_sequence from "./rules/pretty-sequence.js"
 import pretty_ternary from "./rules/pretty-ternary.js"
 import svelte_naming_convention from "./rules/svelte-naming-convention.js"
+import { keep_body_comments } from "./utils/keep_body_comments.js"
 import {
 	keep_comment_order,
 	keep_comments
@@ -14,8 +17,10 @@ import { skip_optional_patterns } from "./utils/skip_optional_patterns.js"
 import { skip_unchanged_fixes } from "./utils/skip_unchanged_fixes.js"
 import { split_declarations } from "./utils/split_declarations.js"
 import stylistic_plugin from "@stylistic/eslint-plugin"
+import { builtinRules } from "eslint/use-at-your-own-risk"
 import { readFileSync } from "node:fs"
-const stylistic = /** @type {import("eslint").ESLint.Plugin} */(stylistic_plugin)/**/
+/** @type {import("eslint").ESLint.Plugin} */
+const stylistic = stylistic_plugin
 /** @type {{ version: string }} */
 const manifest = JSON.parse(
 	readFileSync(
@@ -147,12 +152,14 @@ const strict_rules = {
 			checkTests: true
 		}
 	],
+	"lube/curly": [ "error", "all" ],
+	"lube/prefer-param-tag": "error",
+	"lube/prefer-type-tag": "error",
 	"lube/pretty-imports": "error",
 	"lube/pretty-jsdoc-casting": "error",
 	"lube/pretty-sequence": "error",
 	"lube/pretty-ternary": "error",
 	"lube/svelte-naming-convention": "error",
-	"no-await-in-loop": "warn",
 	"no-case-declarations": "off",
 	"no-console": "warn",
 	"no-duplicate-imports": [
@@ -238,6 +245,11 @@ const plugin = {
 	},
 	rules: {
 		"ascii-order": ascii_order,
+		"curly": keep_body_comments(
+			/** @type {import("eslint").Rule.RuleModule} */(builtinRules.get("curly"))/**/
+		),
+		"prefer-param-tag": prefer_param_tag,
+		"prefer-type-tag": prefer_type_tag,
 		"pretty-imports": pretty_imports,
 		"pretty-jsdoc-casting": pretty_jsdoc_casting,
 		"pretty-sequence": pretty_sequence,