@sister.software/oxlint-config 10.0.0 → 12.0.0

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,39 +12,101 @@ 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. */
+	/**
+	 * Binary/unary operator text, for the threshold rule.
+	 */
 	operator?: string
-	/** Binary-expression operands. */
+	/**
+	 * Binary-expression operands.
+	 */
 	left?: AstNode
 	right?: AstNode
-	/** Unary-expression operand. */
+	/**
+	 * Unary-expression operand.
+	 */
 	argument?: AstNode
-	/** A literal's value, and its verbatim source text (`raw` preserves a `0x` prefix). */
+	/**
+	 * 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. */
+	/**
+	 * `const` / `let` / `var`, for the constant-doc rule.
+	 */
 	kind?: string
-	/** Declarators of a variable declaration. */
+	/**
+	 * Declarators of a variable declaration.
+	 */
 	declarations?: AstNode[]
-	/** A declarator's binding identifier and initializer. */
+	/**
+	 * A declarator's binding identifier and initializer.
+	 */
 	id?: AstNode
 	init?: AstNode | null
-	/** An identifier's name. */
+	/**
+	 * An identifier's name.
+	 */
 	name?: string
-	/** The condition of an `if`/`while`/`for`/ternary, for the length-truthiness rule. */
+	/**
+	 * The condition of an `if`/`while`/`for`/ternary, for the length-truthiness rule.
+	 */
 	test?: AstNode | null
-	/** A member expression's accessed property. */
+	/**
+	 * 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
+	/**
+	 * The key of a class member or a type member, for the acronym-case rule. Computed keys are an expression rather than
+	 * a name, which `computed` distinguishes.
+	 */
+	key?: AstNode
+	computed?: boolean
+	/**
+	 * The two halves of `export { local as exported }`. `exported` also carries the name of an `export * as name from
+	 * "…"`.
+	 */
+	exported?: AstNode | null
+	local?: AstNode
+	/**
+	 * A function's parameter list.
+	 */
+	params?: AstNode[]
+	/**
+	 * A TypeScript class member's `public` / `protected` / `private` modifier.
+	 */
+	accessibility?: string
 }
 
 export interface SourceCode {

package/src/plugin.ts

@@ -6,13 +6,23 @@
  *   names) exposing all of Sister Software's custom rules under the `sister-software/` namespace.
  */
 
+import { noTitleCaseAcronymRule } from "./acronym-case-plugin.js"
 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 = {
@@ -20,11 +30,19 @@ const sisterSoftwarePlugin: Plugin = {
 	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,
+		"no-title-case-acronym": noTitleCaseAcronymRule,
 		"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
 

package/src/restrictions.ts

@@ -7,6 +7,8 @@
 
 import { builtinModules } from "node:module"
 
+import { restrictedBrowserGlobalsRule } from "./browser-globals.js"
+
 //#region Runtime data
 
 /**
@@ -24,7 +26,9 @@ export const RuntimePackageNamesRecord = {
 
 export type RuntimePackageNamesRecord = typeof RuntimePackageNamesRecord
 
-/** Valid runtime names. */
+/**
+ * Valid runtime names.
+ */
 export type RuntimeName = keyof RuntimePackageNamesRecord
 
 /**
@@ -38,7 +42,9 @@ export function createPackageFileMatcher(packageName: string): string[] {
 	return [`**/${packageName}.{js,mjs,cjs,ts,d.ts,mts,tsx}`]
 }
 
-/** Joins a namespace and package name into a specifier, e.g. `@sister.software/client`. */
+/**
+ * Joins a namespace and package name into a specifier, e.g. `@sister.software/client`.
+ */
 function namespaced(packageNamespace: string, packageName: string): string {
 	return [packageNamespace, packageName].filter(Boolean).join("/")
 }
@@ -53,7 +59,9 @@ const NODE_BUILTINS_NO_PREFIX = builtinModules.filter(
 
 const NODE_BUILTINS_PREFIXED = NODE_BUILTINS_NO_PREFIX.map((moduleName) => `node:${moduleName}`)
 
-/** A restricted-import entry: an exact module name plus the message shown when it is imported. */
+/**
+ * A restricted-import entry: an exact module name plus the message shown when it is imported.
+ */
 export interface RestrictedPath {
 	name: string
 	message: string
@@ -80,88 +88,19 @@ export function allNodeBuiltinPaths(message: string): RestrictedPath[] {
 
 //#endregion
 
-//#region Browser globals
+//#region Override generation
 
 /**
- * Browser globals whose bare use is ambiguous (they collide with common identifiers). Browser- and node-runtime files
- * warn on these, nudging toward an explicit `window.` access.
+ * A per-file-glob oxlint override: applies `rules` only to files matching `files`.
  */
-const BROWSER_GLOBALS = [
-	"addEventListener",
-	"blur",
-	"close",
-	"closed",
-	"confirm",
-	"defaultStatus",
-	"defaultstatus",
-	"event",
-	"external",
-	"find",
-	"focus",
-	"frameElement",
-	"frames",
-	"history",
-	"innerHeight",
-	"innerWidth",
-	"length",
-	"location",
-	"locationbar",
-	"menubar",
-	"moveBy",
-	"moveTo",
-	"name",
-	"onblur",
-	"onerror",
-	"onfocus",
-	"onload",
-	"onresize",
-	"onunload",
-	"open",
-	"opener",
-	"opera",
-	"outerHeight",
-	"outerWidth",
-	"pageXOffset",
-	"pageYOffset",
-	"parent",
-	"print",
-	"removeEventListener",
-	"resizeBy",
-	"resizeTo",
-	"screen",
-	"screenLeft",
-	"screenTop",
-	"screenX",
-	"screenY",
-	"scroll",
-	"scrollbars",
-	"scrollBy",
-	"scrollTo",
-	"scrollX",
-	"scrollY",
-	"self",
-	"status",
-	"statusbar",
-	"stop",
-	"toolbar",
-	"top",
-] as const
-
-function restrictedBrowserGlobalsRule(): unknown {
-	return ["warn", ...BROWSER_GLOBALS.map((name) => ({ name, message: `Ambiguous: did you mean \`window.${name}\`?` }))]
-}
-
-//#endregion
-
-//#region Override generation
-
-/** A per-file-glob oxlint override: applies `rules` only to files matching `files`. */
 export interface OxlintOverride {
 	files: string[]
 	rules: Record<string, unknown>
 }
 
-/** A restricted-import pattern: a set of gitignore-style globs plus a message. */
+/**
+ * A restricted-import pattern: a set of gitignore-style globs plus a message.
+ */
 interface RestrictedPattern {
 	group: string[]
 	message: string

package/src/section-marker-plugin.ts

@@ -0,0 +1,306 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Four rules over the comments people use to carve a file into sections. They form one
+ *   escalation ladder, and each rung is a smaller file than the last:
+ *
+ *   1. `prefer-mark-comment` — a `----` banner becomes `// MARK: <label>` (autofixed). A banner is
+ *      three lines of decoration to carry one label.
+ *   2. `concise-section-marker` — a marker's label is a label, not a paragraph. Past the limit, the
+ *      detail belongs in the documented symbol's JSDoc or in the file's own `@file` block.
+ *   3. `prefer-region-over-marks` — past one marker, a file has sections, and sections have ENDS.
+ *      Regions fold, so a reader can collapse what they are not reading.
+ *   4. `max-regions` — past ten regions, the sections want to be files.
+ *
+ *   Rules 3 and 4 are advisory: where a section ends, and whether it should move, are judgment calls
+ *   no fixer can make. Rules 1 and 2 are not — the first has one correct rewrite, the second has a
+ *   measurable limit.
+ */
+
+import type { Comment, Rule, RuleContext, SourceCode } from "./plugin-types.js"
+
+/**
+ * A run of at least this many dashes reads as decoration rather than as prose.
+ */
+const MIN_BANNER_DASHES = 10
+
+/**
+ * Default ceiling for a marker's label, in characters.
+ */
+const DEFAULT_MAX_BODY_LENGTH = 60
+
+/**
+ * Default region ceiling. The rule fires past it, so the eleventh region is the one that trips it.
+ *
+ * Deliberately high. A file with four well-named regions is usually fine — data plus the operations on it, where
+ * splitting would separate a type from its helpers. This is a runaway detector, not a style nudge: past ten sections a
+ * file is doing too many jobs by any reading.
+ */
+const DEFAULT_MAX_REGIONS = 10
+
+/**
+ * A line that is nothing but a comment marker and a rule of dashes.
+ */
+const BANNER_SEPARATOR = new RegExp(String.raw`^[ \t]*//[ \t]*-{${MIN_BANNER_DASHES},}[ \t]*$`)
+
+/**
+ * `// MARK: label`, with the leading dash Xcode allows (`// MARK: - label`) folded away.
+ */
+const MARK_COMMENT = /^[ \t]*\/\/[ \t]*MARK:[ \t]*-?[ \t]*(.*)$/
+
+/**
+ * `//#region label` — the space after `//` is optional, which is how most editors emit it.
+ */
+const REGION_COMMENT = /^[ \t]*\/\/[ \t]*#region\b[ \t]*(.*)$/
+
+/**
+ * One `----`-wrapped banner found in the source.
+ */
+interface Banner {
+	/**
+	 * Zero-based index of the opening separator line.
+	 */
+	startLine: number
+	/**
+	 * Zero-based index of the closing separator line.
+	 */
+	endLine: number
+	/**
+	 * The comment lines between the separators, stripped of their `//` and surrounding space.
+	 */
+	body: string[]
+	/**
+	 * Leading whitespace of the opening separator, so the replacement keeps the block's indentation.
+	 */
+	indent: string
+}
+
+/**
+ * Strip a line comment's `//` and the space that conventionally follows it.
+ */
+function commentBody(line: string): string {
+	return line
+		.trim()
+		.replace(/^\/\/[ \t]?/, "")
+		.trim()
+}
+
+/**
+ * Scan for banner blocks: a separator line, one or more comment lines, then another separator. Blocks are matched on
+ * raw lines rather than on the comment list because a banner is a visual construct — what makes it one is that the
+ * lines are adjacent, which the AST does not model.
+ */
+function findBanners(lines: string[]): Banner[] {
+	const banners: Banner[] = []
+	let i = 0
+
+	while (i < lines.length) {
+		if (!BANNER_SEPARATOR.test(lines[i]!)) {
+			i++
+
+			continue
+		}
+
+		let end = i + 1
+		const body: string[] = []
+
+		while (end < lines.length && lines[end]!.trim().startsWith("//") && !BANNER_SEPARATOR.test(lines[end]!)) {
+			body.push(commentBody(lines[end]!))
+
+			end++
+		}
+
+		if (body.length && end < lines.length && BANNER_SEPARATOR.test(lines[end]!)) {
+			banners.push({ startLine: i, endLine: end, body, indent: /^[ \t]*/.exec(lines[i]!)![0] })
+			i = end + 1
+
+			continue
+		}
+
+		i = end
+	}
+
+	return banners
+}
+
+/**
+ * Byte offset of the first character of a zero-based line.
+ */
+function offsetOfLine(lines: string[], line: number): number {
+	let offset = 0
+
+	for (let i = 0; i < line; i++) {
+		offset += lines[i]!.length + 1
+	}
+
+	return offset
+}
+
+/**
+ * Every line comment in the file, paired with its label under `pattern`.
+ */
+function markersMatching(
+	sourceCode: SourceCode,
+	text: string,
+	pattern: RegExp
+): Array<{ comment: Comment; label: string }> {
+	const found: Array<{ comment: Comment; label: string }> = []
+
+	for (const comment of sourceCode.getAllComments()) {
+		if (comment.type !== "Line") continue
+		const match = pattern.exec(text.slice(comment.range[0], comment.range[1]))
+
+		if (match) {
+			found.push({ comment, label: match[1]!.trim() })
+		}
+	}
+
+	return found
+}
+
+/**
+ * Shared preamble: the source text and its lines, which every rule here walks.
+ */
+function read(context: RuleContext): { sourceCode: SourceCode; text: string; lines: string[] } {
+	const sourceCode = context.sourceCode ?? context.getSourceCode!()
+	const text = sourceCode.getText()
+
+	return { sourceCode, text, lines: text.split("\n") }
+}
+
+export const preferMarkCommentRule: Rule = {
+	meta: {
+		name: "prefer-mark-comment",
+		type: "suggestion",
+		fixable: "code",
+		schema: [{ type: "object", additionalProperties: true }],
+	},
+	create(context) {
+		const { text, lines } = read(context)
+
+		return {
+			Program() {
+				for (const banner of findBanners(lines)) {
+					const start = offsetOfLine(lines, banner.startLine)
+					const end = offsetOfLine(lines, banner.endLine) + lines[banner.endLine]!.length
+					const node = { type: "Line", range: [start, end] as [number, number] }
+
+					// A banner wrapping real prose is a comment someone wrote, not decoration around a
+					// label. Collapsing it would delete the prose, so say what to do and leave it alone.
+					if (banner.body.length > 1) {
+						context.report({
+							node,
+							message:
+								"Banner comment: keep the prose in a JSDoc block on what it describes, and leave a `// MARK: <label>` here.",
+						})
+
+						continue
+					}
+
+					const label = banner.body[0]!
+
+					context.report({
+						node,
+						message: "Banner comment: use `// MARK: <label>`.",
+						fix(fixer) {
+							// The marker wants a blank line on each side. Add one only where the source is
+							// missing it, so a correctly-spaced banner does not gain stray lines.
+							const before = text.slice(0, start).endsWith("\n\n") || start === 0 ? "" : "\n"
+							const after = text.slice(end).startsWith("\n\n") ? "" : "\n"
+
+							return fixer.replaceTextRange([start, end], `${before}${banner.indent}// MARK: ${label}${after}`)
+						},
+					})
+				}
+			},
+		}
+	},
+}
+
+export const conciseSectionMarkerRule: Rule = {
+	meta: {
+		name: "concise-section-marker",
+		type: "suggestion",
+		schema: [{ type: "object", additionalProperties: true }],
+	},
+	create(context) {
+		const { sourceCode, text } = read(context)
+		const options = (context.options[0] ?? {}) as { maxBodyLength?: number }
+		const limit = options.maxBodyLength ?? DEFAULT_MAX_BODY_LENGTH
+
+		return {
+			Program() {
+				const markers = [
+					...markersMatching(sourceCode, text, MARK_COMMENT).map((m) => ({ ...m, kind: "MARK" })),
+					...markersMatching(sourceCode, text, REGION_COMMENT).map((m) => ({ ...m, kind: "#region" })),
+				]
+
+				for (const { comment, label, kind } of markers) {
+					if (label.length <= limit) continue
+
+					context.report({
+						node: { type: "Line", range: comment.range },
+						message:
+							`${kind} label is ${label.length} characters (max ${limit}) — shorten it, move the detail into ` +
+							"the JSDoc of what it describes, or split the file and put it in a `@file` block.",
+					})
+				}
+			},
+		}
+	},
+}
+
+export const preferRegionOverMarksRule: Rule = {
+	meta: {
+		name: "prefer-region-over-marks",
+		type: "suggestion",
+		schema: [{ type: "object", additionalProperties: true }],
+	},
+	create(context) {
+		const { sourceCode, text } = read(context)
+
+		return {
+			Program() {
+				const marks = markersMatching(sourceCode, text, MARK_COMMENT)
+
+				if (marks.length < 2) return
+
+				context.report({
+					node: { type: "Line", range: marks[0]!.comment.range },
+					message:
+						`${marks.length} MARK comments in one file — give each section an END with ` +
+						"`//#region <label>` / `//#endregion`, so a reader can fold what they are not reading.",
+				})
+			},
+		}
+	},
+}
+
+export const maxRegionsRule: Rule = {
+	meta: {
+		name: "max-regions",
+		type: "suggestion",
+		schema: [{ type: "object", additionalProperties: true }],
+	},
+	create(context) {
+		const { sourceCode, text } = read(context)
+		const options = (context.options[0] ?? {}) as { max?: number }
+		const limit = options.max ?? DEFAULT_MAX_REGIONS
+
+		return {
+			Program() {
+				const regions = markersMatching(sourceCode, text, REGION_COMMENT)
+
+				if (regions.length <= limit) return
+
+				context.report({
+					node: { type: "Line", range: regions[0]!.comment.range },
+					message:
+						`${regions.length} regions in one file (max ${limit}) — a file with this many sections is ` +
+						"several files. Split it, and let each one's `@file` block say what it is.",
+				})
+			},
+		}
+	},
+}