@lewishowles/lint-config 0.1.3 → 0.3.0

package/comments/rules/function-documentation.js

@@ -0,0 +1,111 @@
+import { isFunctionValue, reportFunctionDocumentation } from "../utils/documentation.js";
+
+/**
+ * Return the declaration node that owns the documentation position.
+ *
+ * @param  {object}  node
+ *     The function declaration node.
+ *
+ * @returns  {object}
+ *     The node immediately following the documentation block.
+ */
+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 an object property belongs to the outermost object literal.
+ *
+ * @param  {object}  node
+ *     The property node to inspect.
+ *
+ * @returns  {boolean}
+ *     Whether the property is not nested inside another object literal.
+ */
+function isFirstLevelObjectProperty(node) {
+	// Finds the object literal that owns the property.
+	const object = node.parent;
+
+	if (object?.type !== "ObjectExpression") {
+		return false;
+	}
+
+	return object.parent?.parent?.type !== "ObjectExpression";
+}
+
+/**
+ * Create the function-documentation rule.
+ *
+ * @returns  {object}
+ *     The Oxlint rule definition.
+ */
+export default {
+	meta: {
+		docs: { description: "Require JSDoc documentation for named functions and methods." },
+		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 named function declaration for documentation.
+			 *
+			 * @param  {object}  node
+			 *     The function declaration node.
+			 */
+			FunctionDeclaration(node) {
+				if (node.id) {
+					reportFunctionDocumentation(context, getDocumentationNode(node), node);
+				}
+			},
+			/**
+			 * Check a first-level object method for documentation.
+			 *
+			 * @param  {object}  node
+			 *     The property node.
+			 */
+			Property(node) {
+				if (!isFirstLevelObjectProperty(node) || !isFunctionValue(node.value)) {
+					return;
+				}
+
+				reportFunctionDocumentation(context, node, node.value);
+			},
+			/**
+			 * Check a const function variable for documentation.
+			 *
+			 * @param  {object}  node
+			 *     The variable declarator node.
+			 */
+			VariableDeclarator(node) {
+				if (
+					node.id.type !== "Identifier" ||
+					node.parent?.kind !== "const" ||
+					!isFunctionValue(node.init)
+				) {
+					return;
+				}
+
+				reportFunctionDocumentation(context, node.parent, node.init);
+			},
+		};
+	},
+};

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

@@ -0,0 +1,70 @@
+import { formatJSDocTagFormatting, hasTargetJSDocTag, isJSDoc } from "../utils/jsdoc.js";
+import { getCommentText, replaceMinimalComment } from "../utils/source.js";
+
+/**
+ * Create the JSDoc tag-formatting rule.
+ *
+ * @returns  {object}
+ *     The Oxlint rule definition.
+ */
+export default {
+	meta: {
+		docs: { description: "Format Phase 1 JSDoc tag spacing and grouping." },
+		fixable: "code",
+		type: "layout",
+	},
+	/**
+	 * Create the rule's node visitors.
+	 *
+	 * @param  {object}  context
+	 *     The Oxlint rule context.
+	 *
+	 * @returns  {object}
+	 *     The visitor functions for this rule.
+	 */
+	createOnce(context) {
+		return {
+			/**
+			 * Format every JSDoc comment's tags in the file.
+			 */
+			Program() {
+				for (const comment of context.sourceCode.getAllComments()) {
+					if (comment.type !== "Block") {
+						continue;
+					}
+
+					// The comment's raw source text.
+					const commentText = getCommentText(context.sourceCode, comment);
+
+					if (!isJSDoc(commentText) || !hasTargetJSDocTag(context.sourceCode, comment)) {
+						continue;
+					}
+
+					// The comment, with its tag spacing, order, and grouping normalised.
+					const formattedComment = formatJSDocTagFormatting(context.sourceCode, comment);
+
+					if (formattedComment === commentText) {
+						continue;
+					}
+
+					context.report({
+						/**
+						 * Apply the formatted replacement to the comment.
+						 *
+						 * @param  {object}  fixer
+						 *     The Oxlint fixer.
+						 *
+						 * @returns  {object}
+						 *     The fix to apply.
+						 */
+						fix: (fixer) => {
+							return replaceMinimalComment(fixer, comment, commentText, formattedComment);
+						},
+						message: "JSDoc tags must use the configured spacing, order, and grouping.",
+						node: comment,
+					});
+				}
+			},
+		};
+	},
+};

package/comments/rules/line-comments.js

@@ -0,0 +1,86 @@
+import {
+	getCommentText,
+	getLineCommentGroups,
+	getLineIndent,
+	getLineStart,
+} from "../utils/source.js";
+
+/**
+ * Create the line-comment alignment rule.
+ *
+ * @returns  {object}
+ *     The Oxlint rule definition.
+ */
+export default {
+	meta: {
+		docs: { description: "Align wrapped line comments with their first marker." },
+		fixable: "code",
+		type: "layout",
+	},
+	/**
+	 * Create the rule's node visitors.
+	 *
+	 * @param  {object}  context
+	 *     The Oxlint rule context.
+	 *
+	 * @returns  {object}
+	 *     The visitor functions for this rule.
+	 */
+	createOnce(context) {
+		return {
+			/**
+			 * Align every wrapped line-comment group in the file.
+			 */
+			Program() {
+				for (const commentGroup of getLineCommentGroups(context.sourceCode)) {
+					if (commentGroup.length < 2) {
+						continue;
+					}
+
+					// The group's leading comment's indentation.
+					const firstIndent = getLineIndent(context.sourceCode, commentGroup[0].range[0]);
+
+					if (firstIndent === null) {
+						continue;
+					}
+
+					// The reindentation fixes for the group's comments.
+					const fixes = [];
+
+					for (const comment of commentGroup) {
+						// The comment's current indentation.
+						const indentation = getLineIndent(context.sourceCode, comment.range[0]);
+
+						if (indentation === null || indentation === firstIndent) {
+							continue;
+						}
+
+						fixes.push({
+							range: [getLineStart(context.sourceCode, comment.range[0]), comment.range[1]],
+							text: `${firstIndent}${getCommentText(context.sourceCode, comment)}`,
+						});
+					}
+
+					if (fixes.length === 0) {
+						continue;
+					}
+
+					context.report({
+						/**
+						 * Apply the group's alignment fixes.
+						 *
+						 * @param  {object}  fixer
+						 *     The Oxlint fixer.
+						 *
+						 * @returns  {object[]}
+						 *     The fixes to apply.
+						 */
+						fix: (fixer) => fixes.map((fix) => fixer.replaceTextRange(fix.range, fix.text)),
+						message: "Wrapped line comments must align with the first comment marker.",
+						node: commentGroup[0],
+					});
+				}
+			},
+		};
+	},
+};

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

@@ -0,0 +1,159 @@
+import { formatJSDocWrapping, isJSDoc } from "../utils/jsdoc.js";
+
+import {
+	getCommentText,
+	getLineIndent,
+	getNewline,
+	isDirectiveComment,
+	replaceMinimalComment,
+} from "../utils/source.js";
+
+import { formatSentence, wrapWords } from "../utils/wrap.js";
+
+// The line length this rule wraps comments to.
+const maximumLineLength = 80;
+
+/**
+ * Wrap a line comment to the configured maximum width.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object}  comment
+ *     The line comment token.
+ *
+ * @returns  {string|null}
+ *     The wrapped comment, or null when it is not a standalone comment.
+ */
+function formatLineComment(sourceCode, comment) {
+	// The comment's current indentation.
+	const indentation = getLineIndent(sourceCode, comment.range[0]);
+
+	if (indentation === null) {
+		return null;
+	}
+
+	// The available width, allowing for the indent and "// " prefix.
+	const width = maximumLineLength - indentation.length - 3;
+	// The comment's undecorated text.
+	const text = comment.value.trim();
+
+	if (isDirectiveComment(comment)) {
+		return null;
+	}
+
+	if (text === "") {
+		return "//";
+	}
+
+	return wrapWords(text, Math.max(1, width))
+		.map((line, index) => `${index === 0 ? "" : indentation}// ${line}`)
+		.join(getNewline(sourceCode.text));
+}
+
+/**
+ * Wrap an ordinary block comment to the configured maximum width.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object}  comment
+ *     The block comment token.
+ *
+ * @returns  {string|null}
+ *     The wrapped comment, or null when it is not a standalone comment.
+ */
+function formatBlockComment(sourceCode, comment) {
+	// The comment's current indentation.
+	const indentation = getLineIndent(sourceCode, comment.range[0]);
+
+	if (indentation === null) {
+		return null;
+	}
+
+	// The comment's raw source text.
+	const commentText = getCommentText(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;
+	// The comment body, rewrapped to the available width.
+	const lines = wrapWords(text, Math.max(1, width));
+
+	return ["/*", ...lines.map((line) => `${indentation} * ${line}`), `${indentation} */`].join(
+		getNewline(sourceCode.text),
+	);
+}
+
+/**
+ * Create the maximum-line-length rule.
+ *
+ * @returns  {object}
+ *     The Oxlint rule definition.
+ */
+export default {
+	meta: {
+		docs: { description: "Wrap comments at 80 characters." },
+		fixable: "code",
+		type: "layout",
+	},
+	/**
+	 * Create the rule's node visitors.
+	 *
+	 * @param  {object}  context
+	 *     The Oxlint rule context.
+	 *
+	 * @returns  {object}
+	 *     The visitor functions for this rule.
+	 */
+	createOnce(context) {
+		return {
+			/**
+			 * Wrap every over-length comment in the file.
+			 */
+			Program() {
+				for (const comment of context.sourceCode.getAllComments()) {
+					if (comment.type === "Shebang") {
+						continue;
+					}
+
+					// The comment's raw source text.
+					const commentText = getCommentText(context.sourceCode, comment);
+					// The comment's individual source lines.
+					const lines = commentText.split(/\r\n|\n|\r/);
+
+					if (!lines.some((line) => line.length > maximumLineLength)) {
+						continue;
+					}
+
+					// The comment, rewrapped using the formatter matching its type.
+					const formattedComment =
+						comment.type === "Line"
+							? formatLineComment(context.sourceCode, comment)
+							: isJSDoc(commentText)
+								? formatJSDocWrapping(context.sourceCode, comment)
+								: formatBlockComment(context.sourceCode, comment);
+
+					if (formattedComment === null || formattedComment === commentText) {
+						continue;
+					}
+
+					context.report({
+						/**
+						 * Apply the wrapped replacement to the comment.
+						 *
+						 * @param  {object}  fixer
+						 *     The Oxlint fixer.
+						 *
+						 * @returns  {object}
+						 *     The fix to apply.
+						 */
+						fix: (fixer) => {
+							return replaceMinimalComment(fixer, comment, commentText, formattedComment);
+						},
+						message: "Comment exceeds 80 characters.",
+						node: comment,
+					});
+				}
+			},
+		};
+	},
+};

package/comments/rules/placement.js

@@ -0,0 +1,295 @@
+import {
+	getCommentNeighbours,
+	getCommentText,
+	getLineCommentGroups,
+	getLineIndent,
+	getLineStart,
+	getNewline,
+	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.
+ *
+ * @param  {object[][]}  lineCommentGroups
+ *     The adjacent line-comment groups.
+ *
+ * @returns  {object}
+ *     The continuation comments and their leaders.
+ */
+function getLineCommentContinuations(lineCommentGroups) {
+	// The comments that follow a group's leader, across every group.
+	const continuationComments = new Set();
+	// Each group's continuation comments, indexed by their leader.
+	const continuationsByLeader = new Map();
+
+	for (const group of lineCommentGroups) {
+		if (group.length < 2) {
+			continue;
+		}
+
+		// The group's leading comment and its continuations.
+		const [leader, ...continuations] = group;
+
+		continuationsByLeader.set(leader, continuations);
+
+		for (const continuation of continuations) {
+			continuationComments.add(continuation);
+		}
+	}
+
+	return { continuationComments, continuationsByLeader };
+}
+
+/**
+ * Return indentation relative to a comment's current indentation.
+ *
+ * @param  {string}  indentation
+ *     The line indentation.
+ * @param  {string}  commentIndent
+ *     The leading comment's current indentation.
+ *
+ * @returns  {string}
+ *     The indentation to preserve after reindenting.
+ */
+function getRelativeIndent(indentation, commentIndent) {
+	return indentation.startsWith(commentIndent)
+		? indentation.slice(commentIndent.length)
+		: indentation;
+}
+
+/**
+ * Reindent every line of a leading comment.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object}  comment
+ *     The leading comment token.
+ * @param  {string}  commentIndent
+ *     The comment's current indentation.
+ * @param  {string}  expectedIndent
+ *     The documented code's indentation.
+ *
+ * @returns  {string}
+ *     The reindented comment text.
+ */
+function getReindentedCommentText(sourceCode, comment, commentIndent, expectedIndent) {
+	return getCommentText(sourceCode, comment)
+		.split(/\r\n|\n|\r/)
+		.map((line, lineIndex) => {
+			if (lineIndex === 0) {
+				return `${expectedIndent}${line}`;
+			}
+
+			// The line's current indentation.
+			const lineIndent = line.match(/^[ \t]*/)[0];
+			// The indentation to preserve relative to the comment's own indent.
+			const relativeIndent = getRelativeIndent(lineIndent, commentIndent);
+
+			return `${expectedIndent}${relativeIndent}${line.slice(lineIndent.length)}`;
+		})
+		.join(getNewline(sourceCode.text));
+}
+
+/**
+ * Return replacements that align a leading comment group with its code.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object}  comment
+ *     The leading comment token.
+ * @param  {object[]}  continuations
+ *     The comment group's continuation tokens.
+ * @param  {string}  actualIndent
+ *     The comment's current indentation.
+ * @param  {string}  expectedIndent
+ *     The documented code's indentation.
+ *
+ * @returns  {object[]}
+ *     The indentation replacements.
+ */
+function getCommentIndentationFixes(
+	sourceCode,
+	comment,
+	continuations,
+	actualIndent,
+	expectedIndent,
+) {
+	if (actualIndent === expectedIndent) {
+		return [];
+	}
+
+	// The replacements, starting with the leading comment's reindent.
+	const fixes = [
+		{
+			range: [getLineStart(sourceCode, comment.range[0]), comment.range[1]],
+			text: getReindentedCommentText(sourceCode, comment, actualIndent, expectedIndent),
+		},
+	];
+
+	for (const continuation of continuations) {
+		// The continuation's current indentation.
+		const continuationIndent = getLineIndent(sourceCode, continuation.range[0]) ?? "";
+		// The indentation to preserve relative to the leading comment's indent.
+		const relativeIndent = getRelativeIndent(continuationIndent, actualIndent);
+
+		fixes.push({
+			range: [getLineStart(sourceCode, continuation.range[0]), continuation.range[1]],
+			text: `${expectedIndent}${relativeIndent}${getCommentText(sourceCode, continuation)}`,
+		});
+	}
+
+	return fixes;
+}
+
+/**
+ * Return the replacement that places a final leading comment against its code.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object}  comment
+ *     The leading comment token.
+ * @param  {object}  next
+ *     The documented source token.
+ * @param  {object|undefined}  followingComment
+ *     The next comment token.
+ * @param  {string}  expectedIndent
+ *     The documented code's indentation.
+ *
+ * @returns  {object|null}
+ *     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]) {
+		return null;
+	}
+
+	// The source text currently between the comment and its documented code.
+	const gap = getCommentToTokenGap(sourceCode, comment, next);
+	// 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 };
+}
+
+/**
+ * Create the immediate-comment-placement rule.
+ *
+ * @returns  {object}
+ *     The Oxlint rule definition.
+ */
+export default {
+	meta: {
+		docs: { description: "Keep comments immediately before documented code." },
+		fixable: "code",
+		type: "layout",
+	},
+	/**
+	 * Create the rule's node visitors.
+	 *
+	 * @param  {object}  context
+	 *     The Oxlint rule context.
+	 *
+	 * @returns  {object}
+	 *     The visitor functions for this rule.
+	 */
+	createOnce(context) {
+		return {
+			/**
+			 * Align every leading comment in the file with its documented code.
+			 */
+			Program() {
+				// Every comment token in the file, in source order.
+				const comments = context.sourceCode.getAllComments();
+
+				// The continuation comments and their group leaders.
+				const { continuationComments, continuationsByLeader } = getLineCommentContinuations(
+					getLineCommentGroups(context.sourceCode),
+				);
+
+				for (const [index, comment] of comments.entries()) {
+					if (comment.type === "Shebang" || continuationComments.has(comment)) {
+						continue;
+					}
+
+					// The comment's neighbouring token and comment.
+					const { next, previous } = getCommentNeighbours(context.sourceCode, comment);
+
+					if (next === null || !isLeadingComment(context.sourceCode, comment, previous)) {
+						continue;
+					}
+
+					// The documented code's indentation.
+					const expectedIndent = getLineIndent(context.sourceCode, next.range[0]);
+					// The comment's current indentation.
+					const actualIndent = getLineIndent(context.sourceCode, comment.range[0]);
+
+					if (expectedIndent === null || actualIndent === null) {
+						continue;
+					}
+
+					// The reindentation fixes for the comment and its continuations.
+					const fixes = getCommentIndentationFixes(
+						context.sourceCode,
+						comment,
+						continuationsByLeader.get(comment) ?? [],
+						actualIndent,
+						expectedIndent,
+					);
+
+					// 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.
+					const gapFix = getCommentGapFix(
+						context.sourceCode,
+						comment,
+						next,
+						followingComment,
+						expectedIndent,
+					);
+
+					if (gapFix !== null) {
+						fixes.push(gapFix);
+					}
+
+					if (fixes.length === 0) {
+						continue;
+					}
+
+					context.report({
+						/**
+						 * Apply the comment's alignment fixes.
+						 *
+						 * @param  {object}  fixer
+						 *     The Oxlint fixer.
+						 *
+						 * @returns  {object[]}
+						 *     The fixes to apply.
+						 */
+						fix: (fixer) => fixes.map((fix) => fixer.replaceTextRange(fix.range, fix.text)),
+						message: "Comment must be immediately before the documented code.",
+						node: comment,
+					});
+				}
+			},
+		};
+	},
+};