@sister.software/oxlint-config 9.3.0 → 11.0.0

package/src/length-truthiness-plugin.ts

@@ -0,0 +1,142 @@
+/**
+ * @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/multiline-statement-plugin.ts

@@ -0,0 +1,104 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file The `sister-software/multiline-statement-padding` rule: a statement that spans lines gets a
+ *   blank line on each side, so a reader can see where it starts and stops without matching brackets.
+ *
+ *   One rule covers what look like two habits — a big object literal jammed against the next
+ *   declaration, and a multi-line call jammed against the counter after it. Both are the same thing:
+ *   a statement tall enough to read as a block, sitting flush against its neighbour.
+ *
+ *   Neither edge is required at a block boundary, where the brace already separates. `console.*` calls
+ *   are left to `console-padding`, which groups consecutive ones — this rule would split a run that
+ *   happens to contain a tall call, and a run of output is one thing.
+ */
+
+import { createPaddingHelpers } from "./padding-utils.js"
+import type { AstNode, Rule } from "./plugin-types.js"
+
+/**
+ * The object whose calls belong to `console-padding` rather than to this rule.
+ */
+const CONSOLE_OBJECT = "console"
+
+/**
+ * Does this statement's own source span more than one line?
+ */
+function isMultiline(node: AstNode, text: string): boolean {
+	return text.slice(node.range[0], node.range[1]).includes("\n")
+}
+
+/**
+ * Is this statement a bare `console.<method>(…)` call, which `console-padding` owns?
+ */
+function isConsoleStatement(node: AstNode | undefined): boolean {
+	if (node?.type !== "ExpressionStatement") return false
+	const callee = node.expression?.type === "CallExpression" ? node.expression.callee : undefined
+
+	return callee?.type === "MemberExpression" && callee.object?.name === CONSOLE_OBJECT
+}
+
+export const multilineStatementPaddingRule: Rule = {
+	meta: {
+		name: "multiline-statement-padding",
+		type: "layout",
+		fixable: "whitespace",
+		schema: [{ type: "object", additionalProperties: true }],
+	},
+	create(context) {
+		const sourceCode = context.sourceCode ?? context.getSourceCode!()
+		const text = sourceCode.getText()
+		const { requirePadding } = createPaddingHelpers(context)
+
+		function check(node: AstNode): void {
+			const parent = node.parent
+
+			if (!parent || !Array.isArray(parent.body)) return
+
+			if (!isMultiline(node, text) || isConsoleStatement(node)) return
+			const body = parent.body
+			const index = body.indexOf(node)
+
+			if (index === -1) return
+			const previous = body[index - 1]
+			const next = body[index + 1]
+
+			if (previous && !isConsoleStatement(previous)) {
+				requirePadding(previous, node, node, "Expected a blank line before this multi-line statement.")
+			}
+
+			if (next && !isConsoleStatement(next)) {
+				requirePadding(node, next, node, "Expected a blank line after this multi-line statement.")
+			}
+		}
+
+		// Every statement type that can stand in a statement list and span lines. Block-like statements are
+		// already padded from the front by `padding-lines`; this adds their trailing edge.
+		return Object.fromEntries(
+			[
+				"VariableDeclaration",
+				"ExpressionStatement",
+				"IfStatement",
+				"ForStatement",
+				"ForInStatement",
+				"ForOfStatement",
+				"WhileStatement",
+				"DoWhileStatement",
+				"SwitchStatement",
+				"TryStatement",
+				"FunctionDeclaration",
+				"ClassDeclaration",
+				"ReturnStatement",
+				"TSInterfaceDeclaration",
+				"TSTypeAliasDeclaration",
+				"TSEnumDeclaration",
+				"TSModuleDeclaration",
+				// An exported declaration arrives wrapped, and the wrapper spans the same lines as what it
+				// wraps — so matching the wrapper is enough. Without these, every `export` was invisible here.
+				"ExportNamedDeclaration",
+				"ExportDefaultDeclaration",
+			].map((type) => [type, check])
+		)
+	},
+}

package/src/padding-plugin.ts

@@ -3,19 +3,23 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  * @file A padding-lines rule, authored as an oxlint JS plugin (ESLint v9-compatible API). It
- *   requires a blank line before `return` and block-like statements (the equivalent of ESLint's
- *   `padding-line-between-statements` with `{ blankLine: "always", prev: "*", next: "return" | "block-like" }`),
- *   and autofixes by inserting the missing blank line (before any leading comments).
+ *   requires a blank line before the statements that END a path or a step — `return`, `continue`,
+ *   `break`, a bare `x++`/`x--` — and before block-like statements. Roughly ESLint's
+ *   `padding-line-between-statements` with `{ blankLine: "always", prev: "*", next: "return" | "block-like" }`,
+ *   widened to the rest of that family. Autofixes by inserting the blank line before any leading comments.
  */
 
+import { createPaddingHelpers } from "./padding-utils.js"
 import type { AstNode, Rule } from "./plugin-types.js"
 
 /**
- * Statement node types that require a preceding blank line: `return` plus all "block-like" statements (matching
+ * Statement node types that require a preceding blank line: the path-enders plus all "block-like" statements (matching
  * ESLint's `block-like` selector).
  */
 const PADDED_STATEMENT_TYPES = [
 	"ReturnStatement",
+	"ContinueStatement",
+	"BreakStatement",
 	"BlockStatement",
 	"IfStatement",
 	"ForStatement",
@@ -25,8 +29,21 @@ const PADDED_STATEMENT_TYPES = [
 	"DoWhileStatement",
 	"SwitchStatement",
 	"TryStatement",
+	// An interface or a type alias with a body reads as a block too — same braces, same weight on the
+	// page — so it wants the same separation from whatever precedes it.
+	"TSInterfaceDeclaration",
+	"TSTypeAliasDeclaration",
+	"TSEnumDeclaration",
+	"TSModuleDeclaration",
 ] as const
 
+/**
+ * Does this node type require a preceding blank line?
+ */
+function isPaddedType(type: string | undefined): boolean {
+	return !!type && (PADDED_STATEMENT_TYPES as readonly string[]).includes(type)
+}
+
 export const paddingRule: Rule = {
 	meta: {
 		name: "padding-lines",
@@ -35,9 +52,7 @@ export const paddingRule: Rule = {
 		schema: [{ type: "object", additionalProperties: true }],
 	},
 	create(context) {
-		const sourceCode = context.sourceCode ?? context.getSourceCode!()
-		const text = sourceCode.getText()
-		const comments = sourceCode.getAllComments()
+		const { requirePadding } = createPaddingHelpers(context)
 
 		function check(node: AstNode) {
 			const parent = node.parent
@@ -49,32 +64,32 @@ export const paddingRule: Rule = {
 			const index = parent.body.indexOf(node)
 
 			if (index <= 0) return // first statement in the block — nothing to pad against.
-			const previous = parent.body[index - 1]!
 
-			// A blank line should sit before the statement's own leading comments, so measure the gap
-			// up to the earliest comment between the previous statement and this one.
-			let start = node.range[0]
+			requirePadding(parent.body[index - 1]!, node, node, "Expected a blank line before this statement.")
+		}
 
-			for (const comment of comments) {
-				if (comment.range[0] >= previous.range[1] && comment.range[1] <= node.range[0]) {
-					start = Math.min(start, comment.range[0])
+		return {
+			...Object.fromEntries(PADDED_STATEMENT_TYPES.map((type) => [type, check])),
+			// A bare `x++` / `x--` is a counter step, and reads like one only when it stands apart. It
+			// arrives as an ExpressionStatement, so it cannot be matched by node type alone.
+			ExpressionStatement(node: AstNode) {
+				if (node.expression?.type === "UpdateExpression") {
+					check(node)
 				}
-			}
-
-			const gap = text.slice(previous.range[1], start)
-
-			if ((gap.match(/\n/g) ?? []).length >= 2) return // already a blank line.
-
-			context.report({
-				node,
-				message: "Expected a blank line before this statement.",
-				fix(fixer) {
-					return fixer.insertTextAfterRange([previous.range[1], previous.range[1]], "\n")
-				},
-			})
+			},
+			// An exported declaration arrives wrapped. Look through the wrapper so `export interface Foo {}`
+			// is padded exactly like the unexported form.
+			ExportNamedDeclaration(node: AstNode) {
+				if (isPaddedType(node.declaration?.type)) {
+					check(node)
+				}
+			},
+			ExportDefaultDeclaration(node: AstNode) {
+				if (isPaddedType(node.declaration?.type)) {
+					check(node)
+				}
+			},
 		}
-
-		return Object.fromEntries(PADDED_STATEMENT_TYPES.map((type) => [type, check]))
 	},
 }
 

package/src/padding-utils.ts

@@ -0,0 +1,70 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file The blank-line machinery the three padding rules share: how to tell whether two statements are
+ *   already separated, and how to ask for the separation when they are not.
+ *
+ *   All three anchor their fix to the END of the earlier statement. That is deliberate: when two rules
+ *   want the same blank line — a console call before a `return`, say — they emit the identical edit, so
+ *   one is applied and the other is a no-op, instead of each inserting a newline and producing a gap of
+ *   two.
+ */
+
+import type { AstNode, Fixer, RuleContext, SourceCode } from "./plugin-types.js"
+
+/**
+ * What a padding rule needs from its context, resolved once per `create`.
+ */
+export interface PaddingHelpers {
+	/**
+	 * Is there already a blank line between these two statements?
+	 */
+	isPadded(from: AstNode, to: AstNode): boolean
+	/**
+	 * Report and fix a missing blank line between `from` and `to`, unless one is impossible or present.
+	 */
+	requirePadding(from: AstNode, to: AstNode, node: AstNode, message: string): void
+}
+
+/**
+ * Build the helpers for one rule invocation.
+ *
+ * A gap is measured to the earliest comment that leads the later statement, so the blank line lands above a statement's
+ * own comments rather than between them and their subject.
+ */
+export function createPaddingHelpers(context: RuleContext): PaddingHelpers {
+	const sourceCode: SourceCode = context.sourceCode ?? context.getSourceCode!()
+	const text = sourceCode.getText()
+	const comments = sourceCode.getAllComments()
+
+	function isPadded(from: AstNode, to: AstNode): boolean {
+		// Two statements with no newline between them cannot be separated by a blank line. This is the
+		// `;(expr)` ASI guard: the semicolon terminates the PREVIOUS statement, so the gap here is zero
+		// characters wide. Asking for padding there is asking for the impossible.
+		if (!text.slice(from.range[1], to.range[0]).includes("\n")) return true
+		let start = to.range[0]
+
+		for (const comment of comments) {
+			if (comment.range[0] >= from.range[1] && comment.range[1] <= to.range[0]) {
+				start = Math.min(start, comment.range[0])
+			}
+		}
+
+		return (text.slice(from.range[1], start).match(/\n/g) ?? []).length >= 2
+	}
+
+	function requirePadding(from: AstNode, to: AstNode, node: AstNode, message: string): void {
+		if (isPadded(from, to)) return
+
+		context.report({
+			node,
+			message,
+			fix(fixer: Fixer) {
+				return fixer.insertTextAfterRange([from.range[1], from.range[1]], "\n")
+			},
+		})
+	}
+
+	return { isPadded, requirePadding }
+}

package/src/plugin-types.ts

@@ -12,16 +12,81 @@ export interface Comment {
 	range: [number, number]
 }
 
-/** A loosely-typed AST node — only the fields the bundled rules read. */
+/**
+ * A loosely-typed AST node — only the fields the bundled rules read.
+ */
 export interface AstNode {
 	type: string
 	range: [number, number]
 	parent?: AstNode
-	/** A statement-list body (block/program) is an array; a loop body is a single statement. */
+	/**
+	 * A statement-list body (block/program) is an array; a loop body is a single statement.
+	 */
 	body?: AstNode[] | AstNode
-	/** `if`/`else` branches, for the require-braces rule. */
+	/**
+	 * `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
+	/**
+	 * An expression statement's expression, for the console-padding rule.
+	 */
+	expression?: AstNode
+	/**
+	 * An export statement's inner declaration, for the padding rules.
+	 */
+	declaration?: AstNode | null
+	/**
+	 * A call expression's callee.
+	 */
+	callee?: AstNode
+	/**
+	 * A member expression's object.
+	 */
+	object?: AstNode
 }
 
 export interface SourceCode {

package/src/plugin.ts

@@ -7,18 +7,40 @@
  */
 
 import { bracesRule } from "./braces-plugin.js"
+import { consolePaddingRule } from "./console-padding-plugin.js"
+import { requireConstantDocRule } from "./constant-doc-plugin.js"
 import { headerRule } from "./headers-plugin.js"
+import { multilineJSDocRule } from "./jsdoc-plugin.js"
+import { preferLengthTruthinessRule } from "./length-truthiness-plugin.js"
+import { multilineStatementPaddingRule } from "./multiline-statement-plugin.js"
 import { paddingRule } from "./padding-plugin.js"
 import type { Plugin } from "./plugin-types.js"
 import { noProcessGlobalsRule } from "./process-globals-plugin.js"
+import {
+	conciseSectionMarkerRule,
+	maxRegionsRule,
+	preferMarkCommentRule,
+	preferRegionOverMarksRule,
+} from "./section-marker-plugin.js"
+import { noUnnamedThresholdRule } from "./threshold-plugin.js"
 
 const sisterSoftwarePlugin: Plugin = {
 	meta: { name: "sister-software" },
 	rules: {
 		"require-file-header": headerRule,
 		"padding-lines": paddingRule,
+		"console-padding": consolePaddingRule,
+		"multiline-statement-padding": multilineStatementPaddingRule,
 		"require-braces": bracesRule,
 		"no-process-globals": noProcessGlobalsRule,
+		"no-unnamed-threshold": noUnnamedThresholdRule,
+		"require-constant-doc": requireConstantDocRule,
+		"prefer-length-truthiness": preferLengthTruthinessRule,
+		"multiline-jsdoc": multilineJSDocRule,
+		"prefer-mark-comment": preferMarkCommentRule,
+		"concise-section-marker": conciseSectionMarkerRule,
+		"prefer-region-over-marks": preferRegionOverMarksRule,
+		"max-regions": maxRegionsRule,
 	},
 }
 

package/src/process-globals-plugin.ts

@@ -10,7 +10,9 @@
 
 import type { AstNode, Rule } from "./plugin-types.js"
 
-/** `process` members that must be reached through a blessed helper, not accessed directly. */
+/**
+ * `process` members that must be reached through a blessed helper, not accessed directly.
+ */
 const RESTRICTED_MEMBERS = new Set(["env", "argv"])
 
 interface Identifierish extends AstNode {
@@ -24,7 +26,9 @@ interface MemberNode extends AstNode {
 	computed?: boolean
 }
 
-/** The accessed member name for `process.env` (identifier) or `process["env"]` (string literal). */
+/**
+ * The accessed member name for `process.env` (identifier) or `process["env"]` (string literal).
+ */
 function accessedMember(node: MemberNode): string | null {
 	const property = node.property