@lewishowles/lint-config 0.2.0 → 0.4.0

package/comments/utils/source.js

@@ -0,0 +1,346 @@
+// The token types treated as comments.
+const commentTypes = new Set(["Block", "Line", "Shebang"]);
+
+/**
+ * Return whether a source item is a comment token.
+ *
+ * @param  {object}  item
+ *     The source item to inspect.
+ *
+ * @returns  {boolean}
+ *     Whether the item is a comment token.
+ */
+export function isComment(item) {
+	return commentTypes.has(item.type);
+}
+
+/**
+ * Return the source text for a comment token.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object}  comment
+ *     The comment token.
+ *
+ * @returns  {string}
+ *     The comment's source text.
+ */
+export function getCommentText(sourceCode, comment) {
+	return sourceCode.text.slice(comment.range[0], comment.range[1]);
+}
+
+/**
+ * Return the smallest replacement that changes one comment to formatted text.
+ *
+ * @param  {object}  comment
+ *     The comment token.
+ * @param  {string}  commentText
+ *     The comment's source text.
+ * @param  {string}  formattedComment
+ *     The formatted replacement text.
+ *
+ * @returns  {object}
+ *     The source range and replacement text.
+ */
+export function getMinimalCommentReplacement(comment, commentText, formattedComment) {
+	// The count of unchanged characters shared at the start of both texts.
+	let start = 0;
+
+	while (
+		start < commentText.length &&
+		start < formattedComment.length &&
+		commentText[start] === formattedComment[start]
+	) {
+		start += 1;
+	}
+
+	// The count of unchanged characters shared at the end of both texts.
+	let end = 0;
+
+	while (
+		end < commentText.length - start &&
+		end < formattedComment.length - start &&
+		commentText.at(-end - 1) === formattedComment.at(-end - 1)
+	) {
+		end += 1;
+	}
+
+	return {
+		range: [comment.range[0] + start, comment.range[1] - end],
+		text: formattedComment.slice(start, formattedComment.length - end),
+	};
+}
+
+/**
+ * Replace a comment using the smallest changed source range.
+ *
+ * @param  {object}  fixer
+ *     The Oxlint fixer.
+ * @param  {object}  comment
+ *     The comment token.
+ * @param  {string}  sourceText
+ *     The comment's source text.
+ * @param  {string}  formattedText
+ *     The formatted replacement text.
+ *
+ * @returns  {object}
+ *     The fixer replacement.
+ */
+export function replaceMinimalComment(fixer, comment, sourceText, formattedText) {
+	// The smallest source range and text that changes the comment.
+	const replacement = getMinimalCommentReplacement(comment, sourceText, formattedText);
+
+	return fixer.replaceTextRange(replacement.range, replacement.text);
+}
+
+/**
+ * Return whether a comment is an inline tool directive.
+ *
+ * @param  {object}  comment
+ *     The comment token.
+ *
+ * @returns  {boolean}
+ *     Whether the comment starts with a recognised directive prefix.
+ */
+export function isDirectiveComment(comment) {
+	return /^(?:eslint|oxlint|istanbul|c8)-/.test(comment.value.trim());
+}
+
+/**
+ * Return the source line containing an offset.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {number}  offset
+ *     The source offset.
+ *
+ * @returns  {number}
+ *     The one-based source line.
+ */
+export function getLineNumber(sourceCode, offset) {
+	return sourceCode.getLocFromIndex(offset).line;
+}
+
+/**
+ * Return the offset at which an offset's source line starts.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {number}  offset
+ *     The source offset.
+ *
+ * @returns  {number}
+ *     The line-start offset.
+ */
+export function getLineStart(sourceCode, offset) {
+	return sourceCode.lineStartIndices[getLineNumber(sourceCode, offset) - 1];
+}
+
+/**
+ * Return the whitespace before a source offset on its line.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {number}  offset
+ *     The source offset.
+ *
+ * @returns  {string|null}
+ *     The line indentation, or null when code precedes the offset.
+ */
+export function getLineIndent(sourceCode, offset) {
+	// The offset at which the offset's line begins.
+	const lineStart = getLineStart(sourceCode, offset);
+	// The source text between the line start and the offset.
+	const prefix = sourceCode.text.slice(lineStart, offset);
+
+	return /^\s*$/.test(prefix) ? prefix : null;
+}
+
+/**
+ * Return the source items immediately around a comment.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object}  comment
+ *     The comment token.
+ *
+ * @returns  {object}
+ *     The previous and next non-comment source items.
+ */
+export function getCommentNeighbours(sourceCode, comment) {
+	// Every token and comment in the file, in source order.
+	const sourceItems = sourceCode.tokensAndComments;
+
+	// The comment's position within sourceItems.
+	const commentIndex = sourceItems.findIndex(
+		(item) => item.range[0] === comment.range[0] && item.range[1] === comment.range[1],
+	);
+
+	// The preceding non-comment source item, once found.
+	let previous = null;
+	// The following non-comment source item, once found.
+	let next = null;
+
+	for (let index = commentIndex - 1; index >= 0; index -= 1) {
+		if (!isComment(sourceItems[index])) {
+			previous = sourceItems[index];
+
+			break;
+		}
+	}
+
+	for (let index = commentIndex + 1; index < sourceItems.length; index += 1) {
+		if (!isComment(sourceItems[index])) {
+			next = sourceItems[index];
+
+			break;
+		}
+	}
+
+	return { next, previous };
+}
+
+/**
+ * Return the comments that form one adjacent line-comment group.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ *
+ * @returns  {object[][]}
+ *     Adjacent line-comment groups.
+ */
+export function getLineCommentGroups(sourceCode) {
+	// Every line comment in the file, in source order.
+	const comments = sourceCode.getAllComments().filter((comment) => comment.type === "Line");
+	// The adjacent comment groups, built up in place.
+	const groups = [];
+
+	for (const comment of comments) {
+		if (isDirectiveComment(comment)) {
+			continue;
+		}
+
+		// The group currently being built, when there is one.
+		const group = groups.at(-1);
+		// The current group's last comment, when there is one.
+		const previousComment = group?.at(-1);
+
+		// The source text between the previous comment and this one.
+		const gap = previousComment
+			? sourceCode.text.slice(previousComment.range[1], comment.range[0])
+			: "";
+
+		// How many newlines separate this comment from the previous one.
+		const newlineCount = gap.match(/\r\n|\n|\r/g)?.length ?? 0;
+
+		if (group && newlineCount === 1 && /^[ \t]*\r?\n[ \t]*$/.test(gap)) {
+			group.push(comment);
+		} else {
+			groups.push([comment]);
+		}
+	}
+
+	return groups;
+}
+
+/**
+ * Return the newline sequence used by a source file.
+ *
+ * @param  {string}  source
+ *     The source text.
+ *
+ * @returns  {string}
+ *     The source newline sequence.
+ */
+export function getNewline(source) {
+	return source.includes("\r\n") ? "\r\n" : "\n";
+}
+
+/**
+ * Return whether a comment is a leading comment for the next source token.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object}  comment
+ *     The comment token.
+ * @param  {object|null}  previous
+ *     The preceding non-comment source item.
+ *
+ * @returns  {boolean}
+ *     Whether the comment is on a line of its own before code.
+ */
+export function isLeadingComment(sourceCode, comment, previous) {
+	if (getLineIndent(sourceCode, comment.range[0]) === null) {
+		return false;
+	}
+
+	return previous === null || comment.loc.start.line > previous.loc.end.line;
+}
+
+/**
+ * Return whether a line comment immediately documents a source node.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object}  node
+ *     The source node.
+ *
+ * @returns  {boolean}
+ *     Whether an ordinary line comment immediately precedes the node.
+ */
+export function hasImmediateLineComment(sourceCode, node) {
+	// Finds the closest preceding comment.
+	const comment = sourceCode
+		.getAllComments()
+		.findLast((candidate) => candidate.range[1] <= node.range[0]);
+
+	if (comment?.type !== "Line" || isDirectiveComment(comment)) {
+		return false;
+	}
+
+	// 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]);
+
+	return (
+		next?.range[0] === node.range[0] &&
+		isLeadingComment(sourceCode, comment, previous) &&
+		/^\r?\n[ \t]*$/.test(gap)
+	);
+}
+
+/**
+ * Return whether a block comment immediately documents a source node.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object}  node
+ *     The source node.
+ *
+ * @returns  {boolean}
+ *     Whether an ordinary block comment immediately precedes the node.
+ */
+export function hasImmediateBlockComment(sourceCode, node) {
+	// Finds the closest preceding comment.
+	const comment = sourceCode
+		.getAllComments()
+		.findLast((candidate) => candidate.range[1] <= node.range[0]);
+
+	if (comment?.type !== "Block" || isDirectiveComment(comment)) {
+		return false;
+	}
+
+	// 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]);
+
+	return (
+		next?.range[0] === node.range[0] &&
+		isLeadingComment(sourceCode, comment, previous) &&
+		/^\r?\n[ \t]*$/.test(gap)
+	);
+}

package/comments/utils/vue-macro.js

@@ -0,0 +1,70 @@
+/**
+ * Return whether a node is a call expression invoking the given function name.
+ *
+ * @param  {object}  node
+ *     The node to inspect.
+ * @param  {string}  name
+ *     The function name to match.
+ *
+ * @returns  {boolean}
+ *     Whether the node matches.
+ */
+export function isNamedCall(node, name) {
+	return (
+		node?.type === "CallExpression" &&
+		node.callee?.type === "Identifier" &&
+		node.callee.name === name
+	);
+}
+
+/**
+ * Return an object argument from a call, when one is present.
+ *
+ * @param  {object}  callNode
+ *     The call whose argument should be inspected.
+ * @param  {number}  argumentIndex
+ *     The argument position to inspect.
+ *
+ * @returns  {object|null}
+ *     The object argument, or null when it is missing or not an object.
+ */
+export function getObjectArgument(callNode, argumentIndex) {
+	// The candidate object argument for runtime declarations.
+	const argument = callNode.arguments[argumentIndex];
+
+	return argument?.type === "ObjectExpression" ? argument : null;
+}
+
+/**
+ * Return the object properties that represent runtime declarations.
+ *
+ * @param  {object}  objectExpression
+ *     The object expression to inspect.
+ *
+ * @returns  {object[]}
+ *     Its ordinary properties, excluding spread elements.
+ */
+export function getObjectProperties(objectExpression) {
+	return objectExpression.properties.filter((property) => property.type === "Property");
+}
+
+/**
+ * Return the name of an object property.
+ *
+ * @param  {object}  property
+ *     The property to inspect.
+ *
+ * @returns  {string|null}
+ *     The property name, when it is a string or number.
+ */
+export function getPropertyName(property) {
+	if (property.key.type === "Identifier") {
+		return property.key.name;
+	}
+
+	if (typeof property.key.value === "string" || typeof property.key.value === "number") {
+		return String(property.key.value);
+	}
+
+	return null;
+}

package/comments/utils/wrap.js

@@ -0,0 +1,118 @@
+/**
+ * Wrap words to a maximum line width.
+ *
+ * @param  {string}  text
+ *     The text to wrap.
+ * @param  {number}  width
+ *     The maximum output width.
+ *
+ * @returns  {string[]}
+ *     Wrapped lines.
+ */
+export function wrapWords(text, width) {
+	// The text's individual words.
+	const words = text.trim().split(/\s+/).filter(Boolean);
+	// The wrapped lines, built up in place.
+	const lines = [];
+
+	// The line currently being filled.
+	let currentLine = "";
+
+	for (const word of words) {
+		if (word.length > width && currentLine === "") {
+			for (let index = 0; index < word.length; index += width) {
+				lines.push(word.slice(index, index + width));
+			}
+			continue;
+		}
+
+		if (currentLine === "") {
+			currentLine = word;
+		} else if (currentLine.length + word.length + 1 <= width) {
+			currentLine += ` ${word}`;
+		} else {
+			lines.push(currentLine);
+			currentLine = word;
+		}
+	}
+
+	if (currentLine !== "") {
+		lines.push(currentLine);
+	}
+
+	return lines;
+}
+
+/**
+ * Capitalise a sentence and ensure it has terminal punctuation.
+ *
+ * @param  {string}  text
+ *     The sentence text.
+ *
+ * @returns  {string}
+ *     The corrected sentence text.
+ */
+export function formatSentence(text) {
+	return addTerminalPunctuation(capitaliseSentence(text));
+}
+
+/**
+ * Capitalise the first letter of sentence text.
+ *
+ * @param  {string}  text
+ *     The sentence text.
+ *
+ * @returns  {string}
+ *     The capitalised sentence text.
+ */
+export function capitaliseSentence(text) {
+	// The sentence text, without leading or trailing whitespace.
+	const trimmedText = text.trim();
+
+	if (trimmedText === "" || trimmedText.startsWith("@")) {
+		return text;
+	}
+
+	// The index of the first letter character, ignoring leading punctuation.
+	const firstLetter = trimmedText.search(/\p{L}/u);
+
+	if (firstLetter < 0) {
+		return 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.
+	if (/^\p{Ll}[\p{Ll}\p{N}]*\p{Lu}/u.test(leadingWord)) {
+		return text;
+	}
+
+	// The first letter character.
+	const letter = trimmedText[firstLetter];
+	// The text with its first letter capitalised.
+	const formattedText = `${trimmedText.slice(0, firstLetter)}${letter.toLocaleUpperCase()}${trimmedText.slice(firstLetter + 1)}`;
+
+	return text.replace(trimmedText, formattedText);
+}
+
+/**
+ * Add terminal punctuation to sentence text.
+ *
+ * @param  {string}  text
+ *     The sentence text.
+ *
+ * @returns  {string}
+ *     The punctuated sentence text.
+ */
+export function addTerminalPunctuation(text) {
+	// The sentence text, without leading or trailing whitespace.
+	const trimmedText = text.trim();
+
+	if (trimmedText === "" || trimmedText.startsWith("@") || /[.!?]$/.test(trimmedText)) {
+		return text;
+	}
+
+	return text.replace(trimmedText, `${trimmedText}.`);
+}

package/comments.json

@@ -0,0 +1,23 @@
+{
+	"jsPlugins": [
+		{
+			"name": "comments",
+			"specifier": "@lewishowles/lint-config/comments/plugin"
+		}
+	],
+	"rules": {
+		"comments/block-comments": "error",
+		"comments/class-documentation": "error",
+		"comments/configured-api-calls": "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"
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lewishowles/lint-config",
-	"version": "0.2.0",
+	"version": "0.4.0",
 	"description": "Shared oxlint configuration for Lewis Howles projects",
 	"keywords": [
 		"config",
@@ -19,27 +19,36 @@
 		"url": "git+https://github.com/lewishowles/lint-config.git"
 	},
 	"files": [
+		"CHANGELOG.md",
 		"base.json",
+		"comments",
+		"comments.json",
 		"vue.json",
 		"README.md"
 	],
 	"type": "module",
 	"exports": {
 		"./base.json": "./base.json",
+		"./comments.json": "./comments.json",
+		"./comments/plugin": "./comments/plugin.js",
 		"./vue.json": "./vue.json"
 	},
 	"publishConfig": {
 		"access": "public"
 	},
 	"scripts": {
+		"lint": "vp check",
+		"lint:fix": "vp check --fix",
+		"prepare": "vp config --no-agent",
 		"publint": "publint"
 	},
 	"devDependencies": {
-		"publint": "^0.3.21"
+		"publint": "^0.3.22",
+		"vite-plus": "0.2.8"
 	},
 	"peerDependencies": {
 		"@stylistic/eslint-plugin": "*",
-		"vite-plus": "*"
+		"vite-plus": "0.2.8"
 	},
 	"engines": {
 		"node": ">=20"