@sister.software/oxlint-config 9.3.0 → 11.0.0

package/out/threshold-plugin.js

@@ -0,0 +1,78 @@
+/**
+ * @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":"AAAA;;;;;;;;;GASG;AAIH;;GAEG;AACH,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAA;AAEtF;;GAEG;AACH,MAAM,cAAc,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,CAAA;AAExD;;GAEG;AACH,MAAM,cAAc,GAAG,YAAY,CAAA;AAgBnC,MAAM,CAAC,MAAM,sBAAsB,GAAS;IAC3C,IAAI,EAAE;QACL,IAAI,EAAE,sBAAsB;QAC5B,IAAI,EAAE,YAAY;QAClB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,oBAAoB,EAAE,IAAI,EAAE,CAAC;KACxD;IACD,MAAM,CAAC,OAAO;QACb,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAqB,CAAA;QAC9D,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,cAAc,CAAC,CAAA;QACxD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAA;QAEzC,SAAS,KAAK,CAAC,OAA4B;YAC1C,IAAI,CAAC,OAAO;gBAAE,OAAM;YAEpB,IAAI,OAAO,GAAG,OAAO,CAAA;YACrB,IAAI,IAAI,GAAG,CAAC,CAAA;YAEZ,8DAA8D;YAC9D,IAAI,OAAO,CAAC,IAAI,KAAK,iBAAiB,EAAE,CAAC;gBACxC,IAAI,OAAO,CAAC,QAAQ,KAAK,GAAG,IAAI,OAAO,CAAC,QAAQ,KAAK,GAAG;oBAAE,OAAM;gBAEhE,IAAI,CAAC,OAAO,CAAC,QAAQ;oBAAE,OAAM;gBAE7B,IAAI,GAAG,OAAO,CAAC,QAAQ,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;gBACxC,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAA;YAC3B,CAAC;YAED,2FAA2F;YAC3F,gCAAgC;YAChC,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,KAAK,gBAAgB;gBAAE,OAAM;YAE3E,IAAI,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ;gBAAE,OAAM;YAE7C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;YAEhD,6EAA6E;YAC7E,IAAI,QAAQ,IAAI,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC;gBAAE,OAAM;YAEhD,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC;gBAAE,OAAM;YAE5C,sFAAsF;YACtF,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAA;YAE3C,OAAO,CAAC,MAAM,CAAC;gBACd,IAAI,EAAE,OAAO;gBACb,OAAO,EACN,uBAAuB,KAAK,sEAAsE;oBAClG,8CAA8C;aAC/C,CAAC,CAAA;QACH,CAAC;QAED,OAAO;YACN,gBAAgB,CAAC,IAAI;gBACpB,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC;oBAAE,OAAM;gBAEtE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;gBAChB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YAClB,CAAC;SACD,CAAA;IACF,CAAC;CACD,CAAA;AAED,eAAe,sBAAsB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
  "name": "@sister.software/oxlint-config",
- "version": "9.3.0",
+ "version": "11.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/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

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

@@ -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
@@ -67,7 +69,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)
@@ -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 },