@lewishowles/lint-config 0.1.3 → 0.3.0

package/comments/utils/jsdoc.js

@@ -0,0 +1,756 @@
+import { getCommentText, getLineIndent, getNewline } from "./source.js";
+import { addTerminalPunctuation, capitaliseSentence, formatSentence, wrapWords } from "./wrap.js";
+
+// The JSDoc tags this package formats, in their required output order.
+const tagOrder = ["param", "throws", "returns"];
+// Tags whose section content is kept verbatim rather than reflowed.
+const preservedSectionTags = new Set(["example"]);
+// Fast lookup set built from tagOrder.
+const targetTags = new Set(tagOrder);
+
+/**
+ * Return whether source text is a JSDoc-style block comment.
+ *
+ * @param  {string}  commentText
+ *     The comment source text.
+ *
+ * @returns  {boolean}
+ *     Whether the comment starts with JSDoc syntax.
+ */
+export function isJSDoc(commentText) {
+	return commentText.startsWith("/**");
+}
+
+/**
+ * Read the undecorated content lines of a JSDoc comment.
+ *
+ * @param  {string}  commentText
+ *     The comment source text.
+ *
+ * @returns  {string[]}
+ *     The comment content lines.
+ */
+export function getJSDocContent(commentText) {
+	// Strips the /** and */ delimiters, leaving the raw comment body.
+	const body = commentText.slice(3, -2);
+
+	// Removes each line's leading indentation and star decoration.
+	const lines = body.split(/\r\n|\n|\r/).map((line) => {
+		if (/^\s*\*/.test(line)) {
+			return line.replace(/^\s*\* ?/, "");
+		}
+
+		return line.trim();
+	});
+
+	while (lines[0] === "") {
+		lines.shift();
+	}
+
+	while (lines.at(-1) === "") {
+		lines.pop();
+	}
+
+	return lines;
+}
+
+/**
+ * Split JSDoc content into prose and tag lines.
+ *
+ * @param  {string[]}  contentLines
+ *     The undecorated comment content.
+ *
+ * @returns  {object}
+ *     Prose and tag content.
+ */
+function splitJSDocContent(contentLines) {
+	// Finds where the tag section begins, if there is one.
+	const firstTagIndex = contentLines.findIndex((line) => /^@\w+\b/.test(line.trim()));
+
+	if (firstTagIndex < 0) {
+		return { proseLines: contentLines, tagLines: [] };
+	}
+
+	return {
+		proseLines: contentLines.slice(0, firstTagIndex),
+		tagLines: contentLines.slice(firstTagIndex),
+	};
+}
+
+/**
+ * Return the tag name at the beginning of a JSDoc line.
+ *
+ * @param  {string}  line
+ *     The undecorated JSDoc line.
+ *
+ * @returns  {string|null}
+ *     The tag name, or null when the line is not a tag.
+ */
+function getJSDocTagName(line) {
+	// Matches the leading @tagName, ignoring any indentation.
+	const match = line.trim().match(/^@([a-zA-Z][\w-]*)\b/);
+
+	return match?.[1] ?? null;
+}
+
+/**
+ * Return whether a line is a target JSDoc tag.
+ *
+ * @param  {string}  line
+ *     The undecorated JSDoc line.
+ *
+ * @returns  {boolean}
+ *     Whether the line is one of the Phase 1 tags.
+ */
+function isTargetTag(line) {
+	// The tag name, or null when the line isn't a tag at all.
+	const tagName = getJSDocTagName(line);
+
+	return tagName !== null && targetTags.has(tagName);
+}
+
+/**
+ * Return whether a JSDoc tag starts a section whose content stays verbatim.
+ *
+ * @param  {string}  line
+ *     The undecorated JSDoc line.
+ *
+ * @returns  {boolean}
+ *     Whether the line starts a preserved section.
+ */
+function isPreservedSectionTag(line) {
+	return preservedSectionTags.has(getJSDocTagName(line));
+}
+
+/**
+ * Parse target JSDoc tag entries.
+ *
+ * @param  {string[]}  tagLines
+ *     The undecorated tag content.
+ *
+ * @returns  {object[]}
+ *     Parsed target tag entries.
+ */
+function parseTargetTags(tagLines) {
+	// The parsed tag entries, in source order.
+	const entries = [];
+
+	// The tag entry currently collecting description lines.
+	let currentEntry = null;
+
+	for (const line of tagLines) {
+		// Matches a new @param/@throws/@returns tag line.
+		const match = line.trim().match(/^@(param|throws|returns)\b(.*)$/);
+
+		if (match) {
+			currentEntry = {
+				description: [],
+				rest: match[2].trim(),
+				type: match[1],
+			};
+			entries.push(currentEntry);
+		} else if (currentEntry) {
+			currentEntry.description.push(line);
+		}
+	}
+
+	return entries;
+}
+
+/**
+ * Format a target JSDoc tag header.
+ *
+ * @param  {object}  entry
+ *     The parsed tag entry.
+ *
+ * @returns  {string}
+ *     The aligned tag header.
+ */
+function formatTagHeader(entry) {
+	// Splits the tag's remainder into its type, name, and description.
+	const typeMatch = entry.rest.match(/^(\{[^}]+\})(?:\s+(\S+))?(?:\s+(.*))?$/);
+
+	if (!typeMatch) {
+		return `@${entry.type}  ${entry.rest}`.trimEnd();
+	}
+
+	// The bare {type} annotation.
+	const type = typeMatch[1];
+	// The parameter name, when the tag has one.
+	const name = typeMatch[2];
+
+	if (entry.type === "param" && name) {
+		return `@param  ${type}  ${name}`;
+	}
+
+	return `@${entry.type}  ${type}`;
+}
+
+/**
+ * Return the inline description from a target tag.
+ *
+ * @param  {object}  entry
+ *     The parsed tag entry.
+ *
+ * @returns  {string}
+ *     The inline description, when present.
+ */
+function getInlineTagDescription(entry) {
+	// Splits the tag's remainder into its type, name, and description.
+	const typeMatch = entry.rest.match(/^(\{[^}]+\})(?:\s+(\S+))?(?:\s+(.*))?$/);
+
+	return typeMatch?.[3] ?? "";
+}
+
+/**
+ * Format prose without changing its existing line wrapping.
+ *
+ * @param  {string[]}  lines
+ *     The prose content lines.
+ * @param  {boolean}  addPunctuation
+ *     Whether to format each paragraph as a sentence.
+ *
+ * @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.
+	let paragraphStart = null;
+
+	for (let index = 0; index < result.length; index += 1) {
+		if (result[index] !== "") {
+			if (paragraphStart === null) {
+				paragraphStart = index;
+			}
+
+			continue;
+		}
+
+		if (paragraphStart !== null && addPunctuation) {
+			result[paragraphStart] = capitaliseSentence(result[paragraphStart]);
+			result[index - 1] = addTerminalPunctuation(result[index - 1]);
+		}
+
+		paragraphStart = null;
+	}
+
+	if (paragraphStart !== null && addPunctuation) {
+		result[paragraphStart] = capitaliseSentence(result[paragraphStart]);
+		result[result.length - 1] = addTerminalPunctuation(result[result.length - 1]);
+	}
+
+	return result;
+}
+
+/**
+ * Format prose paragraphs to the block-comment width.
+ *
+ * @param  {string[]}  lines
+ *     The prose content lines.
+ * @param  {number}  width
+ *     The available content width.
+ * @param  {boolean}  addPunctuation
+ *     Whether to format each paragraph as a sentence.
+ *
+ * @returns  {string[]}
+ *     Formatted prose content lines.
+ */
+function formatProse(lines, width, addPunctuation) {
+	// The formatted lines, built up in place.
+	const result = [];
+
+	// The prose lines collected for the paragraph in progress.
+	let paragraph = [];
+
+	/**
+	 * Format the collected paragraph and append it to the result.
+	 */
+	function flushParagraph() {
+		if (paragraph.length === 0) {
+			return;
+		}
+
+		// The paragraph text, punctuated as a sentence when requested.
+		let text = paragraph.join(" ").trim();
+
+		if (addPunctuation) {
+			text = formatSentence(text);
+		}
+
+		result.push(...wrapWords(text, width));
+		paragraph = [];
+	}
+
+	for (const line of lines) {
+		if (line.trim() === "") {
+			flushParagraph();
+			if (result.at(-1) !== "") {
+				result.push("");
+			}
+		} else {
+			paragraph.push(line.trim());
+		}
+	}
+
+	flushParagraph();
+
+	while (result.at(-1) === "") {
+		result.pop();
+	}
+
+	return result;
+}
+
+/**
+ * Format the target JSDoc tags, including their group order.
+ *
+ * @param  {string[]}  tagLines
+ *     The undecorated tag content.
+ * @param  {number}  width
+ *     The available description width.
+ * @param  {boolean}  addPunctuation
+ *     Whether to format tag descriptions as sentences.
+ * @param  {boolean}  normaliseTags
+ *     Whether to normalise tag spacing and group order.
+ *
+ * @returns  {string[]}
+ *     Formatted tag content lines.
+ */
+function formatTags(tagLines, width, addPunctuation, normaliseTags) {
+	// The parsed @param/@throws/@returns entries.
+	const entries = parseTargetTags(tagLines);
+	// Whether the block also carries a tag this formatter doesn't normalise.
+	const hasUnknownTag = tagLines.some((line) => line.trim().startsWith("@") && !isTargetTag(line));
+
+	if (!normaliseTags || entries.length === 0) {
+		return formatTagDescriptions(tagLines, width, addPunctuation);
+	}
+
+	if (hasUnknownTag) {
+		return formatMixedTags(tagLines, width, addPunctuation);
+	}
+
+	// The formatted lines, built up in place.
+	const result = [];
+
+	// The tag type of the previously written entry, used to detect group changes.
+	let lastType = null;
+
+	// The entries regrouped into the required tag order.
+	const orderedEntries = tagOrder.flatMap((type) => entries.filter((entry) => entry.type === type));
+
+	for (const entry of orderedEntries) {
+		if (lastType !== null && lastType !== entry.type) {
+			result.push("");
+		}
+
+		result.push(formatTagHeader(entry));
+
+		// The entry's inline and multi-line description text, combined.
+		const description = [getInlineTagDescription(entry), ...entry.description]
+			.filter((line) => line.trim() !== "")
+			.map((line) => line.trim());
+
+		// The description text, punctuated as a sentence when requested.
+		let descriptionText = description.join(" ");
+
+		if (addPunctuation && descriptionText !== "") {
+			descriptionText = formatSentence(descriptionText);
+		}
+
+		if (descriptionText !== "") {
+			result.push(...wrapWords(descriptionText, width).map((line) => `    ${line}`));
+		}
+
+		lastType = entry.type;
+	}
+
+	return result;
+}
+
+/**
+ * Format target tags in place when a JSDoc block also has other tags.
+ *
+ * @param  {string[]}  lines
+ *     The undecorated tag content lines.
+ * @param  {number}  width
+ *     The available description width.
+ * @param  {boolean}  addPunctuation
+ *     Whether to format descriptions as sentences.
+ *
+ * @returns  {string[]}
+ *     Formatted mixed tag content lines.
+ */
+function formatMixedTags(lines, width, addPunctuation) {
+	// The formatted lines, built up in place.
+	const result = [];
+
+	// The tag entry currently collecting description lines.
+	let currentEntry = null;
+	// Whether the current tag's content is copied through unchanged.
+	let preserveSection = false;
+
+	for (const line of lines) {
+		// The tag name, or null when the line isn't a tag at all.
+		const tagName = getJSDocTagName(line);
+		// Matches a new @param/@throws/@returns tag line.
+		const match = line.trim().match(/^@(param|throws|returns)\b(.*)$/);
+
+		if (match) {
+			currentEntry = {
+				description: [],
+				rest: match[2].trim(),
+				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("");
+			}
+		} else {
+			// The description text, punctuated as a sentence when requested.
+			let text = line.trim();
+
+			if (addPunctuation && currentEntry) {
+				text = formatSentence(text);
+			}
+
+			result.push(...wrapWords(text, width).map((wrappedLine) => `    ${wrappedLine}`));
+		}
+	}
+
+	while (result.at(-1) === "") {
+		result.pop();
+	}
+
+	return result;
+}
+
+/**
+ * Format descriptions while retaining non-target tag lines.
+ *
+ * @param  {string[]}  lines
+ *     The undecorated tag content lines.
+ * @param  {number}  width
+ *     The available description width.
+ * @param  {boolean}  addPunctuation
+ *     Whether to format descriptions as sentences.
+ *
+ * @returns  {string[]}
+ *     Formatted tag content lines.
+ */
+function formatTagDescriptions(lines, width, addPunctuation) {
+	// The formatted lines, built up in place.
+	const result = [];
+
+	// The description lines collected for the tag in progress.
+	let description = [];
+	// Whether the current tag's content is copied through unchanged.
+	let preserveSection = false;
+
+	/**
+	 * Format the collected description and append it to the result.
+	 */
+	function flushDescription() {
+		if (description.length === 0) {
+			return;
+		}
+
+		// The description text, punctuated as a sentence when requested.
+		let text = description.join(" ").trim();
+
+		if (addPunctuation) {
+			text = formatSentence(text);
+		}
+
+		result.push(...wrapWords(text, width).map((line) => `    ${line}`));
+		description = [];
+	}
+
+	for (const line of lines) {
+		// The tag name, or null when the line isn't a tag at all.
+		const tagName = getJSDocTagName(line);
+
+		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("");
+			}
+		} else {
+			description.push(line.trim());
+		}
+	}
+
+	flushDescription();
+
+	while (result.at(-1) === "") {
+		result.pop();
+	}
+
+	return result;
+}
+
+/**
+ * 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.
+ *
+ * @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);
+	// The available content width, allowing for the indent and " * " prefix.
+	const width = Math.max(1, 80 - indent.length - 3);
+	// The undecorated comment content lines.
+	const content = getJSDocContent(commentText);
+	// The content split into its prose and tag sections.
+	const { proseLines, tagLines } = splitJSDocContent(content);
+
+	return {
+		hasTagSeparator: proseLines.at(-1)?.trim() === "",
+		indent,
+		newline,
+		proseLines,
+		tagLines,
+		width,
+	};
+}
+
+/**
+ * Append tags after a blank line when the JSDoc format requires one.
+ *
+ * @param  {string[]}  outputLines
+ *     The formatted prose lines.
+ * @param  {string[]}  tags
+ *     The formatted tag lines.
+ */
+function appendJSDocTags(outputLines, tags) {
+	if (tags.length === 0) {
+		return;
+	}
+
+	if (outputLines.length > 0 && outputLines.at(-1) !== "") {
+		outputLines.push("");
+	}
+
+	outputLines.push(...tags);
+}
+
+/**
+ * Append tags while retaining the source's existing separator state.
+ *
+ * @param  {string[]}  outputLines
+ *     The formatted prose lines.
+ * @param  {string[]}  tags
+ *     The formatted tag lines.
+ * @param  {boolean}  hasTagSeparator
+ *     Whether the source had a prose-to-tag separator.
+ */
+function appendJSDocTagsWithExistingSeparator(outputLines, tags, hasTagSeparator) {
+	if (tags.length === 0) {
+		return;
+	}
+
+	if (hasTagSeparator) {
+		appendJSDocTags(outputLines, tags);
+
+		return;
+	}
+
+	outputLines.push(...tags);
+}
+
+/**
+ * Render a JSDoc block comment from its formatted content.
+ *
+ * @param  {object}  formattingContext
+ *     The JSDoc layout details.
+ * @param  {string[]}  outputLines
+ *     The formatted prose and tag lines.
+ *
+ * @returns  {string}
+ *     The formatted comment text.
+ */
+function renderJSDocComment(formattingContext, outputLines) {
+	// The comment's indent and newline style, from the formatting context.
+	const { indent, newline } = formattingContext;
+
+	return [
+		"/**",
+		...outputLines.map((line) => (line === "" ? `${indent} *` : `${indent} * ${line}`)),
+		`${indent} */`,
+	].join(newline);
+}
+
+/**
+ * Format JSDoc block structure and delimiters.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object}  comment
+ *     The JSDoc comment token.
+ *
+ * @returns  {string}
+ *     The formatted comment text.
+ */
+export function formatJSDocBlockStructure(sourceCode, comment) {
+	// 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);
+
+	// The tag lines, without spacing or grouping normalisation.
+	const tags = formatTags(
+		formattingContext.tagLines,
+		Math.max(1, formattingContext.width - 4),
+		false,
+		false,
+	);
+
+	// The formatted comment content, before tags are appended.
+	const outputLines = [...prose];
+
+	appendJSDocTags(outputLines, tags);
+
+	return renderJSDocComment(formattingContext, outputLines);
+}
+
+/**
+ * Format JSDoc tag spacing, order, and grouping.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object}  comment
+ *     The JSDoc comment token.
+ *
+ * @returns  {string}
+ *     The formatted comment text.
+ */
+export function formatJSDocTagFormatting(sourceCode, comment) {
+	// The comment's parsed content and layout details.
+	const formattingContext = getJSDocFormattingContext(sourceCode, comment);
+	// The prose, rewrapped to the comment's available width.
+	const prose = formatProse(formattingContext.proseLines, formattingContext.width, false);
+
+	// The tag lines, with spacing and grouping normalised.
+	const tags = formatTags(
+		formattingContext.tagLines,
+		Math.max(1, formattingContext.width - 4),
+		false,
+		true,
+	);
+
+	// The formatted comment content, before tags are appended.
+	const outputLines = [...prose];
+
+	appendJSDocTagsWithExistingSeparator(outputLines, tags, formattingContext.hasTagSeparator);
+
+	return renderJSDocComment(formattingContext, outputLines);
+}
+
+/**
+ * Format JSDoc sentence capitalisation and punctuation.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object}  comment
+ *     The JSDoc comment token.
+ *
+ * @returns  {string}
+ *     The formatted comment text.
+ */
+export function formatJSDocPunctuation(sourceCode, comment) {
+	// The comment's parsed content and layout details.
+	const formattingContext = getJSDocFormattingContext(sourceCode, comment);
+	// The prose, capitalised and punctuated as sentences.
+	const prose = formatUnwrappedProse(formattingContext.proseLines, true);
+
+	// The tag lines, with descriptions punctuated as sentences.
+	const tags = formatTags(
+		formattingContext.tagLines,
+		Math.max(1, formattingContext.width - 4),
+		true,
+		false,
+	);
+
+	// The formatted comment content, before tags are appended.
+	const outputLines = [...prose];
+
+	appendJSDocTagsWithExistingSeparator(outputLines, tags, formattingContext.hasTagSeparator);
+
+	return renderJSDocComment(formattingContext, outputLines);
+}
+
+/**
+ * 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.
+ *
+ * @returns  {string}
+ *     The formatted comment text.
+ */
+export function formatJSDocWrapping(sourceCode, comment) {
+	// The comment's parsed content and layout details.
+	const formattingContext = getJSDocFormattingContext(sourceCode, comment);
+	// The prose, rewrapped to the comment's available width.
+	const prose = formatProse(formattingContext.proseLines, formattingContext.width, false);
+
+	// The tag lines, without spacing or grouping normalisation.
+	const tags = formatTags(
+		formattingContext.tagLines,
+		Math.max(1, formattingContext.width - 4),
+		false,
+		false,
+	);
+
+	// The formatted comment content, before tags are appended.
+	const outputLines = [...prose];
+
+	appendJSDocTags(outputLines, tags);
+
+	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);
+}