@lewishowles/lint-config 0.2.0 → 0.4.0

package/comments/rules/placement.js

@@ -0,0 +1,290 @@
+import {
+	getCommentNeighbours,
+	getCommentText,
+	getLineCommentGroups,
+	getLineIndent,
+	getLineStart,
+	getNewline,
+	isDirectiveComment,
+	isLeadingComment,
+} from "../utils/source.js";
+
+/**
+ * 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 closes the gap after a final leading comment.
+ *
+ * @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 comment after this one in source order, when there is one.
+ * @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) {
+	// 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;
+	}
+
+	// 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], gapEnd], 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" ||
+						isDirectiveComment(comment) ||
+						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,
+					});
+				}
+			},
+		};
+	},
+};

package/comments/rules/sentence-punctuation.js

@@ -0,0 +1,275 @@
+import { addTerminalPunctuation, capitaliseSentence, formatSentence } from "../utils/wrap.js";
+import { formatJSDocPunctuation, isJSDoc } from "../utils/jsdoc.js";
+import {
+	getCommentText,
+	getLineCommentGroups,
+	getLineIndent,
+	getNewline,
+	replaceMinimalComment,
+} from "../utils/source.js";
+
+/**
+ * Replace only the value of a line comment.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object}  comment
+ *     The line comment token.
+ * @param  {string}  value
+ *     The replacement comment value.
+ *
+ * @returns  {string}
+ *     The replacement comment text.
+ */
+function replaceLineCommentValue(sourceCode, comment, value) {
+	// The comment's raw source text.
+	const commentText = getCommentText(sourceCode, comment);
+
+	return `${commentText.slice(0, 2)}${value}`;
+}
+
+/**
+ * Format the prose text in a standard block-comment line.
+ *
+ * @param  {string}  line
+ *     The block-comment line.
+ * @param  {function}  formatProse
+ *     The formatter for the line's prose.
+ *
+ * @returns  {string}
+ *     The formatted block-comment line.
+ */
+function formatBlockCommentLine(line, formatProse) {
+	// The line's leading `*` decoration, when present.
+	const marker = line.match(/^\s*\*\s?/);
+
+	if (marker === null) {
+		return line;
+	}
+
+	return `${marker[0]}${formatProse(line.slice(marker[0].length).trim())}`;
+}
+
+/**
+ * Return a sentence-formatted line-comment group.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object[]}  comments
+ *     The adjacent line comments.
+ *
+ * @returns  {object|null}
+ *     The first and last replacements, or null when no sentence needs work.
+ */
+function formatLineCommentGroup(sourceCode, comments) {
+	// The group's first comment token.
+	const firstComment = comments[0];
+	// The group's last comment token.
+	const lastComment = comments.at(-1);
+	// The first comment's undecorated text.
+	const firstText = firstComment.value.trim();
+
+	if (firstText === "" || firstText.startsWith("@")) {
+		return null;
+	}
+
+	// The first comment's value, capitalised or fully sentence-formatted.
+	const firstValue =
+		comments.length === 1
+			? formatSentence(firstComment.value)
+			: capitaliseSentence(firstComment.value);
+
+	// The last comment's value, punctuated to close the sentence.
+	const lastValue = comments.length === 1 ? firstValue : addTerminalPunctuation(lastComment.value);
+	// The replacement comment text for the first and last comments.
+	const firstReplacement = replaceLineCommentValue(sourceCode, firstComment, firstValue);
+	// The replacement comment text for the last comment.
+	const lastReplacement = replaceLineCommentValue(sourceCode, lastComment, lastValue);
+
+	if (
+		firstReplacement === getCommentText(sourceCode, firstComment) &&
+		lastReplacement === getCommentText(sourceCode, lastComment)
+	) {
+		return null;
+	}
+
+	return { firstComment, firstReplacement, lastComment, lastReplacement };
+}
+
+/**
+ * Format prose in an ordinary block comment.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object}  comment
+ *     The block comment token.
+ *
+ * @returns  {string}
+ *     The sentence-formatted comment text.
+ */
+function formatOrdinaryBlockComment(sourceCode, comment) {
+	// The comment's raw source text.
+	const commentText = getCommentText(sourceCode, comment);
+	// The indentation the comment's lines are aligned to.
+	const indentation = getLineIndent(sourceCode, comment.range[0]);
+	// The comment body, stripped of its /* */ delimiters.
+	const content = commentText.slice(2, -2).trim();
+
+	if (indentation === null || content === "" || /^(?:eslint|oxlint|istanbul|c8)-/.test(content)) {
+		return commentText;
+	}
+
+	if (!commentText.includes("\n") && !commentText.includes("\r")) {
+		return `/* ${formatSentence(content)} */`;
+	}
+
+	// The comment's individual source lines.
+	const lines = commentText.split(/\r\n|\n|\r/);
+
+	// The indexes of lines carrying prose, excluding the delimiter lines.
+	const proseLineIndexes = lines
+		.slice(1, -1)
+		.map((line, index) => ({ index: index + 1, text: line.replace(/^\s*\*?\s?/, "").trim() }))
+		.filter((line) => line.text !== "")
+		.map((line) => line.index);
+
+	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.
+		const firstProseLine = proseLineIndexes[0];
+		// The last prose line index, which ends the sentence.
+		const lastProseLine = proseLineIndexes.at(-1);
+
+		formattedLines[firstProseLine] = formatBlockCommentLine(
+			formattedLines[firstProseLine],
+			capitaliseSentence,
+		);
+		formattedLines[lastProseLine] = formatBlockCommentLine(
+			formattedLines[lastProseLine],
+			addTerminalPunctuation,
+		);
+
+		return formattedLines.join(getNewline(sourceCode.text));
+	}
+
+	// The comment's prose, joined into a single paragraph.
+	const paragraphs = content
+		.split(/\r\n|\n|\r/)
+		.map((line) => line.replace(/^\s*\*?\s?/, "").trim())
+		.filter(Boolean)
+		.join(" ");
+
+	return ["/*", `${indentation} * ${formatSentence(paragraphs)}`, `${indentation} */`].join(
+		getNewline(sourceCode.text),
+	);
+}
+
+/**
+ * Create the complete-sentence comment rule.
+ *
+ * @returns  {object}
+ *     The Oxlint rule definition.
+ */
+export default {
+	meta: {
+		docs: { description: "Format existing comments as complete sentences." },
+		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 comment in the file as a complete sentence.
+			 */
+			Program() {
+				for (const commentGroup of getLineCommentGroups(context.sourceCode)) {
+					// 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.
+							 *
+							 * @param  {object}  fixer
+							 *     The Oxlint fixer.
+							 *
+							 * @returns  {object[]}
+							 *     The fixes to apply.
+							 */
+							fix: (fixer) => {
+								// The fixes to apply, starting with the first comment's replacement.
+								const fixes = [
+									replaceMinimalComment(
+										fixer,
+										formattedGroup.firstComment,
+										getCommentText(context.sourceCode, formattedGroup.firstComment),
+										formattedGroup.firstReplacement,
+									),
+								];
+
+								if (formattedGroup.lastComment.range[0] !== formattedGroup.firstComment.range[0]) {
+									fixes.push(
+										replaceMinimalComment(
+											fixer,
+											formattedGroup.lastComment,
+											getCommentText(context.sourceCode, formattedGroup.lastComment),
+											formattedGroup.lastReplacement,
+										),
+									);
+								}
+
+								return fixes;
+							},
+							message: "Comment text must be a complete sentence.",
+							node: formattedGroup.firstComment,
+						});
+					}
+				}
+
+				for (const comment of context.sourceCode.getAllComments()) {
+					if (comment.type !== "Block") {
+						continue;
+					}
+
+					// The comment's raw source text.
+					const commentText = getCommentText(context.sourceCode, comment);
+
+					// The comment, sentence-formatted using the JSDoc or ordinary-block formatter.
+					const formattedComment = isJSDoc(commentText)
+						? formatJSDocPunctuation(context.sourceCode, comment)
+						: formatOrdinaryBlockComment(context.sourceCode, comment);
+
+					if (formattedComment !== commentText) {
+						context.report({
+							/**
+							 * Apply the sentence-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: "Comment text must be a complete sentence.",
+							node: comment,
+						});
+					}
+				}
+			},
+		};
+	},
+};

package/comments/rules/variable-declarations.js

@@ -0,0 +1,88 @@
+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.
+ *
+ * @param  {object}  node
+ *     The variable declaration node.
+ *
+ * @returns  {boolean}
+ *     Whether the declaration is exempt from the rule.
+ */
+function isLoopHeaderDeclaration(node) {
+	// Inspects the declaration's parent to identify loop headers.
+	const parent = node.parent;
+
+	return (
+		(parent.type === "ForStatement" && parent.init === node) ||
+		((parent.type === "ForInStatement" || parent.type === "ForOfStatement") && parent.left === node)
+	);
+}
+
+/**
+ * Create the variable-declaration comment rule.
+ *
+ * @returns  {object}
+ *     The Oxlint rule definition.
+ */
+export default {
+	meta: {
+		docs: { description: "Require comments before variable declarations." },
+		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 variable declaration for a preceding line comment.
+			 *
+			 * @param  {object}  node
+			 *     The variable declaration node.
+			 */
+			VariableDeclaration(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;
+				}
+
+				// 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: documentationNode,
+					});
+				}
+
+				if (node.declarations.length > 1) {
+					context.report({
+						message: "Declare one variable per declaration statement.",
+						node,
+					});
+				}
+			},
+		};
+	},
+};