@sister.software/oxlint-config 9.3.0 → 11.0.0

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.",
+				})
+			},
+		}
+	},
+}

package/src/threshold-plugin.ts

@@ -0,0 +1,105 @@
+/**
+ * @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