@lewishowles/lint-config 0.6.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 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
+
+- Breaking: `base` now reports an error for imports that reach into a parent folder, such as `../utils`. Use the package's subpath imports or an alias instead; `--fix` can't rewrite these.
+- Breaking: `base` now expects a blank line before an `await` statement that follows other code, and around `const` declarations that span several lines. Run `--fix` once to update existing code.
+- New opt-in `imports.json` layer with formatter settings that sort imports. See the README for how to add it.
+
 ## 0.6.1: 2026-09-21
 
 ### Fixes

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,15 +190,33 @@ 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, `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 |
+| `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
 
-The base layer sorts named members within each import statement, but leaves declaration order (which import comes first) to Oxfmt: enable Oxfmt's `sortImports` option in your local `.oxfmtrc.json` if you want that sorted and fixed automatically.
+The base lint layer sorts named members within each import statement. To sort whole import statements, opt in to `imports.json`. It contains Oxfmt settings, not an Oxlint layer, so add it to the `fmt` block in `vite.config.js`:
+
+```js
+import { defineConfig } from "vite-plus";
+import importFormat from "@lewishowles/lint-config/imports.json" with { type: "json" };
+import oxfmtrc from "./.oxfmtrc.json" with { type: "json" };
+
+export default defineConfig({
+	fmt: { ...oxfmtrc, ...importFormat },
+});
+```
+
+If your `vite.config.js` already has a `lint` block, add `fmt` to the same `defineConfig` call: `defineConfig({ lint, fmt: { ...oxfmtrc, ...importFormat } })`.
+
+This puts named imports first, including `import type { … }` and imports with both default and named members. Other default imports come second, along with `import type` default imports and namespace imports (`import * as`). `.vue` imports come last. Oxfmt sorts each group by module path, ignoring letter case, and separates the groups with blank lines. Side-effect imports keep their written order and position, so keep them at the top or bottom of your imports: one written among the other imports stays where it is and splits the group around it.
+
+### Parent-folder imports
+
+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).
 
 ## What stays repo-local
 

package/base.json

@@ -1,5 +1,5 @@
 {
-	"plugins": ["oxc", "typescript", "unicorn"],
+	"plugins": ["import", "oxc", "typescript", "unicorn"],
 	"jsPlugins": [
 		"@stylistic/eslint-plugin",
 		{
@@ -25,6 +25,7 @@
 		"no-unexpected-multiline": "error",
 		"no-useless-assignment": "error",
 		"preserve-caught-error": "error",
+		"import/no-relative-parent-imports": "error",
 		"sort-imports": [
 			"error",
 			{
@@ -62,7 +63,24 @@
 			{ "blankLine": "never", "prev": "const", "next": "const" },
 			{ "blankLine": "never", "prev": "let", "next": "let" },
 			{ "blankLine": "always", "prev": "multiline-const", "next": "*" },
-			{ "blankLine": "always", "prev": "*", "next": "multiline-const" }
+			{ "blankLine": "always", "prev": "*", "next": "multiline-const" },
+			{
+				"blankLine": "always",
+				"prev": "*",
+				"next": { "selector": "ExpressionStatement[expression.type=\"AwaitExpression\"]" }
+			},
+			{
+				"blankLine": "always",
+				"prev": { "selector": "ExpressionStatement[expression.type=\"AwaitExpression\"]" },
+				"next": "*"
+			},
+			{
+				"blankLine": "never",
+				"prev": { "selector": "ExpressionStatement[expression.type=\"AwaitExpression\"]" },
+				"next": { "selector": "ExpressionStatement[expression.type=\"AwaitExpression\"]" }
+			},
+			{ "blankLine": "always", "prev": "multiline-expression", "next": "*" },
+			{ "blankLine": "always", "prev": "*", "next": "multiline-expression" }
 		],
 
 		"vite-plus/prefer-vite-plus-imports": "error"

package/comments/rules/class-documentation.js

@@ -1,5 +1,8 @@
-import { getDocumentationNode, reportFunctionDocumentation } from "../utils/documentation.js";
-import { hasImmediateBlockComment, hasImmediateLineComment } from "../utils/source.js";
+import {
+	getDocumentationNode,
+	reportFunctionDocumentation,
+} from "#comments/utils/documentation.js";
+import { hasImmediateBlockComment, hasImmediateLineComment } from "#comments/utils/source.js";
 
 /**
  * Create the class-documentation rule.

package/comments/rules/configured-api-calls.js

@@ -1,5 +1,5 @@
-import { getDocumentationNode } from "../utils/documentation.js";
-import { hasImmediateLineComment } from "../utils/source.js";
+import { getDocumentationNode } from "#comments/utils/documentation.js";
+import { hasImmediateLineComment } from "#comments/utils/source.js";
 
 // The built-in APIs that require a preceding comment by default.
 const builtInApis = new Set([

package/comments/rules/formatting.js

@@ -5,8 +5,7 @@ import {
 	formatJSDocWrapping,
 	hasTargetJSDocTag,
 	isJSDoc,
-} from "../utils/jsdoc.js";
-
+} from "#comments/utils/jsdoc.js";
 import {
 	getCommentNeighbours,
 	getCommentText,
@@ -18,15 +17,14 @@ import {
 	isDirectiveComment,
 	isLeadingComment,
 	replaceMinimalComment,
-} from "../utils/source.js";
-
+} from "#comments/utils/source.js";
 import {
 	addTerminalPunctuation,
 	capitaliseSentence,
 	formatSentence,
 	refillCommentLines,
 	wrapWords,
-} from "../utils/wrap.js";
+} from "#comments/utils/wrap.js";
 
 // The line length this rule wraps comments to.
 const maximumLineLength = 80;
@@ -207,6 +205,7 @@ function formatOrdinaryBlockComment(sourceCode, comment) {
 			formattedLines[firstProseLine],
 			capitaliseSentence,
 		);
+
 		formattedLines[lastProseLine] = formatBlockCommentLine(
 			formattedLines[lastProseLine],
 			addTerminalPunctuation,
@@ -657,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 ?? "");
 
@@ -834,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

@@ -1,4 +1,4 @@
-import { isFunctionValue, reportFunctionDocumentation } from "../utils/documentation.js";
+import { isFunctionValue, reportFunctionDocumentation } from "#comments/utils/documentation.js";
 
 /**
  * Return the declaration node that owns the documentation position.
@@ -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/rules/variable-declarations.js

@@ -1,5 +1,5 @@
-import { getDocumentationNode, isFunctionValue } from "../utils/documentation.js";
-import { hasImmediateLineComment } from "../utils/source.js";
+import { getDocumentationNode, isFunctionValue } from "#comments/utils/documentation.js";
+import { hasImmediateLineComment } from "#comments/utils/source.js";
 
 // Declaration kinds that require an immediately preceding line comment.
 const documentedKinds = new Set(["await using", "const", "let", "using"]);

package/comments/rules/vue-component-documentation.js

@@ -1,5 +1,5 @@
+import { isDirectiveComment } from "#comments/utils/source.js";
 import { existsSync, readFileSync } from "node:fs";
-import { isDirectiveComment } from "../utils/source.js";
 
 // Captures the opening tag's attributes separately, so the setup attribute can
 // be tested without the tag being available from Oxlint's extracted AST.

package/comments/rules/vue-emit-documentation.js

@@ -1,5 +1,9 @@
-import { getCommentNeighbours, isDirectiveComment, isLeadingComment } from "../utils/source.js";
-import { getObjectArgument, getObjectProperties, isNamedCall } from "../utils/vue-macro.js";
+import {
+	getCommentNeighbours,
+	isDirectiveComment,
+	isLeadingComment,
+} from "#comments/utils/source.js";
+import { getObjectArgument, getObjectProperties, isNamedCall } from "#comments/utils/vue-macro.js";
 
 // Matches the single newline and indentation allowed between a comment and an
 // event.

package/comments/rules/vue-prop-documentation.js

@@ -1,10 +1,14 @@
+import {
+	getCommentNeighbours,
+	isDirectiveComment,
+	isLeadingComment,
+} from "#comments/utils/source.js";
 import {
 	getObjectArgument,
 	getObjectProperties,
 	getPropertyName,
 	isNamedCall,
-} from "../utils/vue-macro.js";
-import { getCommentNeighbours, isDirectiveComment, isLeadingComment } from "../utils/source.js";
+} from "#comments/utils/vue-macro.js";
 
 // Matches the single newline and indentation allowed between a comment and a
 // prop.

package/comments/utils/documentation.js

@@ -1,12 +1,11 @@
 import { getJSDocContent, isJSDoc } from "./jsdoc.js";
-import { getPropertyName } from "./vue-macro.js";
-
 import {
 	getCommentNeighbours,
 	getCommentText,
-	isDirectiveComment,
+	getImmediateNonDirectiveComment,
 	isLeadingComment,
 } from "./source.js";
+import { getPropertyName } from "./vue-macro.js";
 
 /**
  * Return the declaration node that owns the documentation position.
@@ -46,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.
@@ -58,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;
 	}
@@ -193,8 +187,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.
@@ -206,21 +201,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);
 			}
 		}
 	}
@@ -335,10 +325,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,
@@ -367,3 +359,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];
+}