@sister.software/oxlint-config 9.3.0 → 10.0.0

package/out/threshold-plugin.js

@@ -0,0 +1,72 @@
+/**
+ * @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.
+ */
+/** 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]/;
+export const noUnnamedThresholdRule = {
+    meta: {
+        name: "no-unnamed-threshold",
+        type: "suggestion",
+        schema: [{ type: "object", additionalProperties: true }],
+    },
+    create(context) {
+        const options = (context.options[0] ?? {});
+        const ignore = new Set(options.ignore ?? DEFAULT_IGNORE);
+        const allowHex = options.allowHex ?? true;
+        function check(operand) {
+            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;
+//# sourceMappingURL=threshold-plugin.js.map

package/out/threshold-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"threshold-plugin.js","sourceRoot":"","sources":["../src/threshold-plugin.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
  "name": "@sister.software/oxlint-config",
- "version": "9.3.0",
+ "version": "10.0.0",
  "description": "Sister Software's oxlint config",
  "license": "AGPL-3.0",
  "author": "teffen@sister.software",
@@ -40,7 +40,7 @@
   "typescript": "^6.0.3"
  },
  "peerDependencies": {
-  "oxlint": "^1.71.0"
+  "oxlint": ">=1.75.0 <2"
  },
  "engines": {
   "node": ">=24.0"

package/src/constant-doc-plugin.ts

@@ -0,0 +1,114 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file A require-constant-doc rule, authored as an oxlint JS plugin (ESLint v9-compatible API). A
+ *   module-level constant that is exported or SCREAMING_CASE is either public surface or a tuning
+ *   knob, and in both cases a reader needs to know what the value means and where it came from. A
+ *   documented table also answers for every number inside it, which is why data-heavy files satisfy
+ *   this rule without extracting a constant per row.
+ */
+
+import type { Rule } from "./plugin-types.js"
+
+/** 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. */
+const FUNCTION_INITIALIZERS = new Set(["ArrowFunctionExpression", "FunctionExpression"])
+
+/** Which module-level constants the rule applies to. */
+export type ConstantDocScope = "exported" | "screaming" | "exported-or-screaming"
+
+/** Options accepted by {@link requireConstantDocRule}. */
+export interface ConstantDocOptions {
+	/** 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
+	 * `description` (whose value IS the help text), a route module's `loader`, and so on.
+	 */
+	ignoreNames?: string[]
+}
+
+export const requireConstantDocRule: Rule = {
+	meta: {
+		name: "require-constant-doc",
+		type: "suggestion",
+		schema: [{ type: "object", additionalProperties: true }],
+	},
+	create(context) {
+		const options = (context.options[0] ?? {}) as ConstantDocOptions
+		const scope = options.scope ?? "exported-or-screaming"
+		const ignoreNames = new Set(options.ignoreNames)
+		const sourceCode = context.sourceCode ?? context.getSourceCode!()
+		const text = sourceCode.getText()
+		const comments = sourceCode.getAllComments()
+
+		/**
+		 * True when a JSDoc block documents the declaration starting at `start`.
+		 *
+		 * Attachment requires the comment to be directly above it — whitespace spanning a single newline. A blank line in
+		 * between means the comment belongs to something else, which is what separates a declaration's own JSDoc from the
+		 * file header block that precedes the first declaration in every file.
+		 */
+		function hasJSDocBefore(start: number): boolean {
+			for (const comment of comments) {
+				if (comment.range[1] > start) continue
+
+				if (comment.type !== "Block" || !comment.value.startsWith("*")) continue
+
+				const gap = text.slice(comment.range[1], start)
+
+				if (/^\s*$/.test(gap) && (gap.match(/\n/g) ?? []).length <= 1) return true
+			}
+
+			return false
+		}
+
+		function inScope(exported: boolean, screaming: boolean): boolean {
+			if (scope === "exported") return exported
+
+			if (scope === "screaming") return screaming
+
+			return exported || screaming
+		}
+
+		return {
+			VariableDeclaration(node) {
+				if (node.kind !== "const") return
+
+				const exported = node.parent?.type === "ExportNamedDeclaration"
+				const container = exported ? node.parent! : node
+
+				// Module level only: the declaration (or its export wrapper) sits directly in Program.
+				if (container.parent?.type !== "Program") return
+
+				if (hasJSDocBefore(container.range[0])) return
+
+				for (const declarator of node.declarations ?? []) {
+					const id = declarator.id
+
+					if (id?.type !== "Identifier" || !id.name) continue
+
+					if (ignoreNames.has(id.name)) continue
+
+					const initializer = declarator.init
+
+					if (initializer && FUNCTION_INITIALIZERS.has(initializer.type)) continue
+
+					if (!inScope(exported, SCREAMING_CASE.test(id.name))) continue
+
+					context.report({
+						node: declarator,
+						message:
+							`\`${id.name}\` is ${exported ? "exported" : "a named constant"} but undocumented — add a ` +
+							`JSDoc block saying what the value means and where it came from.`,
+					})
+				}
+			},
+		}
+	},
+}
+
+export default requireConstantDocRule

package/src/headers-plugin.ts

@@ -67,7 +67,7 @@ export const headerRule: Rule = {
 					const existing = parseInnerLines(leading)
 					const missing = headerLines.filter((line) => !existing.includes(line))
 
-					if (missing.length === 0) return
+					if (!missing.length) return
 
 					const preserved = existing.filter((line) => !HEADER_TAG_PATTERN.test(line))
 					const block = buildBlock(preserved)

package/src/index.ts

@@ -12,6 +12,76 @@ export * from "./restrictions.js"
 /** 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. */
+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/**"]
+
 /** Options for {@link createOxlintConfig}. */
 export interface OxlintConfigOptions {
 	/** The package namespace whose runtime boundaries are enforced, e.g. `@sister.software`. */
@@ -35,13 +105,31 @@ export interface OxlintConfigOptions {
 	 * through blessed helpers, which disable `sister-software/no-process-globals`.
 	 */
 	restrictProcessGlobals?: boolean
+	/**
+	 * 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
+	/** 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[]
 	/** Override the default ignore patterns. */
 	ignorePatterns?: string[]
 	/** 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 +137,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/**",
 ]
 
 /**
@@ -76,18 +167,25 @@ export function createOxlintConfig(options: OxlintConfigOptions = {}): OxlintCon
 		padding = true,
 		braces = true,
 		restrictProcessGlobals = false,
+		unnamedThresholds = false,
+		constantDocs = false,
+		lengthTruthiness = true,
+		limits: limitOverrides = {},
+		testFilePatterns = DefaultTestFilePatterns,
+		generatedFilePatterns = DefaultGeneratedFilePatterns,
 		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 +211,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 +419,68 @@ 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"
+	}
+
+	// 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"
+	}
+
+	/** 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
 			? { 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 },
+		],
 		...overrides,
 	}
 }