@lewishowles/lint-config 0.5.0 → 0.6.1

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.
@@ -79,21 +79,31 @@ export default {
 					return;
 				}
 
+				// 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);
 
-				// With rootOnly, only declarations directly under the
-				// Program need a comment, so a nested variable inside
-				// a function is left alone.
+				// 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)
 				) {

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(
@@ -153,8 +153,7 @@ export default {
 				// 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.
+				// each call rather than tracked with shared state.
 				const scriptBlock = findScriptBlock(context);
 
 				if (hasComponentDocumentation(context, scriptBlock)) {

package/comments/utils/documentation.js

@@ -157,11 +157,14 @@ function getObjectPatternPaths(sourceCode, node, parentPath) {
  *     The Oxlint source code object.
  * @param  {object}  node
  *     The parameter node.
+ * @param  {string}  [rootPath]
+ *     The documented name that starts each path for a destructured object
+ *     parameter. Defaults to options.
  *
  * @returns  {string[]}
  *     The required JSDoc parameter paths.
  */
-function getParameterPaths(sourceCode, node) {
+function getParameterPaths(sourceCode, node, rootPath = "options") {
 	if (node.type === "Identifier") {
 		return [node.name];
 	}
@@ -171,11 +174,11 @@ function getParameterPaths(sourceCode, node) {
 	}
 
 	if (node.type === "ObjectPattern") {
-		return getObjectPatternPaths(sourceCode, node, "options");
+		return getObjectPatternPaths(sourceCode, node, rootPath);
 	}
 
 	if (node.type === "AssignmentPattern") {
-		return getParameterPaths(sourceCode, node.left);
+		return getParameterPaths(sourceCode, node.left, rootPath);
 	}
 
 	return [];
@@ -189,25 +192,40 @@ function getParameterPaths(sourceCode, node) {
  * @param  {object}  comment
  *     The JSDoc comment token.
  *
- * @returns  {Set<string>}
- *     The documented parameter names.
+ * @returns  {object}
+ *     An object with names, the set of every documented parameter path, and
+ *     topLevelNames, the top-level names in the order they are documented.
  */
 function getDocumentedParameters(sourceCode, comment) {
 	// Splits the JSDoc block into its individual lines.
 	const content = getJSDocContent(getCommentText(sourceCode, comment));
 	// Collects the parameter paths documented by @param tags.
 	const names = new Set();
+	// Collects top-level parameter names in their documented order.
+	const topLevelNames = [];
 
 	for (const line of content) {
 		// Matches an @param tag and captures its documented path.
 		const match = line.trim().match(/^@param(?:\s+\{[^}]+\})?\s+(\[[^\]]+\]|\S+)/);
 
 		if (match) {
-			names.add(match[1]);
+			// The documented name as written, including optional brackets and
+			// any default value.
+			const name = match[1];
+
+			names.add(name);
+
+			// Removes optional and default-value syntax before checking for a
+			// nested path.
+			const topLevelName = name.replace(/^\[|\]$/g, "").split("=")[0];
+
+			if (!topLevelName.includes(".")) {
+				topLevelNames.push(topLevelName);
+			}
 		}
 	}
 
-	return names;
+	return { names, topLevelNames };
 }
 
 /**
@@ -293,7 +311,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);
 
@@ -307,11 +324,14 @@ export function reportFunctionDocumentation(context, node, functionNode, options
 	}
 
 	// Reads the parameter paths already documented by @param tags.
-	const documentedParameters = getDocumentedParameters(context.sourceCode, comment);
+	const { names: documentedParameters, topLevelNames } = getDocumentedParameters(
+		context.sourceCode,
+		comment,
+	);
 
 	// Derives the parameter paths the function actually requires.
-	const parameterPaths = functionNode.params.flatMap((parameter) =>
-		getParameterPaths(context.sourceCode, parameter),
+	const parameterPaths = functionNode.params.flatMap((parameter, index) =>
+		getParameterPaths(context.sourceCode, parameter, topLevelNames[index]),
 	);
 
 	for (const path of parameterPaths) {

package/comments/utils/jsdoc.js

@@ -1,5 +1,11 @@
-import { getCommentText, getDisplayWidth, 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,19 +210,24 @@ 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());
+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.
@@ -282,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("");
 			}
@@ -408,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("");
 			}
@@ -477,6 +494,7 @@ function formatTagDescriptions(lines, width, addPunctuation) {
 		}
 
 		result.push(...wrapWords(text, width).map((line) => `    ${line}`));
+
 		description = [];
 	}
 
@@ -487,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("");
 			}
@@ -512,21 +532,18 @@ 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 - getDisplayWidth(indent) - 3);
 	// The undecorated comment content lines.
@@ -613,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(
@@ -643,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);
 
@@ -679,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(
@@ -712,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);
 
@@ -741,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

@@ -315,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]);
 
@@ -349,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,15 +6,10 @@
 		}
 	],
 	"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",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lewishowles/lint-config",
-	"version": "0.5.0",
+	"version": "0.6.1",
 	"description": "Shared oxlint configuration for Lewis Howles projects",
 	"keywords": [
 		"config",