@lewishowles/lint-config 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# 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
+
+- Added `comments/class-documentation`: requires a block comment on class declarations and const-assigned class expressions, JSDoc on constructors and ordinary methods, return-aware JSDoc on getters and setters, and line comments on instance and static fields. Ships in the opt-in `comments.json` layer.
+
+### Fixes
+
+- A directive comment (`eslint-`, `oxlint-`, and similar) sitting between a doc comment and its code is now reported, instead of the doc being treated as attached to the code.
+- Documentation placed before an exported declaration is now recognised.
+- `using` and `await using` declarations now require a preceding line comment, like `const` and `let`.
+
+Earlier versions predate this changelog; see the git history for their changes.

package/README.md

@@ -92,6 +92,46 @@ 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. 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
 
 Your project's `.oxlintrc.json` can override rules, add ignore patterns, add overrides, or add plugins on top of the shared layer.
@@ -122,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
 {
@@ -159,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
 
@@ -168,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/plugin.js

@@ -1,4 +1,5 @@
 import blockComments from "./rules/block-comments.js";
+import classDocumentation from "./rules/class-documentation.js";
 import configuredApiCalls from "./rules/configured-api-calls.js";
 import functionDocumentation from "./rules/function-documentation.js";
 import jsdocTagFormatting from "./rules/jsdoc-tag-formatting.js";
@@ -15,6 +16,7 @@ export default {
 	meta: { name: "comments" },
 	rules: {
 		"block-comments": blockComments,
+		"class-documentation": classDocumentation,
 		"configured-api-calls": configuredApiCalls,
 		"function-documentation": functionDocumentation,
 		"jsdoc-tag-formatting": jsdocTagFormatting,

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

@@ -0,0 +1,134 @@
+import { getDocumentationNode, reportFunctionDocumentation } from "../utils/documentation.js";
+import { hasImmediateBlockComment, hasImmediateLineComment } from "../utils/source.js";
+
+/**
+ * Create the class-documentation rule.
+ *
+ * @returns  {object}
+ *     The Oxlint rule definition.
+ */
+export default {
+	meta: {
+		docs: {
+			description:
+				"Require documentation for classes, their methods, getters, setters, and fields.",
+		},
+		type: "suggestion",
+	},
+	/**
+	 * Create the rule's node visitors.
+	 *
+	 * @param  {object}  context
+	 *     The Oxlint rule context.
+	 *
+	 * @returns  {object}
+	 *     The visitor functions for this rule.
+	 */
+	createOnce(context) {
+		return {
+			/**
+			 * Check a class declaration for a preceding block comment.
+			 *
+			 * @param  {object}  node
+			 *     The class declaration node.
+			 */
+			ClassDeclaration(node) {
+				// Resolves any export wrapper before checking for
+				// documentation.
+				const documentationNode = getDocumentationNode(node);
+
+				if (!hasImmediateBlockComment(context.sourceCode, documentationNode)) {
+					context.report({
+						message: "Classes require an immediately preceding block comment.",
+						node: documentationNode,
+					});
+				}
+			},
+			/**
+			 * Check class methods for required JSDoc blocks and tags.
+			 * Constructors are exempt from the @returns requirement.
+			 *
+			 * @param  {object}  node
+			 *     The method-definition node.
+			 */
+			MethodDefinition(node) {
+				if (node.kind === "constructor") {
+					reportFunctionDocumentation(context, node, node.value, {
+						requiresReturns: false,
+						subject: "Constructors",
+					});
+
+					return;
+				}
+
+				if (node.kind === "get") {
+					reportFunctionDocumentation(context, node, node.value, {
+						subject: "Getters",
+					});
+
+					return;
+				}
+
+				if (node.kind === "set") {
+					reportFunctionDocumentation(context, node, node.value, {
+						subject: "Setters",
+					});
+
+					return;
+				}
+
+				if (node.kind === "method") {
+					reportFunctionDocumentation(context, node, node.value, {
+						subject: "Methods",
+					});
+				}
+			},
+			/**
+			 * Check instance and static fields for a preceding line comment.
+			 *
+			 * @param  {object}  node
+			 *     The property-definition node.
+			 */
+			PropertyDefinition(node) {
+				if (hasImmediateLineComment(context.sourceCode, node)) {
+					return;
+				}
+
+				// 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.";
+
+				context.report({ message, node });
+			},
+			/**
+			 * Check a const class expression for a preceding block comment.
+			 *
+			 * @param  {object}  node
+			 *     The variable declarator node.
+			 */
+			VariableDeclarator(node) {
+				if (
+					node.parent?.kind !== "const" ||
+					node.parent.declarations.length !== 1 ||
+					node.id?.type !== "Identifier" ||
+					node.init?.type !== "ClassExpression"
+				) {
+					return;
+				}
+
+				// Resolves any export wrapper before checking for
+				// documentation.
+				const documentationNode = getDocumentationNode(node.parent);
+
+				if (!hasImmediateBlockComment(context.sourceCode, documentationNode)) {
+					context.report({
+						message: "Classes require an immediately preceding block comment.",
+						node: documentationNode,
+					});
+				}
+			},
+		};
+	},
+};

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

@@ -1,3 +1,4 @@
+import { getDocumentationNode } from "../utils/documentation.js";
 import { hasImmediateLineComment } from "../utils/source.js";
 
 // The built-in APIs that require a preceding comment by default.
@@ -44,9 +45,14 @@ function hasDocumentedVariableDeclaration(sourceCode, node) {
 	// The declarator's enclosing variable declaration.
 	const declaration = declarator.parent;
 
-	return (
-		declaration?.type === "VariableDeclaration" && hasImmediateLineComment(sourceCode, declaration)
-	);
+	if (declaration?.type !== "VariableDeclaration") {
+		return false;
+	}
+
+	// Resolves any export wrapper before checking for documentation.
+	const documentationNode = getDocumentationNode(declaration);
+
+	return hasImmediateLineComment(sourceCode, documentationNode);
 }
 
 /**
@@ -111,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

@@ -5,26 +5,10 @@ import {
 	getLineIndent,
 	getLineStart,
 	getNewline,
+	isDirectiveComment,
 	isLeadingComment,
 } from "../utils/source.js";
 
-/**
- * Return the end-to-token gap for a leading comment.
- *
- * @param  {object}  sourceCode
- *     The Oxlint source code object.
- * @param  {object}  comment
- *     The comment token.
- * @param  {object}  next
- *     The next source token.
- *
- * @returns  {string}
- *     The source gap after the comment.
- */
-function getCommentToTokenGap(sourceCode, comment, next) {
-	return sourceCode.text.slice(comment.range[1], next.range[0]);
-}
-
 /**
  * Return continuation comments indexed by their group leader.
  *
@@ -160,7 +144,7 @@ function getCommentIndentationFixes(
 }
 
 /**
- * Return the replacement that places a final leading comment against its code.
+ * Return the replacement that closes the gap after a final leading comment.
  *
  * @param  {object}  sourceCode
  *     The Oxlint source code object.
@@ -169,7 +153,7 @@ function getCommentIndentationFixes(
  * @param  {object}  next
  *     The documented source token.
  * @param  {object|undefined}  followingComment
- *     The next comment token.
+ *     The comment after this one in source order, when there is one.
  * @param  {string}  expectedIndent
  *     The documented code's indentation.
  *
@@ -177,16 +161,23 @@ function getCommentIndentationFixes(
  *     The gap replacement, or null when none is needed.
  */
 function getCommentGapFix(sourceCode, comment, next, followingComment, expectedIndent) {
-	if (followingComment !== undefined && followingComment.range[0] <= next.range[0]) {
+	// Whether another comment sits between this one and its documented code.
+	const followingCommentIntervenes =
+		followingComment !== undefined && followingComment.range[0] <= next.range[0];
+
+	if (followingCommentIntervenes && !isDirectiveComment(followingComment)) {
 		return null;
 	}
 
-	// The source text currently between the comment and its documented code.
-	const gap = getCommentToTokenGap(sourceCode, comment, next);
+	// Stop at an intervening directive so the fix range never overlaps it.
+	const gapEnd = followingCommentIntervenes ? followingComment.range[0] : next.range[0];
+
+	// What currently follows the comment, up to the code or directive.
+	const gap = sourceCode.text.slice(comment.range[1], gapEnd);
 	// The gap the documented code's indentation requires.
 	const desiredGap = `${getNewline(sourceCode.text)}${expectedIndent}`;
 
-	return gap === desiredGap ? null : { range: [comment.range[1], next.range[0]], text: desiredGap };
+	return gap === desiredGap ? null : { range: [comment.range[1], gapEnd], text: desiredGap };
 }
 
 /**
@@ -225,7 +216,11 @@ export default {
 				);
 
 				for (const [index, comment] of comments.entries()) {
-					if (comment.type === "Shebang" || continuationComments.has(comment)) {
+					if (
+						comment.type === "Shebang" ||
+						isDirectiveComment(comment) ||
+						continuationComments.has(comment)
+					) {
 						continue;
 					}
 
@@ -245,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,
@@ -254,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

@@ -1,5 +1,9 @@
+import { getDocumentationNode } from "../utils/documentation.js";
 import { hasImmediateLineComment } from "../utils/source.js";
 
+// Declaration kinds that require an immediately preceding line comment.
+const documentedKinds = new Set(["await using", "const", "let", "using"]);
+
 /**
  * Return whether a declaration is inside a loop header.
  *
@@ -29,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.
@@ -42,20 +58,48 @@ export default {
 	createOnce(context) {
 		return {
 			/**
-			 * Check a const or let declaration for a preceding comment.
+			 * Check a variable declaration for a preceding line comment.
 			 *
 			 * @param  {object}  node
 			 *     The variable declaration node.
 			 */
 			VariableDeclaration(node) {
-				if ((node.kind !== "const" && node.kind !== "let") || isLoopHeaderDeclaration(node)) {
+				if (!documentedKinds.has(node.kind) || isLoopHeaderDeclaration(node)) {
+					return;
+				}
+
+				// A lone const class expression is documented by
+				// class-documentation.
+				if (
+					node.kind === "const" &&
+					node.declarations.length === 1 &&
+					node.declarations[0].id?.type === "Identifier" &&
+					node.declarations[0].init?.type === "ClassExpression"
+				) {
 					return;
 				}
 
-				if (!hasImmediateLineComment(context.sourceCode, node)) {
+				// 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);
+
+				// 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,
+						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/documentation.js

@@ -8,6 +8,29 @@ import {
 	isLeadingComment,
 } from "./source.js";
 
+/**
+ * Return the declaration node that owns the documentation position.
+ *
+ * @param  {object}  node
+ *     The declaration node.
+ *
+ * @returns  {object}
+ *     The node immediately following the documentation block.
+ */
+export function getDocumentationNode(node) {
+	// Walks up through export wrappers to find the documented position.
+	let documentationNode = node;
+
+	while (
+		documentationNode.parent?.type === "ExportDefaultDeclaration" ||
+		documentationNode.parent?.type === "ExportNamedDeclaration"
+	) {
+		documentationNode = documentationNode.parent;
+	}
+
+	return documentationNode;
+}
+
 /**
  * Return whether a node is a function value, used to tell function-valued
  * options and properties apart from named function declarations.
@@ -264,14 +287,19 @@ function hasValueReturn(node) {
  *     Optional reporting options.
  * @param  {boolean}  [options.requiresReturns=true]
  *     Whether a returned value requires an @returns tag.
+ * @param  {string}  [options.subject="Functions"]
+ *     The declaration kind named in report messages, such as "Constructors".
  */
 export function reportFunctionDocumentation(context, node, functionNode, options = {}) {
+	// Defaults to "Functions" when the caller names no declaration kind.
+	const subject = options.subject ?? "Functions";
+
 	// Finds the JSDoc block documenting this function, when present.
 	const comment = getDocumentationComment(context.sourceCode, node);
 
 	if (!comment) {
 		context.report({
-			message: "Functions require an immediately preceding JSDoc block.",
+			message: `${subject} require an immediately preceding JSDoc block.`,
 			node,
 		});
 
@@ -292,7 +320,7 @@ export function reportFunctionDocumentation(context, node, functionNode, options
 
 		if (!documentedParameters.has(path) && !documentedParameters.has(optionalPath)) {
 			context.report({
-				message: `Functions require an @param for ${path}.`,
+				message: `${subject} require an @param for ${path}.`,
 				node,
 			});
 		}
@@ -307,14 +335,14 @@ export function reportFunctionDocumentation(context, node, functionNode, options
 
 	if (options.requiresReturns !== false && hasValueReturn(functionNode) && !hasReturns) {
 		context.report({
-			message: "Functions that return a value require an @returns tag.",
+			message: `${subject} that return a value require an @returns tag.`,
 			node,
 		});
 	}
 
 	if (containsStatement(functionNode.body, "ThrowStatement") && !hasThrows) {
 		context.report({
-			message: "Functions that throw require an @throws tag.",
+			message: `${subject} that throw require an @throws tag.`,
 			node,
 		});
 	}

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.
  *
@@ -310,3 +325,37 @@ export function hasImmediateLineComment(sourceCode, node) {
 		/^\r?\n[ \t]*$/.test(gap)
 	);
 }
+
+/**
+ * Return whether a block comment immediately documents a source node.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object}  node
+ *     The source node.
+ *
+ * @returns  {boolean}
+ *     Whether an ordinary block comment immediately precedes the node.
+ */
+export function hasImmediateBlockComment(sourceCode, node) {
+	// Finds the closest preceding comment.
+	const comment = sourceCode
+		.getAllComments()
+		.findLast((candidate) => candidate.range[1] <= node.range[0]);
+
+	if (comment?.type !== "Block" || isDirectiveComment(comment)) {
+		return false;
+	}
+
+	// Checks the comments immediately around the node.
+	const { next, previous } = getCommentNeighbours(sourceCode, comment);
+
+	// Confirms there is no blank line before the node.
+	const gap = sourceCode.text.slice(comment.range[1], node.range[0]);
+
+	return (
+		next?.range[0] === node.range[0] &&
+		isLeadingComment(sourceCode, comment, previous) &&
+		/^\r?\n[ \t]*$/.test(gap)
+	);
+}

package/comments.json

@@ -7,6 +7,7 @@
 	],
 	"rules": {
 		"comments/block-comments": "error",
+		"comments/class-documentation": "error",
 		"comments/configured-api-calls": "error",
 		"comments/function-documentation": "error",
 		"comments/jsdoc-tag-formatting": "error",
@@ -18,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.3.0",
+	"version": "0.5.0",
 	"description": "Shared oxlint configuration for Lewis Howles projects",
 	"keywords": [
 		"config",
@@ -19,6 +19,7 @@
 		"url": "git+https://github.com/lewishowles/lint-config.git"
 	},
 	"files": [
+		"CHANGELOG.md",
 		"base.json",
 		"comments",
 		"comments.json",
@@ -39,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",