eslint-plugin-lube 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # Changelog
 
+## 0.9.0
+
+### Breaking
+
+- **The strict and recommended configs use `lube/indent` instead of `@stylistic/indent`**: options and disable
+  comments for `@stylistic/indent` no longer apply to them, so set the indentation with `lube/indent`. The plugin's
+  `@stylistic/indent` is `@stylistic/eslint-plugin`'s own rule again, no longer wrapped. `recommended` now indents a
+  line that starts with an operator (`&&`, `||`, `+`) one level deeper than the line its expression starts on, also
+  when the expression starts its own line after `(`, `[` or `=`, every such line of one expression at that same
+  level; the `*` lines of a block comment align under its `/*`; and a line inside a Svelte template expression is
+  indented as JavaScript from the indent of the line that holds the expression's `{`, while markup lines and `$:`
+  statements stay as they are. A bracket opened in the middle of a line, as in `} of f(`, `); i < bar(` or
+  `|| b).catch(`, indents its contents one level deeper than that line, where `@stylistic/indent` indented them from
+  the line their expression starts on, and its closer goes back to that line's indent; the body of a statement (`if`,
+  `for`, `while`, `switch`, a function or a class) still indents from the statement's first line, wherever its `{`
+  lands.
+  A line that starts with a comment followed by code, such as a JSDoc cast, is indented like that code. Run
+  `eslint --fix` once to re-indent existing code.
+- **The strict config moves nested function declarations below the last statement of their function** with the new
+  `closures-last`: a function declaration inside a function body goes below the `return`, or to the bottom of the
+  body when there is none. The moved functions come in `ascii-order`'s order when that rule checks declarations for
+  the file, and keep their source order otherwise. It has a fix, so run `eslint --fix` once; a moved function whose
+  parameter or local has the name of a variable of the enclosing function is then reported by `no-shadow`, so rename
+  it by hand.
+- **The strict and recommended configs write a JSDoc block of one tag on one line** with the new
+  `pretty-jsdoc-lines`: a block of several lines holding one tag and no description becomes `/** @returns {void} */`,
+  and a one-line block of two or more tags is split, one tag a line. A tag whose type spans lines and a block with a
+  description, a blank line or an `@example` stay as they are. It has a fix, so run `eslint --fix` once.
+- **The strict config requires a `@returns` tag** with the new `require-returns`, on every function declaration and
+  every function held by a `const`. Its fix adds `@returns {void}` (`Promise<void>` for an async function) to a
+  function that returns no value; write the type of the others by hand.
+- **The strict config forbids loose types** with the new `no-loose-types`: `any`, `*`, `object` and `Object` in the
+  type of a JSDoc tag or a TypeScript annotation are reported, while a property or parameter of that name is not. It
+  has no fix; write the real type, or `unknown` for a value that is really arbitrary.
+- **The strict config forbids `@typedef` and `@callback`** with the new `no-typedef`: both JSDoc tags are reported.
+  It has no fix; declare the type in a `.d.ts` file and name it with `import("./types.js").Name`.
+- **The strict config forbids a statement that starts with `(`, `[` or a template literal** with the new
+  `no-ambiguous-start`, also behind a leading JSDoc cast, since without semicolons it joins the line above. It has no
+  fix; assign the value to a `const` first.
+
+### Changed
+
+- **The strict config's fixes settle in fewer passes**: a fix of a `lube` or `@stylistic` rule covers only the text it
+  changes, so it no longer blocks the fixes of other rules next to it within the same `eslint --fix` pass.
+- **`closures-last` fixes bodies with a line that starts with a guarding `;`**: a statement after `"use strict"\n;` or
+  `;[ a ].map(f)` moves like any other, and a moved statement keeps its `;` where the code needs it.
+- **`closures-last` fixes a body where a statement starting with `(`, `[`, `` ` ``, `+`, `-`, `/` or `<` follows a
+  function declaration**: when moving the function would let that statement continue the one before it, the fix puts
+  a `;` at its start, as in `var x = 1\n;(x)`. The strict config, whose `@stylistic/no-extra-semi` removes the `;`
+  written after a function declaration, no longer ends with a `closures-last` report it cannot fix there.
+- **The strict config indents a line that starts with a binary or logical operator** (`||`, `&&`, `??`, `+`,
+  `===`, ...): at the indent of its expression when the expression starts a line of its own, as in `if (\n\ta\n\t&& b\n)`,
+  and one level deeper than the line the expression starts on otherwise, as in `return a\n\t|| b`. The lines of the
+  operand after it, a call `pretty-sequence` splits there among them, move with it in the same pass. Run
+  `eslint --fix` once to re-indent existing code.
+
+### Added
+
+- `pretty-parens`, in the strict and recommended configs: a grouping parenthesis, the parentheses of `if`, `while`,
+  `do ... while`, `for`, `switch`, `catch` and `with`, and the `${ }` of a template literal that hold an expression
+  spanning lines are written either as `(a\n\tb)`, the closing bracket right after the last token, or as
+  `(\n\ta\n\tb\n)`, the closing bracket on its own line when the opening bracket ends its line. Mixed forms are fixed
+  to the form the opening bracket starts; when a line comment ends the content, the fix breaks after the opening
+  bracket instead. JSDoc casts stay with `pretty-jsdoc-casting`, and the brackets of calls, parameters, arrays and
+  objects with `pretty-sequence`.
+- `lube/indent`, in the strict and recommended configs: reports and fixes the indentation of every line, computed
+  from the syntax tree. The first option is `"tab"` or a number of spaces; the second sets `SwitchCase` and
+  `binaryOperator`, both `1` by default and `SwitchCase: 0` in the configs.
+- `closures-last`, in the strict config: reports a function declaration that has another statement after it in the
+  body of a function, a function expression or an arrow function, and fixes it by moving the declarations to the end
+  of the body in their source order, each with the comments above it and the comment after it on its line, and its
+  overload signatures. The top level of a file, nested blocks and functions assigned to variables stay. A body that
+  shares a line with its statements, or a statement that would move up while starting with `(`, `[`, `` ` ``, `+`,
+  `-`, `/` or `<`, is reported without a fix.
+
+### Fixed
+
+- `eslint --fix` with the strict config finishes in one run on files that need many renames: it used to stop
+  after its 10 passes with renames and formatting left. `svelte-naming-convention` now renames every fixable name of a
+  file, with its declarations, usages and export specifiers, in one fix, whatever `fixSameNames` is, which only
+  decides whether usages are reported too. A name with a usage on a line turned off by `eslint-disable` is reported
+  without a fix, like one with a declaration there.
+- `max-statements-per-line` in the strict config puts every declaration of a line like
+  `var a; var b; var c` on its own line in one pass instead of one per pass.
+- In a file whose line breaks are CR alone, `eol-last` counts a final CR as the line break at the end of the file:
+  `eslint --fix` with the recommended config used to stop with circular fixes there, and now ends the file with
+  exactly one CR; the strict config now removes the final CR as it removes a final LF or CRLF.
+
+## 0.8.1
+
+### Fixed
+
+- `svelte-naming-convention` no longer reports or renames an ambient TypeScript declaration (`declare function`, `declare const`, `declare let`, `declare var`, `declare class`, and anything inside `declare global { }` or `declare module "m" { }`) or its usages, since the name belongs to the host that injects it.
+- `svelte-naming-convention` renames every overload signature and the implementation of a function together with its calls, instead of only the calls.
+
 ## 0.8.0
 
 ### Breaking

package/README.md

@@ -82,7 +82,8 @@ Both configs are flat config objects with `plugins` and `rules`, and differ in h
 
 **`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.
+- `pretty-imports`, `pretty-jsdoc-casting`, `pretty-parens`, `pretty-sequence` and `pretty-ternary`, with items on one line up to 80 characters.
+- `pretty-jsdoc-lines`, which writes a JSDoc block of one tag on one line and a block of several tags one tag a line.
 - `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.
@@ -91,9 +92,13 @@ Both configs are flat config objects with `plugins` and `rules`, and differ in h
 - `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).
+- `closures-last`, which moves the function declarations inside a function body below its other statements ([closures-last](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/closures-last.md)).
+- `require-returns`, which asks for a `@returns` tag on every function declaration and every function held by a `const`, and adds `@returns {void}` to one that returns no value ([require-returns](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/require-returns.md)).
+- `no-loose-types`, `no-typedef` and `no-ambiguous-start`, which report `any`, `*`, `object` and `Object` in types, the tags `@typedef` and `@callback`, and a statement starting with `(`, `[` or a template literal ([no-loose-types](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/no-loose-types.md), [no-typedef](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/no-typedef.md), [no-ambiguous-start](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/no-ambiguous-start.md)).
 - `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.
+- A line that starts with `||`, `&&`, `+` or another binary operator indented under its expression, one level deeper than the line the expression starts on (the `binaryOperator` option of `lube/indent`, which `recommended` sets too).
 - `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`.
@@ -101,9 +106,9 @@ In `strict`, `ascii-order` fixes import order assuming modules can run in any or
 - 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.
+Override a rule after the spread: `rules: { ...lube.configs.recommended.rules, "lube/indent": ["error", 4] }`.
+- Formatting rules go by their `@stylistic/` name, except indentation, which is `lube/indent`.
+- An indentation of your own also goes to the `indent` option of `pretty-imports`, `pretty-parens`, `pretty-sequence` and `pretty-ternary`, or those rules and `lube/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.
 
@@ -111,13 +116,21 @@ 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 |
+| [closures-last](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/closures-last.md) | Function declarations inside a function body below its other statements, since they are hoisted | no |
 | [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 |
+| [indent](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/indent.md) | Indentation of every line computed from the syntax tree, including lines that start with an operator, the `*` lines of block comments and the template expressions of `.svelte` files | yes |
+| [no-ambiguous-start](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/no-ambiguous-start.md) | No statement starting with `(`, `[` or a template literal, which joins the line above without semicolons | no |
+| [no-loose-types](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/no-loose-types.md) | No `any`, `*`, `object` or `Object` in JSDoc tag types and TypeScript annotations | no |
+| [no-typedef](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/no-typedef.md) | No `@typedef` or `@callback` JSDoc tags | 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-jsdoc-lines](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/pretty-jsdoc-lines.md) | A JSDoc block of one tag on one line, and a block of several tags one tag a line | yes |
+| [pretty-parens](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/pretty-parens.md) | Parentheses, statement headers and `${ }` that hold a multi-line expression closed right after the last token, or on their own line when the opener ends its line | 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 |
+| [require-returns](https://github.com/artxe/lube-series/blob/master/packages/eslint-plugin-lube/docs/require-returns.md) | A JSDoc `@returns` tag on every function declaration and every function held by a `const` | no |
 | [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

package/docs/closures-last.md

@@ -0,0 +1,34 @@
+# closures-last
+Enforces the function declarations inside a function body below all its other statements: below the `return`, or at the bottom of the body when there is none. A function declaration is hoisted, so moving it never changes what the code does.
+
+- Checked are the statements directly in the body of a function declaration, a function expression or an arrow function.
+- Not checked: the top level of a file, blocks inside a body (`if`, loops, `static` blocks, TypeScript namespaces), and arrow functions or function expressions assigned to variables, which are not hoisted.
+- TypeScript overload signatures move with their implementation.
+- The fix moves the declarations to the end of the body, keeping the comments above each one (JSDoc, `eslint-disable-next-line`, `@ts-expect-error`) and the comment after it on its line. The file's own line breaks are kept.
+- A body whose statements share a line, `function f() { function a() {} return a }`, is reported without a fix.
+- A statement starting with `(`, `[`, a template literal or an operator that moving a function would join to the statement before it, as a semicolon-free file reads them as one expression, gets a `;` at its start: `var x = 1\nfunction a() {}\n(x)` becomes `var x = 1\n;(x)\nfunction a() {}`. One after a statement ending with `;` or with the brace of a block, such as `if (x) {}`, stays as it is.
+- With `ascii-order` enabled for the file and `checkDeclarations` on, the fix emits the moved declarations in `ascii-order`'s order (overloads of one name stay together), so that rule has nothing left to reorder; otherwise they keep their source order.
+
+## options
+None.
+
+## Valid
+```js
+function outer() {
+    return inner
+    function inner() {}
+}
+
+function other() {
+    const handler = () => 1
+    return handler
+}
+```
+
+## Invalid
+```js
+function outer() {
+    function inner() {}
+    return inner
+}
+```

package/docs/indent.md

@@ -0,0 +1,102 @@
+# indent
+Enforces the indentation of every line, computed from the syntax tree, and fixes it.
+
+- A line is indented one level deeper than the line its enclosing block, bracket pair or expression starts on.
+- A line that starts with a binary or logical operator (`&&`, `||`, `??`, `+`, ...) is indented `binaryOperator` levels deeper than the line its expression starts on.
+- The `*` lines of a block comment align under the `/*` that opens it.
+- In a `.svelte` file, a line inside a template expression is indented as JavaScript from the indent of the line that holds the expression's `{`. Markup lines and `$:` statements are left as they are.
+
+## options
+```js
+schema: [
+    {
+        additionalProperties: false,
+        anyOf: [
+            { enum: ["tab"] },
+            { minimum: 0, type: "integer" }
+        ]
+    },
+    {
+        additionalProperties: false,
+        properties: {
+            SwitchCase: { minimum: 0, type: "integer" },
+            binaryOperator: { minimum: 0, type: "integer" }
+        },
+        type: "object"
+    }
+]
+```
+The first option is `"tab"` or the number of spaces of one level. The second is an object.
+### SwitchCase
+The levels a `case` is indented past its `switch`. The default is `1`; the `strict` and `recommended` configs set `0`.
+### binaryOperator
+The levels a line that starts with an operator is indented past the line its expression starts on. The default is `1`; with `0` such a line stays at the indent of its expression.
+
+## Valid
+```js
+function f() {
+	return 1
+}
+const a = b
+	|| c
+f(
+	a
+	|| b
+)
+switch (a) {
+case 1:
+	b()
+}
+/**
+ * @param {number} a
+ */
+function g(a) {}
+```
+`switch` with `["error", "tab", { SwitchCase: 0 }]`. With `["error", "tab", { binaryOperator: 0 }]`, `const a = b\n|| c` is valid.
+```svelte
+<div>
+	{a.map(b => {
+		return b
+	})}
+	{#if a
+		&& b}
+		<p />
+	{/if}
+</div>
+```
+
+## Invalid
+```js
+function f() {
+    return 1
+}
+const a = b
+|| c
+f(
+	a
+		|| b
+)
+if (a) {
+	/**
+		 * b
+		 */
+	b()
+}
+```
+```svelte
+<div>
+	{a.map(b => {
+	return b
+	})}
+</div>
+{#if a
+&& b}
+	<p />
+{/if}
+{#snippet a(
+		b,
+		c
+)}
+	<p />
+{/snippet}
+```

package/docs/no-ambiguous-start.md

@@ -0,0 +1,23 @@
+# no-ambiguous-start
+Disallows an expression statement that starts with `(`, `[` or a template literal.
+
+- Without semicolons such a statement joins the line above and becomes a call, an index or a tagged template of it.
+- A JSDoc cast in front is not a token, so `/** @type {T} */(x).y = 1` counts too.
+- Assign the value to a `const` first, or write the statement another way.
+- It has no fix.
+
+## options
+None.
+
+## Valid
+```js
+const result = (a || b).run()
+foo()
+```
+
+## Invalid
+```js
+(a || b).run()
+;[a, b] = [b, a]
+`x`.trim()
+```

package/docs/no-loose-types.md

@@ -0,0 +1,25 @@
+# no-loose-types
+Disallows `any`, `*`, `object` and `Object` in the type of a JSDoc tag (`@type`, `@param`, `@returns`, `@template`, ...) and in TypeScript type annotations.
+
+- Use `unknown` where the value is really arbitrary, or its real type.
+- A property or parameter named `any` or `object`, a member such as `obj.any` and text inside a string are not types and stay valid.
+- It has no fix, since the type is yours to write.
+
+## options
+None.
+
+## Valid
+```js
+/** @type {Record<string, unknown>} */
+const bag = {}
+```
+
+## Invalid
+```js
+/** @type {any} */
+let a
+/** @param {*} value */
+function f(value) {}
+/** @returns {Promise<object>} */
+async function g() {}
+```

package/docs/no-typedef.md

@@ -0,0 +1,24 @@
+# no-typedef
+Disallows the JSDoc tags `@typedef` and `@callback`.
+
+- Declare the type in a `.d.ts` file and use it through `import("./types.js").Name` or a `/** @import */` tag.
+- A tag inside a `/* */` comment that is not JSDoc, a `//` comment or a string is not checked.
+- It has no fix, since the type moves to another file.
+
+## options
+None.
+
+## Valid
+```js
+/** @type {import("./types.js").Name} */
+let name
+```
+
+## Invalid
+```js
+/** @typedef {string} Name */
+/**
+ * @callback Run
+ * @returns {void}
+ */
+```

package/docs/pretty-jsdoc-lines.md

@@ -0,0 +1,30 @@
+# pretty-jsdoc-lines
+Enforces a JSDoc block of one tag on one line, and a block of two or more tags with one tag a line.
+
+- A block of several lines that holds one tag and no description is joined into one line: `/** @returns {void} */`. A tag whose type spans lines, such as `@param {{\n * a: number\n * }} total`, is left alone, because the line breaks separate the members of a type literal. A block with a description, a blank line or an `@example` is left alone.
+- A one-line block that holds two or more tags is split, one tag a line, a description first. A block that does not start its line is reported without a fix.
+- Braces keep `{@link A}` and the types of the tags from being read as tags.
+
+## options
+None.
+
+## Valid
+```js
+/** @returns {void} */
+function f() {}
+/**
+ * @param {number} count
+ * @returns {void}
+ */
+function g(count) {}
+```
+
+## Invalid
+```js
+/**
+ * @returns {void}
+ */
+function f() {}
+/** @param {number} count @returns {void} */
+function g(count) {}
+```

package/docs/pretty-parens.md

@@ -0,0 +1,59 @@
+# pretty-parens
+Writes a bracket that holds an expression spanning lines in one of two forms: the closing bracket right after the last token when the opening bracket is followed by content, or on a line of its own when the opening bracket ends its line.
+
+- It checks the grouping parentheses of an expression, the parentheses of `if`, `while`, `do ... while`, `for`, `for ... in`, `for ... of`, `switch`, `catch` and `with`, and the `${ }` of a template literal.
+- A bracket whose content sits on one line is left alone. The arguments of calls, function parameters, arrays, objects and imports belong to `pretty-sequence`.
+- If the opening bracket is followed by content on its line, the line break before the closing bracket is removed. If the opening bracket ends its line, a line break and the indent of the opening bracket's line are put before the closing bracket. A line comment right after the opening bracket counts as ending its line.
+- When a line comment ends the content, the closing bracket cannot move up, so the fix breaks after the opening bracket instead.
+- The parentheses of a JSDoc cast, `/** @type {T} */(value)/**/`, are left to `pretty-jsdoc-casting`, which writes them without white space inside.
+- Only the white space next to the bracket changes, so the content keeps its text and comments.
+
+## options
+```js
+schema: [
+    {
+        additionalProperties: false,
+        properties: {
+            indent: { default: "\t", type: "string" }
+        },
+        type: "object"
+    }
+]
+```
+### indent
+The string of one indentation level, used when the fix breaks after an opening bracket. Match it to `lube/indent`, or the two rules keep rewriting each other's fixes.
+
+## Valid
+```js
+var value = (a
+    || b)
+var value = (
+    a
+    || b
+)
+if (a
+    || b) {
+}
+if (
+    a
+    || b
+) {
+}
+var text = `${a
+    ? b
+    : c}`
+```
+
+## Invalid
+```js
+var value = (a
+    || b
+)
+var value = (
+    a
+    || b)
+if (a
+    || b
+) {
+}
+```

package/docs/require-returns.md

@@ -0,0 +1,21 @@
+# require-returns
+Requires a `@returns` tag in the JSDoc of every function declaration and every function held by a `const`.
+
+- Methods, object members, callbacks and functions held by `let` or `var` are not checked.
+- The fix adds `@returns {void}` (`@returns {Promise<void>}` for an async function), creating the block when there is none, only when the function returns no value. A function that returns a value, a generator, and one whose declaration or JSDoc does not start its line are reported without a fix, since the type is yours to write.
+- `@return` counts as a tag too.
+
+## options
+None.
+
+## Valid
+```js
+/** @returns {number} */
+const count = () => 1
+```
+
+## Invalid
+```js
+function run() {}
+const count = () => 1
+```

package/docs/svelte-naming-convention.md

@@ -4,12 +4,13 @@ The strict config turns it on and the recommended config leaves it off, since it
 
 - 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 such as assignments, function bodies, `extends` clauses, JSX and TypeScript expressions are only renamed along with their declaration; `fixSameNames` sets whether they are reported.
 - 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.
+- An ambient TypeScript declaration, `declare function acquireVsCodeApi(): Api`, `declare const`, `declare class`, or anything inside `declare global { }` or `declare module "m" { }`, names a binding the code does not own: it is neither reported nor renamed, and neither are its usages.
 - 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.
+- 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 or a usage 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
@@ -24,10 +25,8 @@ schema: [
 ]
 ```
 ### 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.
+If it is `true`, every usage of a reported declaration is reported too; if it is `false`, only the declaration is.
+Either way, one fix renames every fixable name of the file with all its declarations, usages, assignments, `export { }` specifiers and `export default`, so `eslint --fix` finishes the renames in one pass, a half-renamed usage never resolves to another variable, and no other rule sees a variable apart from its writes: `prefer-const` never turns `let lastBid = 1` into a `const` without its `lastBid += 1`.
 ```js
 myFunction() // Only in the case that fixSameNames is true, an error occurs.
 

package/package.json

@@ -7,11 +7,6 @@
     "@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.12.0"
-  },
   "engines": {
     "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
   },
@@ -53,10 +48,10 @@
   },
   "type": "module",
   "types": "types/index.d.ts",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "scripts": {
     "dts": "node ../../scripts/tsc_with_clean.js eslint-plugin-lube",
     "lint": "pnpm -w lint",
-    "test": "pnpm -w exec vitest run --coverage --coverage.include=packages/eslint-plugin-lube/src/** test/eslint-plugin-lube"
+    "test": "pnpm -w exec vitest run test/eslint-plugin-lube"
   }
 }