@lewishowles/lint-config 0.2.0 → 0.3.0

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,71 @@
+import { hasImmediateLineComment } from "../utils/source.js";
+
+/**
+ * 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 const or let declaration for a preceding comment.
+			 *
+			 * @param  {object}  node
+			 *     The variable declaration node.
+			 */
+			VariableDeclaration(node) {
+				if ((node.kind !== "const" && node.kind !== "let") || isLoopHeaderDeclaration(node)) {
+					return;
+				}
+
+				if (!hasImmediateLineComment(context.sourceCode, node)) {
+					context.report({
+						message: "Variable declarations require an immediately preceding line comment.",
+						node,
+					});
+				}
+
+				if (node.declarations.length > 1) {
+					context.report({
+						message: "Declare one variable per declaration statement.",
+						node,
+					});
+				}
+			},
+		};
+	},
+};

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

@@ -0,0 +1,169 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isDirectiveComment } from "../utils/source.js";
+
+// Captures the opening tag's attributes separately, so the setup attribute
+// can be tested without the tag being available from Oxlint's extracted AST.
+const scriptBlockPattern =
+	/(?<openingTag><script\b(?<attributes>[^>]*)>)(?<content>[\s\S]*?)<\/script\s*>/gi;
+
+// Only a standalone setup attribute qualifies, avoiding matches such as
+// data-setup or setup-mode.
+const setupAttributePattern = /(?:^|\s)setup(?:\s|=|$)/i;
+// Match only indentation and one line break, so documentation sits directly
+// after the script tag.
+const immediateCommentGapPattern = /^[ \t]*(?:\r?\n[ \t]*)?$/;
+
+/**
+ * Read raw Vue source because extracted script text cannot identify script
+ * setup.
+ *
+ * @param  {object}  context
+ *     The Oxlint rule context.
+ *
+ * @returns  {string|null}
+ *     The Vue source, when the physical filename can be read.
+ */
+function getVueSource(context) {
+	try {
+		// The extracted script text does not include the component markup.
+		// Read the opening tag from the Vue file instead.
+		const physicalFilename = context.physicalFilename;
+
+		if (typeof physicalFilename !== "string" || !physicalFilename.endsWith(".vue")) {
+			return null;
+		}
+
+		if (!existsSync(physicalFilename)) {
+			return null;
+		}
+
+		return readFileSync(physicalFilename, "utf8");
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Get raw Vue script blocks in source order.
+ *
+ * @param  {object}  context
+ *     The Oxlint rule context.
+ *
+ * @returns  {RegExpMatchArray[]}
+ *     The Vue script blocks, or an empty array when the source is unavailable.
+ */
+function getScriptBlocks(context) {
+	// Component markup is only available from the physical Vue file.
+	const vueSource = getVueSource(context);
+
+	return vueSource ? Array.from(vueSource.matchAll(scriptBlockPattern)) : [];
+}
+
+/**
+ * Find the raw script block matching the current Program's extracted text.
+ *
+ * @param  {object}  context
+ *     The rule context for the extracted script block.
+ *
+ * @returns  {RegExpMatchArray|undefined}
+ *     The matching raw script block, when one is found.
+ */
+function findScriptBlock(context) {
+	// Re-read on every call rather than caching, since this file's other
+	// script blocks may not have been visited yet or ever in this run.
+	const scriptBlocks = getScriptBlocks(context);
+
+	return scriptBlocks.find(
+		(scriptBlock) => scriptBlock.groups.content.trim() === context.sourceCode.text.trim(),
+	);
+}
+
+/**
+ * Check whether a script block uses Vue's setup attribute.
+ *
+ * @param  {RegExpMatchArray}  scriptBlock
+ *     The raw Vue script block.
+ *
+ * @returns  {boolean}
+ *     Whether the script block is a script setup block.
+ */
+function isScriptSetupBlock(scriptBlock) {
+	// Inspect only the opening tag, so setup code cannot affect the block type.
+	const scriptAttributes = scriptBlock.groups?.attributes ?? "";
+
+	return setupAttributePattern.test(scriptAttributes);
+}
+
+/**
+ * Check whether a Vue script setup block starts with a documentation comment.
+ *
+ * @param  {object}  context
+ *     The rule context for the extracted script block.
+ * @param  {RegExpMatchArray|undefined}  scriptBlock
+ *     The script block matched to the current component's entry point.
+ *
+ * @returns  {boolean}
+ *     Whether the component has the required documentation comment.
+ */
+function hasComponentDocumentation(context, scriptBlock) {
+	if (!scriptBlock || !isScriptSetupBlock(scriptBlock)) {
+		return true;
+	}
+
+	// This Program visitor runs once per script block, so sourceCode is scoped
+	// to the current block and [0] cannot pick up a comment from another one.
+	const comment = context.sourceCode.getAllComments()[0];
+
+	// Lint directives alter rule execution but cannot document a component.
+	if (comment?.type !== "Block" || isDirectiveComment(comment)) {
+		return false;
+	}
+
+	// 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);
+}
+
+export default {
+	meta: {
+		docs: { description: "Require documentation for Vue script setup components." },
+		type: "suggestion",
+	},
+	/**
+	 * Create the checks that inspect each script block.
+	 *
+	 * @param  {object}  context
+	 *     The Oxlint rule context.
+	 *
+	 * @returns  {object}
+	 *     The script-block checks for this rule.
+	 */
+	createOnce(context) {
+		return {
+			/**
+			 * Check the current component's script setup block for documentation.
+			 *
+			 * @param  {object}  node
+			 *     The entry point parsed from the current script block.
+			 */
+			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
+				// call rather than tracked with shared state.
+				const scriptBlock = findScriptBlock(context);
+
+				if (hasComponentDocumentation(context, scriptBlock)) {
+					return;
+				}
+
+				context.report({
+					message:
+						"Vue script setup components require a documentation block after the opening tag.",
+					node: node.body[0] ?? node,
+				});
+			},
+		};
+	},
+};

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

@@ -0,0 +1,123 @@
+import { getCommentNeighbours, isDirectiveComment, isLeadingComment } from "../utils/source.js";
+import { getObjectArgument, getObjectProperties, isNamedCall } from "../utils/vue-macro.js";
+
+// Matches the single newline and indentation allowed between a comment and an
+// event.
+const immediateCommentGapPattern = /^\r?\n[ \t]*$/;
+
+// The message shared by all undocumented runtime events.
+const missingCommentMessage =
+	"Vue emit declarations require an immediately preceding block comment.";
+
+/**
+ * Return whether the current lint target is a physical Vue single-file
+ * component.
+ *
+ * @param  {object}  context
+ *     The Oxlint rule context.
+ *
+ * @returns  {boolean}
+ *     Whether the current file has a Vue filename.
+ */
+function isVueFile(context) {
+	try {
+		// Use the physical path because the AST does not identify Vue files.
+		const physicalFilename = context.physicalFilename;
+
+		return typeof physicalFilename === "string" && physicalFilename.endsWith(".vue");
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Return whether a property has an immediately preceding block comment.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object}  property
+ *     The property to inspect.
+ *
+ * @returns  {boolean}
+ *     Whether the property has the required documentation comment.
+ */
+function hasBlockComment(sourceCode, property) {
+	// Finds the closest preceding comment.
+	const comment = sourceCode
+		.getAllComments()
+		.findLast((candidate) => candidate.range[1] <= property.range[0]);
+
+	if (comment?.type !== "Block" || isDirectiveComment(comment)) {
+		return false;
+	}
+
+	// Checks the comments immediately around the property.
+	const { next, previous } = getCommentNeighbours(sourceCode, comment);
+	// The source text between the comment and the property.
+	const gap = sourceCode.text.slice(comment.range[1], property.range[0]);
+
+	return (
+		next?.range[0] === property.range[0] &&
+		isLeadingComment(sourceCode, comment, previous) &&
+		immediateCommentGapPattern.test(gap)
+	);
+}
+
+/**
+ * Report missing comments for runtime emit events.
+ *
+ * @param  {object}  context
+ *     The Oxlint rule context.
+ * @param  {object}  objectExpression
+ *     The runtime emits object to inspect.
+ */
+function reportEventDocumentation(context, objectExpression) {
+	for (const property of getObjectProperties(objectExpression)) {
+		// Checks whether this event has the required documentation.
+		const hasDocumentation = hasBlockComment(context.sourceCode, property);
+
+		if (!hasDocumentation) {
+			context.report({ message: missingCommentMessage, node: property });
+
+			continue;
+		}
+	}
+}
+
+export default {
+	meta: {
+		docs: { description: "Require block comments for Vue runtime emits." },
+		type: "suggestion",
+	},
+	/**
+	 * Create the rule's node visitors.
+	 *
+	 * @param  {object}  context
+	 *     The Oxlint rule context.
+	 *
+	 * @returns  {object}
+	 *     The call-expression visitor for this rule.
+	 */
+	createOnce(context) {
+		return {
+			/**
+			 * Check runtime defineEmits calls for event documentation.
+			 *
+			 * @param  {object}  node
+			 *     The call expression to inspect.
+			 */
+			CallExpression(node) {
+				if (!isVueFile(context) || !isNamedCall(node, "defineEmits")) {
+					return;
+				}
+
+				// Array and type-only forms have no runtime properties to document.
+				const emitsObject = getObjectArgument(node, 0);
+
+				if (emitsObject) {
+					reportEventDocumentation(context, emitsObject);
+				}
+			},
+		};
+	},
+};