@sister.software/oxlint-config 9.3.0 → 11.0.0

package/src/index.ts

@@ -9,39 +9,209 @@ 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>
 
-/** Options for {@link createOxlintConfig}. */
+/**
+ * Numeric ceilings for the legibility-guardrail rules. Each is a hard ceiling, not a target.
+ */
+export interface OxlintConfigLimits {
+	/**
+	 * Maximum block nesting depth.
+	 */
+	maxDepth: number
+	/**
+	 * Maximum parameters on a single function.
+	 */
+	maxParams: number
+	/**
+	 * Maximum statements in a single function body.
+	 */
+	maxStatements: number
+	/**
+	 * 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.
+	 */
+	maxLines: number
+	/**
+	 * Maximum nested callback depth.
+	 */
+	maxNestedCallbacks: number
+	/**
+	 * Maximum nested call-expression depth, e.g. `a(b(c(d())))`.
+	 */
+	maxNestedCalls: number
+	/**
+	 * Maximum cyclomatic complexity of a single function.
+	 */
+	complexity: number
+}
+
+/**
+ * Calibrated against the mailwoman corpus (1,048 non-test source files). Each value sits just past the knee in that
+ * repo's distribution, so considered human code stays silent and runaway generation does not. See the design spec for
+ * the full sweep.
+ *
+ * The four SIZE ceilings are deliberately looser than the knee. Adopting v10 surfaced 172 pre-existing violations, and
+ * splitting that many functions across a parser — with no accuracy gate available to verify the result — is a larger
+ * risk than the legibility it buys. They are set at the p90 of the measured overage instead, so the worst decile had to
+ * be fixed at adoption while the body was grandfathered:
+ *
+ *     max-statements          n=88  median= 73  p90= 115  max= 272
+ *     complexity              n=32  median= 49  p90=  84  max= 173
+ *     max-lines-per-function  n=26  median=283  p90= 829  max=1329
+ *     max-params              n=15  median=  7  p90=   8  max=  10
+ *
+ * RATCHET THESE DOWN as the grandfathered functions are split. They exist to stop new code drifting, and every step
+ * toward the knee makes them do more of that job.
+ */
+export const DefaultLimits: OxlintConfigLimits = {
+	maxDepth: 5,
+	maxParams: 8,
+	maxStatements: 115,
+	maxLinesPerFunction: 830,
+	maxLines: 750,
+	maxNestedCallbacks: 4,
+	maxNestedCalls: 4,
+	complexity: 85,
+}
+
+/**
+ * Globs treated as test files, where the size and named-constant rules are switched off.
+ */
+export const DefaultTestFilePatterns = [
+	"**/*.test.ts",
+	"**/*.test.tsx",
+	"**/test/**",
+	"**/fixtures/**",
+	"**/*.bench.ts",
+	// Storybook stories are fixtures in the same sense: each export is a rendered case, and its NAME is
+	// the label shown in the sidebar. A JSDoc block on `export const Default: Story = {}` says nothing
+	// the name does not.
+	"**/*.stories.ts",
+	"**/*.stories.tsx",
+]
+
+/**
+ * Globs whose contents are emitted by a generator, not written by hand. The size ceilings are meaningless there — the
+ * file is as long as its input is wide, and no reviewer reads it top to bottom — but every correctness rule still
+ * applies, because generated code ships.
+ */
+export const DefaultGeneratedFilePatterns = ["**/*.gen.ts", "**/*.gen.tsx", "**/*.generated.ts", "**/generated/**"]
+
+/**
+ * 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
 	 * through blessed helpers, which disable `sister-software/no-process-globals`.
 	 */
 	restrictProcessGlobals?: boolean
-	/** Override the default ignore patterns. */
+	/**
+	 * Flag numeric literals used as comparison thresholds (off by default). Pass an object to change the ignore list or
+	 * to stop exempting radix-prefixed literals.
+	 */
+	unnamedThresholds?: boolean | { ignore?: number[]; allowHex?: boolean }
+	/**
+	 * Require a JSDoc block on module-level constants (off by default). `scope` selects which ones: `"exported"`,
+	 * `"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).
+	 */
+	lengthTruthiness?: boolean
+	/**
+	 * 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.
+	 */
+	testFilePatterns?: string[]
+	/**
+	 * Replace the globs treated as generated files, where only the size ceilings are switched off.
+	 */
+	generatedFilePatterns?: string[]
+	/**
+	 * 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. */
+/**
+ * Default ignore patterns for generated/build output and vendored tooling.
+ */
 export const DefaultIgnorePatterns = [
 	"**/out",
 	"**/dist",
@@ -49,6 +219,9 @@ export const DefaultIgnorePatterns = [
 	"**/node_modules",
 	"**/coverage",
 	"**/storybook-static",
+	// Yarn 4 vendors its own release bundle and plugin code here. It is third-party, minified, and
+	// not ours to lint — Tier 2's `no-abusive-eslint-disable` fires on it otherwise.
+	"**/.yarn/**",
 ]
 
 /**
@@ -74,20 +247,32 @@ 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
 
-	const plugins = ["typescript", "unicorn", "oxc", ...(react ? ["react"] : [])]
+	const limits: OxlintConfigLimits = { ...DefaultLimits, ...limitOverrides }
+
+	const plugins = ["typescript", "unicorn", "oxc", "import", "promise", "vitest", ...(react ? ["react"] : [])]
 
 	const rules: Record<string, unknown> = {
 		// JavaScript
 		eqeqeq: ["error", "always", { null: "ignore" }],
 		"prefer-const": "warn",
 		"object-shorthand": ["warn", "always"],
-		"no-shadow": "off",
 		"no-undef": "off",
 		"no-unused-vars": [
 			"warn",
@@ -113,6 +298,191 @@ export function createOxlintConfig(options: OxlintConfigOptions = {}): OxlintCon
 		"typescript/no-non-null-assertion": "off",
 		"typescript/no-var-requires": "off",
 		"typescript/no-require-imports": "off",
+
+		// Tier 1 — legibility guardrails. Thresholds are ceilings past the knee of the calibration
+		// corpus's distribution: they stay silent on considered code and fire on runaway generation.
+		"max-depth": ["error", { max: limits.maxDepth }],
+		"max-params": ["error", { max: limits.maxParams }],
+		"max-statements": ["error", { max: limits.maxStatements }],
+		"max-lines-per-function": ["error", { max: limits.maxLinesPerFunction, skipBlankLines: true, skipComments: true }],
+		"max-lines": ["error", { max: limits.maxLines, skipBlankLines: true, skipComments: true }],
+		"max-nested-callbacks": ["error", { max: limits.maxNestedCallbacks }],
+		"unicorn/max-nested-calls": ["error", { max: limits.maxNestedCalls }],
+		complexity: ["error", limits.complexity],
+		"unicorn/no-array-reduce": "error",
+		"unicorn/no-unreadable-array-destructuring": "error",
+
+		// Tier 2 — defect classes that `correctness` does not cover. Every rule here corresponds to a
+		// way working-looking code is wrong at runtime.
+		"no-shadow": "error",
+		"no-promise-executor-return": "error",
+		"no-useless-assignment": "error",
+		"no-unreachable-loop": "error",
+		"no-unmodified-loop-condition": "error",
+		"no-loop-func": "error",
+		// `.sort()` and `.reverse()` mutate in place; on a shared or cached array that is a bug at a
+		// distance. The fixes are `toSorted()` / `toReversed()`.
+		"unicorn/no-array-sort": "error",
+		"unicorn/no-array-reverse": "error",
+		"unicorn/no-immediate-mutation": "error",
+		"unicorn/no-array-method-this-argument": "error",
+		"unicorn/no-typeof-undefined": "error",
+		"unicorn/no-useless-promise-resolve-reject": "error",
+		"unicorn/prefer-type-error": "error",
+		// Global `isNaN` coerces its argument; `Number.isNaN` does not.
+		"unicorn/prefer-number-properties": "error",
+		"unicorn/no-abusive-eslint-disable": "error",
+		// Off despite the name: it fires on `.map(x => ({ ...x, field }))`, which is O(n·k) overall and the
+		// ordinary way to add a field. The quadratic accumulation worth catching is `acc = { ...acc, x }`
+		// inside a reduce, which this does not distinguish. 14 sites, 14 false positives.
+		"oxc/no-map-spread": "off",
+		"oxc/bad-bitwise-operator": "error",
+		"oxc/branches-sharing-code": "error",
+		"typescript/no-dynamic-delete": "error",
+		"typescript/prefer-ts-expect-error": "error",
+		// A cycle here is not a style issue: it leaves bindings unevaluated at import time, which
+		// surfaces as a base class that is `undefined` at class-definition time.
+		"import/no-cycle": "error",
+		// `ignoreLastCallback` keeps the rule pointed at CHAINS, where a missing return silently feeds
+		// undefined to the next link. A terminal `.then(…)` doing side effects has nothing downstream
+		// to starve, and rewriting those adds a return whose value no one reads.
+		"promise/always-return": ["error", { ignoreLastCallback: true }],
+		// Off: it cannot see that a ternary settles exactly once. `cb((err) => (err ? reject(err) : resolve()))`
+		// is the standard way to bridge a node-style callback to a promise, and the rule flagged every
+		// instance of it on the calibration corpus — 6 sites, 6 false positives, no real double-settle.
+		"promise/no-multiple-resolved": "off",
+
+		// Tier 3 — test discipline. `expect-expect` is the one that matters most: it catches a test
+		// that runs, passes, and asserts nothing.
+		"vitest/expect-expect": "error",
+		// vitest's `expect(value, message)` takes an optional assertion message as a second argument —
+		// the rule's default of one would flag the API's own signature.
+		"vitest/valid-expect": ["error", { maxArgs: 2 }],
+		"vitest/valid-title": "error",
+		"vitest/valid-describe-callback": "error",
+		// Off: the dominant shape it flags is a parameterized assertion helper, where the conditional IS
+		// the contract — `expectProposal(out, { kind, body, minConfidence? })` asserts only what the
+		// caller specified. 33 sites on the calibration corpus, none a hidden never-running assertion.
+		"vitest/no-conditional-expect": "off",
+		"vitest/no-conditional-tests": "error",
+		"vitest/no-disabled-tests": "error",
+		"vitest/no-commented-out-tests": "error",
+		"vitest/no-alias-methods": "error",
+		"vitest/prefer-to-be": "error",
+		"vitest/prefer-to-have-length": "error",
+		"vitest/prefer-to-contain": "error",
+		"vitest/require-to-throw-message": "error",
+		// Playwright names its e2e specs `*.spec.ts`; vitest unit tests are `*.test.ts`. A repo running
+		// both has two legitimate conventions, so the rule is scoped to the vitest ones.
+		"vitest/consistent-test-filename": ["error", { allTestPattern: String.raw`.*\.test\.[tj]sx?$` }],
+		// Enabling a plugin also activates its `correctness`-category rules, so a rule this tier turned
+		// down must be switched off explicitly rather than merely left out of the list above.
+		"vitest/require-mock-type-parameters": "off",
+		"vitest/no-conditional-in-test": "off",
+
+		// Tier 4 — mechanical hygiene. All autofixable, none requiring judgment.
+		// Literal form.
+		"unicorn/numeric-separators-style": "error",
+		"unicorn/no-zero-fractions": "error",
+		"unicorn/text-encoding-identifier-case": "error",
+		"unicorn/escape-case": "error",
+		"unicorn/no-hex-escape": "error",
+		// Import discipline.
+		// `disallowTypeAnnotations: false` keeps the valuable half — a type-only import must be written
+		// `import type` — while allowing `typeof import("…")` in an annotation. That form is how a
+		// guarded dynamic import is typed: the module is optional and loaded at runtime, and the inline
+		// annotation is what says so. `import type` would erase to nothing and read as a hard dep.
+		"typescript/consistent-type-imports": ["error", { disallowTypeAnnotations: false }],
+		"typescript/no-import-type-side-effects": "error",
+		"unicorn/prefer-export-from": "error",
+		"import/no-duplicates": "error",
+		"import/first": "error",
+		"import/newline-after-import": "error",
+		// Modern API preference.
+		"unicorn/prefer-string-replace-all": "error",
+		// `caught` is permitted alongside `error`: when a catch sits inside a scope that already binds
+		// `error` (a React component's error state, say), no-shadow requires a different name and this
+		// rule would otherwise demand the shadowing one. The two rules are in direct conflict without it.
+		"unicorn/catch-error-name": ["error", { ignore: ["caught"] }],
+		"unicorn/prefer-at": "error",
+		"unicorn/prefer-global-this": "error",
+		"unicorn/consistent-existence-index-check": "error",
+		"unicorn/new-for-builtins": "error",
+		"unicorn/prefer-array-find": "error",
+		"unicorn/prefer-structured-clone": "error",
+		"unicorn/prefer-negative-index": "error",
+		"unicorn/prefer-math-min-max": "error",
+		"unicorn/no-useless-collection-argument": "error",
+		"unicorn/throw-new-error": "error",
+		// Two rules that look mechanical but are not type-safe, so they stay off:
+		//
+		// `unicorn/prefer-code-point` rewrites `charCodeAt` to `codePointAt`, which returns
+		// `number | undefined`. It exists for surrogate-pair correctness, but on the ASCII arithmetic
+		// where it usually fires it buys nothing and forces an undefined branch at every site.
+		//
+		// `unicorn/no-useless-undefined` drops an explicitly-passed `undefined` argument. oxlint has no
+		// type information, so it cannot tell an optional parameter from a required one and will
+		// silently turn `f(a, undefined)` into a call that no longer type-checks.
+		//
+		// `unicorn/prefer-string-raw` rewrites a string literal to a String.raw template. That is
+		// runtime-identical but not type-identical: the literal type is lost, so any template-literal
+		// type built from the value collapses. It widens types silently, which is worse than the
+		// escaped backslashes it removes.
+		"unicorn/prefer-code-point": "off",
+		"unicorn/no-useless-undefined": "off",
+		"unicorn/prefer-string-raw": "off",
+		//
+		// `unicorn/prefer-math-trunc` is the one that is not merely type-unsafe but semantically wrong.
+		// `x | 0` and `x >>> 0` are int32/uint32 coercion, and the wrapping is the point — every site on
+		// the calibration corpus was a hash function, a PRNG, or a seeded evaluation harness.
+		// `Math.trunc` does not wrap, so taking its suggestion silently changes what those produce.
+		"unicorn/prefer-math-trunc": "off",
+		//
+		// `unicorn/prefer-number-coercion` rewrites `Number.parseInt(x, 10)` to
+		// `Math.trunc(Number(x))`. parseInt parses a numeric PREFIX; Number is strict, so
+		// `parseInt("12px", 10)` is 12 where `Number("12px")` is NaN. On the calibration corpus the
+		// inputs included CLI options and an HTTP status of uncertain type — exactly where the
+		// difference bites. It also reintroduces Math.trunc, disabled just above.
+		"unicorn/prefer-number-coercion": "off",
+		//
+		// These two are not unsafe — they are unsatisfiable. oxfmt reverts both fixes on its next run:
+		// it lowercases hex digits, and it strips the parentheses unicorn/no-nested-ternary adds. Lint
+		// and format are both CI gates, so a rule the formatter undoes can never go green. Neither
+		// behaviour is configurable in oxfmt today.
+		"unicorn/number-literal-case": "off",
+		"unicorn/no-nested-ternary": "off",
+		//
+		// `unicorn/explicit-length-check` enforces `x.length > 0`, the opposite of the house
+		// convention. `sister-software/prefer-length-truthiness` enforces ours.
+		"unicorn/explicit-length-check": "off",
+		//
+		// Core `no-duplicate-imports` is not TypeScript-aware: it counts a value import and an
+		// `import type` from the same module as a duplicate, which is the split
+		// `typescript/consistent-type-imports` exists to create. On the calibration corpus it reported
+		// 71 sites where the TS-aware `import/no-duplicates` reported 1, and that 1 was real.
+		"no-duplicate-imports": "off",
+
+		// TS style.
+		"typescript/consistent-type-definitions": "error",
+		"typescript/consistent-indexed-object-style": "error",
+		"typescript/prefer-for-of": "error",
+		"typescript/no-inferrable-types": "error",
+		// Small structural.
+		"unicorn/prefer-ternary": "error",
+		"unicorn/prefer-logical-operator-over-ternary": "error",
+		"unicorn/no-lonely-if": "error",
+		"unicorn/no-console-spaces": "error",
+		"unicorn/no-static-only-class": "error",
+		"no-useless-return": "error",
+	}
+
+	if (react) {
+		rules["react-hooks/rules-of-hooks"] = "error"
+		rules["react/no-unstable-nested-components"] = "error"
+		rules["react/no-object-type-as-default-prop"] = "error"
+		rules["react/jsx-no-constructed-context-values"] = "error"
+		// The automatic JSX runtime made this obsolete; the rule predates it.
+		rules["react/react-in-jsx-scope"] = "off"
 	}
 
 	if (headers) {
@@ -136,15 +506,118 @@ export function createOxlintConfig(options: OxlintConfigOptions = {}): OxlintCon
 		rules["sister-software/no-process-globals"] = "error"
 	}
 
+	if (unnamedThresholds) {
+		// Error severity: an unnamed threshold is a legibility defect, not a style preference.
+		rules["sister-software/no-unnamed-threshold"] = [
+			"error",
+			typeof unnamedThresholds === "object" ? unnamedThresholds : {},
+		]
+	}
+
+	if (constantDocs) {
+		// Error severity: an undocumented public constant or tuning knob is a legibility defect.
+		rules["sister-software/require-constant-doc"] = ["error", typeof constantDocs === "object" ? constantDocs : {}]
+	}
+
+	if (lengthTruthiness) {
+		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.
+	const testFileRules: Record<string, unknown> = {
+		"max-lines-per-function": "off",
+		"max-statements": "off",
+		"max-lines": "off",
+	}
+
+	if (react) {
+		// A Storybook `render` IS a component — React calls it as one — but it is not NAMED like one, so
+		// the hook rules read it as a plain function. Test files that render hooks go through a
+		// testing-library wrapper for the same reason.
+		testFileRules["react-hooks/rules-of-hooks"] = "off"
+	}
+
+	if (unnamedThresholds) {
+		testFileRules["sister-software/no-unnamed-threshold"] = "off"
+	}
+
+	if (constantDocs) {
+		testFileRules["sister-software/require-constant-doc"] = "off"
+	}
+
+	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",
+		"max-statements": "off",
+		complexity: "off",
+	}
+
 	return {
 		plugins,
-		...(headers || padding || braces || restrictProcessGlobals
+		...(headers ||
+		padding ||
+		braces ||
+		restrictProcessGlobals ||
+		unnamedThresholds ||
+		constantDocs ||
+		lengthTruthiness ||
+		multilineJSDoc ||
+		sectionMarkers
 			? { jsPlugins: ["@sister.software/oxlint-config/plugin"] }
 			: {}),
 		categories: { correctness: "error" },
 		ignorePatterns,
 		rules,
-		overrides: createRuntimeOverrides(packageNamespace),
+		overrides: [
+			...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} */`)
+						},
+					})
+				}
+			},
+		}
+	},
+}