@lewishowles/lint-config 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.9.1: 2026-10-10
+
+### Fixes
+
+- `comments/formatting` accepts a comment as the only thing between a pair of braces, such as in an empty catch block, function body or object literal. It still checks the comment's sentence formatting.
+
+## 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

package/README.md

@@ -190,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
 
@@ -218,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

@@ -347,6 +347,10 @@ function getBlockCommentDisplayLines(commentText, indentation) {
  * the fix never edits the directive. When an ordinary comment sits between them
  * instead, only the indentation is fixed and the gap is left alone.
  *
+ * A comment that is the only thing between a pair of braces, such as in an
+ * empty catch block or object literal, has no code to sit above, so it is left
+ * where it is.
+ *
  * @param  {object}  sourceCode
  *     The Oxlint source code object.
  * @param  {object}  comment
@@ -364,7 +368,11 @@ function getLeadingCommentPlacement(sourceCode, comment, lastComment, comments)
 	// The code token the comment documents, and the token before the comment.
 	const { next, previous } = getCommentNeighbours(sourceCode, comment);
 
-	if (next === null || !isLeadingComment(sourceCode, comment, previous)) {
+	if (
+		next === null ||
+		!isLeadingComment(sourceCode, comment, previous) ||
+		(previous?.value === "{" && next.value === "}")
+	) {
 		return null;
 	}
 

package/comments/utils/documentation.js

@@ -112,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;
 		}
@@ -135,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;
 		}
 
@@ -152,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.
@@ -167,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);
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lewishowles/lint-config",
-	"version": "0.8.0",
+	"version": "0.9.1",
 	"description": "Shared oxlint configuration for Lewis Howles projects",
 	"keywords": [
 		"config",
@@ -25,12 +25,14 @@
 		"comments.json",
 		"imports.json",
 		"layers.js",
+		"testing",
 		"vue.json",
 		"README.md"
 	],
 	"type": "module",
 	"imports": {
-		"#comments/*": "./comments/*"
+		"#comments/*": "./comments/*",
+		"#testing/*": "./testing/*"
 	},
 	"exports": {
 		"./base.json": "./base.json",
@@ -38,6 +40,7 @@
 		"./comments/plugin": "./comments/plugin.js",
 		"./imports.json": "./imports.json",
 		"./layers": "./layers.js",
+		"./testing/plugin": "./testing/plugin.js",
 		"./vue.json": "./vue.json"
 	},
 	"publishConfig": {
@@ -48,7 +51,7 @@
 		"lint:fix": "vp check --fix",
 		"prepare": "vp config --no-agent",
 		"publint": "publint",
-		"test:unit": "node --test test/comments/*.test.js test/layers/*.test.js"
+		"test:unit": "node --test test/comments/*.test.js test/layers/*.test.js test/testing/*.test.js"
 	},
 	"devDependencies": {
 		"publint": "^0.3.22",

package/testing/plugin.js

@@ -0,0 +1,8 @@
+import noTextLookups from "./rules/no-text-lookups.js";
+
+export default {
+	meta: { name: "testing" },
+	rules: {
+		"no-text-lookups": noTextLookups,
+	},
+};

package/testing/rules/no-text-lookups.js

@@ -0,0 +1,148 @@
+// The array methods that count as a lookup when their callback reads an
+// element's text.
+const searchMethods = new Set([
+	"filter",
+	"find",
+	"findLast",
+	"findIndex",
+	"findLastIndex",
+	"some",
+	"every",
+]);
+
+// The DOM properties that hold an element's visible text.
+const textProperties = new Set(["textContent", "innerText"]);
+
+/**
+ * Return whether a callback body reads an element's text anywhere inside it.
+ *
+ * @param  {object}  node
+ *     The callback body, or a node inside it while searching.
+ *
+ * @returns  {boolean}
+ *     Whether any part of the body calls text() or reads textContent or
+ *     innerText.
+ */
+function containsTextRead(node) {
+	// A nested search callback is reported at its own call, so it isn't
+	// counted again here.
+	if (isSearchCallback(node)) {
+		return false;
+	}
+
+	if (isTextRead(node)) {
+		return true;
+	}
+
+	for (const [key, child] of Object.entries(node)) {
+		if (key === "parent") {
+			continue;
+		}
+
+		if (Array.isArray(child)) {
+			for (const entry of child) {
+				if (entry?.type && containsTextRead(entry)) {
+					return true;
+				}
+			}
+		} else if (child?.type && containsTextRead(child)) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+/**
+ * Return whether a node is an inline callback passed to an array search, such
+ * as the arrow function in items.find(item => item.id === 1).
+ *
+ * @param  {object|undefined}  node
+ *     The node to inspect, or undefined when a call has no arguments.
+ *
+ * @returns  {boolean}
+ *     Whether the rule checks this callback's body for text reads.
+ */
+function isSearchCallback(node) {
+	if (node?.type !== "ArrowFunctionExpression" && node?.type !== "FunctionExpression") {
+		return false;
+	}
+
+	// The call the function is passed to, if it is passed to one.
+	const call = node.parent;
+
+	return (
+		call?.type === "CallExpression" &&
+		call.arguments[0] === node &&
+		call.callee.type === "MemberExpression" &&
+		!call.callee.computed &&
+		searchMethods.has(call.callee.property.name)
+	);
+}
+
+/**
+ * Return whether a node itself reads an element's text, by calling text() or
+ * reading textContent or innerText.
+ *
+ * @param  {object}  node
+ *     The AST node to inspect.
+ *
+ * @returns  {boolean}
+ *     Whether the node calls text() or reads a DOM text property.
+ */
+function isTextRead(node) {
+	if (
+		node.type === "CallExpression" &&
+		node.callee.type === "MemberExpression" &&
+		!node.callee.computed &&
+		node.callee.property.name === "text"
+	) {
+		return true;
+	}
+
+	return (
+		node.type === "MemberExpression" && !node.computed && textProperties.has(node.property.name)
+	);
+}
+
+export default {
+	meta: {
+		docs: { description: "Find test elements by data-test attributes instead of visible text." },
+		type: "problem",
+	},
+
+	/**
+	 * Create the rule's node visitor.
+	 *
+	 * @param  {object}  context
+	 *     The Oxlint rule context.
+	 *
+	 * @returns  {object}
+	 *     The visitor for array search calls.
+	 */
+	createOnce(context) {
+		return {
+			/**
+			 * Report an array search when its inline callback reads visible
+			 * text.
+			 *
+			 * @param  {object}  node
+			 *     The call expression being checked.
+			 */
+			CallExpression(node) {
+				// Only an inline callback is checked, because a callback passed
+				// by name has its body somewhere else.
+				const callback = node.arguments[0];
+
+				if (!isSearchCallback(callback) || !containsTextRead(callback.body)) {
+					return;
+				}
+
+				context.report({
+					message: "Find test elements by a data-test attribute instead of visible text.",
+					node,
+				});
+			},
+		};
+	},
+};

package/vue.json

@@ -12,6 +12,7 @@
 	},
 	"rules": {
 		"vue/no-arrow-functions-in-watch": "error",
+		"vue/no-async-in-computed-properties": "error",
 		"vue/no-deprecated-data-object-declaration": "error",
 		"vue/no-deprecated-delete-set": "error",
 		"vue/no-deprecated-destroyed-lifecycle": "error",
@@ -20,6 +21,7 @@
 		"vue/no-deprecated-vue-config-keycodes": "error",
 		"vue/no-export-in-script-setup": "error",
 		"vue/no-lifecycle-after-await": "error",
+		"vue/no-side-effects-in-computed-properties": "error",
 		"vue/prefer-import-from-vue": "error",
 		"vue/return-in-computed-property": "error",
 		"vue/valid-define-emits": "error",