@lewishowles/lint-config 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 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
+
+- `comments/function-documentation`: accept the name the JSDoc gives a destructured object parameter, instead of always expecting `options`.
+
 ## 0.6.0: 2026-09-21
 
 ### Changes

package/README.md

@@ -186,15 +186,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,

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.

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,
 	isLeadingComment,
 } from "./source.js";
+import { getPropertyName } from "./vue-macro.js";
 
 /**
  * Return the declaration node that owns the documentation position.
@@ -157,11 +156,14 @@ function getObjectPatternPaths(sourceCode, node, parentPath) {
  *     The Oxlint source code object.
  * @param  {object}  node
  *     The parameter node.
+ * @param  {string}  [rootPath]
+ *     The documented name that starts each path for a destructured object
+ *     parameter. Defaults to options.
  *
  * @returns  {string[]}
  *     The required JSDoc parameter paths.
  */
-function getParameterPaths(sourceCode, node) {
+function getParameterPaths(sourceCode, node, rootPath = "options") {
 	if (node.type === "Identifier") {
 		return [node.name];
 	}
@@ -171,11 +173,11 @@ function getParameterPaths(sourceCode, node) {
 	}
 
 	if (node.type === "ObjectPattern") {
-		return getObjectPatternPaths(sourceCode, node, "options");
+		return getObjectPatternPaths(sourceCode, node, rootPath);
 	}
 
 	if (node.type === "AssignmentPattern") {
-		return getParameterPaths(sourceCode, node.left);
+		return getParameterPaths(sourceCode, node.left, rootPath);
 	}
 
 	return [];
@@ -189,25 +191,40 @@ function getParameterPaths(sourceCode, node) {
  * @param  {object}  comment
  *     The JSDoc comment token.
  *
- * @returns  {Set<string>}
- *     The documented parameter names.
+ * @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.
  */
 function getDocumentedParameters(sourceCode, comment) {
 	// Splits the JSDoc block into its individual lines.
 	const content = getJSDocContent(getCommentText(sourceCode, comment));
 	// Collects the parameter paths documented by @param tags.
 	const names = new Set();
+	// Collects top-level parameter names in their documented order.
+	const topLevelNames = [];
 
 	for (const line of content) {
 		// Matches an @param tag and captures its documented path.
 		const match = line.trim().match(/^@param(?:\s+\{[^}]+\})?\s+(\[[^\]]+\]|\S+)/);
 
 		if (match) {
-			names.add(match[1]);
+			// The documented name as written, including optional brackets and
+			// any default value.
+			const name = 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);
+			}
 		}
 	}
 
-	return names;
+	return { names, topLevelNames };
 }
 
 /**
@@ -306,11 +323,14 @@ export function reportFunctionDocumentation(context, node, functionNode, options
 	}
 
 	// Reads the parameter paths already documented by @param tags.
-	const documentedParameters = getDocumentedParameters(context.sourceCode, comment);
+	const { names: documentedParameters, topLevelNames } = getDocumentedParameters(
+		context.sourceCode,
+		comment,
+	);
 
 	// Derives the parameter paths the function actually requires.
-	const parameterPaths = functionNode.params.flatMap((parameter) =>
-		getParameterPaths(context.sourceCode, parameter),
+	const parameterPaths = functionNode.params.flatMap((parameter, index) =>
+		getParameterPaths(context.sourceCode, parameter, topLevelNames[index]),
 	);
 
 	for (const path of parameterPaths) {

package/comments/utils/jsdoc.js

@@ -421,6 +421,7 @@ function formatMixedTags(lines, width, addPunctuation) {
 				rest: match[2].trim(),
 				type: match[1],
 			};
+
 			preserveSection = false;
 
 			result.push(formatTagHeader(currentEntry));

package/imports.json

@@ -0,0 +1,13 @@
+{
+	"sortImports": {
+		"groups": ["named", "default", "vue"],
+		"customGroups": [
+			{ "groupName": "vue", "elementNamePattern": ["**/*.vue"] },
+			{ "groupName": "named", "modifiers": ["named"] },
+			{ "groupName": "default", "modifiers": ["default"] }
+		],
+		"newlinesBetween": true,
+		"order": "asc",
+		"sortSideEffects": false
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lewishowles/lint-config",
-	"version": "0.6.0",
+	"version": "0.7.0",
 	"description": "Shared oxlint configuration for Lewis Howles projects",
 	"keywords": [
 		"config",
@@ -23,14 +23,19 @@
 		"base.json",
 		"comments",
 		"comments.json",
+		"imports.json",
 		"vue.json",
 		"README.md"
 	],
 	"type": "module",
+	"imports": {
+		"#comments/*": "./comments/*"
+	},
 	"exports": {
 		"./base.json": "./base.json",
 		"./comments.json": "./comments.json",
 		"./comments/plugin": "./comments/plugin.js",
+		"./imports.json": "./imports.json",
 		"./vue.json": "./vue.json"
 	},
 	"publishConfig": {