@lewishowles/lint-config 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.6.0: 2026-09-21
+
+### Changes
+
+- Breaking: replace `comments/line-comments`, `comments/max-line-length`, `comments/sentence-punctuation`, `comments/block-comments`, `comments/jsdoc-tag-formatting`, and `comments/placement` with a single `comments/formatting` rule. Remove the old rule IDs from your configuration; `comments.json` already enables `comments/formatting`.
+- Breaking: `base` now reports an error when statements of different kinds, such as a declaration followed by a function call, have no blank line between them, and when consecutive `const` or `let` declarations are separated by a blank line. Run `--fix` once to update existing code.
+- `comments/formatting` moves trailing line comments onto their own line above the code.
+
+### Fixes
+
+- `comments/formatting`: refill comment lines that were wrapped before the 80-column limit.
+- `comments/variable-declarations`: skip the line-comment requirement for `const` declarations assigned to arrow functions or function expressions.
+
+## 0.5.0: 2026-09-11
+
+### Changes
+
+- `comments/variable-declarations`: add a `rootOnly` option; `comments.json` enables it for test files so only root-level variables need comments there. If you override `comments.json` rules, concatenate the test-file override (see README).
+
+### Fixes
+
+- Measure comment width in display columns, with tabs counted as four, so indented comments wrap and validate against the visible 80-column limit.
+
 ## 0.4.0: 2026-08-28
 
 ### New rules

package/README.md

@@ -49,7 +49,7 @@ The Vue layer extends `base.json` internally, so you only need to extend `vue.js
 
 ### Comment formatting (optional)
 
-Add the comments layer alongside the base or Vue layer to enforce the comment-formatting rules, variable-declaration documentation, JSDoc on named functions and first-level object methods, documentation directly after each Vue `<script setup>` opening tag, and block comments for runtime `defineProps` properties:
+Add the comments layer alongside the base or Vue layer to enforce the comment-formatting rules, including moving trailing line comments onto their own line, variable-declaration documentation, JSDoc on named functions and first-level object methods, documentation directly after each Vue `<script setup>` opening tag, and block comments for runtime `defineProps` properties:
 
 ```json
 {
@@ -73,7 +73,7 @@ The Vue component rule reads the raw `.vue` file because Oxlint's JS Plugin API
 		}
 	],
 	"rules": {
-		"comments/line-comments": "error"
+		"comments/formatting": "error"
 	}
 }
 ```
@@ -92,13 +92,45 @@ The `comments/configured-api-calls` rule requires an immediately preceding line
 }
 ```
 
+The `comments/variable-declarations` rule accepts a `rootOnly` option to require comments only before root-level `const`, `let`, and `using` declarations. The comments layer already enables `rootOnly` for test files matched by `**/*.test.*`, `**/*.spec.*`, and `**/test/**`; other files keep the default of `false`. Override it for another scope or to change the behaviour:
+
+```json
+{
+	"rules": {
+		"comments/variable-declarations": ["error", { "rootOnly": true }]
+	}
+}
+```
+
 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.
 
-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. 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 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.
+
+```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 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 });
+```
 
 ## Customising
 
@@ -130,7 +162,7 @@ Ignore patterns are project-specific, so they always live in your project config
 
 ### Adding overrides
 
-Overrides are additive: shared overrides (if any) still apply, and your local ones are appended.
+Overrides are additive in the `vite.config.js` lint block: shared overrides still apply, and your local ones are appended.
 
 ```json
 {
@@ -167,7 +199,7 @@ The base layer sorts named members within each import statement, but leaves decl
 ## What stays repo-local
 
 - `ignorePatterns`, since every project has different build output and tool directories
-- `overrides` for project-specific directories (e.g. `bin/**/*.js`, `src/cli/**/*.js`, `src/playwright/**/*.js`), since the file paths differ per project and can't be generalised
+- `overrides` for project-specific directories (e.g. `bin/**/*.js`, `src/cli/**/*.js`, `src/playwright/**/*.js`), since the file paths differ per project and can't be generalised. The `vite.config.js` lint block appends these local entries after the shared layer overrides.
 - Rule relaxations for specific file patterns (e.g. turning off `vite-plus/prefer-vite-plus-imports` in generated `.d.ts` files)
 - Additional plugins, only for projects that need them
 
@@ -176,6 +208,6 @@ The base layer sorts named members within each import statement, but leaves decl
 When a project's `.oxlintrc.json` extends a shared layer:
 
 - **Rules** shallow-merge by key: your value wins for any rule defined in both
-- **Overrides** are additive: both shared and local `overrides` entries apply, including any `env` declared inside an override block
+- **Overrides** are additive in the `vite.config.js` lint block: it concatenates shared layer and local `overrides` entries, including any `env` declared inside an override block
 - **Plugins** are additive: both shared and local `plugins`/`jsPlugins` load, deduplicated
 - **`env`, `globals`, and `ignorePatterns` don't merge through `extends` at all** (an open Oxlint bug), which is why the usage examples above redeclare `env`/`globals` directly. See [known limitations](docs/limitations.md) for the full detail, including the separate `vite-plus` caveat around resolving `extends` paths.

package/base.json

@@ -35,13 +35,32 @@
 		"@stylistic/no-confusing-arrow": "error",
 		"@stylistic/padding-line-between-statements": [
 			"error",
-			{ "blankLine": "always", "prev": "const", "next": "let" },
-			{ "blankLine": "always", "prev": "let", "next": "const" },
 			{ "blankLine": "always", "prev": "*", "next": "break" },
 			{ "blankLine": "always", "prev": ["const", "let"], "next": "*" },
+			{ "blankLine": "always", "prev": "*", "next": ["const", "let"] },
 			{ "blankLine": "always", "prev": "*", "next": "return" },
-			{ "blankLine": "any", "prev": "const", "next": "const" },
-			{ "blankLine": "any", "prev": "let", "next": "let" },
+			{
+				"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": "always",
+				"prev": { "selector": "ExpressionStatement[expression.type=\"AssignmentExpression\"]" },
+				"next": { "selector": "ExpressionStatement[expression.type=\"CallExpression\"]" }
+			},
+			{
+				"blankLine": "always",
+				"prev": { "selector": "ExpressionStatement[expression.type=\"CallExpression\"]" },
+				"next": { "selector": "ExpressionStatement[expression.type=\"AssignmentExpression\"]" }
+			},
+			{ "blankLine": "never", "prev": "const", "next": "const" },
+			{ "blankLine": "never", "prev": "let", "next": "let" },
 			{ "blankLine": "always", "prev": "multiline-const", "next": "*" },
 			{ "blankLine": "always", "prev": "*", "next": "multiline-const" }
 		],

package/comments/plugin.js

@@ -1,12 +1,7 @@
-import blockComments from "./rules/block-comments.js";
 import classDocumentation from "./rules/class-documentation.js";
 import configuredApiCalls from "./rules/configured-api-calls.js";
+import formatting from "./rules/formatting.js";
 import functionDocumentation from "./rules/function-documentation.js";
-import jsdocTagFormatting from "./rules/jsdoc-tag-formatting.js";
-import lineComments from "./rules/line-comments.js";
-import maxLineLength from "./rules/max-line-length.js";
-import placement from "./rules/placement.js";
-import sentencePunctuation from "./rules/sentence-punctuation.js";
 import variableDeclarations from "./rules/variable-declarations.js";
 import vueComponentDocumentation from "./rules/vue-component-documentation.js";
 import vueEmitDocumentation from "./rules/vue-emit-documentation.js";
@@ -15,15 +10,10 @@ import vuePropDocumentation from "./rules/vue-prop-documentation.js";
 export default {
 	meta: { name: "comments" },
 	rules: {
-		"block-comments": blockComments,
 		"class-documentation": classDocumentation,
 		"configured-api-calls": configuredApiCalls,
+		formatting,
 		"function-documentation": functionDocumentation,
-		"jsdoc-tag-formatting": jsdocTagFormatting,
-		"line-comments": lineComments,
-		"max-line-length": maxLineLength,
-		placement,
-		"sentence-punctuation": sentencePunctuation,
 		"variable-declarations": variableDeclarations,
 		"vue-component-documentation": vueComponentDocumentation,
 		"vue-emit-documentation": vueEmitDocumentation,

package/comments/rules/class-documentation.js

@@ -33,7 +33,8 @@ export default {
 			 *     The class declaration node.
 			 */
 			ClassDeclaration(node) {
-				// Resolves any export wrapper before checking for documentation.
+				// Resolves any export wrapper before checking for
+				// documentation.
 				const documentationNode = getDocumentationNode(node);
 
 				if (!hasImmediateBlockComment(context.sourceCode, documentationNode)) {
@@ -44,8 +45,8 @@ export default {
 				}
 			},
 			/**
-			 * Check class methods for required JSDoc blocks and tags. Constructors are
-			 * exempt from the @returns requirement.
+			 * Check class methods for required JSDoc blocks and tags.
+			 * Constructors are exempt from the @returns requirement.
 			 *
 			 * @param  {object}  node
 			 *     The method-definition node.
@@ -93,7 +94,8 @@ export default {
 					return;
 				}
 
-				// Static and instance fields share the requirement; only the wording differs.
+				// Static and instance fields share the requirement; only the
+				// wording differs.
 				const message = node.static
 					? "Static fields require an immediately preceding line comment."
 					: "Instance fields require an immediately preceding line comment.";
@@ -116,7 +118,8 @@ export default {
 					return;
 				}
 
-				// Resolves any export wrapper before checking for documentation.
+				// Resolves any export wrapper before checking for
+				// documentation.
 				const documentationNode = getDocumentationNode(node.parent);
 
 				if (!hasImmediateBlockComment(context.sourceCode, documentationNode)) {

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

@@ -117,9 +117,9 @@ export default {
 			 *     The call expression node.
 			 */
 			CallExpression(node) {
-				// Read fresh for every call: createOnce's visitor is shared across every file
-				// in the run, so caching this at closure-creation time would freeze the first
-				// file's options.
+				// Read fresh for every call: createOnce's visitor is shared
+				// across every file in the run, so caching this at
+				// closure-creation time would freeze the first file's options.
 				const configuredApis = getConfiguredApis(context);
 
 				if (node.callee.type !== "Identifier" || !configuredApis.has(node.callee.name)) {