@lewishowles/lint-config 0.2.0 → 0.4.0

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);
+				}
+			},
+		};
+	},
+};

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

@@ -0,0 +1,224 @@
+import {
+	getObjectArgument,
+	getObjectProperties,
+	getPropertyName,
+	isNamedCall,
+} from "../utils/vue-macro.js";
+import { getCommentNeighbours, isDirectiveComment, isLeadingComment } from "../utils/source.js";
+
+// Matches the single newline and indentation allowed between a comment and a
+// prop.
+const immediateCommentGapPattern = /^\r?\n[ \t]*$/;
+
+// The message shared by runtime props and their withDefaults entries.
+const missingCommentMessage =
+	"Vue prop declarations require an immediately preceding block comment.";
+
+/**
+ * Return the runtime props object from a defineProps call or withDefaults
+ * wrapper.
+ *
+ * @param  {object}  callNode
+ *     The call to inspect.
+ *
+ * @returns  {object|null}
+ *     The runtime props object, or null for type-only and unrelated calls.
+ */
+function getPropsObject(callNode) {
+	if (isNamedCall(callNode, "defineProps")) {
+		return getObjectArgument(callNode, 0);
+	}
+
+	if (!isNamedCall(callNode, "withDefaults")) {
+		return null;
+	}
+
+	// withDefaults' first argument, expected to be the defineProps call.
+	const definePropsCall = callNode.arguments[0];
+
+	return isNamedCall(definePropsCall, "defineProps") ? getObjectArgument(definePropsCall, 0) : null;
+}
+
+/**
+ * Return the defaults object from a withDefaults call.
+ *
+ * @param  {object}  callNode
+ *     The call to inspect.
+ *
+ * @returns  {object|null}
+ *     The defaults object, when the call has one.
+ */
+function getDefaultsObject(callNode) {
+	return isNamedCall(callNode, "withDefaults") ? getObjectArgument(callNode, 1) : null;
+}
+
+/**
+ * Return whether a defineProps call is already handled by its withDefaults
+ * wrapper.
+ *
+ * @param  {object}  node
+ *     The defineProps call to inspect.
+ *
+ * @returns  {boolean}
+ *     Whether the call is the first argument of withDefaults.
+ */
+function isWrappedDefinePropsCall(node) {
+	// The node's enclosing call, when present.
+	const parent = node.parent;
+
+	return isNamedCall(parent, "withDefaults") && parent.arguments[0] === node;
+}
+
+/**
+ * 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)
+	);
+}
+
+/**
+ * Return the names of documented properties in an object expression.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object}  objectExpression
+ *     The object expression to inspect.
+ *
+ * @returns  {Set<string>}
+ *     The documented property names.
+ */
+function getDocumentedPropertyNames(sourceCode, objectExpression) {
+	// Accumulates property names with a qualifying comment.
+	const documentedPropertyNames = new Set();
+
+	for (const property of getObjectProperties(objectExpression)) {
+		// The property's name, when it can be determined.
+		const propertyName = getPropertyName(property);
+
+		if (propertyName !== null && hasBlockComment(sourceCode, property)) {
+			documentedPropertyNames.add(propertyName);
+		}
+	}
+
+	return documentedPropertyNames;
+}
+
+/**
+ * Report properties without their required block comments.
+ *
+ * @param  {object}  context
+ *     The Oxlint rule context.
+ * @param  {object}  objectExpression
+ *     The object expression whose properties should be checked.
+ * @param  {Set<string>|undefined}  exemptedPropertyNames
+ *     Property names documented by a matching defineProps entry.
+ */
+function reportUndocumentedProperties(context, objectExpression, exemptedPropertyNames) {
+	for (const property of getObjectProperties(objectExpression)) {
+		// The property's name, when it can be determined.
+		const propertyName = getPropertyName(property);
+
+		if (propertyName !== null && exemptedPropertyNames?.has(propertyName)) {
+			continue;
+		}
+
+		if (!hasBlockComment(context.sourceCode, property)) {
+			context.report({ message: missingCommentMessage, node: property });
+		}
+	}
+}
+
+/**
+ * Check runtime props and withDefaults entries for documentation.
+ *
+ * @param  {object}  context
+ *     The Oxlint rule context.
+ * @param  {object}  node
+ *     The call expression to inspect.
+ */
+function reportCallDocumentation(context, node) {
+	// The call's runtime props object, when present.
+	const propsObject = getPropsObject(node);
+
+	if (!propsObject) {
+		return;
+	}
+
+	// Every runtime defineProps property owns a required comment.
+	reportUndocumentedProperties(context, propsObject);
+
+	// The call's withDefaults defaults object, when present.
+	const defaultsObject = getDefaultsObject(node);
+
+	if (!defaultsObject) {
+		return;
+	}
+
+	// A matching defineProps comment documents the corresponding default too.
+	const documentedPropertyNames = getDocumentedPropertyNames(context.sourceCode, propsObject);
+
+	reportUndocumentedProperties(context, defaultsObject, documentedPropertyNames);
+}
+
+export default {
+	meta: {
+		docs: { description: "Require block comments for Vue runtime props." },
+		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 defineProps calls and their withDefaults wrapper.
+			 *
+			 * @param  {object}  node
+			 *     The call expression to inspect.
+			 */
+			CallExpression(node) {
+				if (!isNamedCall(node, "defineProps") && !isNamedCall(node, "withDefaults")) {
+					return;
+				}
+
+				if (isNamedCall(node, "defineProps") && isWrappedDefinePropsCall(node)) {
+					return;
+				}
+
+				reportCallDocumentation(context, node);
+			},
+		};
+	},
+};