@sister.software/oxlint-config 9.3.0 → 10.0.0

package/src/length-truthiness-plugin.ts

@@ -0,0 +1,132 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file A prefer-length-truthiness rule, authored as an oxlint JS plugin (ESLint v9-compatible API).
+ *   It is the house counterpart to `unicorn/explicit-length-check`, which enforces the opposite
+ *   convention and is therefore off: `if (items.length)` reads better here than
+ *   `if (items.length > 0)`.
+ *
+ *   The rule only fires where the value is ALREADY coerced to a boolean — a condition, a ternary
+ *   test, or the operand of `!` — including through `&&`/`||` nested inside one. Outside those
+ *   positions the comparison is the value itself, and rewriting `const hasItems = items.length > 0`
+ *   would silently change its type from boolean to number.
+ */
+
+import type { AstNode, Fixer, Rule, RuleContext } from "./plugin-types.js"
+
+/** Comparisons meaning "non-empty", which become the bare length. */
+const TRUTHY_FORMS = new Set(["> 0", "!== 0", "!= 0", ">= 1"])
+
+/** Comparisons meaning "empty", which become a negated length. */
+const FALSY_FORMS = new Set(["=== 0", "== 0", "< 1"])
+
+/** Members whose length-ness the rule understands. */
+const LENGTH_PROPERTIES = new Set(["length", "size"])
+
+/** The comparison rendered as `<operator> <literal>`, or null when it is not a length comparison. */
+function classify(node: AstNode): { member: AstNode; negate: boolean } | null {
+	if (node.type !== "BinaryExpression" || !node.operator || !node.left || !node.right) return null
+
+	// Accept both `x.length > 0` and the flipped `0 < x.length`.
+	const flipped: Record<string, string> = { "<": ">", ">": "<", "<=": ">=", ">=": "<=" }
+	let { left, right, operator } = { left: node.left, right: node.right, operator: node.operator }
+
+	if (left.type === "Literal" || left.type === "NumericLiteral") {
+		;[left, right] = [right, left]
+		operator = flipped[operator] ?? operator
+	}
+
+	if (left.type !== "MemberExpression" && left.type !== "StaticMemberExpression") return null
+
+	const property = (left as AstNode & { property?: AstNode }).property
+
+	if (!property || property.type !== "Identifier" || !LENGTH_PROPERTIES.has(property.name ?? "")) return null
+
+	if (right.type !== "Literal" && right.type !== "NumericLiteral") return null
+
+	if (typeof right.value !== "number") return null
+
+	const form = `${operator} ${right.value}`
+
+	if (TRUTHY_FORMS.has(form)) return { member: left, negate: false }
+
+	if (FALSY_FORMS.has(form)) return { member: left, negate: true }
+
+	return null
+}
+
+export const preferLengthTruthinessRule: Rule = {
+	meta: {
+		name: "prefer-length-truthiness",
+		type: "suggestion",
+		fixable: "code",
+		schema: [{ type: "object", additionalProperties: true }],
+	},
+	create(context: RuleContext) {
+		const sourceCode = context.sourceCode ?? context.getSourceCode!()
+		const text = sourceCode.getText()
+
+		function report(node: AstNode) {
+			const hit = classify(node)
+
+			if (!hit) return
+
+			const member = text.slice(hit.member.range[0], hit.member.range[1])
+			const replacement = hit.negate ? `!${member}` : member
+
+			context.report({
+				node,
+				message: `Prefer \`${replacement}\` over an explicit length comparison — the house convention is truthiness.`,
+				fix(fixer: Fixer) {
+					return fixer.replaceTextRange(node.range, replacement)
+				},
+			})
+		}
+
+		/** Walk into a boolean context: logical operands and `!` arguments stay boolean. */
+		function visitCondition(node: AstNode | null | undefined) {
+			if (!node) return
+
+			if (node.type === "LogicalExpression") {
+				visitCondition(node.left)
+				visitCondition(node.right)
+
+				return
+			}
+
+			if (node.type === "UnaryExpression" && node.operator === "!") {
+				visitCondition(node.argument)
+
+				return
+			}
+
+			report(node)
+		}
+
+		return {
+			IfStatement(node) {
+				visitCondition(node.test)
+			},
+			WhileStatement(node) {
+				visitCondition(node.test)
+			},
+			DoWhileStatement(node) {
+				visitCondition(node.test)
+			},
+			ForStatement(node) {
+				visitCondition(node.test)
+			},
+			ConditionalExpression(node) {
+				visitCondition(node.test)
+			},
+			UnaryExpression(node) {
+				if (node.operator === "!") {
+					visitCondition(node.argument)
+				}
+			},
+		}
+	},
+}
+
+export default preferLengthTruthinessRule

package/src/plugin-types.ts

@@ -22,6 +22,29 @@ export interface AstNode {
 	/** `if`/`else` branches, for the require-braces rule. */
 	consequent?: AstNode
 	alternate?: AstNode | null
+	/** Binary/unary operator text, for the threshold rule. */
+	operator?: string
+	/** Binary-expression operands. */
+	left?: AstNode
+	right?: AstNode
+	/** Unary-expression operand. */
+	argument?: AstNode
+	/** A literal's value, and its verbatim source text (`raw` preserves a `0x` prefix). */
+	value?: unknown
+	raw?: string
+	/** `const` / `let` / `var`, for the constant-doc rule. */
+	kind?: string
+	/** Declarators of a variable declaration. */
+	declarations?: AstNode[]
+	/** A declarator's binding identifier and initializer. */
+	id?: AstNode
+	init?: AstNode | null
+	/** An identifier's name. */
+	name?: string
+	/** The condition of an `if`/`while`/`for`/ternary, for the length-truthiness rule. */
+	test?: AstNode | null
+	/** A member expression's accessed property. */
+	property?: AstNode
 }
 
 export interface SourceCode {

package/src/plugin.ts

@@ -7,10 +7,13 @@
  */
 
 import { bracesRule } from "./braces-plugin.js"
+import { requireConstantDocRule } from "./constant-doc-plugin.js"
 import { headerRule } from "./headers-plugin.js"
+import { preferLengthTruthinessRule } from "./length-truthiness-plugin.js"
 import { paddingRule } from "./padding-plugin.js"
 import type { Plugin } from "./plugin-types.js"
 import { noProcessGlobalsRule } from "./process-globals-plugin.js"
+import { noUnnamedThresholdRule } from "./threshold-plugin.js"
 
 const sisterSoftwarePlugin: Plugin = {
 	meta: { name: "sister-software" },
@@ -19,6 +22,9 @@ const sisterSoftwarePlugin: Plugin = {
 		"padding-lines": paddingRule,
 		"require-braces": bracesRule,
 		"no-process-globals": noProcessGlobalsRule,
+		"no-unnamed-threshold": noUnnamedThresholdRule,
+		"require-constant-doc": requireConstantDocRule,
+		"prefer-length-truthiness": preferLengthTruthinessRule,
 	},
 }
 

package/src/threshold-plugin.ts

@@ -0,0 +1,93 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file A no-unnamed-threshold rule, authored as an oxlint JS plugin (ESLint v9-compatible API). It
+ *   flags a numeric literal used as a threshold — an operand of a comparison — and nothing else.
+ *   Numbers inside array and object literals are left alone, because a bounding box or a codepoint
+ *   table is data rather than a tuning knob. That distinction is why this exists instead of
+ *   `no-magic-numbers`, which cannot express it.
+ */
+
+import type { AstNode, Rule } from "./plugin-types.js"
+
+/** Operators whose operands read as thresholds. */
+const COMPARISON_OPERATORS = new Set(["<", ">", "<=", ">=", "===", "!==", "==", "!="])
+
+/** Numbers so conventional that naming them costs more clarity than it buys. */
+const DEFAULT_IGNORE = [-1, 0, 1, 2, 0.5, 10, 100, 1000]
+
+/** Radix-prefixed literals: `0x1f`, `0b1010`, `0o777`. */
+const RADIX_PREFIXED = /^0[xXbBoO]/
+
+/** Options accepted by {@link noUnnamedThresholdRule}. */
+export interface ThresholdOptions {
+	/** Values that may appear unnamed. Replaces the default list rather than extending it. */
+	ignore?: number[]
+	/** Exempt radix-prefixed literals, which already read as codepoints or bit masks. */
+	allowHex?: boolean
+}
+
+export const noUnnamedThresholdRule: Rule = {
+	meta: {
+		name: "no-unnamed-threshold",
+		type: "suggestion",
+		schema: [{ type: "object", additionalProperties: true }],
+	},
+	create(context) {
+		const options = (context.options[0] ?? {}) as ThresholdOptions
+		const ignore = new Set(options.ignore ?? DEFAULT_IGNORE)
+		const allowHex = options.allowHex ?? true
+
+		function check(operand: AstNode | undefined) {
+			if (!operand) return
+
+			let literal = operand
+			let sign = 1
+
+			// `x < -273.15` parses as a unary minus wrapping the literal.
+			if (operand.type === "UnaryExpression") {
+				if (operand.operator !== "-" && operand.operator !== "+") return
+
+				if (!operand.argument) return
+
+				sign = operand.operator === "-" ? -1 : 1
+				literal = operand.argument
+			}
+
+			// oxlint's AST uses ESTree `Literal` in some positions and Babel-style `NumericLiteral` in
+			// others, so both are accepted.
+			if (literal.type !== "Literal" && literal.type !== "NumericLiteral") return
+
+			if (typeof literal.value !== "number") return
+
+			const raw = literal.raw ?? String(literal.value)
+
+			// `cp >= 0x3040` already reads as a codepoint boundary; a name adds nothing.
+			if (allowHex && RADIX_PREFIXED.test(raw)) return
+
+			if (ignore.has(sign * literal.value)) return
+
+			// `raw` is the literal's own text, so a negated value reads as `273.15` without this.
+			const shown = sign === -1 ? `-${raw}` : raw
+
+			context.report({
+				node: literal,
+				message:
+					`Unnamed threshold \`${shown}\` — extract it to a documented named constant so a reader can tell ` +
+					`what it means and where the value came from.`,
+			})
+		}
+
+		return {
+			BinaryExpression(node) {
+				if (!node.operator || !COMPARISON_OPERATORS.has(node.operator)) return
+
+				check(node.left)
+				check(node.right)
+			},
+		}
+	},
+}
+
+export default noUnnamedThresholdRule