@sister.software/oxlint-config 9.2.0 → 10.0.0

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