@lewishowles/lint-config 0.4.0 → 0.6.0

package/comments/rules/variable-declarations.js

@@ -1,4 +1,4 @@
-import { getDocumentationNode } from "../utils/documentation.js";
+import { getDocumentationNode, isFunctionValue } from "../utils/documentation.js";
 import { hasImmediateLineComment } from "../utils/source.js";
 
 // Declaration kinds that require an immediately preceding line comment.
@@ -33,6 +33,18 @@ export default {
 	meta: {
 		docs: { description: "Require comments before variable declarations." },
 		type: "suggestion",
+		schema: [
+			{
+				type: "object",
+				properties: {
+					rootOnly: {
+						type: "boolean",
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+		defaultOptions: [{ rootOnly: false }],
 	},
 	/**
 	 * Create the rule's node visitors.
@@ -56,7 +68,8 @@ export default {
 					return;
 				}
 
-				// A lone const class expression is documented by class-documentation.
+				// A lone const class expression is documented by
+				// class-documentation.
 				if (
 					node.kind === "const" &&
 					node.declarations.length === 1 &&
@@ -66,10 +79,34 @@ export default {
 					return;
 				}
 
-				// Resolves any export wrapper before checking for documentation.
+				// Whether every name in this const holds a function. The
+				// function-documentation rule already requires a JSDoc block on
+				// those, so asking for a line comment as well would make the
+				// two rules impossible to satisfy together.
+				const isFunctionValuedConst =
+					node.kind === "const" &&
+					node.declarations.every(
+						({ id, init }) => id.type === "Identifier" && isFunctionValue(init),
+					);
+
+				// The rule's resolved options for the file currently being
+				// visited.
+				const options = context.options?.[0];
+				// Resolves any export wrapper before checking for
+				// documentation.
 				const documentationNode = getDocumentationNode(node);
 
-				if (!hasImmediateLineComment(context.sourceCode, documentationNode)) {
+				// With rootOnly, only declarations directly under the Program
+				// need a comment, so a nested variable inside a function is
+				// left alone.
+				const shouldCheckDocumentation =
+					!options?.rootOnly || documentationNode.parent?.type === "Program";
+
+				if (
+					!isFunctionValuedConst &&
+					shouldCheckDocumentation &&
+					!hasImmediateLineComment(context.sourceCode, documentationNode)
+				) {
 					context.report({
 						message: "Variable declarations require an immediately preceding line comment.",
 						node: documentationNode,

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

@@ -1,8 +1,8 @@
 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.
+// 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;
 
@@ -69,8 +69,8 @@ function getScriptBlocks(context) {
  *     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.
+	// 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(
@@ -119,7 +119,8 @@ function hasComponentDocumentation(context, scriptBlock) {
 		return false;
 	}
 
-	// A blank line would separate the component documentation from its entry point.
+	// 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);
@@ -142,7 +143,8 @@ export default {
 	createOnce(context) {
 		return {
 			/**
-			 * Check the current component's script setup block for documentation.
+			 * Check the current component's script setup block for
+			 * documentation.
 			 *
 			 * @param  {object}  node
 			 *     The entry point parsed from the current script block.
@@ -150,8 +152,8 @@ export default {
 			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.
+				// 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)) {

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

@@ -111,7 +111,8 @@ export default {
 					return;
 				}
 
-				// Array and type-only forms have no runtime properties to document.
+				// Array and type-only forms have no runtime properties to
+				// document.
 				const emitsObject = getObjectArgument(node, 0);
 
 				if (emitsObject) {

package/comments/utils/documentation.js

@@ -293,7 +293,6 @@ function hasValueReturn(node) {
 export function reportFunctionDocumentation(context, node, functionNode, options = {}) {
 	// Defaults to "Functions" when the caller names no declaration kind.
 	const subject = options.subject ?? "Functions";
-
 	// Finds the JSDoc block documenting this function, when present.
 	const comment = getDocumentationComment(context.sourceCode, node);
 

package/comments/utils/jsdoc.js

@@ -1,5 +1,11 @@
-import { getCommentText, getLineIndent, getNewline } from "./source.js";
-import { addTerminalPunctuation, capitaliseSentence, formatSentence, wrapWords } from "./wrap.js";
+import { getDisplayWidth } from "./source.js";
+import {
+	addTerminalPunctuation,
+	capitaliseSentence,
+	formatSentence,
+	refillCommentLines,
+	wrapWords,
+} from "./wrap.js";
 
 // The JSDoc tags this package formats, in their required output order.
 const tagOrder = ["param", "throws", "returns"];
@@ -148,6 +154,7 @@ function parseTargetTags(tagLines) {
 				rest: match[2].trim(),
 				type: match[1],
 			};
+
 			entries.push(currentEntry);
 		} else if (currentEntry) {
 			currentEntry.description.push(line);
@@ -203,21 +210,27 @@ function getInlineTagDescription(entry) {
 }
 
 /**
- * Format prose without changing its existing line wrapping.
+ * Format and refill JSDoc prose while preserving paragraph and list boundaries.
  *
  * @param  {string[]}  lines
  *     The prose content lines.
  * @param  {boolean}  addPunctuation
  *     Whether to format each paragraph as a sentence.
+ * @param  {string}  indentation
+ *     The indentation used by the comment.
  *
  * @returns  {string[]}
  *     The formatted prose lines.
  */
-function formatUnwrappedProse(lines, addPunctuation) {
-	// The formatted lines, built up in place.
-	const result = lines.map((line) => line.trim());
-
-	// The index of the current paragraph's first line, or null between paragraphs.
+function formatUnwrappedProse(lines, addPunctuation, indentation) {
+	// The prose lines after refilling, then formatted in place below.
+	const result = refillCommentLines(
+		lines.map((line) => ({ prefix: `${indentation} * `, text: line })),
+		80,
+	).map(({ text }) => text);
+
+	// The index of the current paragraph's first line, or null between
+	// paragraphs.
 	let paragraphStart = null;
 
 	for (let index = 0; index < result.length; index += 1) {
@@ -281,12 +294,14 @@ function formatProse(lines, width, addPunctuation) {
 		}
 
 		result.push(...wrapWords(text, width));
+
 		paragraph = [];
 	}
 
 	for (const line of lines) {
 		if (line.trim() === "") {
 			flushParagraph();
+
 			if (result.at(-1) !== "") {
 				result.push("");
 			}
@@ -336,7 +351,8 @@ function formatTags(tagLines, width, addPunctuation, normaliseTags) {
 	// The formatted lines, built up in place.
 	const result = [];
 
-	// The tag type of the previously written entry, used to detect group changes.
+	// The tag type of the previously written entry, used to detect group
+	// changes.
 	let lastType = null;
 
 	// The entries regrouped into the required tag order.
@@ -406,15 +422,18 @@ function formatMixedTags(lines, width, addPunctuation) {
 				type: match[1],
 			};
 			preserveSection = false;
+
 			result.push(formatTagHeader(currentEntry));
 		} else if (tagName !== null) {
 			currentEntry = null;
 			preserveSection = isPreservedSectionTag(line);
+
 			result.push(line.trim());
 		} else if (preserveSection) {
 			result.push(line);
 		} else if (line.trim() === "") {
 			currentEntry = null;
+
 			if (result.at(-1) !== "") {
 				result.push("");
 			}
@@ -475,6 +494,7 @@ function formatTagDescriptions(lines, width, addPunctuation) {
 		}
 
 		result.push(...wrapWords(text, width).map((line) => `    ${line}`));
+
 		description = [];
 	}
 
@@ -485,11 +505,13 @@ function formatTagDescriptions(lines, width, addPunctuation) {
 		if (tagName !== null) {
 			flushDescription();
 			result.push(line.trim());
+
 			preserveSection = isPreservedSectionTag(line);
 		} else if (preserveSection) {
 			result.push(line);
 		} else if (line.trim() === "") {
 			flushDescription();
+
 			if (result.at(-1) !== "") {
 				result.push("");
 			}
@@ -510,23 +532,20 @@ function formatTagDescriptions(lines, width, addPunctuation) {
 /**
  * Return the details needed to format a JSDoc block comment.
  *
- * @param  {object}  sourceCode
- *     The Oxlint source code object.
- * @param  {object}  comment
- *     The JSDoc comment token.
+ * @param  {string}  commentText
+ *     The JSDoc comment text.
+ * @param  {object}  formattingOptions
+ *     The indentation (`indent`) and newline style (`newline`) of the source
+ *     around the comment.
  *
  * @returns  {object}
  *     The JSDoc content and layout details.
  */
-function getJSDocFormattingContext(sourceCode, comment) {
-	// The raw comment source text.
-	const commentText = getCommentText(sourceCode, comment);
-	// The indentation the comment's lines are aligned to.
-	const indent = getLineIndent(sourceCode, comment.range[0]) ?? "";
-	// The newline style used by the surrounding source.
-	const newline = getNewline(sourceCode.text);
+function getJSDocFormattingContext(commentText, formattingOptions) {
+	// The indentation and newline style used by the surrounding source.
+	const { indent, newline } = formattingOptions;
 	// The available content width, allowing for the indent and " * " prefix.
-	const width = Math.max(1, 80 - indent.length - 3);
+	const width = Math.max(1, 80 - getDisplayWidth(indent) - 3);
 	// The undecorated comment content lines.
 	const content = getJSDocContent(commentText);
 	// The content split into its prose and tag sections.
@@ -611,19 +630,20 @@ function renderJSDocComment(formattingContext, outputLines) {
 /**
  * Format JSDoc block structure and delimiters.
  *
- * @param  {object}  sourceCode
- *     The Oxlint source code object.
- * @param  {object}  comment
- *     The JSDoc comment token.
+ * @param  {string}  commentText
+ *     The JSDoc comment text.
+ * @param  {object}  formattingOptions
+ *     The indentation (`indent`) and newline style (`newline`) of the source
+ *     around the comment.
  *
  * @returns  {string}
  *     The formatted comment text.
  */
-export function formatJSDocBlockStructure(sourceCode, comment) {
+export function formatJSDocBlockStructure(commentText, formattingOptions) {
 	// The comment's parsed content and layout details.
-	const formattingContext = getJSDocFormattingContext(sourceCode, comment);
-	// The prose lines, rewrapped without changing existing line breaks.
-	const prose = formatUnwrappedProse(formattingContext.proseLines, false);
+	const formattingContext = getJSDocFormattingContext(commentText, formattingOptions);
+	// The prose lines, refilled before tags are appended.
+	const prose = formatUnwrappedProse(formattingContext.proseLines, false, formattingContext.indent);
 
 	// The tag lines, without spacing or grouping normalisation.
 	const tags = formatTags(
@@ -641,20 +661,34 @@ export function formatJSDocBlockStructure(sourceCode, comment) {
 	return renderJSDocComment(formattingContext, outputLines);
 }
 
+/**
+ * Return whether a JSDoc comment contains a @param, @throws, or @returns tag.
+ *
+ * @param  {string}  commentText
+ *     The JSDoc comment text.
+ *
+ * @returns  {boolean}
+ *     Whether one of those tags is present.
+ */
+export function hasTargetJSDocTag(commentText) {
+	return getJSDocContent(commentText).some(isTargetTag);
+}
+
 /**
  * Format JSDoc tag spacing, order, and grouping.
  *
- * @param  {object}  sourceCode
- *     The Oxlint source code object.
- * @param  {object}  comment
- *     The JSDoc comment token.
+ * @param  {string}  commentText
+ *     The JSDoc comment text.
+ * @param  {object}  formattingOptions
+ *     The indentation (`indent`) and newline style (`newline`) of the source
+ *     around the comment.
  *
  * @returns  {string}
  *     The formatted comment text.
  */
-export function formatJSDocTagFormatting(sourceCode, comment) {
+export function formatJSDocTagFormatting(commentText, formattingOptions) {
 	// The comment's parsed content and layout details.
-	const formattingContext = getJSDocFormattingContext(sourceCode, comment);
+	const formattingContext = getJSDocFormattingContext(commentText, formattingOptions);
 	// The prose, rewrapped to the comment's available width.
 	const prose = formatProse(formattingContext.proseLines, formattingContext.width, false);
 
@@ -677,19 +711,20 @@ export function formatJSDocTagFormatting(sourceCode, comment) {
 /**
  * Format JSDoc sentence capitalisation and punctuation.
  *
- * @param  {object}  sourceCode
- *     The Oxlint source code object.
- * @param  {object}  comment
- *     The JSDoc comment token.
+ * @param  {string}  commentText
+ *     The JSDoc comment text.
+ * @param  {object}  formattingOptions
+ *     The indentation (`indent`) and newline style (`newline`) of the source
+ *     around the comment.
  *
  * @returns  {string}
  *     The formatted comment text.
  */
-export function formatJSDocPunctuation(sourceCode, comment) {
+export function formatJSDocPunctuation(commentText, formattingOptions) {
 	// The comment's parsed content and layout details.
-	const formattingContext = getJSDocFormattingContext(sourceCode, comment);
+	const formattingContext = getJSDocFormattingContext(commentText, formattingOptions);
 	// The prose, capitalised and punctuated as sentences.
-	const prose = formatUnwrappedProse(formattingContext.proseLines, true);
+	const prose = formatUnwrappedProse(formattingContext.proseLines, true, formattingContext.indent);
 
 	// The tag lines, with descriptions punctuated as sentences.
 	const tags = formatTags(
@@ -710,17 +745,18 @@ export function formatJSDocPunctuation(sourceCode, comment) {
 /**
  * Format JSDoc prose and tags to the configured line width.
  *
- * @param  {object}  sourceCode
- *     The Oxlint source code object.
- * @param  {object}  comment
- *     The JSDoc comment token.
+ * @param  {string}  commentText
+ *     The JSDoc comment text.
+ * @param  {object}  formattingOptions
+ *     The indentation (`indent`) and newline style (`newline`) of the source
+ *     around the comment.
  *
  * @returns  {string}
  *     The formatted comment text.
  */
-export function formatJSDocWrapping(sourceCode, comment) {
+export function formatJSDocWrapping(commentText, formattingOptions) {
 	// The comment's parsed content and layout details.
-	const formattingContext = getJSDocFormattingContext(sourceCode, comment);
+	const formattingContext = getJSDocFormattingContext(commentText, formattingOptions);
 	// The prose, rewrapped to the comment's available width.
 	const prose = formatProse(formattingContext.proseLines, formattingContext.width, false);
 
@@ -739,18 +775,3 @@ export function formatJSDocWrapping(sourceCode, comment) {
 
 	return renderJSDocComment(formattingContext, outputLines);
 }
-
-/**
- * Return whether a JSDoc comment contains a target tag.
- *
- * @param  {object}  sourceCode
- *     The Oxlint source code object.
- * @param  {object}  comment
- *     The comment token.
- *
- * @returns  {boolean}
- *     Whether a Phase 1 tag is present.
- */
-export function hasTargetJSDocTag(sourceCode, comment) {
-	return getJSDocContent(getCommentText(sourceCode, comment)).some(isTargetTag);
-}

package/comments/utils/source.js

@@ -156,6 +156,21 @@ export function getLineIndent(sourceCode, offset) {
 	return /^\s*$/.test(prefix) ? prefix : null;
 }
 
+/**
+ * Return the number of columns a source string occupies on screen, so comment
+ * lines are measured and wrapped against the 80-column limit under tab
+ * indentation. A tab counts as four columns, the width this package assumes.
+ *
+ * @param  {string}  sourceText
+ *     The source string to measure, such as a line or its indentation.
+ *
+ * @returns  {number}
+ *     The source string's width in display columns.
+ */
+export function getDisplayWidth(sourceText) {
+	return sourceText.replaceAll("\t", "    ").length;
+}
+
 /**
  * Return the source items immediately around a comment.
  *
@@ -300,7 +315,6 @@ export function hasImmediateLineComment(sourceCode, node) {
 
 	// Checks the comments immediately around the node.
 	const { next, previous } = getCommentNeighbours(sourceCode, comment);
-
 	// Confirms there is no blank line before the node.
 	const gap = sourceCode.text.slice(comment.range[1], node.range[0]);
 
@@ -334,7 +348,6 @@ export function hasImmediateBlockComment(sourceCode, node) {
 
 	// Checks the comments immediately around the node.
 	const { next, previous } = getCommentNeighbours(sourceCode, comment);
-
 	// Confirms there is no blank line before the node.
 	const gap = sourceCode.text.slice(comment.range[1], node.range[0]);
 

package/comments/utils/wrap.js

@@ -1,3 +1,5 @@
+import { getDisplayWidth } from "./source.js";
+
 /**
  * Wrap words to a maximum line width.
  *
@@ -23,6 +25,7 @@ export function wrapWords(text, width) {
 			for (let index = 0; index < word.length; index += width) {
 				lines.push(word.slice(index, index + width));
 			}
+
 			continue;
 		}
 
@@ -32,6 +35,7 @@ export function wrapWords(text, width) {
 			currentLine += ` ${word}`;
 		} else {
 			lines.push(currentLine);
+
 			currentLine = word;
 		}
 	}
@@ -43,6 +47,123 @@ export function wrapWords(text, width) {
 	return lines;
 }
 
+/**
+ * Refill comment lines when the next line starts early enough to fit.
+ *
+ * @param  {object[]}  lines
+ *     The comment lines, each with a display prefix and undecorated text.
+ * @param  {number}  maximumLineLength
+ *     The maximum display width for a complete comment line.
+ *
+ * @returns  {object[]}
+ *     The refilled comment lines.
+ */
+export function refillCommentLines(lines, maximumLineLength) {
+	// The lines copied so refilling does not change the caller's values.
+	const result = lines.map(({ prefix, text }) => ({ prefix, text: text.trimEnd() }));
+
+	for (let index = 0; index < result.length - 1; index += 1) {
+		// The current line being considered for refilling.
+		const currentLine = result[index];
+
+		while (index < result.length - 1) {
+			// The following line being considered for refilling.
+			const nextLine = result[index + 1];
+
+			if (!canRefillLine(currentLine.text) || !canProvideWords(nextLine.text)) {
+				break;
+			}
+
+			// The words still waiting on the following line.
+			const nextWords = nextLine.text.split(/\s+/).filter(Boolean);
+
+			// Whether the following line was removed after giving up all its
+			// words.
+			let removedNextLine = false;
+
+			while (nextWords.length > 0) {
+				// The first word that could move onto the current line.
+				const nextWord = nextWords[0];
+				// The candidate line after moving the next word.
+				const candidate = `${currentLine.prefix}${currentLine.text} ${nextWord}`;
+
+				if (getDisplayWidth(candidate) > maximumLineLength) {
+					break;
+				}
+
+				currentLine.text = `${currentLine.text} ${nextWord}`;
+
+				nextWords.shift();
+
+				nextLine.text = nextWords.join(" ");
+
+				if (nextLine.text === "") {
+					result.splice(index + 1, 1);
+
+					removedNextLine = true;
+
+					break;
+				}
+
+				if (!canRefillLine(currentLine.text)) {
+					break;
+				}
+			}
+
+			if (!removedNextLine) {
+				break;
+			}
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Return whether a line may receive words from the next line.
+ *
+ * @param  {string}  text
+ *     The undecorated comment text.
+ *
+ * @returns  {boolean}
+ *     Whether the line can be refilled.
+ */
+function canRefillLine(text) {
+	// The line's text without its surrounding whitespace.
+	const trimmedText = text.trim();
+
+	return trimmedText !== "" && !/[.!?]$/.test(trimmedText) && !isListItem(trimmedText);
+}
+
+/**
+ * Return whether a line may provide words to the line above it.
+ *
+ * @param  {string}  text
+ *     The undecorated comment text.
+ *
+ * @returns  {boolean}
+ *     Whether the line can provide its first word.
+ */
+function canProvideWords(text) {
+	// The line's text without its surrounding whitespace.
+	const trimmedText = text.trim();
+
+	return trimmedText !== "" && !isListItem(trimmedText);
+}
+
+/**
+ * Return whether text starts with a list-item marker.
+ *
+ * @param  {string}  text
+ *     The undecorated comment text.
+ *
+ * @returns  {boolean}
+ *     Whether the text is a list item.
+ */
+function isListItem(text) {
+	return /^(?:[-*]\s+|\d+\.\s+)/.test(text.trim());
+}
+
 /**
  * Capitalise a sentence and ensure it has terminal punctuation.
  *
@@ -83,8 +204,8 @@ export function capitaliseSentence(text) {
 	// The leading word, starting from the first letter character.
 	const leadingWord = trimmedText.slice(firstLetter).match(/^\p{L}[\p{L}\p{N}]*/u)?.[0] ?? "";
 
-	// A camelCase word (lowercase start, later uppercase) is a code
-	// identifier and must keep its own casing rather than sentence casing.
+	// A camelCase word (lowercase start, later uppercase) is a code identifier
+	// and must keep its own casing rather than sentence casing.
 	if (/^\p{Ll}[\p{Ll}\p{N}]*\p{Lu}/u.test(leadingWord)) {
 		return text;
 	}

package/comments.json

@@ -6,18 +6,21 @@
 		}
 	],
 	"rules": {
-		"comments/block-comments": "error",
 		"comments/class-documentation": "error",
 		"comments/configured-api-calls": "error",
+		"comments/formatting": "error",
 		"comments/function-documentation": "error",
-		"comments/jsdoc-tag-formatting": "error",
-		"comments/line-comments": "error",
-		"comments/max-line-length": "error",
-		"comments/placement": "error",
-		"comments/sentence-punctuation": "error",
 		"comments/variable-declarations": "error",
 		"comments/vue-component-documentation": "error",
 		"comments/vue-emit-documentation": "error",
 		"comments/vue-prop-documentation": "error"
-	}
+	},
+	"overrides": [
+		{
+			"files": ["**/*.test.*", "**/*.spec.*", "**/test/**"],
+			"rules": {
+				"comments/variable-declarations": ["error", { "rootOnly": true }]
+			}
+		}
+	]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lewishowles/lint-config",
-	"version": "0.4.0",
+	"version": "0.6.0",
 	"description": "Shared oxlint configuration for Lewis Howles projects",
 	"keywords": [
 		"config",
@@ -40,7 +40,8 @@
 		"lint": "vp check",
 		"lint:fix": "vp check --fix",
 		"prepare": "vp config --no-agent",
-		"publint": "publint"
+		"publint": "publint",
+		"test:unit": "node --test test/comments/*.test.js"
 	},
 	"devDependencies": {
 		"publint": "^0.3.22",