@lewishowles/lint-config 0.2.0 → 0.4.0

package/comments/rules/configured-api-calls.js

@@ -0,0 +1,143 @@
+import { getDocumentationNode } from "../utils/documentation.js";
+import { hasImmediateLineComment } from "../utils/source.js";
+
+// The built-in APIs that require a preceding comment by default.
+const builtInApis = new Set([
+	"onBeforeMount",
+	"onMounted",
+	"onBeforeUpdate",
+	"onUpdated",
+	"onBeforeUnmount",
+	"onUnmounted",
+	"onActivated",
+	"onDeactivated",
+	"onErrorCaptured",
+	"onRenderTracked",
+	"onRenderTriggered",
+	"onServerPrefetch",
+	"watch",
+	"watchEffect",
+	"watchPostEffect",
+	"watchSyncEffect",
+	"onClickOutside",
+]);
+
+/**
+ * Return whether a call is the documented initializer of a variable
+ * declaration.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object}  node
+ *     The call expression node.
+ *
+ * @returns  {boolean}
+ *     Whether the call is directly initialized by a documented declaration.
+ */
+function hasDocumentedVariableDeclaration(sourceCode, node) {
+	// The call's enclosing variable declarator, when there is one.
+	const declarator = node.parent;
+
+	if (declarator?.type !== "VariableDeclarator" || declarator.init !== node) {
+		return false;
+	}
+
+	// The declarator's enclosing variable declaration.
+	const declaration = declarator.parent;
+
+	if (declaration?.type !== "VariableDeclaration") {
+		return false;
+	}
+
+	// Resolves any export wrapper before checking for documentation.
+	const documentationNode = getDocumentationNode(declaration);
+
+	return hasImmediateLineComment(sourceCode, documentationNode);
+}
+
+/**
+ * Return the configured API names for the rule.
+ *
+ * @param  {object}  context
+ *     The Oxlint rule context.
+ *
+ * @returns  {Set<string>}
+ *     The built-in and configured API names.
+ */
+function getConfiguredApis(context) {
+	// The rule's resolved options for the file currently being visited.
+	const options = context.options?.[0];
+	// The project-configured API names to add to the built-in list.
+	const additionalApis = options?.additionalApis ?? [];
+
+	return new Set([...builtInApis, ...additionalApis]);
+}
+
+/**
+ * Create the configured API call comment rule.
+ *
+ * @returns  {object}
+ *     The Oxlint rule definition.
+ */
+export default {
+	meta: {
+		docs: { description: "Require comments before configured API calls." },
+		type: "suggestion",
+		schema: [
+			{
+				type: "object",
+				properties: {
+					additionalApis: {
+						type: "array",
+						items: { type: "string" },
+						uniqueItems: true,
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+		defaultOptions: [{ additionalApis: [] }],
+	},
+
+	/**
+	 * 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 configured API call for a preceding comment.
+			 *
+			 * @param  {object}  node
+			 *     The call expression node.
+			 */
+			CallExpression(node) {
+				// Read fresh for every call: createOnce's visitor is shared across every file
+				// in the run, so caching this at closure-creation time would freeze the first
+				// file's options.
+				const configuredApis = getConfiguredApis(context);
+
+				if (node.callee.type !== "Identifier" || !configuredApis.has(node.callee.name)) {
+					return;
+				}
+
+				if (
+					hasDocumentedVariableDeclaration(context.sourceCode, node) ||
+					hasImmediateLineComment(context.sourceCode, node)
+				) {
+					return;
+				}
+
+				context.report({
+					message: "Configured API calls require an immediately preceding line comment.",
+					node,
+				});
+			},
+		};
+	},
+};

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