@sister.software/oxlint-config 10.0.0 → 11.0.0

package/src/index.ts

@@ -9,26 +9,46 @@ import { createRuntimeOverrides } from "./restrictions.js"
 
 export * from "./restrictions.js"
 
-/** An oxlint configuration object, as consumed by `oxlint.config.ts` / `.oxlintrc.json`. */
+/**
+ * An oxlint configuration object, as consumed by `oxlint.config.ts` / `.oxlintrc.json`.
+ */
 export type OxlintConfig = Record<string, unknown>
 
-/** Numeric ceilings for the legibility-guardrail rules. Each is a hard ceiling, not a target. */
+/**
+ * Numeric ceilings for the legibility-guardrail rules. Each is a hard ceiling, not a target.
+ */
 export interface OxlintConfigLimits {
-	/** Maximum block nesting depth. */
+	/**
+	 * Maximum block nesting depth.
+	 */
 	maxDepth: number
-	/** Maximum parameters on a single function. */
+	/**
+	 * Maximum parameters on a single function.
+	 */
 	maxParams: number
-	/** Maximum statements in a single function body. */
+	/**
+	 * Maximum statements in a single function body.
+	 */
 	maxStatements: number
-	/** Maximum lines in a single function body, blank lines and comments excluded. */
+	/**
+	 * Maximum lines in a single function body, blank lines and comments excluded.
+	 */
 	maxLinesPerFunction: number
-	/** Maximum lines in a single file, blank lines and comments excluded. */
+	/**
+	 * Maximum lines in a single file, blank lines and comments excluded.
+	 */
 	maxLines: number
-	/** Maximum nested callback depth. */
+	/**
+	 * Maximum nested callback depth.
+	 */
 	maxNestedCallbacks: number
-	/** Maximum nested call-expression depth, e.g. `a(b(c(d())))`. */
+	/**
+	 * Maximum nested call-expression depth, e.g. `a(b(c(d())))`.
+	 */
 	maxNestedCalls: number
-	/** Maximum cyclomatic complexity of a single function. */
+	/**
+	 * Maximum cyclomatic complexity of a single function.
+	 */
 	complexity: number
 }
 
@@ -61,7 +81,9 @@ export const DefaultLimits: OxlintConfigLimits = {
 	complexity: 85,
 }
 
-/** Globs treated as test files, where the size and named-constant rules are switched off. */
+/**
+ * Globs treated as test files, where the size and named-constant rules are switched off.
+ */
 export const DefaultTestFilePatterns = [
 	"**/*.test.ts",
 	"**/*.test.tsx",
@@ -82,23 +104,56 @@ export const DefaultTestFilePatterns = [
  */
 export const DefaultGeneratedFilePatterns = ["**/*.gen.ts", "**/*.gen.tsx", "**/*.generated.ts", "**/generated/**"]
 
-/** Options for {@link createOxlintConfig}. */
+/**
+ * Globs for files JavaScript checks at runtime rather than TypeScript checking ahead of it. A JSDoc block there often
+ * IS the type annotation, and a one-line `@type` cast is the idiomatic form — so the multi-line requirement, which
+ * exists to make prose read as documentation, does not apply.
+ */
+export const DefaultUntypedFilePatterns = ["**/*.js", "**/*.mjs", "**/*.cjs", "**/*.jsx"]
+
+/**
+ * Options for {@link createOxlintConfig}.
+ */
 export interface OxlintConfigOptions {
-	/** The package namespace whose runtime boundaries are enforced, e.g. `@sister.software`. */
+	/**
+	 * The package namespace whose runtime boundaries are enforced, e.g. `@sister.software`.
+	 */
 	packageNamespace?: string
-	/** The copyright holder stamped into file headers. */
+	/**
+	 * The copyright holder stamped into file headers.
+	 */
 	copyrightHolder?: string
-	/** The SPDX license identifier stamped into file headers. */
+	/**
+	 * The SPDX license identifier stamped into file headers.
+	 */
 	spdxLicenseIdentifier?: string
-	/** The author stamped into file headers. */
+	/**
+	 * The author stamped into file headers.
+	 */
 	author?: string
-	/** Enable oxlint's React plugin (off by default). */
+	/**
+	 * Enable oxlint's React plugin (off by default).
+	 */
 	react?: boolean
-	/** Enforce file headers via the bundled JS plugin (on by default). */
+	/**
+	 * Enforce file headers via the bundled JS plugin (on by default).
+	 */
 	headers?: boolean
-	/** Require a blank line before `return`/block-like statements (on by default). */
+	/**
+	 * Require a blank line before `return`/block-like statements (on by default).
+	 */
 	padding?: boolean
-	/** Require braces around single-statement work bodies (bare `return` exempt; on by default). */
+	/**
+	 * Blank line on each side of a `console.*` call, with runs of them grouped (on by default).
+	 */
+	consolePadding?: boolean
+	/**
+	 * Blank line on each side of a statement that spans lines (on by default).
+	 */
+	multilineStatementPadding?: boolean
+	/**
+	 * Require braces around single-statement work bodies (bare `return` exempt; on by default).
+	 */
 	braces?: boolean
 	/**
 	 * Forbid direct `process.env` / `process.argv` access (off by default). Turn on once the project funnels those reads
@@ -115,21 +170,48 @@ export interface OxlintConfigOptions {
 	 * `"screaming"`, or the default `"exported-or-screaming"`.
 	 */
 	constantDocs?: boolean | { scope?: "exported" | "screaming" | "exported-or-screaming" }
-	/** Rewrite explicit length comparisons to truthiness in boolean positions (on by default). */
+	/**
+	 * Rewrite explicit length comparisons to truthiness in boolean positions (on by default).
+	 */
 	lengthTruthiness?: boolean
-	/** Override individual legibility ceilings. Unspecified keys keep their calibrated default. */
+	/**
+	 * Require JSDoc blocks to span multiple lines (on by default). Off for untyped files.
+	 */
+	multilineJSDoc?: boolean
+	/**
+	 * Enforce the section-marker ladder — `----` banners become `// MARK:`, long labels are flagged, and a file with many
+	 * markers is nudged toward regions and then toward being several files (on by default).
+	 */
+	sectionMarkers?: boolean | { maxBodyLength?: number; maxRegions?: number }
+	/**
+	 * Override individual legibility ceilings. Unspecified keys keep their calibrated default.
+	 */
 	limits?: Partial<OxlintConfigLimits>
-	/** Replace the globs treated as test files. */
+	/**
+	 * Replace the globs treated as test files.
+	 */
 	testFilePatterns?: string[]
-	/** Replace the globs treated as generated files, where only the size ceilings are switched off. */
+	/**
+	 * Replace the globs treated as generated files, where only the size ceilings are switched off.
+	 */
 	generatedFilePatterns?: string[]
-	/** Override the default ignore patterns. */
+	/**
+	 * Replace the globs treated as untyped, where the multi-line JSDoc requirement switches off.
+	 */
+	untypedFilePatterns?: string[]
+	/**
+	 * Override the default ignore patterns.
+	 */
 	ignorePatterns?: string[]
-	/** Extra config deep-merged last; an escape hatch for per-repo tweaks. */
+	/**
+	 * Extra config deep-merged last; an escape hatch for per-repo tweaks.
+	 */
 	overrides?: OxlintConfig
 }
 
-/** Default ignore patterns for generated/build output and vendored tooling. */
+/**
+ * Default ignore patterns for generated/build output and vendored tooling.
+ */
 export const DefaultIgnorePatterns = [
 	"**/out",
 	"**/dist",
@@ -165,14 +247,19 @@ export function createOxlintConfig(options: OxlintConfigOptions = {}): OxlintCon
 		react = false,
 		headers = true,
 		padding = true,
+		consolePadding = true,
+		multilineStatementPadding = true,
 		braces = true,
 		restrictProcessGlobals = false,
 		unnamedThresholds = false,
 		constantDocs = false,
 		lengthTruthiness = true,
+		multilineJSDoc = true,
+		sectionMarkers = true,
 		limits: limitOverrides = {},
 		testFilePatterns = DefaultTestFilePatterns,
 		generatedFilePatterns = DefaultGeneratedFilePatterns,
+		untypedFilePatterns = DefaultUntypedFilePatterns,
 		ignorePatterns = DefaultIgnorePatterns,
 		overrides = {},
 	} = options
@@ -436,6 +523,38 @@ export function createOxlintConfig(options: OxlintConfigOptions = {}): OxlintCon
 		rules["sister-software/prefer-length-truthiness"] = "error"
 	}
 
+	if (consolePadding) {
+		rules["sister-software/console-padding"] = "warn"
+	}
+
+	if (multilineStatementPadding) {
+		rules["sister-software/multiline-statement-padding"] = "warn"
+	}
+
+	if (multilineJSDoc) {
+		rules["sister-software/multiline-jsdoc"] = "error"
+	}
+
+	if (sectionMarkers) {
+		const markerOptions = typeof sectionMarkers === "object" ? sectionMarkers : {}
+		// The two mechanical rungs are errors: a banner has exactly one correct rewrite, and a label
+		// length is measurable. The two judgment rungs warn — where a section ends, and whether it
+		// should become its own file, are not decisions a linter gets to make.
+		rules["sister-software/prefer-mark-comment"] = "error"
+
+		rules["sister-software/concise-section-marker"] = [
+			"error",
+			markerOptions.maxBodyLength === undefined ? {} : { maxBodyLength: markerOptions.maxBodyLength },
+		]
+
+		rules["sister-software/prefer-region-over-marks"] = "warn"
+
+		rules["sister-software/max-regions"] = [
+			"warn",
+			markerOptions.maxRegions === undefined ? {} : { max: markerOptions.maxRegions },
+		]
+	}
+
 	// Rules switched off inside test files. Table-driven test bodies are legitimately long, and
 	// expected values are legitimately unnamed numbers. oxlint validates override entries against the
 	// registered rule set, so an entry may only name a rule this config actually turned on.
@@ -460,7 +579,16 @@ export function createOxlintConfig(options: OxlintConfigOptions = {}): OxlintCon
 		testFileRules["sister-software/require-constant-doc"] = "off"
 	}
 
-	/** Generated files: size ceilings only. Everything else still applies — generated code ships. */
+	if (sectionMarkers) {
+		// A test file's sections track the suite's shape, which the code under test dictates — a big
+		// table of cases legitimately wants many markers, and splitting it would scatter the suite.
+		testFileRules["sister-software/prefer-region-over-marks"] = "off"
+		testFileRules["sister-software/max-regions"] = "off"
+	}
+
+	/**
+	 * Generated files: size ceilings only. Everything else still applies — generated code ships.
+	 */
 	const generatedFileRules: Record<string, unknown> = {
 		"max-lines": "off",
 		"max-lines-per-function": "off",
@@ -470,7 +598,15 @@ export function createOxlintConfig(options: OxlintConfigOptions = {}): OxlintCon
 
 	return {
 		plugins,
-		...(headers || padding || braces || restrictProcessGlobals || unnamedThresholds || constantDocs || lengthTruthiness
+		...(headers ||
+		padding ||
+		braces ||
+		restrictProcessGlobals ||
+		unnamedThresholds ||
+		constantDocs ||
+		lengthTruthiness ||
+		multilineJSDoc ||
+		sectionMarkers
 			? { jsPlugins: ["@sister.software/oxlint-config/plugin"] }
 			: {}),
 		categories: { correctness: "error" },
@@ -480,6 +616,7 @@ export function createOxlintConfig(options: OxlintConfigOptions = {}): OxlintCon
 			...createRuntimeOverrides(packageNamespace),
 			{ files: testFilePatterns, rules: testFileRules },
 			{ files: generatedFilePatterns, rules: generatedFileRules },
+			...(multilineJSDoc ? [{ files: untypedFilePatterns, rules: { "sister-software/multiline-jsdoc": "off" } }] : []),
 		],
 		...overrides,
 	}

package/src/jsdoc-plugin.ts

@@ -0,0 +1,75 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file The `sister-software/multiline-jsdoc` rule: a JSDoc block always spans multiple lines, even
+ *   when its content would fit on one. A one-line block reads as an aside; the multi-line form reads
+ *   as documentation, and it leaves somewhere to put the second sentence when one is needed.
+ *
+ *   Two shapes are left alone. A JSDoc that shares its line with code is a type cast or an inline
+ *   annotation, and expanding those changes what the line means. A JSDoc on a union or intersection
+ *   member labels one alternative in what reads as a list — three lines per entry turns a list you
+ *   can scan into a page you have to read.
+ */
+
+import type { Rule } from "./plugin-types.js"
+
+/**
+ * The JSDoc opener, so the rule can tell a documentation block from a plain block comment.
+ */
+const JSDOC_OPENER = "/**"
+
+/**
+ * A `|` or `&` as the next thing after a comment, meaning the comment labels one member of a union or intersection
+ * rather than documenting a declaration.
+ */
+const UNION_MEMBER = /^\s*[|&]/
+
+export const multilineJSDocRule: Rule = {
+	meta: {
+		name: "multiline-jsdoc",
+		type: "layout",
+		fixable: "whitespace",
+		schema: [{ type: "object", additionalProperties: true }],
+	},
+	create(context) {
+		const sourceCode = context.sourceCode ?? context.getSourceCode!()
+		const text = sourceCode.getText()
+
+		return {
+			Program() {
+				for (const comment of sourceCode.getAllComments()) {
+					if (comment.type !== "Block") continue
+					const raw = text.slice(comment.range[0], comment.range[1])
+
+					if (!raw.startsWith(JSDOC_OPENER) || raw.includes("\n")) continue
+
+					// `value` excludes the delimiters, so a one-line block arrives as `"* x "`.
+					const body = comment.value.replace(/^\*/, "").trim()
+
+					if (!body) continue
+
+					// Everything from the start of the line up to the comment. All-whitespace means the
+					// block leads its line and owns the indentation; anything else means it is inline.
+					const lineStart = text.lastIndexOf("\n", comment.range[0] - 1) + 1
+					const indent = text.slice(lineStart, comment.range[0])
+
+					if (indent.trim()) continue
+
+					// A block documenting a union or intersection member is a label on one alternative, and
+					// the members read as a list. Three lines per entry turns a scannable list into a page,
+					// so the requirement does not reach inside one.
+					if (UNION_MEMBER.test(text.slice(comment.range[1]))) continue
+
+					context.report({
+						node: { type: "Block", range: comment.range },
+						message: "JSDoc should span multiple lines.",
+						fix(fixer) {
+							return fixer.replaceTextRange(comment.range, `/**\n${indent} * ${body}\n${indent} */`)
+						},
+					})
+				}
+			},
+		}
+	},
+}

package/src/length-truthiness-plugin.ts

@@ -15,16 +15,24 @@
 
 import type { AstNode, Fixer, Rule, RuleContext } from "./plugin-types.js"
 
-/** Comparisons meaning "non-empty", which become the bare length. */
+/**
+ * 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. */
+/**
+ * Comparisons meaning "empty", which become a negated length.
+ */
 const FALSY_FORMS = new Set(["=== 0", "== 0", "< 1"])
 
-/** Members whose length-ness the rule understands. */
+/**
+ * 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. */
+/**
+ * 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
 
@@ -84,7 +92,9 @@ export const preferLengthTruthinessRule: Rule = {
 			})
 		}
 
-		/** Walk into a boolean context: logical operands and `!` arguments stay boolean. */
+		/**
+		 * Walk into a boolean context: logical operands and `!` arguments stay boolean.
+		 */
 		function visitCondition(node: AstNode | null | undefined) {
 			if (!node) return
 

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]))
 	},
 }