eslint-plugin-lube 0.5.0 → 0.6.0

package/docs/pretty-jsdoc-casting.md

@@ -1,24 +1,32 @@
-# pretty-jsdoc-casting
-Enforces additional empty comment when type casting in JSDoc.
-
-## options
-```js
-schema: undefined
-```
-
-## Valid
-```js
-var v = func(
-    a
-)
-var v = /** @type {A} */(/** @type {B} */(/** @type {C} */(a)/**/)/**/)/**/
-var v = /** @type {A} */(a)/**/()
-var v = { b: /** @type {A} */(a)/**/ }
-```
-
-## Invalid
-```js
-var v = /** @type {A} */(  /** @type {B} */(/** @type {C} */((a))))
-var v = { b: /** @type {A} */(a) }
-var v = { b: /**@type {A}*/(a)/**/ }
+# pretty-jsdoc-casting
+Enforces an empty comment after a JSDoc type cast, `/** @type {T} */(value)/**/`, so the end of the cast is as visible as its start, and writes the cast on one line without white space inside its parentheses.
+
+- TypeScript files, `.ts`, `.tsx`, `.mts` and `.cts`, are not checked, since TypeScript reads no type from a JSDoc cast there.
+- A type comment is a `/**` comment with `@type {T}`. One holding only the type is written as `/** @type {T} */`; any other, such as one spanning lines, is kept as written.
+- Nested castings that end together get one empty comment, after the outermost one.
+- A casting of an inner expression is never moved out of its parentheses.
+- The white space inside the parentheses it removes is dropped, unless a line comment ends there, so a casting written over several lines becomes one line.
+- A casting after `return`, `throw` or `yield` is not checked when a line break stays between the keyword and the expression, such as one ending a line comment inside the parentheses.
+- Parentheses holding the arguments of a call, `new` or `import()` are never read as a casting, even after a type comment: without a semicolon, `/** @type {T} */(a)` on a line of its own calls the expression above it.
+- A casting is not checked when a comment other than a type comment sits between its opening parenthesis and the expression, such as the JSDoc of a function inside the cast, because the fix would move that comment in front of the type comment.
+
+## options
+None.
+
+## Valid
+```js
+var v = func(
+    a
+)
+var v = /** @type {A} */(/** @type {B} */(/** @type {C} */(a)))/**/
+var v = /** @type {A} */(a)/**/()
+var v = { b: /** @type {A} */(a)/**/ }
+```
+
+## Invalid
+```js
+var v = /** @type {A} */(  /** @type {B} */(/** @type {C} */((a))))
+var v = { b: /** @type {A} */(a) }
+var v = { b: /**@type {A}*/(a)/**/ }
+var v = /** @type {A} */(/** @type {B} */(a)/**/)/**/
 ```

package/docs/pretty-sequence.md

@@ -1,118 +1,130 @@
-# pretty-sequence
-Enforces arrays, objects, and functions to have a pretty format by enforcing proper indentation in sequences.
-
-## options
-```js
-schema: [
-    {
-        properties: {
-            arrayBracketSpacing: { type: "boolean", default: true },
-            checkCall: { type: "boolean", default: true },
-            checkArray: { type: "boolean", default: true },
-            checkObject: { type: "boolean", default: true },
-            checkSequence: { type: "boolean", default: true },
-            funcCallSpacing: { type: "boolean", default: false },
-            ignoreTemplateLiteral: { type: "boolean", default: true },
-            indent: { type: "string", default: "\t" },
-            maxLength: { type: "number", default: 30 },
-            objectCurlySpacing: { type: "boolean", default: true }
-        },
-        type: "object"
-    }
-]
-```
-### arrayBracketSpacing
-If it is `true`, it inserts spaces inside array brackets.
-### checkArray
-If it is `true`, it checks the array statement.
-### checkCall
-If it is `true`, it checks the function statement.
-### checkObject
-If it is `true`, it checks the object statement.
-### checkSequence
-If it is `true`, it checks the sequence statement.
-### funcCallSpacing
-If it is `true`, it inserts spaces inside function parenthesis.
-### ignoreTemplateLiteral
-If it is `true`, it ignores the template literal syntax.
-### indent
-This is the character to be used for indentation.
-### maxLength
-If the sum of the characters in the Sequences is greater than the set value, apply line breaks.
-```js
-// If maxLength is less than or equal to 20, an error occurs.
-var value = { fff, ggg, hhh, iii, jjj, kkk, lll }
-```
-### objectCurlySpacing
-If it is `true`, it inserts spaces inside object braces.
-
-## Valid
-```js
-var value = [ a, b, c ]
-var value = [
-    aaaaaaaaaa,
-    bbbbbbbbbb,
-    cccccccccc,
-    dddddddddd
-]
-var value = { a, b, c, d, e }
-var value = {
-    aaaaaaaaaa,
-    bbbbbbbbbb,
-    cccccccccc,
-    dddddddddd
-}
-function func(a, b, c) {
-
-}
-function func(
-    aaaaaaaaaa,
-    bbbbbbbbbb,
-    cccccccccc,
-    dddddddddd
-) {
-
-}
-var value = `${[a,b,c]}`
-
-func(
-    aaaaaaaaaa_bbbbbbbbbb_cccccccccc
-)
-    .a(
-        aaaaaaaaaa_bbbbbbbbbb_cccccccccc
-    )
-    .b(
-        aaaaaaaaaa_bbbbbbbbbb_cccccccccc
-    )
-    .c(
-        aaaaaaaaaa_bbbbbbbbbb_cccccccccc
-    )
-
-var value = {
-    a: [ a, b, c ],
-    b: true,
-    c: {
-        aaaaaaaaaa: a,
-        bbbbbbbbbb: b,
-        c: [
-            aaaaaaaaaa,
-            bbbbbbbbbbb,
-            ccccccccccc
-        ],
-        d: {
-            aaaaaaaaaa,
-            bbbbbbbbbbb,
-            ccccccccccc
-        }
-    }
-}
-```
-
-## Invalid
-```js
-var value = [a,b,c]
-var value = { aaaaaaaaaa, bbbbbbbbbb, cccccccccc, dddddddddd }
-new Obj(
-
-)
+# pretty-sequence
+Formats arrays, objects, parameters and arguments: the items on one line when they fit, or one per line.
+
+- Comments are never removed. A line comment after an item stays on the line of that item, and a sequence containing a multiline string, template literal or JSX attribute string that would have to be re-indented is not fixed.
+- TypeScript type annotations and type arguments are supported, and parameters with decorators are not fixed.
+- Items the rule moves to a line of their own are indented one level deeper than the line the sequence opens on, and the closing bracket returns to that line's indentation. Two cases follow `@stylistic/indent` instead: a sequence opening on the first line of a declaration whose last declarator starts on a later line gets one level more, and a line starting with `;`, as `@stylistic/semi-style: first` writes it, counts as indented like its statement.
+- A sequence already written over several lines is left to `@stylistic/indent`, which owns the indentation of lines this rule did not write; `fixIndent` gives that back to this rule.
+
+## options
+```js
+schema: [
+    {
+        additionalProperties: false,
+        properties: {
+            arrayBracketSpacing: { default: true, type: "boolean" },
+            checkArray: { default: true, type: "boolean" },
+            checkCall: { default: true, type: "boolean" },
+            checkObject: { default: true, type: "boolean" },
+            checkSequence: { default: true, type: "boolean" },
+            fixIndent: { default: false, type: "boolean" },
+            funcCallSpacing: { default: false, type: "boolean" },
+            ignoreTemplateLiteral: { default: true, type: "boolean" },
+            indent: { default: "\t", type: "string" },
+            maxLength: { default: 30, type: "number" },
+            objectCurlySpacing: { default: true, type: "boolean" }
+        },
+        type: "object"
+    }
+]
+```
+### arrayBracketSpacing
+If it is `true`, it writes a space inside array brackets: `[ a, b ]`.
+### checkArray
+If it is `true`, it checks arrays and array patterns.
+### checkCall
+If it is `true`, it checks the arguments of calls and `new`, and the parameters of functions.
+### checkObject
+If it is `true`, it checks objects and object patterns.
+### checkSequence
+If it is `true`, it checks sequence expressions, `a, b`.
+### fixIndent
+If it is `true`, it also reports a sequence whose lines differ from this rule only in their indentation. Leave it off while `@stylistic/indent` is on, or the two rules keep rewriting each other's fixes.
+### funcCallSpacing
+If it is `true`, it writes a space inside the parentheses of arguments and parameters: `f( a, b )`.
+### ignoreTemplateLiteral
+If it is `true`, it ignores sequences inside template literals.
+### indent
+The string of one indentation level. Match it to `@stylistic/indent`, or the two rules keep rewriting each other's fixes.
+### maxLength
+The items are written one per line when they are longer than this together, commas and spaces not counted, and on one line when they fit. A character that takes two columns, such as a Korean, Chinese or Japanese one, counts as two, so the number is the width the items take on screen. The default of 30, which the strict config keeps, breaks most calls with more than a couple of arguments; the recommended config sets 80. For another length, set it in the config, and `eslint --fix` rewrites the sequences it now reports both ways:
+```js
+rules: { ...lube.configs.recommended.rules, "lube/pretty-sequence": ["error", { maxLength: 100 }] }
+```
+```js
+// If maxLength is less than or equal to 20, an error occurs.
+var value = { fff, ggg, hhh, iii, jjj, kkk, lll }
+```
+### objectCurlySpacing
+If it is `true`, it writes a space inside object braces: `{ a, b }`.
+
+## Valid
+```js
+var value = [ a, b, c ]
+var value = [
+    aaaaaaaaaa,
+    bbbbbbbbbb,
+    cccccccccc,
+    dddddddddd
+]
+var value = { a, b, c, d, e }
+var value = {
+    aaaaaaaaaa,
+    bbbbbbbbbb,
+    cccccccccc,
+    dddddddddd
+}
+function func(a, b, c) {
+
+}
+function func2(
+    aaaaaaaaaa,
+    bbbbbbbbbb,
+    cccccccccc,
+    dddddddddd
+) {
+
+}
+var value = `${[a,b,c]}`
+
+func(
+    aaaaaaaaaa_bbbbbbbbbb_cccccccccc
+)
+    .a(
+        aaaaaaaaaa_bbbbbbbbbb_cccccccccc
+    )
+    .b(
+        aaaaaaaaaa_bbbbbbbbbb_cccccccccc
+    )
+    .c(
+        aaaaaaaaaa_bbbbbbbbbb_cccccccccc
+    )
+
+var value = {
+    a: [ a, b, c ],
+    b: true,
+    c: {
+        aaaaaaaaaa: a,
+        bbbbbbbbbb: b,
+        c: [
+            aaaaaaaaaa,
+            bbbbbbbbbbb,
+            ccccccccccc
+        ],
+        d: {
+            aaaaaaaaaa,
+            bbbbbbbbbbb,
+            ccccccccccc
+        }
+    }
+}
+```
+
+## Invalid
+```js
+var value = [a,b,c]
+var value = { aaaaaaaaaa, bbbbbbbbbb, cccccccccc, dddddddddd }
+new Obj(
+
+)
 ```

package/docs/pretty-ternary.md

@@ -0,0 +1,55 @@
+# pretty-ternary
+Breaks nested and long ternaries, `a ? b : c` and TypeScript conditional types, before `?` and `:`.
+
+- A ternary is broken when a branch is another ternary, when it is longer than `maxLength`, or when it already spans lines.
+- A missing line break before `?` or `:` is inserted one level deeper than the line the ternary starts on, and one level deeper again for a ternary in a branch. A ternary inside parentheses is checked on its own.
+- The indentation of a `?` or `:` that already starts a line is left to `@stylistic/indent`, which indents it the same way.
+- Only the spaces around `?` and `:` are fixed, so the operands keep their text and comments. A ternary with a line comment right after `?` or `:` is not fixed.
+
+## options
+```js
+schema: [
+    {
+        additionalProperties: false,
+        properties: {
+            ignoreTemplateLiteral: { default: true, type: "boolean" },
+            indent: { default: "\t", type: "string" },
+            maxLength: { default: 80, type: "number" }
+        },
+        type: "object"
+    }
+]
+```
+### ignoreTemplateLiteral
+If it is `true`, it ignores ternaries inside template literals.
+### indent
+The string of one indentation level. Match it to `@stylistic/indent`, or the two rules keep rewriting each other's fixes.
+### maxLength
+A ternary longer than this, counted as if written on one line, is broken over lines. A ternary with a ternary branch is broken at any length.
+
+## Valid
+```ts
+var value = a ? b : c
+var value = a
+    ? b
+    : c
+        ? d
+        : e
+type MergeValue<A, B> = B extends NotPlain | Primitive
+    ? B
+    : B extends WeakKey
+        ? A extends NotPlain | Primitive
+            ? B
+            : A extends WeakKey
+                ? MergeObject<A, B>
+                : B
+        : B
+```
+
+## Invalid
+```ts
+var value = a ? b : c ? d : e
+var value = a ? b
+    : c
+type M<A> = A extends string ? 1 : A extends number ? 2 : 3
+```

package/docs/svelte-naming-convention.md

@@ -1,47 +1,60 @@
-# svelte-naming-convention
-Enforces snake_case with some symbols for variable declaration.  
-[svelte#code-conventions](https://github.com/sveltejs/svelte/blob/master/CONTRIBUTING.md#code-conventions)
-
-## options
-```js
-schema: [
-    {
-        properties: {
-            fixSameNames: { type: "boolean", default: true }
-        },
-        type: "object"
-    }
-]
-```
-### fixSameNames
-If set to `true`, an error will be returned if the variable name is the same, even in the case of function calls that are the target of `defer`.
-```js
-myFunction() // Only in the case that fixSameNames is true, an error occurs.
-
-// Identifier 'myFunction' does not match for svelte's naming conventions.
-function myFunction() {
-
-}
-```
-
-## Valid
-```js
-var snake_case = 'Hello'
-var snake1_2_3case_4 = 'Hello'
-var SNAKE_CASE = 'Hello'
-var SNAKE1_2_3CASE_4 = 'Hello'
-var PascalCase = 'Hello'
-var P1ascal2Case345 = 'Hello'
-var __ = 'Hello'
-var $$ = 'Hello'
-var __snake_case$$ = 'Hello'
-var $$snake_case$$ = 'Hello'
-```
-
-## Invalid
-```js
-var camelCase = 'Hello'
-var NO_SNAKE__CASE = 'Hello'
-var NO_SNAKE_CASE_ = 'Hello'
-var __camelCase$$ = 'Hello'
+# svelte-naming-convention
+Enforces snake_case declarations, following the [Svelte code conventions](https://github.com/sveltejs/svelte/blob/master/CONTRIBUTING.md#code-conventions).
+The strict config turns it on and the recommended config leaves it off, since its fix renames identifiers.
+
+- Declarations such as variables, parameters, catch clauses, array patterns and non-shorthand object patterns, `const { key: camelCase } = value`, are reported. A shorthand property, `const { camelCase } = value`, and a shorthand import, `import { camelCase } from "m"`, are not, because the name is the key or the export it reads; write `const { camelCase: camel_case } = value` or `import { camelCase as camel_case }` to rename it.
+- The message names the expected name, `Rename 'camelCase' to 'camel_case'`, or, for a name without a snake_case form such as `NO_SNAKE__CASE`, asks for snake_case, UPPER_SNAKE_CASE or PascalCase.
+- Usages such as assignments, function bodies, `extends` clauses, JSX and TypeScript expressions are only renamed along with their declaration; `fixSameNames` sets the order.
+- Usages are matched to declarations by scope, so a global, an import or an exported camelCase function of the same name is left as it is.
+- A declaration exported with `export { camelCase }` is renamed together with the export specifier, `export { camel_case as camelCase }`.
+- The JSDoc of a renamed parameter follows it: `@param {T} [camelCase]`, `{camelCase is T}` and `{typeof camelCase}`.
+- In a `.svelte` file, the store subscriptions of a renamed store are renamed with it, `$camelCase` into `$camel_case`, in the same fix, and so are the usages in the markup: mustache tags, attributes, directives and the expression of `{#if}`, `{#each}`, `{#await}` and `{#key}`. A shorthand attribute is written out, `{camelCase}` into `camelCase={camel_case}`, so the name of the property stays. Names the markup declares, the context of `{#each}`, the value of `{#await}` and a `let:` property, are not reported.
+- A name is reported without a fix when it has no snake_case form, such as `NO_SNAKE__CASE`, when the snake_case name would shadow or capture another variable, when it is also declared where the rule does not rename, such as a TypeScript namespace merged with a function or `export var camelCase`, when a declaration of it is turned off with an `eslint-disable` comment, when it is used as a JSX or Svelte component tag, `<Camel_Case />`, which a lowercase name would turn into an HTML tag, when it also appears where the rule cannot tell a reference from a type or a property, such as `let a: camelCase` or markup of a Svelte parser, or when it is read as a store, `$camelCase`, outside a `.svelte` file, where `$camelCase` is a name of its own.
+
+## options
+```js
+schema: [
+    {
+        additionalProperties: false,
+        properties: {
+            fixSameNames: { default: true, type: "boolean" }
+        },
+        type: "object"
+    }
+]
+```
+### fixSameNames
+If it is `true`, every usage of a reported declaration is reported and fixed on its own, and the declaration is renamed in a later pass of `eslint --fix`, once no usage of the old name is left, so a fix another rule overrides in the same pass never leaves a usage behind.
+Assignments to the variable and `export default` of it are renamed with the declaration, not on their own, so `prefer-const` never sees `let lastBid = 1` without its `lastBid += 1` and turns it into a `const`, and `ascii-order` never sees a default-exported function under another name and moves it.
+The declaration and its usages are renamed in one fix instead when the snake_case name is already declared in the file or a variable of the same name is declared in a nested scope, so a half-renamed usage never resolves to another variable.
+If it is `false`, only the declaration is reported, and its fix renames the declaration and every usage at once.
+```js
+myFunction() // Only in the case that fixSameNames is true, an error occurs.
+
+// Rename 'myFunction' to 'my_function': declarations are snake_case, following the Svelte code conventions
+function myFunction() {
+
+}
+```
+
+## Valid
+```js
+var snake_case = 'Hello'
+var snake1_2_3case_4 = 'Hello'
+var SNAKE_CASE = 'Hello'
+var SNAKE1_2_3CASE_4 = 'Hello'
+var PascalCase = 'Hello'
+var P1ascal2Case345 = 'Hello'
+var __ = 'Hello'
+var $$ = 'Hello'
+var __snake_case$$ = 'Hello'
+var $$snake_case$$ = 'Hello'
+```
+
+## Invalid
+```js
+var camelCase = 'Hello'
+var NO_SNAKE__CASE = 'Hello'
+var NO_SNAKE_CASE_ = 'Hello'
+var __camelCase$$ = 'Hello'
 ```

package/package.json

@@ -1,38 +1,62 @@
 {
-	"author": "artxe2",
-	"bugs": {
-		"url": "https://github.com/Artxe2/lube-series/issues"
-	},
-	"description": "Full fixable rules for auto-formatting with ESLint only without Prettier",
-	"devDependencies": {
-		"@types/eslint": "^9.6.1",
-		"@types/estree": "^1.0.8",
-		"@typescript-eslint/parser": "^8.35.0",
-		"eslint": "^9.29.0",
-		"mocha": "^11.7.0",
-		"typescript": "^5.8.3"
-	},
-	"keywords": [
-		"eslint-plugin",
-		"lube",
-		"eslint-plugin-lube",
-		"prettier",
-		"jsdoc"
-	],
-	"license": "MIT",
-	"name": "eslint-plugin-lube",
-	"peerDependencies": {
-		"eslint": ">=9.0.0"
-	},
-	"repository": {
-		"directory": "packages/eslint-plugin-lube",
-		"type": "git",
-		"url": "https://github.com/Artxe2/lube-series"
-	},
-	"scripts": {
-		"dts": "tsc",
-		"test": "mocha"
-	},
-	"type": "commonjs",
-	"version": "0.5.0"
+  "author": "artxe",
+  "bugs": {
+    "url": "https://github.com/artxe/lube-series/issues"
+  },
+  "dependencies": {
+    "@stylistic/eslint-plugin": "^5.10.0"
+  },
+  "description": "Fixable ESLint rules that format code without Prettier",
+  "devDependencies": {
+    "@types/estree": "^1.0.9",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "eslint": "^10.10.0"
+  },
+  "engines": {
+    "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "CHANGELOG.md",
+    "docs",
+    "src",
+    "types/index.*"
+  ],
+  "homepage": "https://github.com/artxe/lube-series/tree/master/packages/eslint-plugin-lube#readme",
+  "keywords": [
+    "eslint",
+    "eslint-plugin",
+    "eslint-plugin-lube",
+    "eslintplugin",
+    "formatting",
+    "jsdoc",
+    "lube",
+    "prettier",
+    "sort",
+    "svelte"
+  ],
+  "license": "MIT",
+  "main": "src/index.js",
+  "name": "eslint-plugin-lube",
+  "peerDependencies": {
+    "eslint": ">=9.0.0"
+  },
+  "repository": {
+    "directory": "packages/eslint-plugin-lube",
+    "type": "git",
+    "url": "https://github.com/artxe/lube-series"
+  },
+  "type": "module",
+  "types": "types/index.d.ts",
+  "version": "0.6.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"
+  }
 }