@sister.software/oxlint-config 9.2.0 → 10.0.0

package/out/process-globals-plugin.js

@@ -0,0 +1,48 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file A no-process-globals rule, authored as an oxlint JS plugin (ESLint v9-compatible API). It
+ *   forbids direct `process.env` / `process.argv` access so those reads can be funneled through a
+ *   few blessed helpers; the helper files disable the rule (`sister-software/no-process-globals`).
+ *   oxlint has no `no-restricted-syntax`, so this is a small dedicated rule instead.
+ */
+/** `process` members that must be reached through a blessed helper, not accessed directly. */
+const RESTRICTED_MEMBERS = new Set(["env", "argv"]);
+/** The accessed member name for `process.env` (identifier) or `process["env"]` (string literal). */
+function accessedMember(node) {
+    const property = node.property;
+    if (!property)
+        return null;
+    if (!node.computed && property.type === "Identifier")
+        return property.name ?? null;
+    if (node.computed && (property.type === "Literal" || property.type === "StringLiteral")) {
+        return typeof property.value === "string" ? property.value : null;
+    }
+    return null;
+}
+export const noProcessGlobalsRule = {
+    meta: {
+        name: "no-process-globals",
+        type: "problem",
+        schema: [{ type: "object", additionalProperties: true }],
+    },
+    create(context) {
+        return {
+            MemberExpression(node) {
+                const member = node;
+                if (member.object?.type !== "Identifier" || member.object.name !== "process")
+                    return;
+                const name = accessedMember(member);
+                if (!name || !RESTRICTED_MEMBERS.has(name))
+                    return;
+                context.report({
+                    node,
+                    message: `Direct \`process.${name}\` access is restricted — read it through the project's blessed helper (disable \`sister-software/no-process-globals\` there).`,
+                });
+            },
+        };
+    },
+};
+export default noProcessGlobalsRule;
+//# sourceMappingURL=process-globals-plugin.js.map

package/out/process-globals-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-globals-plugin.js","sourceRoot":"","sources":["../src/process-globals-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,8FAA8F;AAC9F,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAA;AAanD,oGAAoG;AACpG,SAAS,cAAc,CAAC,IAAgB;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAA;IAE9B,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAA;IAE1B,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,KAAK,YAAY;QAAE,OAAO,QAAQ,CAAC,IAAI,IAAI,IAAI,CAAA;IAElF,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,SAAS,IAAI,QAAQ,CAAC,IAAI,KAAK,eAAe,CAAC,EAAE,CAAC;QACzF,OAAO,OAAO,QAAQ,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAA;IAClE,CAAC;IAED,OAAO,IAAI,CAAA;AACZ,CAAC;AAED,MAAM,CAAC,MAAM,oBAAoB,GAAS;IACzC,IAAI,EAAE;QACL,IAAI,EAAE,oBAAoB;QAC1B,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,oBAAoB,EAAE,IAAI,EAAE,CAAC;KACxD;IACD,MAAM,CAAC,OAAO;QACb,OAAO;YACN,gBAAgB,CAAC,IAAI;gBACpB,MAAM,MAAM,GAAG,IAAkB,CAAA;gBAEjC,IAAI,MAAM,CAAC,MAAM,EAAE,IAAI,KAAK,YAAY,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS;oBAAE,OAAM;gBAEpF,MAAM,IAAI,GAAG,cAAc,CAAC,MAAM,CAAC,CAAA;gBAEnC,IAAI,CAAC,IAAI,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC;oBAAE,OAAM;gBAElD,OAAO,CAAC,MAAM,CAAC;oBACd,IAAI;oBACJ,OAAO,EAAE,oBAAoB,IAAI,gIAAgI;iBACjK,CAAC,CAAA;YACH,CAAC;SACD,CAAA;IACF,CAAC;CACD,CAAA;AAED,eAAe,oBAAoB,CAAA"}

package/out/threshold-plugin.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @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 { Rule } from "./plugin-types.js";
+/** 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 declare const noUnnamedThresholdRule: Rule;
+export default noUnnamedThresholdRule;
+//# sourceMappingURL=threshold-plugin.d.ts.map

package/out/threshold-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"threshold-plugin.d.ts","sourceRoot":"","sources":["../src/threshold-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,mBAAmB,CAAA;AAWtD,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAChC,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,qFAAqF;IACrF,QAAQ,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,eAAO,MAAM,sBAAsB,EAAE,IA4DpC,CAAA;AAED,eAAe,sBAAsB,CAAA"}

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.2.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)