@lewishowles/lint-config 0.7.0 → 0.9.0

package/comments/utils/source.js

@@ -301,28 +301,68 @@ export function isLeadingComment(sourceCode, comment, previous) {
  *     The source node.
  *
  * @returns  {boolean}
- *     Whether an ordinary line comment immediately precedes the node.
+ *     Whether an ordinary line comment sits directly above the node. Tool
+ *     directive comments may sit between them.
  */
 export function hasImmediateLineComment(sourceCode, node) {
-	// Finds the closest preceding comment.
-	const comment = sourceCode
-		.getAllComments()
-		.findLast((candidate) => candidate.range[1] <= node.range[0]);
+	// The closest comment above the node, looking past tool directive comments.
+	const comment = getImmediateNonDirectiveComment(sourceCode, node);
 
-	if (comment?.type !== "Line" || isDirectiveComment(comment)) {
+	if (comment?.type !== "Line") {
 		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 next?.range[0] === node.range[0] && isLeadingComment(sourceCode, comment, previous);
+}
+
+/**
+ * Return the closest comment above a node, skipping tool directive comments
+ * such as `// eslint-disable-next-line`. The comment, each directive and the
+ * node must each start on the line after the one before, with no blank lines.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object}  node
+ *     The source node.
+ *
+ * @returns  {object|null}
+ *     The comment above the node, or null when no comment sits directly above
+ *     the node.
+ */
+export function getImmediateNonDirectiveComment(sourceCode, node) {
+	// Comments before the node, in source order.
+	const comments = sourceCode
+		.getAllComments()
+		.filter((comment) => comment.range[1] <= node.range[0]);
+
+	// The position of the closest comment that is not a tool directive.
+	const commentIndex = comments.findLastIndex((comment) => !isDirectiveComment(comment));
+
+	if (commentIndex < 0) {
+		return null;
+	}
+
+	// The comment that may document the node.
+	const comment = comments[commentIndex];
+
+	// Where the comment or directive checked last ends.
+	let previousEnd = comment.range[1];
+
+	for (const next of [...comments.slice(commentIndex + 1), node]) {
+		// The text between the previous item and this one.
+		const gap = sourceCode.text.slice(previousEnd, next.range[0]);
+
+		if (!/^\r?\n[ \t]*$/.test(gap)) {
+			return null;
+		}
+
+		previousEnd = next.range[1];
+	}
+
+	return comment;
 }
 
 /**
@@ -334,26 +374,19 @@ export function hasImmediateLineComment(sourceCode, node) {
  *     The source node.
  *
  * @returns  {boolean}
- *     Whether an ordinary block comment immediately precedes the node.
+ *     Whether an ordinary block comment sits directly above the node. Tool
+ *     directive comments may sit between them.
  */
 export function hasImmediateBlockComment(sourceCode, node) {
-	// Finds the closest preceding comment.
-	const comment = sourceCode
-		.getAllComments()
-		.findLast((candidate) => candidate.range[1] <= node.range[0]);
+	// The closest comment above the node, looking past tool directive comments.
+	const comment = getImmediateNonDirectiveComment(sourceCode, node);
 
-	if (comment?.type !== "Block" || isDirectiveComment(comment)) {
+	if (comment?.type !== "Block") {
 		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 next?.range[0] === node.range[0] && isLeadingComment(sourceCode, comment, previous);
 }

package/comments/utils/wrap.js

@@ -1,8 +1,22 @@
 import { getDisplayWidth } from "./source.js";
 
+// One word of comment text. A backtick code span counts as part of the word
+// around it, so wrapping never splits the code inside it across lines.
+const wordPattern = /(?:`[^`]*`|[^\s`]+|`)+/g;
+// Text that is only an inline code span, which reads as code, not a sentence.
+const codeSpanOnlyPattern = /^`[^`]*`$/;
+// An inline code span anywhere in the text.
+const codeSpanPattern = /`[^`]*`/;
+// Text that is only a quotation, in straight or curly quotes.
+const quoteOnlyPattern = /^(?:"[^"]*"|'[^']*'|“[^”]*”|‘[^’]*’)$/;
+
 /**
  * Wrap words to a maximum line width.
  *
+ * A code span is never split: one wider than the line goes whole on its own
+ * line. Any other word wider than the line also gets its own line, and is cut
+ * at the width only when nothing comes before it on the line.
+ *
  * @param  {string}  text
  *     The text to wrap.
  * @param  {number}  width
@@ -12,8 +26,8 @@ import { getDisplayWidth } from "./source.js";
  *     Wrapped lines.
  */
 export function wrapWords(text, width) {
-	// The text's individual words.
-	const words = text.trim().split(/\s+/).filter(Boolean);
+	// The text's words, with code spans kept whole.
+	const words = text.trim().match(wordPattern) ?? [];
 	// The wrapped lines, built up in place.
 	const lines = [];
 
@@ -22,6 +36,13 @@ export function wrapWords(text, width) {
 
 	for (const word of words) {
 		if (word.length > width && currentLine === "") {
+			// Code stays whole even when it overflows the line.
+			if (codeSpanPattern.test(word)) {
+				lines.push(word);
+
+				continue;
+			}
+
 			for (let index = 0; index < word.length; index += width) {
 				lines.push(word.slice(index, index + width));
 			}
@@ -74,8 +95,8 @@ export function refillCommentLines(lines, maximumLineLength) {
 				break;
 			}
 
-			// The words still waiting on the following line.
-			const nextWords = nextLine.text.split(/\s+/).filter(Boolean);
+			// The next line's words, with code spans kept whole.
+			const nextWords = nextLine.text.match(wordPattern) ?? [];
 
 			// Whether the following line was removed after giving up all its
 			// words.
@@ -180,6 +201,9 @@ export function formatSentence(text) {
 /**
  * Capitalise the first letter of sentence text.
  *
+ * Text that starts with anything other than a letter, such as a code span, a
+ * quote or an emoji, is returned unchanged.
+ *
  * @param  {string}  text
  *     The sentence text.
  *
@@ -194,15 +218,14 @@ export function capitaliseSentence(text) {
 		return text;
 	}
 
-	// The index of the first letter character, ignoring leading punctuation.
-	const firstLetter = trimmedText.search(/\p{L}/u);
-
-	if (firstLetter < 0) {
+	// Code, quoted text and emoji keep their own casing, so only a sentence
+	// that starts with a letter is capitalised.
+	if (!/^\p{L}/u.test(trimmedText)) {
 		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] ?? "";
+	// The leading word, before any space or punctuation.
+	const leadingWord = trimmedText.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.
@@ -211,15 +234,20 @@ export function capitaliseSentence(text) {
 	}
 
 	// The first letter character.
-	const letter = trimmedText[firstLetter];
+	const letter = trimmedText[0];
 	// The text with its first letter capitalised.
-	const formattedText = `${trimmedText.slice(0, firstLetter)}${letter.toLocaleUpperCase()}${trimmedText.slice(firstLetter + 1)}`;
+	const formattedText = `${letter.toLocaleUpperCase()}${trimmedText.slice(1)}`;
 
 	return text.replace(trimmedText, formattedText);
 }
 
 /**
- * Add terminal punctuation to sentence text.
+ * Add a full stop to sentence text that has no closing punctuation.
+ *
+ * Text ending in a colon introduces what follows, and text that is only a code
+ * span or a quotation is not a sentence, so both are returned unchanged. A
+ * sentence that ends in a code span or quotation gets its full stop after the
+ * closing mark.
  *
  * @param  {string}  text
  *     The sentence text.
@@ -231,7 +259,13 @@ export function addTerminalPunctuation(text) {
 	// The sentence text, without leading or trailing whitespace.
 	const trimmedText = text.trim();
 
-	if (trimmedText === "" || trimmedText.startsWith("@") || /[.!?]$/.test(trimmedText)) {
+	if (
+		trimmedText === "" ||
+		trimmedText.startsWith("@") ||
+		/[.!?:]$/.test(trimmedText) ||
+		codeSpanOnlyPattern.test(trimmedText) ||
+		quoteOnlyPattern.test(trimmedText)
+	) {
 		return text;
 	}
 

package/comments.json

@@ -19,6 +19,7 @@
 		{
 			"files": ["**/*.test.*", "**/*.spec.*", "**/test/**"],
 			"rules": {
+				"comments/function-documentation": ["error", { "ignoreInlineArrows": true }],
 				"comments/variable-declarations": ["error", { "rootOnly": true }]
 			}
 		}

package/layers.js

@@ -0,0 +1,60 @@
+import base from "./base.json" with { type: "json" };
+import comments from "./comments.json" with { type: "json" };
+import vueConfig from "./vue.json" with { type: "json" };
+
+// The Vue layer. It includes base as an object because Oxlint rejects the file
+// path that vue.json uses to extend base.
+export const vue = { ...vueConfig, extends: [base] };
+
+/**
+ * Build a Vite+ lint block from the selected layers and local settings.
+ *
+ * @param  {object[]}  layers
+ *     The layer objects to extend. When two layers set the same env or global,
+ *     the later layer's value is used.
+ * @param  {object}  local
+ *     Project settings that take priority over the layers. Its extends list is
+ *     ignored, so every layer must be passed in layers.
+ *
+ * @returns  {object}
+ *     A lint block with inherited environments and globals at the top level.
+ */
+export function lintConfig(layers, local = {}) {
+	// The environments inherited from the selected layers.
+	const env = {};
+	// The globals inherited from the selected layers.
+	const globals = {};
+
+	for (const layer of layers) {
+		collectEnvAndGlobals(layer, env, globals);
+	}
+
+	return {
+		...local,
+		env: { ...env, ...local.env },
+		globals: { ...globals, ...local.globals },
+		extends: layers,
+	};
+}
+
+/**
+ * Copy a layer's env and globals into the collected values. The layers it
+ * extends are copied first, so the layer's own values win.
+ *
+ * @param  {object}  layer
+ *     The layer to read, along with every layer it extends.
+ * @param  {object}  env
+ *     The collected environments, updated in place.
+ * @param  {object}  globals
+ *     The collected globals, updated in place.
+ */
+function collectEnvAndGlobals(layer, env, globals) {
+	for (const extendedLayer of layer.extends ?? []) {
+		collectEnvAndGlobals(extendedLayer, env, globals);
+	}
+
+	Object.assign(env, layer.env);
+	Object.assign(globals, layer.globals);
+}
+
+export { base, comments };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lewishowles/lint-config",
-	"version": "0.7.0",
+	"version": "0.9.0",
 	"description": "Shared oxlint configuration for Lewis Howles projects",
 	"keywords": [
 		"config",
@@ -24,18 +24,23 @@
 		"comments",
 		"comments.json",
 		"imports.json",
+		"layers.js",
+		"testing",
 		"vue.json",
 		"README.md"
 	],
 	"type": "module",
 	"imports": {
-		"#comments/*": "./comments/*"
+		"#comments/*": "./comments/*",
+		"#testing/*": "./testing/*"
 	},
 	"exports": {
 		"./base.json": "./base.json",
 		"./comments.json": "./comments.json",
 		"./comments/plugin": "./comments/plugin.js",
 		"./imports.json": "./imports.json",
+		"./layers": "./layers.js",
+		"./testing/plugin": "./testing/plugin.js",
 		"./vue.json": "./vue.json"
 	},
 	"publishConfig": {
@@ -46,15 +51,15 @@
 		"lint:fix": "vp check --fix",
 		"prepare": "vp config --no-agent",
 		"publint": "publint",
-		"test:unit": "node --test test/comments/*.test.js"
+		"test:unit": "node --test test/comments/*.test.js test/layers/*.test.js test/testing/*.test.js"
 	},
 	"devDependencies": {
 		"publint": "^0.3.22",
-		"vite-plus": "0.2.8"
+		"vite-plus": "1.0.0"
 	},
 	"peerDependencies": {
 		"@stylistic/eslint-plugin": "*",
-		"vite-plus": "0.2.8"
+		"vite-plus": "^1.0.0"
 	},
 	"engines": {
 		"node": ">=20"

package/testing/plugin.js

@@ -0,0 +1,8 @@
+import noTextLookups from "./rules/no-text-lookups.js";
+
+export default {
+	meta: { name: "testing" },
+	rules: {
+		"no-text-lookups": noTextLookups,
+	},
+};

package/testing/rules/no-text-lookups.js

@@ -0,0 +1,148 @@
+// The array methods that count as a lookup when their callback reads an
+// element's text.
+const searchMethods = new Set([
+	"filter",
+	"find",
+	"findLast",
+	"findIndex",
+	"findLastIndex",
+	"some",
+	"every",
+]);
+
+// The DOM properties that hold an element's visible text.
+const textProperties = new Set(["textContent", "innerText"]);
+
+/**
+ * Return whether a callback body reads an element's text anywhere inside it.
+ *
+ * @param  {object}  node
+ *     The callback body, or a node inside it while searching.
+ *
+ * @returns  {boolean}
+ *     Whether any part of the body calls text() or reads textContent or
+ *     innerText.
+ */
+function containsTextRead(node) {
+	// A nested search callback is reported at its own call, so it isn't
+	// counted again here.
+	if (isSearchCallback(node)) {
+		return false;
+	}
+
+	if (isTextRead(node)) {
+		return true;
+	}
+
+	for (const [key, child] of Object.entries(node)) {
+		if (key === "parent") {
+			continue;
+		}
+
+		if (Array.isArray(child)) {
+			for (const entry of child) {
+				if (entry?.type && containsTextRead(entry)) {
+					return true;
+				}
+			}
+		} else if (child?.type && containsTextRead(child)) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+/**
+ * Return whether a node is an inline callback passed to an array search, such
+ * as the arrow function in items.find(item => item.id === 1).
+ *
+ * @param  {object|undefined}  node
+ *     The node to inspect, or undefined when a call has no arguments.
+ *
+ * @returns  {boolean}
+ *     Whether the rule checks this callback's body for text reads.
+ */
+function isSearchCallback(node) {
+	if (node?.type !== "ArrowFunctionExpression" && node?.type !== "FunctionExpression") {
+		return false;
+	}
+
+	// The call the function is passed to, if it is passed to one.
+	const call = node.parent;
+
+	return (
+		call?.type === "CallExpression" &&
+		call.arguments[0] === node &&
+		call.callee.type === "MemberExpression" &&
+		!call.callee.computed &&
+		searchMethods.has(call.callee.property.name)
+	);
+}
+
+/**
+ * Return whether a node itself reads an element's text, by calling text() or
+ * reading textContent or innerText.
+ *
+ * @param  {object}  node
+ *     The AST node to inspect.
+ *
+ * @returns  {boolean}
+ *     Whether the node calls text() or reads a DOM text property.
+ */
+function isTextRead(node) {
+	if (
+		node.type === "CallExpression" &&
+		node.callee.type === "MemberExpression" &&
+		!node.callee.computed &&
+		node.callee.property.name === "text"
+	) {
+		return true;
+	}
+
+	return (
+		node.type === "MemberExpression" && !node.computed && textProperties.has(node.property.name)
+	);
+}
+
+export default {
+	meta: {
+		docs: { description: "Find test elements by data-test attributes instead of visible text." },
+		type: "problem",
+	},
+
+	/**
+	 * Create the rule's node visitor.
+	 *
+	 * @param  {object}  context
+	 *     The Oxlint rule context.
+	 *
+	 * @returns  {object}
+	 *     The visitor for array search calls.
+	 */
+	createOnce(context) {
+		return {
+			/**
+			 * Report an array search when its inline callback reads visible
+			 * text.
+			 *
+			 * @param  {object}  node
+			 *     The call expression being checked.
+			 */
+			CallExpression(node) {
+				// Only an inline callback is checked, because a callback passed
+				// by name has its body somewhere else.
+				const callback = node.arguments[0];
+
+				if (!isSearchCallback(callback) || !containsTextRead(callback.body)) {
+					return;
+				}
+
+				context.report({
+					message: "Find test elements by a data-test attribute instead of visible text.",
+					node,
+				});
+			},
+		};
+	},
+};

package/vue.json

@@ -12,6 +12,7 @@
 	},
 	"rules": {
 		"vue/no-arrow-functions-in-watch": "error",
+		"vue/no-async-in-computed-properties": "error",
 		"vue/no-deprecated-data-object-declaration": "error",
 		"vue/no-deprecated-delete-set": "error",
 		"vue/no-deprecated-destroyed-lifecycle": "error",
@@ -20,6 +21,7 @@
 		"vue/no-deprecated-vue-config-keycodes": "error",
 		"vue/no-export-in-script-setup": "error",
 		"vue/no-lifecycle-after-await": "error",
+		"vue/no-side-effects-in-computed-properties": "error",
 		"vue/prefer-import-from-vue": "error",
 		"vue/return-in-computed-property": "error",
 		"vue/valid-define-emits": "error",