@lewishowles/lint-config 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 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

@@ -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/comments/rules/block-comments.js

@@ -40,7 +40,8 @@ export default {
 						continue;
 					}
 
-					// The comment, with its block structure and delimiters normalised.
+					// The comment, with its block structure and delimiters
+					// normalised.
 					const formattedComment = formatJSDocBlockStructure(context.sourceCode, comment);
 
 					if (formattedComment === commentText) {

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,8 +117,10 @@ 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
+				// 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);
 

package/comments/rules/jsdoc-tag-formatting.js

@@ -40,7 +40,8 @@ export default {
 						continue;
 					}
 
-					// The comment, with its tag spacing, order, and grouping normalised.
+					// The comment, with its tag spacing, order, and grouping
+					// normalised.
 					const formattedComment = formatJSDocTagFormatting(context.sourceCode, comment);
 
 					if (formattedComment === commentText) {

package/comments/rules/max-line-length.js

@@ -2,6 +2,7 @@ import { formatJSDocWrapping, isJSDoc } from "../utils/jsdoc.js";
 
 import {
 	getCommentText,
+	getDisplayWidth,
 	getLineIndent,
 	getNewline,
 	isDirectiveComment,
@@ -33,7 +34,7 @@ function formatLineComment(sourceCode, comment) {
 	}
 
 	// The available width, allowing for the indent and "// " prefix.
-	const width = maximumLineLength - indentation.length - 3;
+	const width = maximumLineLength - getDisplayWidth(indentation) - 3;
 	// The comment's undecorated text.
 	const text = comment.value.trim();
 
@@ -74,7 +75,7 @@ function formatBlockComment(sourceCode, comment) {
 	// The comment body, sentence-formatted.
 	const text = formatSentence(commentText.slice(2, -2).trim());
 	// The available width, allowing for the indent and " * " prefix.
-	const width = maximumLineLength - indentation.length - 3;
+	const width = maximumLineLength - getDisplayWidth(indentation) - 3;
 	// The comment body, rewrapped to the available width.
 	const lines = wrapWords(text, Math.max(1, width));
 
@@ -120,11 +121,20 @@ export default {
 					// The comment's individual source lines.
 					const lines = commentText.split(/\r\n|\n|\r/);
 
-					if (!lines.some((line) => line.length > maximumLineLength)) {
+					// The whitespace before the comment, absent when code
+					// precedes it.
+					const indentation = getLineIndent(context.sourceCode, comment.range[0]) ?? "";
+					// The comment lines as they appear on screen. The raw text
+					// omits the first line's indentation, so it is restored
+					// before measuring.
+					const displayLines = [`${indentation}${lines[0]}`, ...lines.slice(1)];
+
+					if (!displayLines.some((line) => getDisplayWidth(line) > maximumLineLength)) {
 						continue;
 					}
 
-					// The comment, rewrapped using the formatter matching its type.
+					// The comment, rewrapped using the formatter matching its
+					// type.
 					const formattedComment =
 						comment.type === "Line"
 							? formatLineComment(context.sourceCode, comment)

package/comments/rules/placement.js

@@ -240,7 +240,8 @@ export default {
 						continue;
 					}
 
-					// The reindentation fixes for the comment and its continuations.
+					// The reindentation fixes for the comment and its
+					// continuations.
 					const fixes = getCommentIndentationFixes(
 						context.sourceCode,
 						comment,
@@ -249,10 +250,12 @@ export default {
 						expectedIndent,
 					);
 
-					// The next comment token, used to avoid overlapping gap fixes.
+					// The next comment token, used to avoid overlapping gap
+					// fixes.
 					const followingComment = comments[index + 1];
 
-					// The fix that closes the gap between the comment and its code, when needed.
+					// The fix that closes the gap between the comment and its
+					// code, when needed.
 					const gapFix = getCommentGapFix(
 						context.sourceCode,
 						comment,

package/comments/rules/sentence-punctuation.js

@@ -136,7 +136,8 @@ function formatOrdinaryBlockComment(sourceCode, comment) {
 	if (lines[0] === "/*" && lines.at(-1).trim() === "*/" && proseLineIndexes.length > 0) {
 		// The comment lines, formatted in place.
 		const formattedLines = [...lines];
-		// The first and last prose line indexes, which start and end the sentence.
+		// The first and last prose line indexes, which start and end the
+		// sentence.
 		const firstProseLine = proseLineIndexes[0];
 		// The last prose line index, which ends the sentence.
 		const lastProseLine = proseLineIndexes.at(-1);
@@ -193,13 +194,15 @@ export default {
 			 */
 			Program() {
 				for (const commentGroup of getLineCommentGroups(context.sourceCode)) {
-					// The group's replacement text, or null when it already reads as a sentence.
+					// The group's replacement text, or null when it already
+					// reads as a sentence.
 					const formattedGroup = formatLineCommentGroup(context.sourceCode, commentGroup);
 
 					if (formattedGroup) {
 						context.report({
 							/**
-							 * Apply the formatted replacement to the comment group.
+							 * Apply the formatted replacement to the comment
+							 * group.
 							 *
 							 * @param  {object}  fixer
 							 *     The Oxlint fixer.
@@ -208,7 +211,8 @@ export default {
 							 *     The fixes to apply.
 							 */
 							fix: (fixer) => {
-								// The fixes to apply, starting with the first comment's replacement.
+								// The fixes to apply, starting with the first
+								// comment's replacement.
 								const fixes = [
 									replaceMinimalComment(
 										fixer,
@@ -245,7 +249,8 @@ export default {
 					// The comment's raw source text.
 					const commentText = getCommentText(context.sourceCode, comment);
 
-					// The comment, sentence-formatted using the JSDoc or ordinary-block formatter.
+					// The comment, sentence-formatted using the JSDoc or
+					// ordinary-block formatter.
 					const formattedComment = isJSDoc(commentText)
 						? formatJSDocPunctuation(context.sourceCode, comment)
 						: formatOrdinaryBlockComment(context.sourceCode, comment);
@@ -253,7 +258,8 @@ export default {
 					if (formattedComment !== commentText) {
 						context.report({
 							/**
-							 * Apply the sentence-formatted replacement to the comment.
+							 * Apply the sentence-formatted replacement to the
+							 * comment.
 							 *
 							 * @param  {object}  fixer
 							 *     The Oxlint fixer.

package/comments/rules/variable-declarations.js

@@ -33,6 +33,18 @@ export default {
 	meta: {
 		docs: { description: "Require comments before variable declarations." },
 		type: "suggestion",
+		schema: [
+			{
+				type: "object",
+				properties: {
+					rootOnly: {
+						type: "boolean",
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+		defaultOptions: [{ rootOnly: false }],
 	},
 	/**
 	 * Create the rule's node visitors.
@@ -56,7 +68,8 @@ export default {
 					return;
 				}
 
-				// A lone const class expression is documented by class-documentation.
+				// A lone const class expression is documented by
+				// class-documentation.
 				if (
 					node.kind === "const" &&
 					node.declarations.length === 1 &&
@@ -66,10 +79,24 @@ export default {
 					return;
 				}
 
-				// Resolves any export wrapper before checking for documentation.
+				// The rule's resolved options for the file currently being
+				// visited.
+				const options = context.options?.[0];
+
+				// Resolves any export wrapper before checking for
+				// documentation.
 				const documentationNode = getDocumentationNode(node);
 
-				if (!hasImmediateLineComment(context.sourceCode, documentationNode)) {
+				// With rootOnly, only declarations directly under the
+				// Program need a comment, so a nested variable inside
+				// a function is left alone.
+				const shouldCheckDocumentation =
+					!options?.rootOnly || documentationNode.parent?.type === "Program";
+
+				if (
+					shouldCheckDocumentation &&
+					!hasImmediateLineComment(context.sourceCode, documentationNode)
+				) {
 					context.report({
 						message: "Variable declarations require an immediately preceding line comment.",
 						node: documentationNode,

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

@@ -119,7 +119,8 @@ function hasComponentDocumentation(context, scriptBlock) {
 		return false;
 	}
 
-	// A blank line would separate the component documentation from its entry point.
+	// A blank line would separate the component documentation from its entry
+	// point.
 	const commentGap = context.sourceCode.text.slice(0, comment.range[0]);
 
 	return immediateCommentGapPattern.test(commentGap);
@@ -142,7 +143,8 @@ export default {
 	createOnce(context) {
 		return {
 			/**
-			 * Check the current component's script setup block for documentation.
+			 * Check the current component's script setup block for
+			 * documentation.
 			 *
 			 * @param  {object}  node
 			 *     The entry point parsed from the current script block.
@@ -150,7 +152,8 @@ export default {
 			Program(node) {
 				// createOnce builds this visitor once for the whole run, and a
 				// single file's script blocks are not necessarily visited
-				// consecutively, so the matching block is looked up fresh on each
+				// consecutively, so the matching block is looked up fresh on
+				// each
 				// call rather than tracked with shared state.
 				const scriptBlock = findScriptBlock(context);
 

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

@@ -111,7 +111,8 @@ export default {
 					return;
 				}
 
-				// Array and type-only forms have no runtime properties to document.
+				// Array and type-only forms have no runtime properties to
+				// document.
 				const emitsObject = getObjectArgument(node, 0);
 
 				if (emitsObject) {

package/comments/utils/jsdoc.js

@@ -1,4 +1,4 @@
-import { getCommentText, getLineIndent, getNewline } from "./source.js";
+import { getCommentText, getDisplayWidth, getLineIndent, getNewline } from "./source.js";
 import { addTerminalPunctuation, capitaliseSentence, formatSentence, wrapWords } from "./wrap.js";
 
 // The JSDoc tags this package formats, in their required output order.
@@ -217,7 +217,8 @@ function formatUnwrappedProse(lines, addPunctuation) {
 	// The formatted lines, built up in place.
 	const result = lines.map((line) => line.trim());
 
-	// The index of the current paragraph's first line, or null between paragraphs.
+	// The index of the current paragraph's first line, or null between
+	// paragraphs.
 	let paragraphStart = null;
 
 	for (let index = 0; index < result.length; index += 1) {
@@ -336,7 +337,8 @@ function formatTags(tagLines, width, addPunctuation, normaliseTags) {
 	// The formatted lines, built up in place.
 	const result = [];
 
-	// The tag type of the previously written entry, used to detect group changes.
+	// The tag type of the previously written entry, used to detect group
+	// changes.
 	let lastType = null;
 
 	// The entries regrouped into the required tag order.
@@ -526,7 +528,7 @@ function getJSDocFormattingContext(sourceCode, comment) {
 	// The newline style used by the surrounding source.
 	const newline = getNewline(sourceCode.text);
 	// The available content width, allowing for the indent and " * " prefix.
-	const width = Math.max(1, 80 - indent.length - 3);
+	const width = Math.max(1, 80 - getDisplayWidth(indent) - 3);
 	// The undecorated comment content lines.
 	const content = getJSDocContent(commentText);
 	// The content split into its prose and tag sections.

package/comments/utils/source.js

@@ -156,6 +156,21 @@ export function getLineIndent(sourceCode, offset) {
 	return /^\s*$/.test(prefix) ? prefix : null;
 }
 
+/**
+ * Return the number of columns a source string occupies on screen, so comment
+ * lines are measured and wrapped against the 80-column limit under tab
+ * indentation. A tab counts as four columns, the width this package assumes.
+ *
+ * @param  {string}  sourceText
+ *     The source string to measure, such as a line or its indentation.
+ *
+ * @returns  {number}
+ *     The source string's width in display columns.
+ */
+export function getDisplayWidth(sourceText) {
+	return sourceText.replaceAll("\t", "    ").length;
+}
+
 /**
  * Return the source items immediately around a comment.
  *

package/comments.json

@@ -19,5 +19,13 @@
 		"comments/vue-component-documentation": "error",
 		"comments/vue-emit-documentation": "error",
 		"comments/vue-prop-documentation": "error"
-	}
+	},
+	"overrides": [
+		{
+			"files": ["**/*.test.*", "**/*.spec.*", "**/test/**"],
+			"rules": {
+				"comments/variable-declarations": ["error", { "rootOnly": true }]
+			}
+		}
+	]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lewishowles/lint-config",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"description": "Shared oxlint configuration for Lewis Howles projects",
 	"keywords": [
 		"config",
@@ -40,7 +40,8 @@
 		"lint": "vp check",
 		"lint:fix": "vp check --fix",
 		"prepare": "vp config --no-agent",
-		"publint": "publint"
+		"publint": "publint",
+		"test:unit": "node --test test/comments/*.test.js"
 	},
 	"devDependencies": {
 		"publint": "^0.3.22",