@sister.software/oxlint-config 10.0.0 → 12.0.0

package/src/acronym-case-plugin.ts

@@ -0,0 +1,370 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file A no-title-case-acronym rule, authored as an oxlint JS plugin (ESLint v9-compatible API). An
+ *   acronym is capitalized as a whole camelCase component — `parseJSON`, `POILookup`,
+ *   `createWOFResolver` — never title-cased. The mechanism knows nothing about any particular
+ *   project: the acronyms are options, so adding one is a config edit rather than a code change.
+ *
+ *   The subtlety the rule exists for is the COMPONENT BOUNDARY. `Poi` appears inside `Point`, `Id`
+ *   inside `Identifier`, `Us` inside `User` — none of those are acronyms, they are prefixes of
+ *   ordinary words. A substring match reports every one of them; a component match reports none.
+ *
+ *   Deliberately not fixable: renaming a declaration without renaming its references produces code
+ *   that does not compile, and a linter cannot see the references.
+ */
+
+import type { AstNode, Rule } from "./plugin-types.js"
+
+/**
+ * Acronyms enforced when the caller names none. Deliberately generic — every entry is an acronym in general programming
+ * rather than in some particular domain, because this list ships to consumers who share none of each other's
+ * vocabulary. Domain acronyms belong in `extraAcronyms`.
+ *
+ * `ID` is on the list and `Id` is NOT the house form: `placeID`, `sourceID`, `nodeID`. It is the one entry short enough
+ * to hide inside ordinary words — `Id` leads `Identifier`, `Idle`, `Ideal` — which is what the component boundary is
+ * for, and it holds: none of those end a component.
+ *
+ * The other short candidates were measured against a 1,587-file corpus and turned down. Read this before adding one
+ * back:
+ *
+ * - `IO` — `IoT` is the settled spelling of the commonest identifier component starting with `Io`, so the rule would
+ *   report `IoTGateway` and suggest the wrong `IOTGateway`. Zero drift in the corpus, so nothing offsets that.
+ * - `UI` — zero drift in the corpus, and the uppercase form is not settled the way `ID`'s is. `UiButton` is a deliberate
+ *   choice in plenty of React codebases, and `UiPath` is a vendor that spells itself that way.
+ * - `DB` — a shorthand for one word rather than an initialism, so there is no English uppercase form to settle on. It is
+ *   also the exact collision the exemptions exist for: every hit in the corpus was a Pastel option key, where the
+ *   framework derives `adminDb` from `--admin-db` and the schema has to match its derivation.
+ */
+export const DefaultAcronyms = [
+	"API",
+	// oxlint-disable-next-line unicorn/text-encoding-identifier-case -- an entry in an acronym list, not an encoding label.
+	"ASCII",
+	"CLI",
+	"CPU",
+	"CSS",
+	"CSV",
+	"DNS",
+	"DOM",
+	"GPU",
+	"HTML",
+	"HTTP",
+	"HTTPS",
+	"ID",
+	"JSON",
+	"JSONL",
+	"JWT",
+	"MIME",
+	"PDF",
+	"RGB",
+	"RGBA",
+	"SDK",
+	"SQL",
+	"SSL",
+	"SVG",
+	"TLS",
+	"TSV",
+	"TTL",
+	"URI",
+	"URL",
+	"UTC",
+	// oxlint-disable-next-line unicorn/text-encoding-identifier-case -- an entry in an acronym list, not an encoding label.
+	"UTF8",
+	"UUID",
+	"XML",
+	"YAML",
+] as const
+
+/**
+ * Which declarations the rule reads.
+ */
+export type AcronymCaseScope = "exported" | "all"
+
+/**
+ * Options accepted by {@link noTitleCaseAcronymRule}.
+ */
+export interface AcronymCaseOptions {
+	/**
+	 * Acronyms in the ALL-CAPS spelling identifiers should use; the rule derives the title-case form (`POI` → `Poi`) and
+	 * reports that. Replaces {@link DefaultAcronyms} rather than extending it.
+	 *
+	 * Add an acronym once the project has settled on its capitalized form. This reports drift from an established
+	 * convention; it does not invent one.
+	 */
+	acronyms?: string[]
+	/**
+	 * Acronyms added to whichever list is in effect — the usual way to layer a project's own vocabulary on the default.
+	 */
+	extraAcronyms?: string[]
+	/**
+	 * Identifiers exempt everywhere, for names whose casing is not ours to choose: an external library's own spelling
+	 * (`HttpStatusCode` from axios), a wire field someone else named (`operationId` in OpenAPI), or a prop a framework
+	 * derives from something else (Pastel turns `--run-id` into `runId`, so the schema key has to match its derivation).
+	 *
+	 * Prefer a scoped `// oxlint-disable-next-line sister-software/no-title-case-acronym` at the one site that needs it.
+	 * A config entry silently covers every future declaration of the same name.
+	 */
+	ignoreNames?: string[]
+	/**
+	 * `"exported"` (the default) reads the names a consumer can see: exported declarations, the members of exported
+	 * interfaces, classes and enums, and the exported half of a re-export. That is where a wrong acronym costs someone a
+	 * breaking rename later; a local costs nothing to rename at any time.
+	 *
+	 * `"all"` reads every declaration in the file, exported or not. Object-literal keys are never read under either
+	 * setting — a wire contract is a string, and its casing belongs to whoever is on the other end.
+	 */
+	scope?: AcronymCaseScope
+}
+
+/**
+ * Characters that may follow a title-cased run for it to be a whole component: the start of the next component, a
+ * digit, or an underscore.
+ */
+const COMPONENT_END = /[A-Z0-9_]/
+
+/**
+ * Characters that may precede a title-cased run for it to START a component.
+ */
+const COMPONENT_START = /[a-z0-9_]/
+
+/**
+ * Node types opening a scope whose names are private to it. Meeting one on the walk up means the declaration is a
+ * local, however deep inside an exported declaration it sits — the body of an exported function is not public surface.
+ */
+const SCOPE_BOUNDARIES = new Set([
+	"ArrowFunctionExpression",
+	"BlockStatement",
+	"FunctionDeclaration",
+	"FunctionExpression",
+	"Program",
+	"StaticBlock",
+	"TSModuleBlock",
+])
+
+/**
+ * Node types that make what they wrap part of the module's public surface.
+ */
+const EXPORT_WRAPPERS = new Set(["ExportNamedDeclaration", "ExportDefaultDeclaration"])
+
+/**
+ * One title-cased run found inside an identifier.
+ */
+interface AcronymHit {
+	/**
+	 * Where the run starts in the identifier.
+	 */
+	index: number
+	/**
+	 * The house spelling, e.g. `POI`.
+	 */
+	acronym: string
+	/**
+	 * The drifted spelling actually written, e.g. `Poi`.
+	 */
+	found: string
+}
+
+/**
+ * Title case of an acronym — the drifted spelling (`POI` → `Poi`, `NZ` → `Nz`).
+ */
+function titleCase(acronym: string): string {
+	return acronym[0]! + acronym.slice(1).toLowerCase()
+}
+
+/**
+ * Is the run of `found` at `index` a whole camelCase component of `identifier`?
+ *
+ * This is the entire subtlety of the rule. A component ENDS where the next character starts another one — uppercase, a
+ * digit, `_`, or the end of the identifier — and STARTS at the identifier's start or after a lowercase letter, digit or
+ * underscore. `PoiBoard` qualifies (`B` follows); `Point` does not (`n` follows).
+ */
+function isWholeComponent(identifier: string, index: number, found: string): boolean {
+	const after = identifier[index + found.length]
+
+	if (after !== undefined && !COMPONENT_END.test(after)) return false
+
+	const before = identifier[index - 1]
+
+	return before === undefined || COMPONENT_START.test(before)
+}
+
+/**
+ * Every title-cased acronym in `identifier`, plus the identifier as it should have been written.
+ */
+function findTitleCasedAcronyms(
+	identifier: string,
+	acronyms: readonly string[]
+): { hits: AcronymHit[]; expected: string } {
+	const candidates: AcronymHit[] = []
+
+	for (const acronym of acronyms) {
+		const found = titleCase(acronym)
+
+		// A one-letter acronym, or one whose tail is already caseless (`H3`), has no drifted spelling to
+		// look for: title case and house case are the same string, so every match would be a correct one.
+		if (found === acronym) continue
+
+		for (let index = identifier.indexOf(found); index !== -1; index = identifier.indexOf(found, index + 1)) {
+			if (isWholeComponent(identifier, index, found)) {
+				candidates.push({ index, acronym, found })
+			}
+		}
+	}
+
+	// Longest run first where two start together, so `Jsonl` wins over `Json`.
+	const ordered = candidates.toSorted(
+		(left, right) => left.index - right.index || right.found.length - left.found.length
+	)
+
+	const hits: AcronymHit[] = []
+	let expected = ""
+	let cursor = 0
+
+	for (const hit of ordered) {
+		if (hit.index < cursor) continue
+
+		hits.push(hit)
+		expected += identifier.slice(cursor, hit.index) + hit.acronym
+		cursor = hit.index + hit.found.length
+	}
+
+	return { hits, expected: expected + identifier.slice(cursor) }
+}
+
+/**
+ * Is `node` part of what the module exports?
+ *
+ * The walk stops at the first scope boundary rather than running to the root, which is what separates an exported
+ * declaration from a local one that merely lives inside an exported function.
+ */
+function isPublicSurface(node: AstNode): boolean {
+	let current = node.parent
+
+	while (current) {
+		if (EXPORT_WRAPPERS.has(current.type)) return true
+
+		if (SCOPE_BOUNDARIES.has(current.type)) return false
+
+		current = current.parent
+	}
+
+	return false
+}
+
+export const noTitleCaseAcronymRule: Rule = {
+	meta: {
+		name: "no-title-case-acronym",
+		type: "suggestion",
+		schema: [{ type: "object", additionalProperties: true }],
+	},
+	create(context) {
+		const options = (context.options[0] ?? {}) as AcronymCaseOptions
+		const configured = options.acronyms ?? DefaultAcronyms
+		const acronyms = [...configured, ...(options.extraAcronyms ?? [])].map((acronym) => acronym.toUpperCase())
+		const ignoreNames = new Set(options.ignoreNames)
+		const scope = options.scope ?? "exported"
+		const reported = new Set<string>()
+
+		/**
+		 * Reports the identifier bound by `node`, if it title-cases an acronym.
+		 */
+		function check(node: AstNode | undefined | null): void {
+			if (node?.type !== "Identifier" || !node.name) return
+
+			if (ignoreNames.has(node.name)) return
+
+			// A declaration can be reached by two visitors at once (an export specifier and the binding it
+			// names, say); the range keys the site so it is reported once.
+			const site = `${node.range[0]}:${node.range[1]}`
+
+			if (reported.has(site)) return
+
+			const { hits, expected } = findTitleCasedAcronyms(node.name, acronyms)
+
+			if (!hits.length) return
+
+			reported.add(site)
+
+			const spelled = hits.map((hit) => `\`${hit.acronym}\``).join(", ")
+
+			context.report({
+				node,
+				message:
+					`\`${node.name}\` title-cases ${hits.length > 1 ? "the acronyms" : "the acronym"} ${spelled} — an ` +
+					`acronym is capitalized as a whole camelCase component, so this reads \`${expected}\`.`,
+			})
+		}
+
+		function inScope(node: AstNode): boolean {
+			return scope === "all" || isPublicSurface(node)
+		}
+
+		/**
+		 * Parameters are declarations too, but renaming one breaks nobody, so they are read only when the caller has asked
+		 * for every declaration in the file.
+		 */
+		function parameters(node: AstNode): void {
+			if (scope !== "all") return
+
+			for (const parameter of node.params ?? []) {
+				check(parameter)
+			}
+		}
+
+		/**
+		 * A named declaration: `function`, `class`, `interface`, `type`, `enum`, `module`, and enum members.
+		 */
+		function declared(node: AstNode): void {
+			parameters(node)
+
+			if (inScope(node)) {
+				check(node.id)
+			}
+		}
+
+		/**
+		 * A member of an interface, type literal, or class — public surface of the type that holds it.
+		 */
+		function member(node: AstNode): void {
+			if (node.computed || node.accessibility === "private") return
+
+			if (inScope(node)) {
+				check(node.key)
+			}
+		}
+
+		return {
+			FunctionDeclaration: declared,
+			ClassDeclaration: declared,
+			TSInterfaceDeclaration: declared,
+			TSTypeAliasDeclaration: declared,
+			TSEnumDeclaration: declared,
+			TSModuleDeclaration: declared,
+			TSEnumMember: declared,
+			TSPropertySignature: member,
+			TSMethodSignature: member,
+			PropertyDefinition: member,
+			MethodDefinition: member,
+			VariableDeclaration(node) {
+				if (!inScope(node)) return
+
+				for (const declarator of node.declarations ?? []) {
+					check(declarator.id)
+				}
+			},
+			// The exported half of `export { poiBoard as PoiBoard }` and `export * as PoiBoard from "…"` is
+			// the name a consumer imports, whatever the local one is called.
+			ExportSpecifier(node) {
+				check(node.exported)
+			},
+			ExportAllDeclaration(node) {
+				check(node.exported)
+			},
+			FunctionExpression: parameters,
+			ArrowFunctionExpression: parameters,
+		}
+	},
+}
+
+export default noTitleCaseAcronymRule

package/src/browser-globals.ts

@@ -0,0 +1,77 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file The browser globals whose bare use is ambiguous, and the rule entry built from them. A list
+ *   this long is reference data — it belongs beside the code that consumes it, not inside the file
+ *   that assembles the platform-layering overrides.
+ */
+
+/**
+ * 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.
+ */
+export 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
+
+export function restrictedBrowserGlobalsRule(): unknown {
+	return ["warn", ...BROWSER_GLOBALS.map((name) => ({ name, message: `Ambiguous: did you mean \`window.${name}\`?` }))]
+}

package/src/console-padding-plugin.ts

@@ -0,0 +1,76 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file The `sister-software/console-padding` rule: a `console.*` call gets a blank line on each
+ *   side, so the lines that produce output stand apart from the lines that compute it. Scanning a
+ *   long procedural script for "what does this print" then works visually.
+ *
+ *   A RUN of console calls is one group — no blank lines inside it, one before the first and one
+ *   after the last, because consecutive calls are one block of output. Neither edge is required
+ *   where the block boundary already provides the separation: nothing is needed before a call that
+ *   opens a block, or after one that closes it.
+ */
+
+import { createPaddingHelpers } from "./padding-utils.js"
+import type { AstNode, Rule } from "./plugin-types.js"
+
+/**
+ * The object whose method calls this rule treats as output.
+ */
+const CONSOLE_OBJECT = "console"
+
+/**
+ * Is this statement a bare `console.<method>(…)` call?
+ */
+function isConsoleStatement(node: AstNode | undefined): boolean {
+	if (node?.type !== "ExpressionStatement") return false
+	const call = node.expression
+
+	if (call?.type !== "CallExpression") return false
+	const callee = call.callee
+
+	return (
+		callee?.type === "MemberExpression" && callee.object?.type === "Identifier" && callee.object.name === CONSOLE_OBJECT
+	)
+}
+
+export const consolePaddingRule: Rule = {
+	meta: {
+		name: "console-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)
+
+		return {
+			ExpressionStatement(node: AstNode) {
+				if (!isConsoleStatement(node)) return
+				const parent = node.parent
+
+				// Only statements in a statement list have neighbours to pad against.
+				if (!parent || !Array.isArray(parent.body)) return
+				const body = parent.body
+				const index = body.indexOf(node)
+
+				if (index === -1) return
+				const previous = body[index - 1]
+				const next = body[index + 1]
+
+				// Nothing before a call that opens the block, and nothing between calls in one run.
+				if (previous && !isConsoleStatement(previous)) {
+					requirePadding(previous, node, node, "Expected a blank line before this console call.")
+				}
+
+				// Nothing after a call that closes the block — the brace already separates it.
+				if (next && !isConsoleStatement(next)) {
+					requirePadding(node, next, node, "Expected a blank line after this console call.")
+				}
+			},
+		}
+	},
+}

package/src/constant-doc-plugin.ts

@@ -11,18 +11,28 @@
 
 import type { Rule } from "./plugin-types.js"
 
-/** Names in SCREAMING_SNAKE_CASE, the convention for a tuning knob. */
+/**
+ * Names in SCREAMING_SNAKE_CASE, the convention for a tuning knob.
+ */
 const SCREAMING_CASE = /^[A-Z][A-Z0-9_]*$/
 
-/** Initializers that make the binding a function rather than a constant value. */
+/**
+ * Initializers that make the binding a function rather than a constant value.
+ */
 const FUNCTION_INITIALIZERS = new Set(["ArrowFunctionExpression", "FunctionExpression"])
 
-/** Which module-level constants the rule applies to. */
+/**
+ * Which module-level constants the rule applies to.
+ */
 export type ConstantDocScope = "exported" | "screaming" | "exported-or-screaming"
 
-/** Options accepted by {@link requireConstantDocRule}. */
+/**
+ * Options accepted by {@link requireConstantDocRule}.
+ */
 export interface ConstantDocOptions {
-	/** Defaults to `"exported-or-screaming"`. */
+	/**
+	 * Defaults to `"exported-or-screaming"`.
+	 */
 	scope?: ConstantDocScope
 	/**
 	 * Export names a framework requires and gives meaning to, which a JSDoc block cannot improve on — Pastel's

package/src/headers-plugin.ts

@@ -9,7 +9,9 @@
 
 import type { Comment, Plugin, Rule } from "./plugin-types.js"
 
-/** Options accepted by the header rule. */
+/**
+ * Options accepted by the header rule.
+ */
 export interface HeaderRuleOptions {
 	copyrightHolder?: string
 	spdxLicenseIdentifier?: string
@@ -96,7 +98,9 @@ export const headerRule: Rule = {
 	},
 }
 
-/** The Sister Software oxlint header plugin. Registers the `sister-software/require-file-header` rule. */
+/**
+ * The Sister Software oxlint header plugin. Registers the `sister-software/require-file-header` rule.
+ */
 const headerPlugin: Plugin = {
 	meta: { name: "sister-software" },
 	rules: { "require-file-header": headerRule },