eslint-plugin-lube 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,283 @@
+# Changelog
+
+## 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
+
+- **Two configs replace `configs.plugins` and `configs.rules`.** `configs.strict` holds the rules
+  `configs.rules` held, the house style with renaming, sorting and core rules, and
+  `configs.recommended` is a lighter set that only formats and orders, with rules that all have a
+  fix. Each is a flat config object with `plugins` and `rules`: replace
+  `plugins: lube.configs.plugins, rules: { ...lube.configs.rules }` with
+  `plugins: lube.configs.strict.plugins, rules: { ...lube.configs.strict.rules }`, or spread
+  `...lube.configs.strict` into the config.
+- **Every rule rejects options it does not know.** A misspelled option such as `maxLenght` is a
+  configuration error instead of being ignored, and `pretty-jsdoc-casting` takes no options.
+- **`svelte-naming-convention` is a `suggestion` rule, no longer `layout`,** since its fix renames
+  identifiers: `eslint --fix --fix-type layout` leaves names alone now.
+- **The package is an ES module only.** `import lube from "eslint-plugin-lube"` works as before on
+  Node.js 18.18+, 20.9+ and 21.1+, the versions `@stylistic/eslint-plugin` supports. A CommonJS
+  `eslint.config.cjs` still gets the plugin itself from `require("eslint-plugin-lube")` on Node.js
+  20.19+ and 22.12+, which ESLint 10 requires anyway. Deep paths such as `eslint-plugin-lube/rules/ascii-order` are gone; the rules are
+  `lube.rules`.
+- **Both configs use `@stylistic/eslint-plugin` instead of the deprecated core formatting
+  rules,** which ESLint 11 removes. Rename overrides of those rules:
+  ```js
+  // before
+  rules: { ...lube.configs.rules, "indent": ["error", 4] }
+  // after
+  rules: { ...lube.configs.strict.rules, "@stylistic/indent": ["error", 4] }
+  ```
+  `func-call-spacing` is `@stylistic/function-call-spacing`. `@stylistic/indent` also checks
+  TypeScript syntax, and `@stylistic/operator-linebreak` checks `=` of type aliases, which stays at the
+  end of the line: `type Name =` followed by `| "a"`.
+- **The strict config reports blank lines** with `@stylistic/no-multiple-empty-lines` (`max: 0`)
+  and fixes `arrow-body-style`, `new-parens`, `no-extra-boolean-cast`, `no-extra-semi`,
+  `no-unneeded-ternary`, `no-useless-computed-key`, `no-useless-rename`, `no-useless-return`,
+  `prefer-exponentiation-operator`, `prefer-object-spread` and `yoda`. Run `eslint --fix` once.
+- **The strict config reports functions assigned to variables** with `func-style`
+  (`declaration`): write `function name() {}` instead of `const name = () => {}`. Callbacks and
+  arrow functions that use `this` are not reported. It cannot be fixed.
+- **The strict config sorts import statements, import and export names, object keys, function
+  declarations and test cases** with the new `ascii-order`, all of its options on. Run
+  `eslint --fix` once, then reorder by hand what it reports without a fix, or disable it where the
+  order matters: `// eslint-disable-next-line lube/ascii-order`. A report without a fix says why,
+  ``Move key "a" before "b" to keep keys in ASCII order; it is not fixed automatically because moving
+  `f()` could change the order of side effects, so reorder it by hand``, or that a comment or statement
+  next to the item would end up in the wrong place. Keys whose values construct a
+  built-in from literals, such as `{ updatedAt: new Date(), createdAt: new Date() }` and
+  `{ s: new Set([ 1 ]), m: new Map() }`, are fixed, and so are keys whose values are a `const`, a
+  namespace import or a function or class declaration that is never assigned, which no call can
+  change: `{ shadow: shadowed(), helper }`. A `const` or class counts only where the value comes
+  after its declaration and outside a function declaration, which could run before it, so a read
+  that throws in the temporal dead zone still throws after the calls written before it. A
+  construction that always throws, such as `new RegExp("(")`, `new Array(-1)` or `new Map([ 1 ])`,
+  is not moved, nor one that another runtime may reject or that allocates a lot while linting:
+  `new RegExp` with a flag other than `gimsuy` or with syntax newer than ES2018, such as
+  `new RegExp("a", "v")` or `(?i:a)`, and `new Array`, a buffer, a typed array or a `DataView` with a
+  number over 65536 in its arguments, such as `new Set(new Array(1e8))`. Its fix assumes modules can run
+  in any order and nothing reads key order: sorted keys change `Object.keys`, `JSON.stringify` and
+  `for...in`, and an import without names, such as `import "./setup.js"`, is never moved and no
+  import moves across it. Under `exports` and `imports` of a
+  `package.json` it puts `types` first and `default` last, as TypeScript and Node.js read them.
+- **Both configs break nested and long ternaries** with the new `pretty-ternary`: a
+  ternary with a ternary branch, or longer than 80 characters, puts `?` and `:` at the start of their
+  lines, one indent deeper per level. Run `eslint --fix` once.
+- **`pretty-imports` checks imports with a default import** such as `import def, {a,b} from "m"`,
+  which it skipped before.
+- **`pretty-sequence` and `pretty-imports` leave the indentation of code that is already written over
+  several lines to `@stylistic/indent`,** and write it only for the line breaks they insert themselves.
+  The two rules owned the same lines before, so wherever the indent rule measures a line differently,
+  `eslint --fix` never finished. Turn `fixIndent` on in a config without an indent rule.
+- **Both configs wrap the `@stylistic` rules whose fixes break code or never settle:**
+  `comma-style` leaves the comma of an array hole on its own line, `operator-linebreak` leaves an
+  operator a comment follows, `object-curly-newline` and `object-curly-spacing` skip optional
+  destructured parameters, `key-spacing`, `semi-spacing`, `space-unary-ops`, `generator-star-spacing`,
+  `rest-spread-spacing` and `yield-star-spacing` keep the comments in the space they remove, every fix
+  writes the line break of the file, and a fix that would change nothing is dropped.
+- **`max-len` is in neither config,** since it cannot be fixed.
+- **`svelte-naming-convention` reports more declarations.** Function expression names and
+  parameters, `catch` parameters, parameters of exported camelCase functions, non-shorthand
+  destructuring such as `const { key: camelCase } = value` and `import { "name" as camelCase }`
+  are reported now. Expect new errors on existing code.
+- **`svelte-naming-convention` treats `for...in` and `for...of` targets as usages.** They are fixed
+  together with their declaration, like assignments, instead of being renamed on their own.
+- **`pretty-jsdoc-casting` puts one empty comment after nested castings that end together,** after
+  the outermost one: `/** @type {A} */(/** @type {unknown} */(a))/**/` instead of
+  `/** @type {A} */(/** @type {unknown} */(a)/**/)/**/`. Run `eslint --fix` once.
+- **Every rule message says what to change and why:** `Rename 'isV' to 'is_v'`,
+  ``Write these items on one line as `[ a, b ]`, since they fit in 30 characters``,
+  `Put each item and the closing bracket on a line of its own, since the items are longer than 30
+  characters together`, ``Break this ternary before `?` and `:`, since a branch is another ternary``,
+  `Move key "a" before "b" to keep keys in ASCII order`. The message IDs are new:
+  `pretty-sequence` reports `multiline`, `single_line` and `indent`; `pretty-imports` `multiline`,
+  `single_line`, `indent`, `semicolon` and `no_semicolon` for imports and exports alike;
+  `pretty-ternary` `multiline` and `spacing`; `pretty-jsdoc-casting` `marker` and `format`; and
+  `svelte-naming-convention` `rename` and `case`.
+
+### Fixed
+
+- The `maxLength` of `pretty-sequence` and `pretty-imports` counts a character that takes two
+  columns, such as a Korean, Chinese or Japanese one, as two. A line of Korean strings and a line of
+  Latin ones that take the same width on screen are now broken or joined alike, where the Korean one
+  used to stay on one line at twice the width.
+- The message that asks for one line said the items "fit in" the `maxLength`, although it measures
+  the items alone, without the code around them, so the line it wrote could be much longer. It now
+  names the width it measured: "since the items are 75 characters together, within the 80 allowed".
+- `pretty-jsdoc-casting` added `/**/` after casts in TypeScript files, where a JSDoc cast means
+  nothing. `.ts`, `.tsx`, `.mts` and `.cts` files are not checked now.
+- The `one-var` fix of the strict config left `const a = 1; const b = 2` on one line, which
+  `@stylistic/max-statements-per-line` reported without a fix. `eslint --fix` puts each of the
+  declarations on a line of its own now.
+- `no-duplicate-imports` of the strict config reported `import type { A } from "m"` next to
+  `import { b } from "m"`. A separate type import is allowed now.
+- The `@stylistic/space-unary-ops`, `rest-spread-spacing`, `generator-star-spacing`,
+  `yield-star-spacing`, `semi-spacing` and `key-spacing` fixes of both configs deleted a
+  comment in the space they remove, or moved a colon into one: `!/** @type {A} */(a)/**/` lost its
+  type cast, `.../* @__PURE__ */ f()` its comment, and `a // note` followed by `: 1` became
+  `a // note: 1`. Such a space is left unreported now.
+- In a file whose line breaks are CRLF, CR, U+2028 or U+2029, `pretty-sequence`, `pretty-imports`
+  and `pretty-ternary` counted only LF as a line break, so they indented from the wrong line, wrote
+  LF line breaks into the file and never stopped fixing it; `pretty-sequence` also indented the lines
+  inside a string or a template that spans such lines, changing its value, `` f(`a `` + U+2028 +
+  `` b`, c) `` grew a tab in front of `b`, and `pretty-ternary` and `pretty-jsdoc-casting` read those
+  line breaks as none. Every rule and the `@stylistic` fixes of both configs follow the
+  line break of the file now.
+- `ascii-order` sorted only the outermost of nested objects, patterns or import braces per
+  `eslint --fix` pass, one pass per nesting level, so deeply nested files needed more than the 10
+  passes ESLint runs. Nested ones are sorted in the same pass now.
+- `ascii-order` swapped destructuring targets whose order matters: `var { b: x, a: x } = o` changed
+  the value of `x`, and `({ b: this.b, a: this.a } = o)` the order of the setter calls. They are
+  reported without a fix now.
+- `pretty-imports` removed `type` from `import type` and `export type`, import attributes such as
+  `with { type: "json" }`, and comments between the braces.
+- `pretty-imports` removed a semicolon another statement needs: the one before a statement on the
+  same line, `import { a } from "m";var b = 1` became `import { a } from "m"var b = 1`, and the one
+  that starts the next line, `;[a].map(f)`. It also added a semicolon before the `}` that closes a
+  namespace, which `@stylistic/semi` of both configs removed again on every fix.
+- `pretty-jsdoc-casting` changed what a cast means: it moved the cast of an inner expression out of
+  the parentheses, `/** @type {X} */(/** @type {A} */(a).b)` became
+  `/** @type {A} *//** @type {X} */((a).b)`, deleted the text after the type of a type comment,
+  `/** @type {A} @deprecated */ (a)` lost `@deprecated`, turned the plain comment
+  `/* @type {A} */ (a)` into a type cast, and removed the empty comment after a type comment that
+  spans lines. A type comment is kept as written now unless it holds only the type. It also mangled
+  `/** @type {A} */(a)/**//**/`, left a double space for `/** @type {A} */ (a)` and moved a cast onto
+  the next line when a line break followed the type comment.
+- `pretty-jsdoc-casting` moved what stood between the cast parenthesis and the expression in front
+  of the type comment: a line break, so `return /** @type {A} */(` followed by `b)/**/` returned
+  `undefined`; the JSDoc of a function inside the cast, which landed between `export default` and
+  the cast with broken indentation; and the white space of a cast written over several lines, which
+  put the cast on a new line and left the old one empty, so with either config every
+  `eslint --fix` added one more line and one more indent level. That white space is dropped now,
+  unless a line comment ends there, and a cast is left unfixed when another comment stands there or
+  when a line break after `return`, `throw` or `yield` would stay.
+- `pretty-jsdoc-casting` read the argument parentheses of a call as cast parentheses when a type
+  comment stood before them, so `var x = 1` followed by `/** @type {T} */(f(a))` (a call, because no
+  semicolon ends the first line) got a `/**/` marker and never stopped fighting `pretty-sequence`.
+  The parentheses of a call, `new` or `import()` are left alone now.
+- `pretty-sequence` and `pretty-jsdoc-casting` took time quadratic in the file size, and
+  `pretty-sequence` in the line length: a 258 KB file took about 40 seconds per rule and takes about
+  0.1 seconds, and a 1.4 MB single-line file took 33 seconds and takes about 2 seconds, most of it
+  parsing.
+- `pretty-sequence` broke TypeScript: `({ a, b }: Props) => a` became `({ a, b s) => a`, the
+  annotation of an array pattern was deleted, and `f<(x: number) => void>( a )` became `f<(a)`.
+- `pretty-sequence` lost or moved comments and holes: a line comment after the last item commented
+  out the closing bracket, `[ b, c // note` followed by `]` became `[ b, c // note ]`; comments after
+  a trailing comma or inside empty brackets and the trailing hole of `[a, ,]` were deleted; and a
+  line comment after an item's comma moved onto the next item's line. It stays with its item now.
+- `pretty-sequence` changed the value of a multiline template literal, a string with a line
+  continuation or a multiline JSX attribute string, `f(a, <div title="one` followed by `  two">)`,
+  by re-indenting its lines. Such sequences are left unfixed.
+- `pretty-sequence`: with `funcCallSpacing`, `a => b` gained more spaces on every fix.
+- `pretty-sequence` wrote indentation onto the empty lines of a function it moved to a new line.
+- `pretty-sequence` and `@stylistic/indent` fixed each other endlessly ("Circular fixes detected")
+  for a sequence opening on the first line of a declaration whose last declarator starts on a later
+  line, `let i = [` … `], a = 1`, for a line starting with `;` as `@stylistic/semi-style: first`
+  writes it, for the arguments of a call that follows a multiline parenthesized expression on the
+  same line, `(a` `|| b).catch(c, d)` or `(a ? b : "") + f(c, d)`, and for a sequence on a line that
+  starts inside a block comment, `*/ const a = [b, c]`. `pretty-sequence` indents them like
+  `@stylistic/indent` now.
+- In `.svelte` files, `pretty-sequence` and `pretty-ternary` indented a template expression such as
+  `{await f(` from the column where the markup before it started, and `@stylistic/indent` undid it
+  on every fix.
+- The `pretty-sequence` rule description was copied from `pretty-jsdoc-casting`.
+- `svelte-naming-convention` renamed usages as if they were declarations, arrow function bodies and
+  `extends` clauses among them, so references to imported or global names broke, and it left other
+  usages with the old name: `do...while` conditions, computed keys, class field values, `import()`,
+  JSX, decorators, TypeScript expressions such as `camelCase as T`, `camelCase!` and
+  `typeof camelCase`, `export = camelCase`, enum member values, type predicates, the overloads of a
+  function (only the implementation was renamed), the object of a JSX member tag such as
+  `<routeModule.Layout>`, and the markup of a `.svelte` file, where every node was read as a name
+  the rule must not touch, so `{camelCase}` in a mustache tag, an attribute, a directive or a block
+  expression stopped the rename. Every usage that scope analysis reaches is renamed with its
+  declaration now, a shorthand attribute becomes `camelCase={camel_case}`, what the markup declares,
+  such as the context of `{#each}` or a `let:` property, is left alone, and a name is reported
+  without a fix where the rule cannot tell a reference from a type or a property, such as
+  `let a: camelCase`, or where it is a component tag, `<My_Comp />`, which a lowercase name would
+  turn into an HTML tag.
+- `svelte-naming-convention` broke destructuring and exports: `{ camelCase: camelCase }` was read as
+  a shorthand property and became `{ camelCase: camelCase: camel_case }`, a shorthand with a default,
+  `{ camelCase = 1 }` in a pattern, was never renamed while every other use of the name was, and
+  `export { camelCase }` lost its binding. They become `{ camelCase: camel_case }`,
+  `{ camelCase: camel_case = 1 }` and `export { camel_case as camelCase }` now, the declaration and
+  its export specifier in one fix, since separate fixes in one pass could leave `export` pointing at
+  a name that no longer exists, a syntax error.
+- `svelte-naming-convention` matched usages to declarations by name only, so its fixes broke code
+  that the Svelte code base holds: a global or an exported camelCase function used where a parameter
+  of the same name was renamed elsewhere was renamed too, e.g. `requestAnimationFrame()` or
+  `flushSync()` became undefined; the usages of an import, `import { fetchModule }`, were renamed
+  with a same-named declaration elsewhere but not the import; a name whose snake_case form is already
+  a variable was renamed into it, e.g. `itemCount` next to `item_count`; the type annotation and `?`
+  of a TypeScript name were deleted, `itemCount?: number` became `item_count`; a parameter mentioned
+  in the prose of a JSDoc comment was renamed while `@param {T} callbackFn`, `[superClass]`,
+  `{callbackFn is F}` and `typeof callbackFn` kept the old name and failed type checking; and a store
+  read as `$userStore` lost its declaration. Usages follow scope analysis now, an import becomes
+  `import { fetchModule as fetch_module }` and `import { foo_bar as fooBar }` becomes
+  `import { foo_bar }`, a colliding rename is reported without a fix, only `typeof`, `asserts` and
+  `is` inside `{ }` of a JSDoc comment are renamed with the parameter, and in a `.svelte` file the
+  `$camelCase` subscriptions are renamed with the store in one fix, while outside one `$camelCase`
+  stays a name of its own and nothing is renamed.
+- `svelte-naming-convention` renamed only part of a name and broke the code when another rule's fix
+  overlapped a usage in the same `eslint --fix` pass, such as one inside an argument list
+  `pretty-sequence` reformats, or when a declaration of the name is one the rule does not rename: a
+  function merged with a TypeScript namespace of the same name, as in `.d.ts` files,
+  `declare namespace pLimit` and `declare function pLimit(): pLimit.Limit`, a declaration exported
+  with `export var` next to a `var` of the same name, a parameter that shadows a function of the same
+  name, and a declaration turned off with `// eslint-disable-next-line`, `// eslint-disable-line` or
+  `/* eslint-disable */`, whose usages were renamed anyway. With `fixSameNames`, usages are renamed
+  first and the declaration in a later pass, once no usage of the old name is left, together with the
+  assignments to it and an `export default` of it, so `prefer-const` of the strict config never
+  turns `let lastBid = 1` into a `const` whose `lastBid += 1` was renamed in an earlier pass, and
+  `ascii-order` never moves a default-exported function while the export names it differently; a
+  name whose snake_case form is declared elsewhere is renamed in one fix with its usages; with
+  `fixSameNames: false` a declaration is renamed with its usages instead of without them; and the
+  other names are reported without a fix.
+
+### Added
+
+- `pretty-sequence` and `pretty-imports` take `fixIndent`. With it on, the rule reports a sequence or a
+  list of specifiers whose lines differ from it only in their indentation, as it always did.
+- `ascii-order`, in the strict config: sorts import statements by module path, names in import
+  and export braces, object keys, function declarations next to each other and `describe`, `it` and
+  `test` calls in ASCII order, each turned off with `checkImports`, `checkNames`, `checkKeys`,
+  `checkDeclarations` or `checkTests`. Side-effect imports and a function exported with
+  `export default name` keep their place. When moving an item could change what the code does, such
+  as swapping two object values that call functions, it reports without a fix.
+- `pretty-ternary`, in both configs: breaks a ternary or TypeScript conditional type
+  before `?` and `:` when a branch is another ternary, when it is longer than `maxLength` (80) or
+  when it already spans lines, indenting each nested level once more. Only the spaces around `?`
+  and `:` change.
+- `configs.recommended`, for format on save: the `@stylistic` formatting rules, `pretty-imports`,
+  `pretty-jsdoc-casting`, `pretty-sequence` and `pretty-ternary` with items on one line up to 80
+  characters, and `ascii-order` for the names inside import and export braces only. It ends a file
+  with a line break, allows one blank line, never renames or moves statements or keys, and every
+  rule in it has a fix: `{ ...lube.configs.recommended, files: ["**/*.js"] }`, or
+  `extends: ["lube/recommended"]` with `defineConfig`.
+- `configs.strict`, the house style: everything above plus `svelte-naming-convention`, every
+  `ascii-order` check, `pretty-sequence` and `pretty-imports` at 30 characters, no blank lines, no
+  line break at the end of a file, one statement per line and core rules such as `func-style`,
+  `no-shadow` and `prefer-const`.
+- `meta.version`, so ESLint can cache results per plugin version.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 artxe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,9 +1,123 @@
-# Eslint plugin lube
-## Full fixable rules for auto-formatting with ESLint only without Prettier
-
-| Rule | Docs | Code | Test |
-|---|---|---|---|
-| pretty-imports | [docs](https://github.com/Artxe2/lube-series/blob/master/packages/eslint-plugin-lube/docs/pretty-imports.md) | [code](https://github.com/Artxe2/lube-series/blob/master/packages/eslint-plugin-lube/rules/pretty-imports.js) | [test](https://github.com/Artxe2/lube-series/blob/master/packages/eslint-plugin-lube/test/pretty-imports) |
-| pretty-jsdoc-casting | [docs](https://github.com/Artxe2/lube-series/blob/master/packages/eslint-plugin-lube/docs/pretty-jsdoc-casting.md) | [code](https://github.com/Artxe2/lube-series/blob/master/packages/eslint-plugin-lube/rules/pretty-jsdoc-casting.js) | [test](https://github.com/Artxe2/lube-series/blob/master/packages/eslint-plugin-lube/test/pretty-jsdoc-casting) |
-| pretty-sequence | [docs](https://github.com/Artxe2/lube-series/blob/master/packages/eslint-plugin-lube/docs/pretty-sequence.md) | [code](https://github.com/Artxe2/lube-series/blob/master/packages/eslint-plugin-lube/rules/pretty-sequence.js) | [test](https://github.com/Artxe2/lube-series/blob/master/packages/eslint-plugin-lube/test/pretty-sequence) |
-| svelte-naming-convention | [docs](https://github.com/Artxe2/lube-series/blob/master/packages/eslint-plugin-lube/docs/svelte-naming-convention.md) | [code](https://github.com/Artxe2/lube-series/blob/master/packages/eslint-plugin-lube/rules/svelte-naming-convention.js) | [test](https://github.com/Artxe2/lube-series/blob/master/packages/eslint-plugin-lube/test/svelte-naming-convention) |
+# ESLint Plugin Lube
+Fixable formatting and ordering rules, so `eslint --fix` formats a project without Prettier.
+
+Instead of Prettier next to ESLint, with a second config and a plugin to keep the two from fighting, formatting is a set of ESLint rules: one `eslint --fix` formats and lints, and each rule can be tuned or turned off like any other.
+
+## Installation
+```bash
+npm i -D eslint eslint-plugin-lube
+```
+Requires ESLint 9 or later and Node.js 18.18+, 20.9+ or 21.1+; a CommonJS `eslint.config.cjs` needs Node.js 20.19+ or 22.12+ to `require` it. `@stylistic/eslint-plugin` is installed with the plugin.
+
+## Usage
+```js
+// eslint.config.js
+import lube from "eslint-plugin-lube"
+
+export default [
+    {
+        ...lube.configs.recommended,
+        files: ["**/*.js", "**/*.ts"]
+    }
+]
+```
+`eslint --fix` with `recommended` turns this:
+```js
+import {writeFile,readFile} from 'node:fs/promises';
+
+export async function copy(from,to){
+  const text=await readFile(from,'utf8');
+  await writeFile(to,text.replace(/\r\n/g,'\n'),{encoding:'utf8',flag:'wx',mode:0o644,flush:true});
+  return text.length>1000?text.length>100000?'large':'medium':'small';
+}
+```
+into this:
+```js
+import { readFile, writeFile } from "node:fs/promises"
+
+export async function copy(from, to) {
+	const text = await readFile(from, "utf8")
+	await writeFile(
+		to,
+		text.replace(/\r\n/g, "\n"),
+		{ encoding: "utf8", flag: "wx", mode: 0o644, flush: true }
+	)
+	return text.length > 1000
+		? text.length > 100000
+			? "large"
+			: "medium"
+		: "small"
+}
+```
+
+For TypeScript files, add the parser from `@typescript-eslint/parser`:
+```js
+// eslint.config.js
+import tsParser from "@typescript-eslint/parser"
+import lube from "eslint-plugin-lube"
+
+export default [
+    {
+        ...lube.configs.recommended,
+        files: ["**/*.js", "**/*.ts"],
+        languageOptions: { parser: tsParser }
+    }
+]
+```
+With `defineConfig`, extend the config by name:
+```js
+// eslint.config.js
+import { defineConfig } from "eslint/config"
+import lube from "eslint-plugin-lube"
+
+export default defineConfig({
+    extends: ["lube/recommended"],
+    files: ["**/*.js"],
+    plugins: { lube }
+})
+```
+
+### Choosing a config
+Both configs are flat config objects with `plugins` and `rules`, and differ in how much they decide for you. Start with `recommended`; take `strict` for a code base that follows the Svelte code conventions or wants every choice made for it.
+
+**`configs.recommended`** only formats and orders, and every rule in it has a fix, so it suits format on save.
+- The `@stylistic` formatting rules: tab indentation, double quotes, no semicolons, spacing and line breaks.
+- `pretty-imports`, `pretty-jsdoc-casting`, `pretty-sequence` and `pretty-ternary`, with items on one line up to 80 characters.
+- `ascii-order` for the names inside import and export braces only.
+- A line break at the end of a file and at most one blank line, as editors write them.
+- It never renames an identifier, never moves an import, key, function or test, and reports nothing about what the code does.
+
+**`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-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.
+- `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.
+- Disable the rule where key or import order matters; [ascii-order](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/ascii-order.md) lists what it does not fix.
+
+### Changing a rule
+Override a rule after the spread: `rules: { ...lube.configs.recommended.rules, "@stylistic/indent": ["error", 4] }`.
+- Formatting rules go by their `@stylistic/` name.
+- An indentation of your own also goes to the `indent` option of `pretty-imports`, `pretty-sequence` and `pretty-ternary`, or those rules and `@stylistic/indent` keep rewriting each other's fixes.
+- `pretty-sequence` writes the items of an array, object or call one per line once they are longer than its `maxLength` together, 80 in `recommended` and 30 in `strict`: `"lube/pretty-sequence": ["error", { maxLength: 100 }]`.
+- Every option of a rule is checked, so a misspelled option is a configuration error.
+
+## 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-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 |
+| [pretty-ternary](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/pretty-ternary.md) | Nested and long ternaries broken before `?` and `:`, one indent deeper per level | yes |
+| [svelte-naming-convention](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/svelte-naming-convention.md) | snake_case declarations, following the Svelte code conventions | no |
+
+## What it is not
+- **Not a formatter you run on its own.** There is no CLI and no config file: the rules run inside `eslint --fix`, and a file ESLint does not lint is not formatted.
+- **Not a whole style guide.** `recommended` only formats and orders, and every rule it turns on has a fix. The opinions, such as renaming and the core rules, are in `strict`, which is the house style of this repository rather than a recommendation.

package/docs/ascii-order.md

@@ -0,0 +1,81 @@
+# ascii-order
+Sorts import statements, import and export names, object keys, function declarations and test cases in ASCII order, so uppercase before lowercase. The strict config turns all five on; the recommended config only sorts names inside import and export braces, which never changes what the code does.
+
+- **Import statements** next to each other, by module path: `"../a.js"`, `"./b.js"`, `"c"`, `"node:d"`. Side-effect imports such as `import "polyfill"` keep their place and split the imports into groups.
+- **Names** in import and export braces, by the name written first: `import def, { B, a as c }`, `export { a as z, b }`.
+- **Keys** of object literals, destructuring patterns, TypeScript type literals and interfaces. Spread, rest, computed keys and index signatures split the keys into groups sorted on their own. Under `exports` and `imports` of a `package.json`, where conditions match in order, `types` goes first and `default` last, and the conditions between them are in ASCII order.
+- **Function declarations** next to each other in the same block, TypeScript overloads included. A function exported with `export default name` keeps its place.
+- **Test cases**: `describe`, `it` and `test` calls next to each other with a string title, `it.skip` and `test.only` included.
+
+Comments on their own lines above an item and comments after it on the same line move with it.
+Nested objects, patterns and braces are sorted in the same pass.
+
+The fix assumes three things it cannot see, and changes behavior where they do not hold:
+- **Modules evaluate in any order.** Moving an import statement changes the order in which its module and the modules it imports run their top-level code. A module whose top-level code has to run first, such as a polyfill or a setup file, is imported without names, `import "./setup.js"`, which the rule never moves and never moves another import across. Disable the rule for the other imports whose order matters.
+- **Key order is not observed.** Sorting keys changes the order of `Object.keys`, `Object.entries`, `JSON.stringify` and `for...in`, so an object literal serialized or iterated in a written order changes its output, and a destructuring pattern reads the properties, running their getters, in the new order. Integer-like keys such as `2` and `10` are listed in numeric order by JavaScript anyway. A key written twice keeps its last value.
+- **Tests do not depend on each other.**
+
+Where the order matters, disable the rule for that statement, `// eslint-disable-next-line lube/ascii-order`, or turn off one kind with the options below.
+
+Beyond that, only the error is reported, without a fix, when moving would change what the code evaluates or where comments end up. The message then says why and names the value that keeps it in place, as in ``Move key "a" before "b" to keep keys in ASCII order; it is not fixed automatically because moving `f()` could change the order of side effects, so reorder it by hand``:
+- An object value that calls a function, constructs an object, assigns, updates, deletes, awaits or yields would change places with another value that is not a constant or a function. A variable is a constant when it is a `const`, a namespace import (`import * as x`), or a function or class declaration that is never assigned, and the value is the variable itself, also inside an array, `!x`, `typeof x`, `x === y`, `a ? x : y` or `x ?? y`; `x.y`, `` `${x}` ``, `-x`, `x + 1` and `...x` can run code of `x`. A `let`, `var`, parameter, global or named import, which the exporting module can reassign, still counts as a variable a call may change, so `{ b: f(), a: x }` is fixed only for such a constant `x`. A `const` or class counts only where the value comes after its declaration and not inside a function declaration, which can run before it: reading it earlier throws in its temporal dead zone, and moving the read before `f()` would throw before `f()` runs. Constructing a built-in counts as reading a variable: it reads the global of the constructor, which a call may replace, so it never moves across a call, while `{ updatedAt: new Date(), createdAt: new Date() }` and `{ s: new Set([ 1 ]), m: new Map() }` are fixed: `new` of `Array`, `ArrayBuffer`, `Date`, `Map`, `RegExp`, `Set`, `WeakMap`, `WeakSet`, the typed arrays such as `Uint8Array`, and `Error` and its subclasses except `AggregateError`, when the name is not declared in the file and every argument is built only from literals, `undefined`, `NaN`, `Infinity`, templates without expressions, negative numbers, array and object literals and such constructions, and when the construction does not throw with those arguments, which the rule tries while linting: `new RegExp("(")`, `new Array(-1)`, `new Set(1)`, `new Map([ 1 ])`, `new WeakSet([ 1 ])` and `new URL("/a")` would throw before the values moved in front of them run, and are not fixed. The runtime that lints is not the one that runs the code, so `new RegExp` is fixed only with the flags `g`, `i`, `m`, `s`, `u` and `y` and the syntax of ES2018: `new RegExp("a", "v")`, the `d` flag, modifiers such as `(?i:a)` and a group name used twice may throw in an older runtime, and are not fixed. The same goes for `DataView` and `URL`, as in `new DataView(new ArrayBuffer(8))` and `new URL("a", "https://example.com")`. An `Array`, `ArrayBuffer`, typed array or `DataView` with a number, a numeric string or an object property over 65536 in its arguments, as in `new Array(1e8)`, `new ArrayBuffer(8, { maxByteLength: 1e9 })` or `new Uint8Array({ length: 1e9 })`, is not tried and not fixed, since trying it would allocate that much while linting. Two `new Date()` values may then read the clock in the other order. `new Date(x)` and `new Set(items)` can run code of `x` and `items`, and are not fixed.
+- A destructuring default that is not a constant would change places with another key.
+- A destructuring target is assigned by two keys, or a member such as `this.a` would change places with another key.
+- A comment shares a line with two items, or a line comment would end up before a closing bracket.
+- The first statement of a file has comments before it and would move.
+- A statement without a semicolon would end up on a line with the next one, as in `import b from "b"; import a from "a"`.
+
+## options
+```js
+schema: [
+    {
+        additionalProperties: false,
+        properties: {
+            checkDeclarations: { default: true, type: "boolean" },
+            checkImports: { default: true, type: "boolean" },
+            checkKeys: { default: true, type: "boolean" },
+            checkNames: { default: true, type: "boolean" },
+            checkTests: { default: true, type: "boolean" }
+        },
+        type: "object"
+    }
+]
+```
+### checkDeclarations
+If it is `true`, it sorts function declarations.
+### checkImports
+If it is `true`, it sorts import statements.
+### checkKeys
+If it is `true`, it sorts object keys.
+### checkNames
+If it is `true`, it sorts the names in import and export braces.
+### checkTests
+If it is `true`, it sorts test cases.
+
+## Valid
+```js
+import { A, B, a } from "a-module"
+import value from "b-module"
+const object = { a: 1, b: 2, ...rest, a_b: 3 }
+function main() {}
+function b() {}
+function c() {}
+export default main
+it("a", () => {})
+it("b", () => {})
+```
+
+## Invalid
+```js
+import other from "b-module"
+import { y, x } from "a-module"
+const value = { b: 1, a: 2 }
+function b() {}
+function a() {}
+it("b", () => {})
+it("a", () => {})
+// reported without a fix: g() would run before f()
+const later = { b: f(), a: g() }
+// fixed: constructing a built-in from literals runs no code of the file
+const empty = { s: new Set([ 1 ]), m: new Map() }
+```

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[]} */([])/**/
+```