eslint-plugin-etc-misc 1.1.0 → 1.1.2

package/docs/rules/no-function-declare-after-return.md

@@ -0,0 +1,143 @@
+# no-function-declare-after-return
+
+Disallow function declarations that appear after a `return` statement in the same block scope.
+
+## Rule details
+
+JavaScript hoists `function` declarations to the top of their enclosing scope,
+which means the following code is syntactically valid and runs without errors:
+
+```ts
+function publicMethods(obj) {
+    if (obj instanceof CustomClass) {
+        return {
+            get: methodGetter(obj), // ← called before its declaration ❌
+        };
+    }
+    function methodGetter(obj) { // ← declared after the return
+        // …
+    }
+}
+```
+
+Even though this works at runtime, it is a readability trap:
+
+- A reader scanning the function top-to-bottom will encounter the call to
+  `methodGetter` before they see its definition.
+- Newcomers unfamiliar with hoisting may not realize `methodGetter` is even in
+  scope at the call site.
+- Linters such as `no-unreachable` do not flag this because the declaration is
+  not unreachable — it is hoisted.
+
+This rule enforces that every `FunctionDeclaration` is placed **before** any
+`ReturnStatement` in the same block scope, making hoisting irrelevant from a
+readability perspective.
+
+### Scope boundaries
+
+This rule reports only when the function declaration is a **direct sibling** of
+the `return` statement in the same statement list (`BlockStatement` or
+`Program`).
+
+- `return` inside `switch` cases is out of scope for this rule.
+- Function declarations nested inside later `if`/`try`/`for` blocks are not directly targeted by this rule.
+
+> **Note:** This rule targets only `FunctionDeclaration` nodes. Arrow functions,
+> function expressions, generator functions, and async function expressions
+> assigned to variables are **not** flagged — those are expression statements and
+> are genuinely unreachable. Use `no-unreachable` for those cases.
+
+## ❌ Incorrect
+
+```ts
+function outer() {
+    return 42;
+    function helper() {} // ← 'helper' should be moved before the return
+}
+```
+
+```ts
+function publicMethods(obj) {
+    if (obj) {
+        return {
+            set: methodSetter(obj),
+            get: methodGetter(obj),
+        };
+        function methodSetter(obj) { /* … */ } // ← should be before return
+        function methodGetter(obj) { /* … */ } // ← should be before return
+    }
+}
+```
+
+## ✅ Correct
+
+```ts
+function outer() {
+    function helper() {} // ← declared before the return
+    return helper();
+}
+```
+
+```ts
+function publicMethods(obj) {
+    function methodSetter(obj) { /* … */ } // ← before the return
+    function methodGetter(obj) { /* … */ } // ← before the return
+    if (obj) {
+        return {
+            set: methodSetter(obj),
+            get: methodGetter(obj),
+        };
+    }
+}
+```
+
+```ts
+// Arrow functions and function expressions after return are NOT flagged —
+// use no-unreachable for those.
+function outer() {
+    return 1;
+    const arrow = () => {}; // not a FunctionDeclaration — not flagged here
+}
+```
+
+## Autofix
+
+This rule provides an **autofix**. When triggered, it moves the offending
+`FunctionDeclaration` to immediately before the `ReturnStatement`, preserving
+the correct indentation level.
+
+When a function declaration has leading comments (including JSDoc), the fixer
+moves those comments together with the declaration.
+
+## Options
+
+This rule has no options.
+
+## When not to use it
+
+- If your team relies on intentional hoisting patterns with thorough documentation,
+  you may disable this rule.
+- If the function declaration lives in a different block scope from the return
+  statement (e.g., hoisted to the outer function while the return is inside an
+  `if`-block), the fix may require manual review to confirm the intended
+  placement.
+
+## Further reading
+
+- [MDN: Function declarations — Hoisting](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function#hoisting)
+- [ESLint built-in: `no-unreachable`](https://eslint.org/docs/rules/no-unreachable)
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/no-function-declare-after-return": "warn",
+        },
+    },
+];
+```

package/docs/rules/no-use-extend-native.md

@@ -0,0 +1,89 @@
+# no-use-extend-native
+
+Disallow usage of non-native members on built-in JavaScript objects.
+
+## Rule details
+
+This rule helps prevent implicit reliance on monkey-patched native prototypes (for example from legacy libraries that add methods like `String.prototype.green`).
+
+Relying on extended native objects can make code unpredictable across runtimes, bundling targets, and dependency versions.
+
+This rule reports member usage on obvious built-in values when the accessed member is not part of the native API.
+
+## Targeted pattern scope
+
+This rule is intentionally conservative and focuses on obvious built-in object shapes such as:
+
+- String/number/boolean/regexp literals.
+- Array/object literals.
+- `new` expressions for built-ins.
+- `String.prototype.<member>` / `Array.prototype.<member>` style accesses.
+
+It does **not** attempt full-flow inference for arbitrary identifiers.
+
+## ❌ Incorrect
+
+```ts
+const value = "unicorn".green;
+```
+
+```ts
+const value = [].customFunction();
+```
+
+```ts
+const value = String.prototype.shortHash();
+```
+
+## ✅ Correct
+
+```ts
+const value = "unicorn".toUpperCase();
+```
+
+```ts
+const value = [].map((entry) => entry);
+```
+
+```ts
+const value = String.prototype.toLowerCase.call("ABC");
+```
+
+## Options
+
+This rule has no options.
+
+## Relationship to ESLint `no-extend-native`
+
+- ESLint core [`no-extend-native`](https://eslint.org/docs/latest/rules/no-extend-native) prevents adding properties to native prototypes.
+- This rule prevents consuming non-native members when they appear in code.
+
+Using both rules together gives better protection:
+
+1. Prevent introducing prototype extension.
+2. Prevent relying on prototype extension from third-party code.
+
+## When not to use it
+
+- If your project intentionally and explicitly relies on controlled prototype extension.
+- If your runtime environment guarantees specific prototype patches and that dependency is accepted in your architecture.
+
+## Further reading
+
+- [ESLint `no-extend-native`](https://eslint.org/docs/latest/rules/no-extend-native)
+- [MDN: Inheritance and the prototype chain](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain)
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/no-use-extend-native": "error",
+        },
+    },
+];
+```

package/docs/rules/no-vulnerable.md

@@ -0,0 +1,110 @@
+# no-vulnerable
+
+Disallow regular expressions that are potentially vulnerable to ReDoS (Regular Expression Denial of Service).
+
+## Rule details
+
+This rule analyzes regular expression literals and statically-resolvable `RegExp(...)` constructor calls using [`recheck`](https://www.npmjs.com/package/recheck).
+
+Catastrophic backtracking can make an application spend excessive CPU time on crafted inputs. In server contexts, that can become an availability issue.
+
+This rule reports patterns that `recheck` identifies as vulnerable with polynomial or exponential complexity.
+
+## What this rule checks
+
+This rule checks:
+
+- `/(...)/flags` literals.
+- `RegExp("...")` and `new RegExp("...", "flags")` when both arguments are statically-known strings.
+
+This rule intentionally skips dynamic patterns/flags it cannot resolve safely at lint time.
+
+## ❌ Incorrect
+
+```ts
+const unsafe = /(a+)+$/;
+```
+
+```ts
+const unsafe = RegExp("(a+)+$");
+```
+
+```ts
+const unsafe = new RegExp("(a+)+$", "u");
+```
+
+## ✅ Correct
+
+```ts
+const safe = /^a+$/;
+```
+
+```ts
+const source = getPatternFromConfig();
+const maybeUnsafe = RegExp(source); // Dynamic value: intentionally not analyzed.
+```
+
+## Options
+
+```ts
+type Options = [
+    {
+        ignoreErrors?: boolean;
+        permittableComplexities?: Array<"polynomial" | "exponential">;
+        timeout?: number | null;
+    }?,
+];
+```
+
+### Default options
+
+```ts
+{
+    ignoreErrors: true,
+    permittableComplexities: [],
+}
+```
+
+### `ignoreErrors`
+
+When `true` (default), analysis failures from `recheck` are ignored.
+When `false`, analysis failures are reported.
+
+### `permittableComplexities`
+
+Allows selected vulnerable complexity classes to pass.
+
+For example, to allow polynomial but still report exponential:
+
+```ts
+{
+    permittableComplexities: ["polynomial"],
+}
+```
+
+## When not to use it
+
+- If your codebase never handles untrusted input with regexes.
+- If lint-time regex analysis cost is unacceptable for your workflow.
+- If you prefer running ReDoS scanning as a separate CI security step rather than as an ESLint rule.
+
+## Further reading
+
+- [OWASP: Regular expression Denial of Service (ReDoS)](https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS)
+- [`recheck` package](https://www.npmjs.com/package/recheck)
+- [MDN: Regular expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions)
+
+## ESLint flat config example
+
+```ts
+import etcMisc from "eslint-plugin-etc-misc";
+
+export default [
+    {
+        plugins: { "etc-misc": etcMisc },
+        rules: {
+            "etc-misc/no-vulnerable": "error",
+        },
+    },
+];
+```