@lewishowles/lint-config 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 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,14 @@ The `comments/configured-api-calls` rule requires an immediately preceding line
 }
 ```
 
+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.
+
 ## Customising
 
 Your project's `.oxlintrc.json` can override rules, add ignore patterns, add overrides, or add plugins on top of the shared layer.

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/class-documentation.js

@@ -0,0 +1,131 @@
+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);
 }
 
 /**

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;
 					}
 

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.
  *
@@ -42,20 +46,33 @@ 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)) {
+				// Resolves any export wrapper before checking for documentation.
+				const documentationNode = getDocumentationNode(node);
+
+				if (!hasImmediateLineComment(context.sourceCode, documentationNode)) {
 					context.report({
 						message: "Variable declarations require an immediately preceding line comment.",
-						node,
+						node: documentationNode,
 					});
 				}
 

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/source.js

@@ -310,3 +310,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",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lewishowles/lint-config",
-	"version": "0.3.0",
+	"version": "0.4.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",