@lewishowles/lint-config 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.9.0: 2026-10-07
+
+### Changes
+
+- `base` now reports an error for TypeScript non-null assertions (`!`) in `.ts` files and Vue `<script lang="ts">` blocks (`typescript/no-non-null-assertion`). Check for `null` or `undefined` before using the value instead. The rule finds nothing in components or helpers, so upgrading needs no fixes there.
+- `vue` now reports an error when a computed property changes state (`vue/no-side-effects-in-computed-properties`) or runs async code (`vue/no-async-in-computed-properties`). Neither rule finds anything in components or helpers, so upgrading needs no fixes there. `vue/no-mutating-props`, `vue/no-use-v-if-with-v-for` and `vue/require-explicit-emits` will follow once Oxlint supports them.
+- `base` now reports an error when a unit test (`*.test.*` or `*.spec.*`) searches an array for an element by reading its visible text (`testing/no-text-lookups`). Find the element by a `data-test` attribute instead. Playwright and Cypress files are unaffected.
+- `comments/function-documentation` is stricter: a parameter written as an array, such as `function f([x, y])` or `function f(...[x, y])`, now needs one `@param` for the whole array. The tag can have any name, as it can for a destructured object, and a missing tag is reported as `options`. The items inside the array still need no `@param` of their own.
+- `comments/function-documentation` is stricter for object rest properties: `{ a, ...rest }` now needs `@param options.rest`, and `{ a: { ...rest } }` needs `@param options.a.rest`. A documented root name replaces `options` in those paths.
+
+### Fixes
+
+- `comments/function-documentation` now checks properties inside a nested object that has a default value. In `function f({ a: { b = 1 } = {} })`, `b` now needs `@param options.a.b`, as it already did without the `= {}`. Projects that skipped those tags will see new errors.
+- In test files (`*.test.*`, `*.spec.*`, `*.pw.*` and `*.cy.*`), blank lines between calls, awaits, assignments and multiline expressions are now up to you, so you can separate test steps with them. `base` no longer adds or removes those lines in tests. Blank lines around declarations, blocks, `return` and `break` are still checked. If you ran the 0.8 auto-fix on your tests, you may want to restore the blank lines it removed.
+
+## 0.8.0: 2026-10-05
+
+### Changes
+
+- Breaking: `vite-plus` 1.0.0 is now required. Put the selected lint layers in a `vite.config.js` `lint` block; `vp check` and `vp lint` ignore a `.oxlintrc.json` on its own. Use `lintConfig` from `@lewishowles/lint-config/layers` to build the block, with an optional `.oxlintrc.json` for local settings. Vite+ 1.0 also adds its own `vite-plus/prefer-vite-plus-imports` rule, which may report new problems after upgrading.
+- New `./layers` export provides `base`, `vue`, `comments`, and `lintConfig`. The Vue layer includes base, and `lintConfig` carries inherited environments and globals into the Vite+ lint block.
+- `comments/function-documentation` adds an `ignoreInlineArrows` option, enabled by `comments.json` for test files. Arrow functions used as object property values no longer need JSDoc there; other function forms and files keep their existing requirements.
+- `comments/formatting` changes the output of `--fix` for comments. Run `--fix` once after upgrading.
+
+### Fixes
+
+- `comments/formatting` keeps code spans, quotes, colons, Markdown blocks, and descriptions in mixed-tag JSDoc blocks as written. It places free-form tag text at the comment margin, removes a separator hyphen when a tag description moves onto its own line, keeps wrapped parameter, return, and throw descriptions indented, and preserves line breaks between adjacent `//` comments.
+- The documentation rules for functions, variables, configured API calls and classes recognise comments across tool directives such as `eslint-disable-next-line`. `comments/function-documentation` accepts plain or optional JSDoc names for destructured parameters with defaults.
+
 ## 0.7.0: 2026-09-30
 
 ### Changes

package/README.md

@@ -62,6 +62,14 @@ Add the comments layer alongside the base or Vue layer to enforce the comment-fo
 }
 ```
 
+For functions, variables, configured API calls and classes, a tool directive comment such as `// eslint-disable-next-line` may sit between the documentation comment and the code.
+
+For destructured parameters with defaults, document the parent and each property. Plain names such as `result.errors` and optional names such as `[result.errors]` or `[result.errors=[]]` all match `errors = []`. The parent can likewise be `result`, `[result]` or `[result={}]`. A documented default does not have to match the value in the code.
+
+Lines below a free-form tag such as `@description` or `@note` start at the comment margin so they can be pasted into Markdown without becoming a code block. `@example` content is left as written. Wrapped `@param`, `@returns` and `@throws` descriptions keep a four-space hanging indent so each description is easy to scan beneath its tag. A description written as `name - description` loses the hyphen when it moves onto its own line.
+
+Consecutive `//` comments keep their line breaks, and only a line past 80 columns is wrapped.
+
 The Vue component rule reads the raw `.vue` file because Oxlint's JS Plugin API only receives the extracted script block. The comments layer loads its plugin for you, so there's no relative `jsPlugins` path to add. To pick rules yourself instead, add the plugin directly:
 
 ```json
@@ -102,36 +110,32 @@ The `comments/variable-declarations` rule accepts a `rootOnly` option to require
 }
 ```
 
+The `comments/function-documentation` rule accepts an `ignoreInlineArrows` option. The comments layer enables it for the same test files, so arrow functions used as object property values do not need JSDoc there. Function declarations, method shorthand, function expression properties, and `const` functions still need JSDoc. Other files keep the default of `false`.
+
 The `comments/class-documentation` rule requires an immediately preceding block comment before class declarations and const-assigned class expressions. Constructors, methods, getters, and setters require full JSDoc; constructors never need an `@returns` tag, and getters and setters need one only when they return a value. Instance and static fields require an immediately preceding line comment.
 
 ### `vp check` configuration
 
-The `vp check` and `vp lint` commands read Oxlint settings only from a `lint` block in `vite.config.js`; they do not read `.oxlintrc.json` directly. If `vite.config.js` is missing, they silently use an unrelated default configuration. You may still see plausible warnings and exit codes, but none of your rules are applied.
+On vite-plus 1.0.0, `vp check` and `vp lint` take their Oxlint settings from the `lint` block in `vite.config.js`. They ignore a `.oxlintrc.json` on its own, even though the Vite+ documentation says `vp lint` finds Oxlint config files by itself. If `vite.config.js` is missing, both commands quietly fall back to default settings. You still see plausible warnings and exit codes, but none of your rules are applied.
 
-Each consuming repo needs a `vite.config.js` with a `lint` block built from the config layer(s) and the repo's `.oxlintrc.json`, imported as JSON. Concatenate the `overrides` arrays from every imported layer before the local overrides so shared file-specific rules still apply. Verify the setup with `vp lint --print-config <file>` and check that your real values, not defaults, are active.
+Each consuming repo needs a `vite.config.js` with a `lint` block. Use `lintConfig` with the layers you want. Oxlint ignores `env` and `globals` in configs listed under `extends`, so `lintConfig` copies them into the `lint` block itself, including values from the layers each one extends. Without that, `no-undef` reports Vue macros such as `defineProps` and browser globals such as `window` (see [docs/limitations.md](docs/limitations.md)). The Vue layer already includes base; add comments only if you want the comment rules. You can pass your project's `.oxlintrc.json` as the second argument to keep its local settings. `lintConfig` ignores the `extends` list in that file, so list every layer you want in the first argument.
 
 ```js
 import { defineConfig } from "vite-plus";
-import lintConfigBase from "@lewishowles/lint-config/base.json" with { type: "json" };
-import lintConfigComments from "@lewishowles/lint-config/comments.json" with { type: "json" };
+import { base, comments, lintConfig } from "@lewishowles/lint-config/layers";
 import oxlintrc from "./.oxlintrc.json" with { type: "json" };
 
-const lint = {
-	...lintConfigBase,
-	env: oxlintrc.env,
-	ignorePatterns: oxlintrc.ignorePatterns,
-	jsPlugins: [...lintConfigBase.jsPlugins, ...lintConfigComments.jsPlugins],
-	overrides: [
-		...(lintConfigBase.overrides ?? []),
-		...(lintConfigComments.overrides ?? []),
-		...(oxlintrc.overrides ?? []),
-	],
-	rules: { ...lintConfigBase.rules, ...lintConfigComments.rules },
-};
-
-export default defineConfig({ lint });
+export default defineConfig({
+	lint: lintConfig([base, comments], oxlintrc),
+});
 ```
 
+For a Vue project, use `lintConfig([vue, comments], oxlintrc)` and import `vue` instead of `base`. The local config is optional; `lintConfig([vue, comments])` also works. If you combine layers by hand, use object layers in `extends` and lift their `env` and `globals` to the top level yourself. Spreading JSON layers together replaces earlier `jsPlugins`, `overrides`, and `rules` arrays or objects.
+
+Verify the setup with `vp lint --print-config <file>` and check that your real values, not defaults, are active. The printed `rules` leave out every rule that comes from a plugin, such as `comments/*` and `@stylistic/*`, even when those rules are running. To check a plugin layer, confirm the plugin is listed in `jsPlugins`, then lint a file that breaks one of its rules.
+
+Vite+ also adds its own `vite-plus` lint plugin, so `vp check` can report rules that this package doesn't define. For example, `vite-plus/prefer-vite-plus-imports` reports imports from `oxlint` packages that Vite+ already provides, such as `oxlint/plugins-dev`.
+
 ## Customising
 
 Your project's `.oxlintrc.json` can override rules, add ignore patterns, add overrides, or add plugins on top of the shared layer.
@@ -186,11 +190,11 @@ Plugins are additive and deduplicated: your local plugins are added to the share
 
 ## Layers
 
-| Layer      | File            | Contents                                                                                        |
-| ---------- | --------------- | ----------------------------------------------------------------------------------------------- |
-| `base`     | `base.json`     | Correctness and formatting rules, import sorting, `import`/`oxc`/`typescript`/`unicorn` plugins |
-| `comments` | `comments.json` | Optional comment-formatting rules, variable-declaration documentation, JSDoc checks             |
-| `vue`      | `vue.json`      | Extends `base`, adds the `vue` plugin, Vue compiler macro globals, Vue-specific rules           |
+| Layer      | File            | Contents                                                                                                                                                                       |
+| ---------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `base`     | `base.json`     | Correctness and formatting rules, import sorting, `import`/`oxc`/`typescript`/`unicorn` plugins; errors when unit tests (`*.test.*`, `*.spec.*`) find elements by visible text |
+| `comments` | `comments.json` | Optional comment-formatting rules, variable-declaration documentation, JSDoc checks                                                                                            |
+| `vue`      | `vue.json`      | Extends `base`, adds the `vue` plugin, Vue compiler macro globals, Vue-specific rules                                                                                          |
 
 ### Import sorting
 
@@ -214,6 +218,23 @@ This puts named imports first, including `import type { … }` and imports with
 
 The base layer reports imports from a parent folder (`../`), with no automatic fix. Same-folder (`./`), `@/` alias and package `#` subpath imports are allowed. After upgrading, any existing `../` imports fail lint until they move to an `@/` alias or, in a package without one, to [package subpath imports](https://nodejs.org/api/packages.html#subpath-imports).
 
+### Text lookups in unit tests
+
+The base layer's `testing/no-text-lookups` rule reports an array search such as `find`, `filter` or `some` when its inline callback reads `.text()`, `.textContent` or `.innerText`. Find the element by a `data-test` attribute instead. It doesn't report data-test lookups, assertions about the text of an element you have already found, or callbacks passed by name. It applies to `*.test.*` and `*.spec.*` files, not Playwright `*.pw.*` or Cypress `*.cy.*` files.
+
+To turn it off, add an override for unit tests to your project's `.oxlintrc.json`:
+
+```json
+{
+	"overrides": [
+		{
+			"files": ["**/*.test.*", "**/*.spec.*"],
+			"rules": { "testing/no-text-lookups": "off" }
+		}
+	]
+}
+```
+
 ## What stays repo-local
 
 - `ignorePatterns`, since every project has different build output and tool directories

package/base.json

@@ -5,6 +5,10 @@
 		{
 			"name": "vite-plus",
 			"specifier": "vite-plus/oxlint-plugin"
+		},
+		{
+			"name": "testing",
+			"specifier": "@lewishowles/lint-config/testing/plugin"
 		}
 	],
 	"categories": {
@@ -26,6 +30,7 @@
 		"no-useless-assignment": "error",
 		"preserve-caught-error": "error",
 		"import/no-relative-parent-imports": "error",
+		"typescript/no-non-null-assertion": "error",
 		"sort-imports": [
 			"error",
 			{
@@ -89,6 +94,48 @@
 		{
 			"files": ["**/vite.config.*", "**/vitest.config.*", "**/playwright*.config.*"],
 			"env": { "node": true }
+		},
+		{
+			"files": ["**/*.test.*", "**/*.spec.*", "**/*.pw.*", "**/*.cy.*"],
+			"rules": {
+				"@stylistic/padding-line-between-statements": [
+					"error",
+					{ "blankLine": "always", "prev": "*", "next": "break" },
+					{ "blankLine": "always", "prev": ["const", "let"], "next": "*" },
+					{ "blankLine": "always", "prev": "*", "next": ["const", "let"] },
+					{ "blankLine": "always", "prev": "*", "next": "return" },
+					{
+						"blankLine": "always",
+						"prev": [
+							"block-like",
+							"class",
+							"do",
+							"for",
+							"function",
+							"if",
+							"switch",
+							"try",
+							"while"
+						],
+						"next": "*"
+					},
+					{
+						"blankLine": "always",
+						"prev": "*",
+						"next": ["block-like", "class", "do", "for", "function", "if", "switch", "try", "while"]
+					},
+					{ "blankLine": "never", "prev": "const", "next": "const" },
+					{ "blankLine": "never", "prev": "let", "next": "let" },
+					{ "blankLine": "always", "prev": "multiline-const", "next": "*" },
+					{ "blankLine": "always", "prev": "*", "next": "multiline-const" }
+				]
+			}
+		},
+		{
+			"files": ["**/*.test.*", "**/*.spec.*"],
+			"rules": {
+				"testing/no-text-lookups": "error"
+			}
 		}
 	],
 	"options": {

package/comments/rules/formatting.js

@@ -656,13 +656,10 @@ function reportLineCommentGroups(context) {
 			});
 		});
 
-		// The group's lines after refilling words from early-wrapped lines.
-		const refilledLines = refillCommentLines(formattedLines, maximumLineLength);
-
 		// The group's text after applying its final line formatting and
 		// placement gap.
 		const formattedText =
-			refilledLines
+			formattedLines
 				.map(({ prefix, text }) => (text === "" ? prefix.trimEnd() : `${prefix}${text}`))
 				.join(getNewline(context.sourceCode.text)) + (placement?.gap ?? "");
 
@@ -833,9 +830,10 @@ function reportBlockComments(context) {
 }
 
 /**
- * The comment-formatting rule: punctuates comments as sentences, refills
- * early-wrapped lines, reindents line-comment groups and wraps any comment past
- * 80 columns, replacing each comment in one edit.
+ * The comment-formatting rule: punctuates comments as sentences and wraps any
+ * comment past 80 columns, replacing each comment in one edit. Block comments
+ * that wrap too early are refilled. Line-comment groups are reindented, but
+ * words never move between their lines.
  */
 export default {
 	meta: {

package/comments/rules/function-documentation.js

@@ -53,6 +53,18 @@ export default {
 	meta: {
 		docs: { description: "Require JSDoc documentation for named functions and methods." },
 		type: "suggestion",
+		schema: [
+			{
+				type: "object",
+				properties: {
+					ignoreInlineArrows: {
+						type: "boolean",
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+		defaultOptions: [{ ignoreInlineArrows: false }],
 	},
 	/**
 	 * Create the rule's node visitors.
@@ -77,13 +89,20 @@ export default {
 				}
 			},
 			/**
-			 * Check a first-level object method for documentation.
+			 * Check a first-level object method for documentation. When the
+			 * ignoreInlineArrows option is on, arrow function values are
+			 * skipped, which suits small inline callbacks.
 			 *
 			 * @param  {object}  node
 			 *     The property node.
 			 */
 			Property(node) {
-				if (!isFirstLevelObjectProperty(node) || !isFunctionValue(node.value)) {
+				if (
+					!isFirstLevelObjectProperty(node) ||
+					!isFunctionValue(node.value) ||
+					(context.options?.[0]?.ignoreInlineArrows &&
+						node.value.type === "ArrowFunctionExpression")
+				) {
 					return;
 				}
 

package/comments/utils/documentation.js

@@ -2,7 +2,7 @@ import { getJSDocContent, isJSDoc } from "./jsdoc.js";
 import {
 	getCommentNeighbours,
 	getCommentText,
-	isDirectiveComment,
+	getImmediateNonDirectiveComment,
 	isLeadingComment,
 } from "./source.js";
 import { getPropertyName } from "./vue-macro.js";
@@ -45,8 +45,8 @@ export function isFunctionValue(node) {
 }
 
 /**
- * Return the JSDoc comment immediately preceding a node, when the comment
- * qualifies as that node's documentation.
+ * Return the JSDoc comment directly above a node, when the comment qualifies as
+ * that node's documentation. Tool directive comments may sit between them.
  *
  * @param  {object}  sourceCode
  *     The Oxlint source code object.
@@ -57,26 +57,21 @@ export function isFunctionValue(node) {
  *     The qualifying JSDoc comment, or null when none precedes the node.
  */
 function getDocumentationComment(sourceCode, node) {
-	// Finds the closest preceding comment.
-	const comment = sourceCode
-		.getAllComments()
-		.findLast((candidate) => candidate.range[1] <= node.range[0]);
+	// The closest comment above the node, looking past tool directive comments.
+	const comment = getImmediateNonDirectiveComment(sourceCode, node);
 
-	if (comment?.type !== "Block" || isDirectiveComment(comment)) {
+	if (comment?.type !== "Block") {
 		return null;
 	}
 
 	// Checks the comments immediately around the documented node.
 	const { next, previous } = getCommentNeighbours(sourceCode, comment);
-	// Confirms there is no blank line before the documented node.
-	const gap = sourceCode.text.slice(comment.range[1], node.range[0]);
 
 	if (
 		!next ||
 		next.range[0] > node.range[0] ||
 		next.range[1] > node.range[1] ||
-		!isLeadingComment(sourceCode, comment, previous) ||
-		!/^\r?\n[ \t]*$/.test(gap)
+		!isLeadingComment(sourceCode, comment, previous)
 	) {
 		return null;
 	}
@@ -117,6 +112,13 @@ function getObjectPatternPaths(sourceCode, node, parentPath) {
 	const paths = [parentPath];
 
 	for (const property of node.properties) {
+		// A rest property holds every key not named before it, so it is
+		// documented at its own dotted path, such as options.rest.
+		if (property.type === "RestElement") {
+			paths.push(`${parentPath}.${property.argument.name}`);
+			continue;
+		}
+
 		if (property.type !== "Property") {
 			continue;
 		}
@@ -140,6 +142,14 @@ function getObjectPatternPaths(sourceCode, node, parentPath) {
 
 		if (value.type === "AssignmentPattern") {
 			paths.push(`[${propertyPath}=${getDefaultValue(sourceCode, value.right)}]`);
+
+			// A defaulted nested object still needs its own properties
+			// documented. The first nested path is the object itself, which
+			// is already listed above with its default, so it is skipped.
+			if (value.left.type === "ObjectPattern") {
+				paths.push(...getObjectPatternPaths(sourceCode, value.left, propertyPath).slice(1));
+			}
+
 			continue;
 		}
 
@@ -157,8 +167,8 @@ function getObjectPatternPaths(sourceCode, node, parentPath) {
  * @param  {object}  node
  *     The parameter node.
  * @param  {string}  [rootPath]
- *     The documented name that starts each path for a destructured object
- *     parameter. Defaults to options.
+ *     The documented name that starts each path for a destructured parameter.
+ *     Defaults to options.
  *
  * @returns  {string[]}
  *     The required JSDoc parameter paths.
@@ -172,6 +182,15 @@ function getParameterPaths(sourceCode, node, rootPath = "options") {
 		return [node.argument.name];
 	}
 
+	// An array is documented as one value. Its items get no paths of their
+	// own because JSDoc has no standard way to name them.
+	if (
+		node.type === "ArrayPattern" ||
+		(node.type === "RestElement" && node.argument.type === "ArrayPattern")
+	) {
+		return [rootPath];
+	}
+
 	if (node.type === "ObjectPattern") {
 		return getObjectPatternPaths(sourceCode, node, rootPath);
 	}
@@ -192,8 +211,9 @@ function getParameterPaths(sourceCode, node, rootPath = "options") {
  *     The JSDoc comment token.
  *
  * @returns  {object}
- *     An object with names, the set of every documented parameter path, and
- *     topLevelNames, the top-level names in the order they are documented.
+ *     An object with names, the set of every documented parameter path with
+ *     optional brackets and defaults removed, and topLevelNames, the top-level
+ *     names in the order they are documented.
  */
 function getDocumentedParameters(sourceCode, comment) {
 	// Splits the JSDoc block into its individual lines.
@@ -205,21 +225,16 @@ function getDocumentedParameters(sourceCode, comment) {
 
 	for (const line of content) {
 		// Matches an @param tag and captures its documented path.
-		const match = line.trim().match(/^@param(?:\s+\{[^}]+\})?\s+(\[[^\]]+\]|\S+)/);
+		const match = line.trim().match(/^@param(?:\s+\{[^}]+\})?\s+(\S+)/);
 
 		if (match) {
-			// The documented name as written, including optional brackets and
-			// any default value.
-			const name = match[1];
+			// The documented path without optional brackets or a default value.
+			const name = getPlainParameterPath(match[1]);
 
 			names.add(name);
 
-			// Removes optional and default-value syntax before checking for a
-			// nested path.
-			const topLevelName = name.replace(/^\[|\]$/g, "").split("=")[0];
-
-			if (!topLevelName.includes(".")) {
-				topLevelNames.push(topLevelName);
+			if (!name.includes(".")) {
+				topLevelNames.push(name);
 			}
 		}
 	}
@@ -334,10 +349,12 @@ export function reportFunctionDocumentation(context, node, functionNode, options
 	);
 
 	for (const path of parameterPaths) {
-		// The optional JSDoc spelling for this parameter path.
-		const optionalPath = `[${path}]`;
+		// The path without optional brackets or a default. Documented defaults
+		// are not compared with the code, so result.errors, [result.errors] and
+		// [result.errors=[]] all document the same property.
+		const plainPath = getPlainParameterPath(path);
 
-		if (!documentedParameters.has(path) && !documentedParameters.has(optionalPath)) {
+		if (!documentedParameters.has(plainPath)) {
 			context.report({
 				message: `${subject} require an @param for ${path}.`,
 				node,
@@ -366,3 +383,18 @@ export function reportFunctionDocumentation(context, node, functionNode, options
 		});
 	}
 }
+
+/**
+ * Reduce a parameter path to its plain name, so a documented path matches the
+ * required one however the documentation spells it.
+ *
+ * @param  {string}  path
+ *     The documented or required parameter path.
+ *
+ * @returns  {string}
+ *     The path with brackets and any default removed, such as result.errors for
+ *     [result.errors=[]].
+ */
+function getPlainParameterPath(path) {
+	return path.replace(/^\[|\]$/g, "").split("=")[0];
+}